# Course Web Macros

[UW] [Math] [CS] [CGL] [Michael McCool]

Recently I wrote some Perl scripts to make the task of maintaining a course web page easier. The goals were

• Maintenance of common source for hypertext and printed versions of course information.
• Reflection of all printed material in web pages.
• Provision of additional information on the web pages.
• Easy update of term information, course numbers, instructor's name and office hours, etc.
An example is given in the course web for CS488/688.

## Macro Substitutions

The latex2html script solves part of the problem, but has some restrictions. In particular, simple macros often defined in TeX to replace the instructor's name, etc will confuse it. The script applymacros solves this problem. Macros are first defined in an information file named Info. Each line in the file is of the form
    key:	substitution text

where occurences of the key between colons, like :so: is replaced with the substitution text. A colon terminates the key and leading white space is stripped from the beginning of the substitution text. Note that substitutions occur everywhere: inside quotes, comments, in verbatim environments... this is usually an advantage.

This script also convert strings of the form $Date: stuff$ and $Id: stuff$ to just plain stuff to prettify RCS information.

The script expects filename ending in .tex or .html, searches for a corresponding .texsrc or .htmlsrc file, and converts it, adding a comment at the top pointing back to the source file. This sample Makefile may be helpful.

In addition, I wanted to make information available on overheads available by hypertext, along with some additional information (what chapters in the textbook go along with this overhead material, for example). While giving a lecture, it would also be nice to have this additional material in a printed form.

I wrote a second Perl script, hslide2latex, that converts a directory structure of LaTeX fragments into LaTeX destined for three different publication formats, meanwhile also applying the above macros. The publication formats are:

Uses a modified lslide style file to create overheads of the material.
html
Creates hypertext of the same material, but with optional additional information included.
lectures
Creates a printed version of the material in the hypertext for possible inclusion in printed course notes or as an aid in giving lectures.
Slides are organized into modules each of which (optionally) consists of a number of sections each of which (optionally) consists of a number of subsections. This hierarchy is reflected in a hierarchical directory structure. At the top level of the directory tree, the following files are specified.
Catalog
Contains information on all modules (chapters), giving the base name and the title. Modules can be commented out with a leading %, or converted to additional information status'' with a leading @.
Overview
Optional. Additional information which is put a the beginning of the notes, before any modules. A LaTeX fragment.
Every module is referred to with a base name. If that name appears without a suffix as a directory, it is searched recursively for another Catalog and an optional Overview. However, the base name can also be used with .slide and .notes suffixes. If these files are present, they are treated as LaTeX fragments (no \begin{document}, \end{document}). The .slide information is the body of (possibly multiple) slides, while the .notes information is optional additional information'' which does not appear on a slide but does appear in hypertext and in the printed lecture notes.

Recursion only works down two levels: sections and subsections. In the overheads the subsection structure is effectively ignored, since subsections are not visually distinguished.

Why the exploded file format? Three reasons: it allows fragments to be inserted in various global file formats more easily; it allows modules, sections, or subsections to be easily commented out to configure a course for a particular lecturer's style; and finally, multiple people can edit different parts of the tree under RCS control.

This sample Makefile might be helpful.

## Tips on Using latex2html

This program works suprisingly well, but a few tips can make life a lot smoother.
• The latex2html utility works in a subdirectory and compiles all LaTeX fragments it doesn't understand into images by running latex and ripping out images from the rasterization. Images included from the LaTeX source won't work properly unless you (a) use absolute paths (ick) or (b) make a link in the subdirectory. The lecture notes sample Makefile does the latter. However a :macro: could be used to define an absolute path cleanly, since these macros work inside quotes.
• Use the verbatim environment for pseudocode and tables, if possible. Otherwise a huge image gets created which is usually a waste of bandwidth.
• You might want to use {\it x} instead of $x$ for reference to single mathematical variables. The latter gets turned into an image, the former gets italicized and takes up less space and bandwidth. Hopefully HTML and latex2html will get extended to better handle math in the near future.

## Other Tools

Check out the webify tool, which converts postscript files to a collection of thumbnail and fullscreen GIF images. Crude, but effective if all you have is postscript.

At UW there is an SGML editor available by inContext that runs under Windows on PC's; Paul Beam's group has tools to convert SGML to HTML and LaTeX as needed. Eventually, SGML is probably the way to go for formatting math and maintaining document consistency.

Author and Maintainer: Michael McCool, mmccool@cgl.uwaterloo.ca.
Revision 1.8 by cs488 on 1997/08/16 00:20:39 (UTC).