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).
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.
There are four different ways to make this work. All of these possibilities are checked in the following order.
All other lines in the conf file are configuration options. These lines have the general format
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.
|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
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
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.
|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.
|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.
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.
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
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.
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.
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.