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.
Overheads and Lecture Notes
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:
- overheads
- 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).