Writing a single card

A card source file looks almost like a HTML file. The main difference is that a card neither contains a head section, nor any of the surrounding doctype, html or body tags. All of these will be automatically created. As another special feature, a card usually contains some special non HTML tags which are interpreted by our tools. I tried to choose names unlikely to be ever used as regular HTML tags.

Currently, the syntax used by our pseudo tags is mainly intended to allow a trivial parser, of course this implies small complications for you as an author. We expect each pseudo tag to start on its own line, and most of the tags need a single line all for themself. The exceptions to this rule will be explicitely stated.

Possibly the easiest way to understand our card files is to look at the examples provided in the examples directory in the mcards source tarball. These examples are installed in the documentation directory /usr/share/doc/packages/mcards.

The pseudo tags

We are going to discuss all supported pseudo tags. As already mentioned, each of these pseudo tags should start on its own line.

The admin tag

This pseudo tag uses the following general format.

<admin class=type>argument</admin>

Generally, these tags are used for editorial data. The class type may be chosen from the following list.

class Meaning
rcs Argument is some kind of version string for this source file. When using rcs(1), you may use the keyword substitutions performed by co(1), for example

<admin class=rcs>$Id$</admin>
author Here, argument specifies the author of this card.
title Argument should be a short string used in the logo at the top of each card.
height This is the height used for the title string specified with class=title. Usually, you just omit this tag and a default will be used.
subtitle Sometimes, there is not enough space for a meaningfull title in the logo at the top of our card. In these cases, you may use the class=subtitle option to specify a long title. Of course, this long title string is the string argument.
keys Arguments is a comma separated list of keywords associated with this card. These keywords are currently not used, but you should specify them, anyway.

The mathlink tag

This tag uses the following format.

<mathlink ref=card>text</mathlink>

These tags are used to give some references to closely related topics. The argument text describes the topic which is referenced by this link. The first argument, card, is the name of another card in this topic. No .html extension is used for card. A simple example is a line like

<mathlink ref=projective>Projective planes</mathlink>

The seealso tag

These tags are handled exactly like the mathlink tag above. The links specified with a seealso tag are listed at the very end of a card.

The latex tag

The latex tag is used to include formulas in a HTML document. There are three distinct types of this command.

<latex>formula</latex>[trailing stuff]
<latex display>formula</latex> [trailing stuff]
<latex top=n>formula</latex> [trailing stuff]

In all of these three formats, you are allowed to continue the line starting with the latex tag. This is usefull to add punctuation characters after a formula. Of course, in each case the argument formula is the formula to be inserted in your text. This formula uses LaTeX math mode, but you must not surround it by '$' signs.

It is possible that the completed image will not adjust with the baseline of the current text. In these cases, the option top=n inserts n pixels of white space above the image. Effectively, this moves the image n pixels down. You will have to experiment until the formula fits on the line.

Finally, the option display of the latex tag marks the formula as a display type formula, i.e. it will be typeset similar to formulas enclosed in \[ ... \] in LaTeX.

The cache tag

The tag cache is similar to the latex tag. Assume you are using some formula over and over again, then we will happily create the very same image many times. To avoid this effect, you may create the formula in question exactly once, and refer to it using a symbolic name. These symbolic names are assigned in the conf file of the current topic.

Given such a symbolic name symbol, you may use the formula in a card file by the line

<cache>symbol</cache>[trailing text]

As with the latex tag, you are allowed to continue the line after closing the cache tag.

Installing and debugging a card

After writing a new card, lets say foo.html, you usually install the completed card in your HTML tree. The mcards package provides the mkcard(1) command to accomplish this task. Usually, you just execute the command

mkcard -v topic foo.

Here, topic is the topic containing our card foo.html. The option -v produces informational output on the standard output. By default, mkcard(1) assumes you are using the default source tree, but this may be overwritten using the -s option. The created HTML file is tailored to be stored on your HTTP server, but this is somewhat unpractical for debugging purposes.

Maybe you don't make any errors, but we mortal people usually need a second try. I'm using a special debugging directory, in my example /disk/hauke/testing, and write my HTML files into this directory. Moreover, the files in the debugging directory use local file URL's. We use the following command.

mkcard -v -l -d /disk/hauke/testing topic foo

The -l option forces local file URL's and -d specifies the destination directory to use. See the mkcard(1) manual page for an overview of all options accepted by mkcard(1).

Building an entire tree

For convenience, the mkallcards(1) command creates all files in all topics of an entire source tree. Please, see the mkallcards(1) manual page for details.

The command mkhead(1) is used to build the index page for a topic topic. For example, assume your are trying to create an index for a topic called foo contained in the default source directory. The command

mkhead -v foo

combines the file intro/foo.html in your default source directory with a list of all cards in this topic, and builds an overview file foo.html in the toplevel destination directory. All possible options are listed in the mkhead(1) manual page. When using mkallcards(1), it is not necessary to run this command, this is already done by the mkallcards(1) tool.

The documentation directory /usr/share/doc/packages/mcards contains a small shell script sitedaily, which may be used as an example for using these commands.

Broken links

By default, the mkcard(1) command ignores all mathlink and seealso links pointing to a not existing card. This behaviour is sometimes slightly unpractical. For example, I don't write new cards at regular intervals, but only from time to time, usually one card any few days. In particular, I link to cards which may not exist for some time to come. Nevertheless, I like to see even the links to non existent cards, hence mkcard(1) and mkallcards(1) accept a -f option to include broken links.

Unfortunately, I don't write my cards in an organized fashion, and usually don't know exactly which cards are currently missing. The lstbroken(1) command is intended to help in these situations. For example, the command

lstbroken geometry projective

looks at the card projective.html and searches for broken links in this card. When such a link is found, it will be printed and lstbroken stops. Otherwise, lstbroken reads all cards linked to from projective.html and searches these cards for broken links. Again, if something was found, it will be printed and lstbroken stops. This process continues until we found a broken link, or there are no new cards to read. Please, see the lstbroken(1) manual page for the possible options.

There are two distinct kinds of broken links in one of our topic source trees. First, there are mathlink or seealso tags pointing to a non existing card, as already described. Second, the HTML text may use a tags using such a non existing card. Our default behaviour is to ignore the first kind of links, and pass the second kind unmodified to the output file.

Mkcard(1) accepts two options two modify the default. First, the already mentioned -f includes all broken links in mathlink and seealso tags. The second option -b replaces both kinds of broken links with a link to a special catch-all file, displaying an error message. Note that this requires to rebuild some old cards after creating a new card.

The -b option of mkallcards(1) passes -b to mkcard(1) and rebuilds all old cards who need this.