compiled by David Farmer from suggestions by several people
This page describes various issues that arise when converting a source document (our examples come from MathBook XML) to multiple formats. Each example will illustrate the point that source which converts properly to one format may fail to convert properly to a second format. And, adjusting the source to accommodate the second format may break the conversion to the first.
The underlying causes seem to be shortcomings in HTML, MathJax, (La)TeX, or XSL.
In this document we use the word "wrong" to describe markup which:
Once this list is expanded to include more examples, an approach to resolving these issues will be proposed.
Consider:
If <m>x \lt 3</m>, then <m>x^2 \lt 9</m>. The converse is not true in general.
What is wrong?
In the HTML version, punctuation following math mode may appear on the following line. That is rare because punctuation is so small, but it can happen.
Possible alternative: The HTML will look okay if the source is
If <m>x \lt 3\text{,}</m> then <m>x^2 \lt 9\text{.}</m> The converse is not true in general.
However, that fails all three possibilities of wrong.
Note: for display math, recent discussion about multiline formulas suggested that the MBX source should have the punctuation after the closing <mX> tag. That makes sense semantically, but seems to suffer from its own set of concerns.
Brian Walton pointed out that the same issue can arise with pubctuation before math mode, as in
blah blah blah (<m>0 \lt x \lt 3</m>) blah blah blah
Analysis: Seems to arise from issues with HTML and MathJax.
Consider
<theorem><title>Euler's <m>\zeta(2)</m> identity</title>
<statement>
<p>We have
<md>
\sum_{n=1}^\infty \frac{1}{n^2} = \frac{\pi^2}{6}
</md>.
</p>
</statement>
</theorem>
What is wrong?
When a theorem (or exercise or ...) only contains one paragraph, then why do I have to wrap it in a <statement>? Isn't it obvious that the only thing there is the statement of the theorem?
Analysis: Having optional <statement> wrappers is likely to be added as a feature of MBX, so this example may not actually belong on this list. There would need to be a discussion about whether or not the <statement> can be inferred in the presence of an introduction/proof/solution/conclusion.
Thankfully, index entries such as <index>excessive markup</index> are now interpreted as <index><main>excessive markup</main></index>. But why can't I use LaTeX-style syntax for sub-entries and have
<index>markup!excessive</index>interpreted as
<index><main>markup</main><sub>excessive</sub></index> ?
What can go wrong?
The interpretation of the "!" needs to be somewhat clever, because there may be an index entry about the factorial function, or about the '80s pop group Wham!. But if there is a letter on either side of the exclamation point then it is reasonable to interpret it as a sub index entry. (If necessary, you can wrap it in <main> to avoid the automatic conversion.)
Analysis: The official MBX markup for index entries is likely to get simplified, but probably not to the extent suggested above.
Consider the following paragraph from Applied Combinatorics by Keller and Trotter, with the source reorganized the way some people prefer:
<p> You likely have already been introduced to optimization problems, as calculus students around the world are familiar with the plight of farmers trying to fence the largest area of land given a certain amount of fence, or people needing to cross rivers downstream from their current location who must decide where they should cross based on the speed at which they can run and swim. However, these problems are inherently continuous. In theory, you can cross the river at any point you want, even if it were irrational. (OK, so not exactly irrational, but a good decimal approximation.) In this course, we will examine a few optimization problems that are not continuous, as only integer values for the variables will make sense. It turns out that many of these problems are very hard to solve in general. </p>
Notable aspects of that paragraph are that everything is indented, a new line starts after every sentence, often after a comma, and at other places so as to keep the lines to a reasonable length.
There is a relevant XKCD comic.
What is wrong?
The white space after the opening <p> tag, and the carriage returns within the paragraph, can cause problems with some of the conversions to other formats. Similar issues may be in the theorem in Example 2.
In terms of taking less effort to edit, such an arrangement of lines in a paragraph is better than one long line. Perhaps you use an editor that wraps long lines, so you don't see the advantage of hard-coded line feeds? But there is a significant advantage. Since a common editing step is to delete or move an entire sentence (or phrase in a sentence), an arrangement as above makes that faster. That is, grabbing consecutive physical lines is faster and requires less careful pointing with the mouse than having to carefully click from the beginning to the end of a random block of text. (It is also faster than navigating to the beginning of the sentence and then using a feature of the editor to select a sentence.) Maybe there is a start-up cost to learning a new source layout, but in the long run it pays off.
Also, with the above layout the most common edits will be easy to see in a pull request on GitHub.
It is up to each individual to decide whether to insert carriage returns into source paragraphs. But it is not reasonable to tell other people that they are prohibited from making use of that approach. (Or, if you expect people to change how they write, then the advantages better be pretty outrageous, and you also better give them a good explanation for why those restrictions are unavoidable. MBX is pretty outrageous, but that won't stop people from objecting to restrictions they don't understand.)
Analysis: It is looking more likely that a purely XSL solution may allow flexibility in the use of carriage returns. A recent posting addressed similar issues in the context of <md> and <mrow>.
Consider
Use the chain rule to differentiate <m>f(e^{x^2})</m> and <m>g\left(\frac{1}{x}\right)</m>.
What is wrong?
When typeset, both will look bad, but for different reasons. The first needs larger parentheses because the argument of the function is large. The second has larger parentheses, but those parentheses have an improper amount of extra space around them. If you don't see the extra space in the typeset version, keep staring at it until you do.
Possible alternative: A way to obtain the correct appearance is
<m>g\mathopen{}\left(\frac{1}{x}\right)\mathclose{}</m>
but writing all that is wrong because it puts an excessive burden on the author.
The underlying problem is that parentheses for implied multiplication are mathematically different objects than parentheses enclosing the argument of a function. (La)TeX fails to provide an easy way to make that distinction.
One possibility is to introduce a macro "\fa", meaning "function apply", which takes two arguments, as in <m>\fa{f}{e^{x^2}}</m> and <m>\fa{g}{\frac{1}{c}}</m>. This could be considered semantic, and the definition of the \fa macro can include the markup which makes everything look right. But it seems like a tall order to get everyone to agree to write it that way, even though it is probably true that "it becomes natural after you get used to it" and "it actually is less typing than repeatedly writing \left and \right".
Analysis: Seems to be a fundamental issue with (La)TeX.
Some of the built-in problems with TeX include:
Suggested by Alex Jordan. Below is an abbreviated account of a complicated topic which has been previously discussed.
Consider a set described by set builder notation. Also assume that the "such that" symbol is a vertical line instead of a colon. (There are many good reasons for that choice. For now just accept that option.) Let's start here:
<md>
A = \{f\in \C[x] | \int_0^1 f(x) dx = 0 \}
</md>
There are numerous ways in which the above is wrong. The keyboard symbol "|" is not the correct separator, because it is not a binary operator and so will not have the necessary extra space around it. For the exact same reason, \vert is wrong. A reasonable option is \mid, which automatically gets the extra space.
But (you knew there was a 'but') if you correctly put \left and \right before the curly brackets (necessary because the condition on f(x) is very tall), then the \mid will still be small.
LaTeX has a \middle to go with the \left and \right, which can be used to make the "such that" symbol large. But (this is not even the last 'but'), the \mid operator is not a delimiter, so it cannot be the target of a \middle. You need to use \vert, which is a delimiter and can grow, but then you also need to directly hard-code extra space on either side of the \vert. It is wrong to put that extra space in the source. A reasonable option is to make a new macro, such as \st (short for "such that"), which contains that markup in its definition.
But (this is the final 'but' in this example), if you put \middle in the definition of your \st, then you are forced to use \left and \right every time, which is wrong. So it looks like you need two versions of the "such that" macro, which seems confusing.
Another option is to define a macro which takes two arguments: the part before the "such that" and the part after. That has similar costs and benefits to the \fa macro of the previous example.
Note: FCLA has a \set macro that takes one argument and wraps it in curly brackets, and a \setparts macro that takes two arguments.
Analysis: \set and \setparts have a better chance than \fa of becoming standard, but it seems that inherent properties of (La)TeX prevent the source from being written in a natural way.
This example is from Alex Jordan.
You have a picture that contains text. For example, a simple model of a water molecule, with words labeling the oxygen and hydrogen atoms.
What is wrong?
How do you make it so that the overall image will be the size you want it to be, while also making the text the size you want it to be (for the sake of simplicity, suppose you want it to inherit the size of the ambient paragraph text).
What image making tool to use? Once you laboriously tweak things in your image- making, using say width=50% on the image, can you be free to later make it width=100% without making the text any bigger?
Or, with the image width=50%, how do you make it so that a web browser user can change their default font size (Zoom Text Only) and have that affect the text in the image too, but leave the image itself at 50%?
Analysis: MathJax matches the size of the surrounding text, so something along these lines is already happening.
If the image is SVG, and the words are text in the SVG (possibly with some CSS class), then the source will have enough structure that in principle it should be possible to scale the text separately from the image.
This example is from Rob Beezer.
A side-by-side has "panels" organized horizontally. You can specify their widths as percentages (in flexible ways) and then margins and spacing are computed automatically, with a couple of options.
An image placed in a panel is scaled to fit the width. This will exhibit Alex's example. But tables are worse (before and after this past summer's refactor).
The table is not scaled, so there is no coordination between the width of the panel and the width of the table. So the panel width is a bit of a fiction, and the table can easily run off the right side of the panel.
I did find some ways to scale a table to a specific width, but now the text of the table will shrink/grow to appear different than the surrounding text (like text on images). And we know for large factors, scaling fonts linearly is not optimal.