[Haskell-cafe] Haddock Markup

[Richard O'Keefe]

On 12 Feb 2009, at 8:48 pm, Wolfgang Jeltsch wrote:
>
> I don’t understand this. The way which works is conversion from  
> MathML to TeX.
> So your suggestion would be to use MathML as the source language.  
> But this is
> obviously not what you suggest. I’m confused.

It's explicit enough in the original message:
	Use "a substantial chunk of MathML"
	in "a TeX-parseable syntax".

>
> If you want to use a subset of TeX in Haddock comments, how would  
> you render them on a webpage?

I didn't say "a subset of TeX" but a subset of >>MathML<<.

MathML is two things: a set of labelled trees with some sort
of semantics, and a representation of those trees as XML.
Anything that can be written as
	<X a="b">...</X>
can also be written as
	\X[b]{...}
with a reasonable amount of care.  (Not necessarily the same X and b,
of course, and ... would be recursively transformed.)

Let's take this example from the web.
<math> <mrow> <msup> <mi>x</mi><mn>2</mn> </msup> <mo>+</mo> <mrow>  
<mn>4</mn><mo>&InvisibleTimes;</mo><mi>x</mi> </mrow> <mo>+</mo>  
<mn>4</mn> </mrow> </math>
Step 1.  Rule that letters c stand for \mi{c} unless otherwise
quoted.  Rule that digit sequences d stand for \mn{d} unless
otherwise quoted.  Rule that normal operators x stand for \mo{x}
unless otherwise quoted.  Rule that x^y stands for
\msup{x}{y}.  Rule that x_y stands for \msub{x}{y}.
Step 2.  Introduce names for (some) things MathML has, like
&InvisibleTimes; and TeX does not.

Step 3.  Write a checker that enforces the conventions.
By step 3, we have the ability to write
\mathml{\mrow{x^2 + \mrow{4\itimes x} + 4}}

and have LaTeX process it directly.  The advantage of this stuff
is that you can put it in your technical papers.  Why bother?
Because of the checker.  (I do not have such a program.  This is
a design sketch on a tablecloth, not to be taken any more seriously
than that.)  Why not use MathML?  (La)TeX macros spring to mind as
a good reason...  Not having to use XML as another.

Step 4.  Based on the checker, write a program to convert this
notation to MathML.  MathML was, after all, designed for machines
to write and read; it is not practical for people to write and it
couldn't be called even remotely readable by its best friend.
That makes it a pretty appalling choice for something to write
in Haddock comments in source files.

By step 4, you have something you can check better than standard
TeX, something you can cut and paste between TeX papers and
Haddock documentation without making the source code unreadable,
and at the same time something that can be converted to MathML
any time you want.
By the way, I wonder very much how much semantics people _are_
putting into their MathML?  The INEX consortium of people doing
XML-based information retrieval have run into the problem that
there is very little semantic markup out there, so for getting
semantics out XML is *in practice as yet* little or no advance
on plain text.  Even with an equation editor, writing formulas
on a computer is enough work that I'd expect people to do the
minimum they need for the immediate taste, even using MathML.
I don't have a body of MathML to examine, so I make no empirical
claim here, I just raise the question.