OASIS Darwin Information Typing Architecture (DITA) TC

 View Only

Proposed Enhancement to The Equation Domain

  • 1.  Proposed Enhancement to The Equation Domain

    Posted 02-05-2014 15:58
    I've been communicating with Dr Patrick Leevers, a professor of engineering at Imperial College London, about the new MathML and equation domains. Dr. Leevers is working on using DITA as the source for STEM course materials, so of course mathematics is extremely important. The feedback I got from Dr. Leevers is that in mathematical writing the decision to display an equation that is within prose as block or inline and, for block equations, whether or not to number an equation, is a per-equation-instance decision made by the author. He pointed me to these dicsussions: > This discussion about equations and punctuation is good, especially the > first and last responses: > > http://english.stackexchange.com/questions/31124/should-there-be-a-period- > after-an-equation > The question of equation numbering enters here: > > http://english.stackexchange.com/questions/22535/do-mathematical-equations >-require-punctuation > and it takes us to the ultimate authority Knuth (who invented TeX) at > http://tex.loria.fr/typographie/mathwriting.pdf > who on p4, p7 etc. does punctuation-and-numbers stuff. Dr. Leevers' feedback is also consistent with work I've been doing recently for a client that is using DITA to represent scientific journal articles, some with many equations--we ran into just these same issues around equation flow within paragraphs, capturing and rendering text around block equations, and capturing and rendering equation numbers. The challenge revolves around how to display and whether to number equations that are part of a larger sentence. For example, say I have this sentence: "The amount of energy in a given unit of mass can be determined by the equation E = mc^^2, where E is the energy, m is the mass, and c is the speed of light in a vacuum." The equation "E = mc^^2" is part of the sentence grammatically and rhetorically. However, the author could choose to render the sentence like this: "The amount of energy in a given unit of mass can be determined by the equation E = mc^^2, where E is the energy, m is the mass, and c is the speed of light in a vacuum." Note the "," after the equation--this reflects that the sentence is still a single sentence despite the block display of the equation. If the author needs to refer to that equation they may decide to add an equation number: "The amount of energy in a given unit of mass can be determined by the equation E = mc^^2, (1) where E is the energy, m is the mass, and c is the speed of light in a vacuum." This way of using equations has several implications for the current design of the equation domain: 1. The block/inline distinction intended by the <equation-block> and <equation-inline> elements is not useful in this context: in all three of the cases above, the only correct element type is <equation-inline> (a specialization of <ph>) because in all three cases the content is a sentence within a paragraph, e.g.: <p>"The amount of energy in a given unit of mass can be determined by the equation <equation-inline>E = mc^^2</equation-inline>, where E is the energy, m is the mass, and c is the speed of light in a vacuum.</p> 2. Because numbering can be on a per-instance basis, and because those numbers may be completely arbitrary, there needs to be an element specifically for specifying the equation number that can be put inside the equation container, e.g. <equation-number>. 3. Because numbering is on a per-instance basis, using <equation-figure> in place of <equation-inline> simply to trigger numbering is not really realistic. For one reason, while <fig> is allowed in <p>, it's not allowed in all contexts where <ph> is also allowed (for obvious reasons), so equation-figure and equation-inline can't be used interchangeably in the general case. This all leads me to suggest the following refinements to the current equation domain design: 1. Define the following values to be used in @outputclass on <equation-inline>: - block/inline: Indicates whether the equation should be rendered as block or inline, with inline being the default rendering if no value is specified. - block-numbered: Indicates that the equation should be rendered as a numbered block equation with the number to be generated if not specified explicitly (the normal case). - inline-numbered: Indicates that the equation should be rendered as a numbered inline equation with the number to be generated if not specified explicitly (the normal case). This may be a rare case but is included for symmetry at least. I'm using "compound" values here rather than multiple keywords to make authoring easier: tools that support using subjectScheme to define attribute values don't always support setting multiple keywords (and such support requires a more complicated user interface than just a simple dropdown list). 2. Define the new element <equation-number>, specialized from <ph> and allowed within <equation-block>, <equation-inline>, and <equation-figure> . The content of the equation number is the equation number and is used in place of any number that might be generated. Cheers, Eliot -- Eliot Kimber Senior Solutions Architect "Bringing Strategy, Content, and Technology Together" Main: 512.554.9368 www.reallysi.com www.rsuitecms.com