Equations: Alignment, automatic numbering, referencing, etc.

[khd.oxy]

I'm using oxygenxml-editor.

By entering "file --> new file --> "math" (in filter text field)" i got with "Composite with MathML" quickly a starting point for equations in dita.

After that i searched for code examples concerning questions like:

• How to change equation alignment from "left" to "centered"?
• How to automatically assign numbers to selected equations?
• How to refer to these equations?

I found that the <equation> element is a specialisation of the <fig> element, thus we can assign a title to the equation and a equation can be referred like a figure. But the result after rendering PDF looks figure-like not equation-like. How can i get a result like:

Code: Select all

Einstein discoverd



  E = m c²           (11)



In equation (11) the letter c represents the vacuum light speed.

Furthermore, is there a way to omit the "mml:" prefix in "<mml:mrow>"?

Beside answers to the questions raised above, any pointers to (online) tutorials or books, that cover the topic "DITA, MathML and Oxygen XML" in detail (i.e. including code examples and their rendering results) are cordially welcome.

[Radu]

Dear Frank,

Oxygen uses the open source DITA Open Toolkit processor to publish DITA content to various output format.
First of all, the default DITA publishing does not have support for using embedded MathML equations in PDF and XHTML-based outputs.
In order to overcome this limitation we added a special mathml plugin to the DITA Open Toolkit bundled with Oxygen:

OXYGEN_INSTALL_DIR\frameworks\dita\DITA-OT\plugins\mathml

This plugin does two things:

1) It adds a new DITA specialization which allows you to create that Composite with MathML file type.

2) It adds custom XSLT stylesheets which contribute to properly render the mathml equation in the output.

The DITA 1.3 standard which is planned to be released at the end of this year will have support of embedding MathML code directly in any kind of DITA topic, task, concept or anything else.

Please see some answers below:

How to change equation alignment from "left" to "centered"?

Right now there is no such a built-in possibility. You can probably try to set a special attribute on the equation like:

Code: Select all

 <equation outputclass="center">

.........

and then via an XSLT customization you can match that particular element with that particular outputclass value and create the appropriate XSL-FO elements like:

Code: Select all

 <fo:block text-align="center">

....

How to automatically assign numbers to selected equations?

Again this is not possible without additional XSLT customizations.

How to refer to these equations?

Probably like you did, assign an ID to the figure and then refer to that ID in other places.

I found that the <equation> element is a specialisation of the <fig> element, thus we can assign a title to the equation and a equation can be referred like a figure. But the result after rendering PDF looks figure-like not equation-like. How can i get a result like:

Einstein discoverd
E = m c² (11)
In equation (11) the letter c represents the vacuum light speed.

Again, not without a customization.

Furthermore, is there a way to omit the "mml:" prefix in "<mml:mrow>"?

In the DITA DTD specialization there is already a DITA element called mathml which inside it includes the <math> element from the MathML namespace. Unfortunately the DTD is not namespace aware so we are forced to have a prefix for all mathml elements in the DITA content. Maybe by modifying the DTD specialization you could make that prefix be m: instead of mml: if you can insert that easier.

One more thing, as an alternative to having the mathml content embedded inside the topic, you can save it to a separate file and then refer to it using the DITA image element, as if it would be an image like:

Code: Select all

<fig id="fig_y5t_qvn_rs">

                <image placement="break" id="image_b4w_qvn_rs" href="test.mml" align="center"/>

            </fig>

This works in the PDF output but does not work in the XHTML output because web browsers require the MathML equations to be embedded in the content.

Regards,
Radu

[khd.oxy]

Dear Radu,

thank You for Your quick response and Your in depth explanations.

It's of great help to know how the "machine" works (plugins, OxygenXML architecture).

From the practical part of Your illustrations i learned, that i either have to customize my setup or have to wait for the DITA 1.3 standard, which is planned to be released at the end of this year.

We will do the latter, because the aim of my colleagues and me is to write content: Product usage manuals and in particular product development specifications containing a lot of mathematics. Therefore we hope that the DITA standardisation committee has some members with LaTeX know-how.

Dealing with bibliographies seems to be another topic where DITA can take inspritation from LaTeX / BibTeX.

Again, thank You for Your first class answer.

Best regards,

Frank

[expatriate]

Dear Frank, Radu,
I've come late to this discussion, but I write DITA content for STEM education and have been struggling with similar problems for a few years. Salvation by DITA 1.3 now seems very close, but I still find it difficult to figure out what we should write into a <block-equation>'s <equation-number> element and how it should be rendered.

Taking into account how we write such content as authors and what LaTeX would allow, I'd like to suggest an outline which similar users can shoot holes in.

If you want an equation to be numbered, set <equation-number> to any number within delimiters. A cautious author might number consecutive equations (100), (200) etc., so that new ones could be inserted within a topic. These numbers effectively become author-accessible IDs, which can be referenced later. They need not be sequential: sections in draft papers or notes often get moved around.

When the topic is rendered, these provisional numbers will be replaced with a normal, regular sequence, like those for figures and tables. Whatever delimiters the author(s) used, the processor must make them consistent within the root map: () or [] or {}. Number style, i.e. (12), (3.12) or (3-12) will also be imposed at root map level.

A few simple rules should allow the processor to render what the author(s) wanted, e.g.:
- If the first character after the opening delimiter is a digit the processor will replace it and any following digits by a sequential number, leaving any closing non-alphanumeric characters such as '!' or '*'
- …otherwise the delimiter contents are just rendered as seen.
- If there is a character a-h between a digit and a closing delimiter the processor will assume a roman-numbered 'subordinate' sequence and process similar neighbours as e.g. 2.12i, 2.12ii, 2.12iii etc., until an exception ends the sequence.
- If there is a character a-h between a digit and a closing delimiter the processor will assume a letter 'subordinate' sequence and process neighbours like it as e.g. 2.12a, 2.12b, 2.12c etc. until an exception ends the sequence.

I believe (hope) that <equation-number>'s definition allows it to contain a reference, so that a modified variant of equation (2.12) could appear several positions after its parent, e.g. (2.12a) might appear after (2.13) and (2.14).

Does this concept of 'dummy numbering' seem an appropriate way to use <equation-number>?

Pat

[Radu]

Hi Pat,

Oxygen 17.1 has experimental support for DITA 1.3 which can be enabled from the DITA Preferences page.
The DITA 1.3 specs about the equation-number element:

https://www.oxygenxml.com/dita/1.3/spec ... umber.html

In my opinion when someone wants to produce HTML based outputs from DITA content such numbering of figures, tables, equations should be avoided because users may end up on various pages from the HTML help and that numbering has no meaning for them. What is the use for the user to know that a certain equation is the 23'rd equation in the entire publication?

Regards,
Radu

[expatriate]

Hi Radu
Apologies for the (very) late response. This is now a live issue for me again. Thanks very much for taking the related xref-to-equation issue forward as https://github.com/dita-ot/dita-ot/issues/2183.

I see your point, but in STEM-type content equations have no titles. References to them are very often needed and are usually styled as "Eq. (3.2)", "Equation (3.2)"or similarly. Students use our DITA teaching materials both as PDFs (for in-lecture annotation) and as webhelps (for queries etc.). It's really important that equation-blocks in both formats have the same equation numbers.

Cheers
Pat

[Radu]

Hi Pat,

Thanks for the extra details.
Unfortunately I do not have a solution for you right now. Even if the GitHub issue were to be fixed, the equation numbering would be reset for each topic from which HTML is obtained, so for each produced HTML document the countering would being again with 0, 1, etc... instead of continuing. With the current architecture of the publishing engine this is quite hard to fix, if at some point we come up with a solution for this we'll update this forum thread.

Regards,
Radu

[Patrik]

FYI: I just updated my DITA-OT-Plugin https://github.com/dita-semia/org.dita-semia.topic-num to handle equations as well. So it will add consecutive numbers to their title and to the cross reference.

Patrik

[Radu]

Hi Patrik,

I looked a little bit at the implementation, interesting idea, we might at some point try to add such a behavior by default to the generated WebHelp output.

Regards,
Radu