simplifying documentation source

[davidcarlisle]

the current xml source requires a somewhat complicated dtd (it is docbook+mathml+relaxNG+XSD+OpenMath+OMSTS+OMCD+OMCDGroups all in one grammar)

the main cause of the complication is the use of entities to include external files.

for example openmath2.rnc is included by

<literallayout>
&omrnc;
</literallayout>

where &omrnc; is defined in the dtd via

<!ENTITY omrnc SYSTEM "../build/openmath2rnc.xml">

and build/openmath2rnc.xml needs to be generated before the main file is parsed by running the perl script rnc2dbk over openmath2.rnc.

Of course the build script takes care of all this but trying to validate in other formats or trying to add another file is an interesting exercise in xml arcane corners of xml.

I have working (and propose to check in) a new variant where the source markup is

<literallayout role="rnc" file="openmath2.rnc"/>

and the file inclusion and regex parsing of the Relax NG text is done on the fly by the XSLT so there is no need to extend the dtd and no need to pre-process a specific list of files with perl.

I intend to do this incrementally for the other file inclusions (XSD, etc) and will commit them referencing this issue.

In the medium term I think we should probably also drop the inclusion of the full docbook dtd and use a custom dtd (eg generated from the omstd20.rnc the processing of this document has never been able to accept arbitrary docbook markup. A custom markup (perhaps migrating more towards html) would be simpler to document. But first keep the existing markup but just constrain the dtd rather than including a copy of docbook.

[JamesHDavenport]

You’re the expert, but this all seems good. James

From: David Carlisle [mailto:notifications@github.com] Sent: 02 October 2017 21:23 To: OpenMath/OMSTD OMSTD@noreply.github.com Cc: Subscribed subscribed@noreply.github.com Subject: [OpenMath/OMSTD] simplifying documentation source (#41)

the current xml source requires a somewhat complicated dtd (it is docbook+mathml+relaxNG+XSD+OpenMath+OMSTS+OMCD+OMCDGroups all in one grammar)

the main cause of the complication is the use of entities to include external files.

for example openmath2.rnc is included by

&omrnc;

where &omrnc; is defined in the dtd via

<!ENTITY omrnc SYSTEM "../build/openmath2rnc.xml">

and build/openmath2rnc.xml needs to be generated before the main file is parsed by running the perl script rnc2dbk over openmath2.rnc.

Of course the build script takes care of all this but trying to validate in other formats or trying to add another file is an interesting exercise in xml arcane corners of xml.

I have working (and propose to check in) a new variant where the source markup is

and the file inclusion and regex parsing of the Relax NG text is done on the fly by the XSLT so there is no need to extend the dtd and no need to pre-process a specific list of files with perl.

I intend to do this incrementally for the other file inclusions (XSD, etc) and will commit them referencing this issue.

In the medium term I think we should probably also drop the inclusion of the full docbook dtd and use a custom dtd (eg generated from the omstd20.rnc the processing of this document has never been able to accept arbitrary docbook markup. A custom markup (perhaps migrating more towards html) would be simpler to document. But first keep the existing markup but just constrain the dtd rather than including a copy of docbook.

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHubhttps://github.com/OpenMath/OMSTD/issues/41, or mute the threadhttps://github.com/notifications/unsubscribe-auth/AGvamYZfvzkk3L1CAkMU3VVlqKMGtrC0ks5soUYygaJpZM4PrMsi.

[kohlhase]

I would really welcome the simplification.

[kohlhase]

This looks almost done, so I am adding it to the R2 milestone

[davidcarlisle]

Could always do more but I'm going to close this, done everything that was suggested at the top.