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.
Generally, these tags are used for editorial data. The class type may be chosen from the following list.
|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
|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.|
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
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.
Given such a symbolic name symbol, you may use the formula in a card file by the line
As with the latex tag, you are allowed to continue the line after closing the cache tag.
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.
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).
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
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.
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
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.