This is the mail archive of the
docbook@lists.oasis-open.org
mailing list for the DocBook project.
[docbook] Re: equations
- From: Doug du Boulay <ddb at owari dot msl dot titech dot ac dot jp>
- To: Norman Walsh <ndw at nwalsh dot com>
- Cc: docbook at lists dot oasis-open dot org
- Date: Sat, 5 Feb 2005 18:27:54 +0900 (JST)
- Subject: [docbook] Re: equations
On Thursday 03 February 2005 07:33, Norman Walsh wrote:
> / Doug du Boulay <ddb@owari.msl.titech.ac.jp> was heard to say:
> | Norman Walsh <ndw@nwalsh.com> wrote:
> |> DocBook NG still has both the formal and informal versions.
> |>
> |> The odd man out in all this is equation which, for backwards
> |> compatibility reasons in DocBook *4* still has an *optional* title,
> |> even though there's also an informalequation element. I see two
> |> possible ways forward:
> |>
> |> 1. Keep the formal/informal distinction and make title on equation
> |> required. (This is what I've actually done in DocBook NG.)
> |>
> |> 2. Drop the distinction, drop
informal{equation,table,example,figure}
> |> and make title on all those elements optional.
> |>
> |> Option 1 is probably easier for users and for tools, so I'm inclined
> |> to go that way at the moment. The only advantage to option 2, really,
> |> is that DocBook becomes four elements smaller. But the semantic
> |> disjunction is probably too high a price to pay.
> |
> | For the record, even though many equations do actually have names,
> | in the scientific literature I think you will find exactly zero
instances
> | of titles on equations (for that matter there would be no TOC equation
> | lists iether). For this reason IMHO option 1 would actually be a
> | backwards step hindering the adoption of DocBook amongst a broader
> | community.
>
> Hmm. So requiring title on equation is likely to be controversial :-)
>
> | Customarily equation blocks fall into two classes, these being
> | numerically labelled and unlabelled equations. The existing equation
and
> | informalequation elements provide a useful method for distinguishing
> | between those cases and my hope is that they could be retained.
>
> Ah, so you use
>
> <equation>
> equation content
> </equation>
>
> (without a title) for equations that should be labeled with a number
> and
>
> <informalequation>
> equation content
> </informalequation>
>
> for ones that shouldn't be numbered?
yep. In my experiments, I also used the "role" attribute on both of those
as a means of identifying when some sequences of labelled and
unlabelled eautions should maintain some semblance of horizontal
alignment.
> | Its a shame there isn't a third option:
> |
> | 3. The equation element be shifted out from the formal list into
> | a group of its own, because in reality it has a completely
> | different usage model.
>
> Voila! A third option :-)
If it really *is* a viable option, IMHO, retaining backward compatability
would be best. I have actually encountered some online docbook docs that
had
titles on their equations, presumably written by authors keeping an eye
to the future where titles were slated to be compulsory in version 5 in
"The Definitive Guide".
But scientific documents tend to use mathematics as a tool to demonstrate
why and wherefore relationships, and in that use extraneous titles
interrupt the flow of ideas.
Other styles of documentation might treat equations more like curious
pictures to look at, in which case titles could be useful but perhaps the
whole block would be better treated as a <figure> element?
(dunno. no experience)
> | Alternatively, if option 2 was adopted could some other standardised
> | means be established to discriminate between labelled and unlabelled
> | equation blocks?
>
> Yes, let's forget the informal/formal distinction for equations.
>
> How would you suggest distinguishing between labeled and unlabeled
> equations?
For labelled equations there are a few different approaches I guess.
(1) The label can be determined automagically from its sequence
within the document/chapter and displayed and crossreferenced
uniformly in the output rendering via the stylesheet transformations.
(2) an explicitly specified label could be embedded within the actual
encoded math content and rendered into the mediaobject or mathML but
it would thereby remain inaccessible to the DocBook stylesheets for
consistent crossreferencing. Insertion of new labelled
equations into the document would likely screw up embedded sequential
labelling schemes.
(3) Tentatively, the label from (1) could be automatically inserted into
the actual encoded math content of (2), leaving the presentation
of the label to the math renderer.
Possibly (3) is best but difficult to implement, (2) has huge scope
for confusion but I guess is what most folk are actually doing? Manually
relabelling would be ludicrous for large documents undergoing review. (1)
is something which seems to work but has some a few drawbacks.
The examples below are encoded using latex math, because its
compact and easy to edit by hand. IIRC the OpenMath crowd can convert
latex math to MathML through some process, iff it is written in the right
style, but I haven't investigated that thoroughly.
In my experience, equation labelling on the right hand side seems to
predominate in hardcopy books, but for online docs that potentially extend
beyond the browser screen, labels on the left would be easier to identify.
Unfortunately, as in example (iv) and (v), it looks a bit incongruous.
Example(i)
Mostly you just want a nicely centred equation and a label
IDEAL
a=b+c (1.1)
MARKUP
<equation label="yes" id="E-1">
<alt role="tex">\[a=b+c\] </alt>
</equation>
(hate to think what the equivalent two pages of MathML looks like)
rendered as
RESULT
(1.1) a=b+c
where for html, an <xref linkend="E-1"> results in <a
href="#E-1">(1.1)</a>
Example (ii)
Often an equation should be annotated with inline text
and inlineequation fragments
IDEAL
i.e. a=b+c where b and c are unknown. (1.2)
(a)
MARKUP
<equation label="yes">
<alt role="tex">\[ \text{i.e.}\qquad a=b+c
\qquad \text{where $b$ and $c$ are unknown.} \] </alt>
</equation>
this would work.
or (b)
MARKUP
<equation label="yes">
i.e.
<alt role="tex">\[a=b+c\] </alt>
where <inlineequation><alt role="tex">\(b\)</alt> and
<inlineequation><alt role="tex">\(c\)</alt> are unknown.
</equation>
this wouldn't, but it could ultimately be more consistent.
Example (iii)
There are some instances where two , or more?
large equations are placed on one, possibly labelled or
unlabelled line which includes some in between text:
IDEAL
Variance s^2= Sum (x-<x>)^2/ n where <x>=Sum x/ n (1.3)
(a) MARKUP
<equation label="yes">
Variance
<alt role="tex">\[s_x^2=\frac{\sum_{i=1}^n(x_i-<x>)^2}{n}\]
</alt>
where
<alt role="tex">\[<x>=\frac{\sum_{i=1}^n x_i}{n}\]</alt>
and
<inlineequation><alt role="tex">x</alt><inlineequation>
is an observation
</equation>
nope. that doesn't work iether, but for consistency of para text
it would be nicer if it could.
(b) MARKUP
<equation label="yes">
<alt role="tex">\[\text{Variance}\qqaud
s_x^2=\frac{\sum_{i=1}^n(x_i-<x>)^2}{n}
\qquad \text{where} \qquad
<x>=\frac{\sum_{i=1}^n x_i}{n}
\text {and $x$ is an observation.}
</alt><inlineequation>
</equation>
this would probably work.
Example (iv)
And occasionally you have some small set of related equations and labels
IDEAL
a=b+c (1.4a)
b=d+e for d>200 and e unknown. (1.4b)
(a)
MARKUP
<equation label="yes" id="myEq3">
<alt role="tex">\begin{align}a &= b+c \tag{a}\\
b &= d + e \qquad \text{for $d>200$ and $e$
unknown.}\tag{b}
\end{align}
</alt>
</equation>
The & marks work as horizontal alignment boundaries and the
trailing "\\" on a line is an equation newline.
Possibly <xref linkend="myEq3" linkterm="a"> might be renderable as (1.4a)
also the latex \tag{a} might be a bad thing to use in general but perhaps
some better alternative exists ...?
RESULT
a=b+c (a)
(1.4)
b=d+e for d>200 and e unknown. (b)
But in this case the \text{} would likely be in a different font to
surrounding paras, which looks bad.
(b)MARKUP
<equation label="yes" id="myEq3">
<alt role="tex">\begin{align}a &= b+c \tag{a}\\
b &= d + e
</alt>
for <inlineequation><alt role="tex">\(d>200\)</alt> and
<inlineequation><alt role="tex">\(e\)</alt>unknown.
<alt role="tex"> \tag{b} \end{align} </alt>
</equation>
This could look nicer, but I can't see how it would work in practice
though.
Example (v)
Very rarely you might encounter "case" statements
like this:
IDEAL
{ -x^2, if x<0; (1.5a)
f(x) = { alpha+x, if 0<=x<=1; (1.5b)
{ x^2, otherwise. (1.5c)
MARKUP
<equation label="yes">
<alt role="tex">\[
f(x)=
\begin{cases}
-x^{2}, \&\text{if} x < 0; \tag{a}\\
\alpha +x, \&\text{if} 0\leq 1; \tag{b}\\
x^{2}, \&\text{otherwise.} \tag{c}
\end{cases}
\]</alt>
</equation>
RESULT
{ -x^2, if x<0; (a)
(1.5) f(x) = { alpha+x, if 0<=x<=1; (b)
{ x^2, otherwise. (c)
again problems with fonts in the \text{}
Example (vi)
In some instances all you want is some semblance of order between
the various important and inconsequential steps of a derivation
IDEAL
a=b+c (1.6)
=(d+e) + 2 pi sqrt(d)
= f + Integral(g) dx
= 42 (1.7)
(a)MARKUP, assuming Norm's option (2)
<equation label="yes" role="cont">
<alt role="tex">\begin{align}a &=b+c \\</alt>
</equation>
<equation role="cont"> <!-- no labels here! -->
<alt role="tex"> & = (d+e) + 2 \pi \sqrt(d)\\
& = f + \int{g dx} \\
</alt>
</equation>
<equation label="yes" role="terminal">
<alt role="tex"> &=42
\end{align}
</alt>
</equation>
yep three distinct equation elements there.
(b) MARKUP, assuming option (3)
<equation role="cont">
<alt role="tex">\begin{align}a &=b+c \\</alt>
</equation>
<informalequation role="cont"> <!-- no labels here! -->
<alt role="tex"> & = (d+e) + 2 \pi \sqrt(d)\\
& = f + \int{g dx} \\
</alt>
</informalequation>
<equation role="terminal">
<alt role="tex"> &=42
\end{align}
</alt>
</equation>
(I have a html xsl customization which seems to work with this
for html output and dvi2bitmap. It automatically generates the label
and imagefilename)
Not much to choose between those last two MARKUP cases really.
Both would work ok.
For option (2) I am not sure if there is any scope for having an extra
attribute sublabel="a b c", or somesuch as a future sublabelling
mechanism for automatic insertion in the latex \tag{} or its equivalent.
Just to confuse the issue, for latex markup a \label{} is analogous to a
named unique xml id="" attribute and doesn't appear in the text, whereas a
\tag{} apparently sets an explicit unique \label{}/id and also replaces
the numeric label.
Possibly, for completeness, there should be an attribute for
explicit non-numeric labelling of <equation/> elements also?
And no doubt there are problems with all this for the dblatex pdf/ps
output folk who might be doing all equation labelling in pure tex within
the <alt role="tex"/> stuff. Maybe everything just works for them. I don't
know.
How are equations done with FO, purely using mediaobjects?
Does MathML support equation labelling?
better ideas?
help!
best regards
Doug
P.S. sorry about the broken list thread.