Equations in QTML

Carl Milsted, Jr on Sep 11 17:37:26

View QTML

Here's a quick tutorial to get you started writing equations in QTML. Let's dive in with a simple example, Albert Einstein's famous equation relating mass and energy:

To typeset the equation above, I typed in the following code:

.eqn 1
e = m c sup 2
..eqn

The eqn QTML tag begins a display equation. For an inline equation, such as$e=m{c}^2$ , use the eqni tag. The eqn tag takes an optional argument which is the equation number or label. Notice the 1 that shows up to the right of the equation above. In between the QTML tags, you describe your equation in the venerable eqn language developed by Brian Kernighan and Lorinda Cherry back in the 1970s for the UNIX operating system.

Behind the scenes, the Conntects QTML converter sends your equations to the GNU version of eqn, with flags to generate MathML, the HTML standard for displaying equations. For some email clients, such as Thunderbird, you can copy the MathML generated here on Conntects and send equations to your friends. Alas, some email clients such as gmail and yahoo mail do not render MathML correctly—yet.

A Quick Tour of Eqn

The eqn language is well documented in Typesetting Mathematics—User's Guide (Second Edition) by Kernighan and Cherry. There are some differences between GNU eqn and what is described in this document, including a couple of bugs, alas.

So, let's begin the quick tour to get you hooked, and then you can look at the linked document if you want to get fancy.

Looking back at equation 1, the equation was typed in just as you would do intuitively, save that I used the sup keyword to create a superscript. Baby stuff! And if you need subscripts, just use the sub keyword.

For our next keyword, let's drop back to Newton's formula for kinetic energy:

Which was made with:

.eqn 2
e = 1 over 2 m v sup 2
..eqn

To make upright fractions, just use the over keyword.

Let's make a fancier fraction:

.eqn 3
v sub x = { DELTA x } over { DELTA t }
..eqn

Not only did we get to use a subscript to denote the $x$ component of the velocity, we have multiple symbols on the top and bottom of the fraction. To group symbols together for any operator, use curly braces. Finally, we get our first taste of Greek letters. To make a capital Greek delta, spell out DELTA in all capitals. For a small delta, just use the word delta. Likewise for any other Greek letter.

Caution: if there is a Roman letter which is identical in appearance to a Greek letter, use the Roman letter. For example

.eqn
ALPHA RHO
..eqn

Gives:

which is probably not what you want. (Actually, this worked better than expected. In old UNIX I would have gotten ALPHA RHO instead of A R. But the GNU eqn is wrong above! The capital Greek rho should look like a Roman P!)

Let's get a wee bit fancier and do the Quadratic Formula:

.eqn 5
x = {- b +- sqrt {b sup 2 - 4 a c}} over {2 a}
..eqn

To get a square root sign, use the keyword sqrt .For other roots, use fractional powers. To my knowledge, there is no way to use the radical symbol to do cube roots and whatnot.

Let's move on to power series:

.eqn 6
sum from {i=1} to inf left ( 1 over 2 right ) sup i = 1
..eqn

We have the new sum keyword for summation, inf for infinity, and the all important left and right keywords. The latter two make parentheses grow big enough to enclose the expression they contain. These keywords can also be used for square brackets, curly braces, vertical lines and more. In fact, to make curly braces visible, you have to use left or right.

The from and to keywords work for products, integrals, and more. For example:

.eqn 7
int from 0 to 1 x sup 2 dx = 
left [ x sup 3 over 3 right ] sub 0 sup 1
..eqn

Decorating Your Variables

Mere letters are not sufficient to denote vector quantities. There are two conventions. The first is to put an arrow over vector quantities.

.eqn 8
F vec = m a vec
..eqn

The second is to make vector quantities bold:

.eqn 9
bold F = m bold a
..eqn

I prefer the latter, as it leaves room for other decorations:

.eqn 10
bold PI sub e = bold PI tilde sub e e sup {i k z}
..eqn

Macros

If you go wild with decorated variables in a long post, it's nice to take some shortcuts. For this purpose there is the define statement. For example, I could have rewritten the previous equation thusly.

.eqn 11
define Pve bold PI sub e
define Pvet bold PI tilde sub e

Pve = Pvet e sup {i k z}
..eqn

So far, this has bought me nothing. But here's the deal: defines carry over to subsequent equations in the same post or comment! For example:

.eqn 12
phi = - del cdot epsilon Pve
..eqn

A long time ago in a state far far away, I made extensive use of such defines in order to typeset my doctoral dissertation.

Piles and Columns

It's time to get really fancy:

.eqn 13
roman {Let}~ y~ = 
left {
lpile{ 1 above 0 } 
~~~lpile { if~x > 2 above if ~ x <=2}
right "   "
..eqn

We have several new things to deal with. First the roman keyword renders to next block of characters in a Roman font. Tildes [things thingies: ~~~] act as spacers. (If you want a half space use a circumflex [^].)

The pile stacks things over each other with the above keyword as a separator. This is a family of keywords with lpile for left justified piles, pile for centered piles and rpile for right justified piles.

Finally, note how I used a left brace without a matching right brace. According to the original eqn specification, a left does not need a corresponding right . But with the GNU version of eqn, I get a big ugly NULL on the right if I don't have a corresponding right something. I eventually got the above to work by using multiple blanks inside quotes for the closing right. This is one place where the freeware hasn't caught up with the original product. (Another place is a bug where the approx keyword does not render the approximately equal symbol like it should.)

I could go on to describe how to use piles and braces to build column vectors and matrices, but I'm getting tired, and I've either got your interest going or I haven't. If I have gotten your interest going, look at the old official manual for eqn. It's only eleven pages. Print it out if you are serious about writing equations.

The Future

The eqn language does not have nearly as many symbols at LaTeX. And there are probably some other important limitations. I haven't used LaTeX in three decades, so I am more than rusty on the subject.

If Conntects becomes profitable and the more critical parts of the system become sufficiently stable, I'd like to extend the GNU version of eqn to include the symbols available in TeX. Given how MathML works, this shouldn't be too terribly hard.

Or better yet, I could hire someone else to do this job.

TeX is powerful, but having to type backslashes before every keyword drove me batty back in the day. (And since I was running TeX on an Atari 1040 ST, I ended up writing my own terminate and stay resident text editor that fit in 100K of RAM. Said text editor used control-K for the backslash to cut down on pinky gymnastics, and I had multiple copy and past buffers so I could avoid retyping the more common TeX keywords.)

So enjoy eqn. It fits nicely into the Easy to Type philosophy of QTML. (Or to be more precise, QTML was inspired by the Easy to Type philosophy of troff, and UNIX in general.)

Tags: equations QTML