Introduction

Please, don't take this document too seriously. Basically, it's just an experiment testing the presentation of simple mathematical stuff in HTML. All content should be directly viewable in a graphical browser, hence the usual download of postscript or dvi files does not really fit our goal. Of course, the primary problem is to display mathematical formulas in a HTML document. At some point in the future, this problem will be solved by the emerging MathML standard, but I couldn't find free tools to support this stuff. To be honest, I think Math ML is way too complicated for the pretty basic needs of this document collection.

Consequently, math formulas are simply converted to images, and embedded using the img tag of HTML. The conversion process is similar to the method used by the latex2html(1) tool, i.e. we are using dvips(1) and the netpbm tools. The necessary software is described in a separate document.

In summary, you have to write a source file in a pseudo HTML format, and this file will be converted to a real HTML document. The conversion process preprocesses the source file in question, and creates all image formulas. The source file may be written using the ASCII editor of your choice, for example the one real editor vi(1).

Directory layout

The entire document collection is divided in various sections, called topics. This is somewhat euphemic, in fact there is only one topic, namely geometry but you are free to create entirely new topics. We are using two distinct directory trees, a source tree and a destination tree. The source tree contains all the source files, and the completed HTML documents are written under the destination directory. I think of the single HTML pages as some kind of cards, so we will use this word to denote these files. In addition to the text in the corresponding source file, each card has a heading on top, implemented as a GIF image.

In my case, I don't have direct access to the HTTP server, so I use a directory, let's say /disk/hauke/html, which contains a copy of all files on the server. I update this directory on my local machine, and use sitecopy(1) to transfer the modified or new files to the real server. In fact, this isn't even the real server but the files will be copied from this machine to the true real server, the wonders of paranoia, but i digress. However, I'm using a subdirectory of this local server copy, i.e. /disk/hauke/html/math, as the destination directory. You are not expected to use this scheme too, but you have to choose some destination directory.

Global configuration

You may be specify a source directory with all our tools, but usually, you will just use one single source tree. Hence, it's not really convenient to specify this directory over and over again, and in fact, there is a way to set a default.

There are four different ways to make this work. All of these possibilities are checked in the following order.

  1. If the environment variable MCARDSTREE is set, its value will be used as the path to our default source directory.
  2. If the file .mcards exists in the home directory of the current user, its first line will be used as the name of the default source directory. Either this name begins with a '/' and will be treated as an absolute path, or it begins with a '~', and this first character will be replaced by the path to the home directory of the current user.
  3. If the file /etc/mcards exists, it will be treated like the .mcards file above.
  4. Finally, a compile time constant is used. This constant defaults to /disk/hauke/tree, and may be changed in the Makefile used to build the mcards package.
We are going to describe the source directory. The most important file in the source directory is called conf. This file contains all the global configuration data relating to this source tree. The conf file is read line by line and all empty lines are ignored. Lines beginning with a '#' are comments, and will be ignored, too.

All other lines in the conf file are configuration options. These lines have the general format

keyword arguments

The keyword must begin at the very first character of the line, and it is separated from arguments by one or more space characters. The following keywords are known.

Keyword Meaning
destination This command specifies the destination directory usually used with this source tree. All of our tools accept options to overwrite this value, but you must specify a default destination. Of course, the used directory is argument, and this must be an absolute path.
base This directive is purely optional. The given argument is expected to be an URL, and this URL will be used with the base tag in the HTML code of all documents generated by our tools. Usually, it's a good thing to use this option.

For example, I'm using a common top level directory for all topics on the HTTP server hosting my home page. Hence, I specify

base http://www.math.uni-kiel.de/geometrie/klein/math/

in the conf file, and link to a card called foo under the topic bar with the relative URL "bar/foo.html", for example <a href="bar/foo.html">text</a>.

home This command is another optional directive. Here, argument specifies an URL, usually the absolute address of your home page, and we will arrange for a link back to this URL in each generated card file. For example, I am using the following home command

home http://www.math.uni-kiel.de/geometrie/klein/

Per default, this only works if a base URL is specified. When using home but no base, you must copy the files Home.gif and Main.gif to the images subdirectory of the current topic. If there is also a base URL specified, we will create an additional link back to the index page of the current topic.

mail This command is used to specify a mail address, and we will create a mailto tag in each card using this mail address. As above, we expect a specified base, or copy the file Mail.gif to the images directory.
errors This option is optional. As already mentioned, we will use LaTeX to create formulas in our HTML documents. The latex source files used for this purpose are automatically generated by a programm called latextag(1). Sometimes, latex(1) fails to create any dvi output. Latextag(1) responds to such an event by first printing an error message, and second ignoring the formula in question. The offending latex source file will be removed.

If our conf file contains an errors line, then all failed latex sources and the log files produced by latex(1) are copied to a special directory. The argument to errors controls which directory is used. There are three distinct cases for the value of arguments.

  1. If arguments equals the value "on", then we will use a direct subdirectory of the top level source directory with the name failed.
  2. If arguments does not begins with a '/', then arguments specifies a relative path with respect to the top level source directory. Of course, you can't use the relative path "on", but I can live with that.
  3. Otherwise, arguments is an absolute path to the error directory.
topic These are the most important directives in the conf file. Each of these lines defines one known topic, and the source files belonging to this topic are kept in a subdirectory with the name of the topic. The full line is expected to be of the following type.

topic name word width height delta

Name is the name of the topic defined on this line. The following string word is the word written at the top of each completed card. Usually, this is just the name with a capital first letter. The last three arguments width, height and delta are used to create the card headings for this topic. The string word will be printed in a rectangular array of the given width and height. The delta is the color gradient used in percent.

It is recommend to use the same value for width with all topics in a common source tree.

Special subdirectories

The top level source directory contains some subdirectories containing special purpose source files. Given any topic foo defined in the conf file, we will create an index page which contains an ordered list of links for all the cards in this topic. This index file will be called foo.html, and is placed in the top level destination directory.

Of course, a simple card list isn't a great introduction to the foo topic, so you are expected to provide a static text announcing the glory of foo. This file consists of HTML body stuff only, and you have to use the filename foo.html. All of these files, one for each topic, are collected in a subdirectory called intro.

The directory html contains additional HTML files to be copied to the top level destination directory. This subdirectory isn't mandantory, but usually present. For example, I'm using the html directory for these documentation files. We said the files in html are copied to the destination directory, but this isn't the full story. All files in html have to use the extension .html, otherwise they will be ignored. If a file in html contains a line of the form

<base>

then this line will be replaced with a base tag containing the base URL specified in the conf file. When using this feature, you must put a base line in the conf file.

It is pretty common to use some images in the HTML files in our html directory, and we expect to find these images in the subdirectory images of the source tree. All the files in this directory are copied to a subdirectory images of the destination directory. When using the base feature discussed above, you may simply link to these file using a relative URL like "images/foo.gif".

Some other directories will be created automatically by our tools. Simply ignore these subdirectories, they don't contain any interesting stuff. But, there is a single exception to this rule. The directory failed collects all LaTeX formulas which couldn't be correctly build. You are expected to maintain this directory on your own. You may change the name of this error directory, or even supress this feature entirely. Please, see the discussion of the errors directive in the global configuration file.

Topic directories

Each topic has its own subdirectory using the same name as the topic itself. Each single file in this directory is the source for a single card. By default, you are expected to manage your source files using the RCS version control system. Please, read the rcs(1) manual page for details. In principle, source control is a pretty good idea, but if you don't like it for whatever reasons, there is a way around our default behaviour. The source file format for each single card is described in another document.

In addition to these source files, the topic subdirectory may contain a file called conf. This file uses the same format as the global configuration file, i.e. empty lines and lines with a '#' are ignored. The remaining lines should use the following general format.

cache [top=num] name formula

Each of these lines defines a formula intended to be used in more than one card. The LaTeX formula formula will be usable under the symbolic name name. Please see the the description of the cache tag for details. The optional argument top=num is similar to the top option of the latex tag.

Create a new source tree

In summary, to start a mcards source tree you will use the following steps.

Now, you are ready to write the various cards in your bar topic.