Return to README CVS log

Up to [LON-CAPA] / doc / help

Updated information for accuracy.

This directory contains utilities for manipulating the .tex help
system file used by LON-CAPA, information about that system, and the
source files to re-construct paper manuals.

All scripts in this directory are coded to expect the tex files and
other help information is in loncapa/loncom/html/adm/help/, and to be
run from this directory. So you'll see references to
../../loncom/html/adm/help/* in these programs.

SECTIONS: (dashes to help with using search)

* ---texxml---
* ---fragmentLabels.gdbm---
* ---latexSplitter.py---
* ---simpleEdit.py---
* ---rebuildLabelHash.pl---
* ---texxml files---

---texxml---

texxml is a quick little XML thing to reconstruct the original XML
documents as given in user manual tutorial and such. This file
documents the format.

The texxml format is the following:

* A root <texxml> document, which contains the following children:
  * <tex content=""/> will place the referenced tex directly into the
    file.   
  * <section name=""/>, <subsection name=""/>, and <subsubsection
    name=""/>, all of which drop \section, \subsection, and
    \subsubsections into the tex file with that name.

  * <file name=""/> drops the named file directly into the
    reconstruction.

  * <topic name=""/> drops the named topic into the
    reconstruction. Recommended over use of file.

*section contain as children the subsections they have. tex, file, and
topic do not have children, or indeed content at all.

In order to reconstruct the Latex document, walk the XML file with the
texxml2latex perl script, which accepts a texxml file on <>, and
outputs the latex to std.output.. Then you can render the resulting .tex
however you want.

Note that the current user needs to be able to read the tex files in
/home/httpd/html/adm/help/tex/, or the script will not work properly
(and does not currently have any failure messages).

---fragmentLabels.gdbm---

LaTeX supports the idea of cross-references, which on the web is
equivalent to a link. The idea in LaTeX is that you drop \label{}
commands where you want to link to later, placing some descriptive
text in the {}. Later, you can cross-reference that label, which will
print the chapter the reference is used on.

TtH contains full support for this usage, but unfortunately, when
chopping something like a user manual into this many pieces,
cross-references are in completely seperate files, which does TtH no
good. Therefore, we store what file has what labels ourself.

The GDBM file fragmentLabels.gdbm contains a hash of labels to files
they are included in. This allows the help script, when it encounters
a label, to know what to link to. Additionally, the help script should
drop HTML anchors in the test, so the link can go directly to the
label.

This should allow us to reap the benefits of a labelling scheme.

A similar scheme could be used to take advantage of the \index tags in
the LaTeX, which allow you to create indexes.

The perl script rebuildLabelHash.pl will walk through all the files in
the directory, extracting the labels and storing it in the
hash. Errors will be printed out if multiple files have the same
label. This is an error in LaTeX, too. (Essentially, it must be
possible to think of the concatenation of all files, with the header
and the footer in the right place, as a legitimate .tex file.) It
takes no arguements.

---latexSplitter.py---

latexSplitter is a quick Python script to assist with chopping a large
.tex file into a series of smaller, more managable tex files. You can
paste a file into the text box, or load a file into latexSplitter
using a command-line argument. 

Then, you can break that file down by giving a section a title (which
will be entered into the fragmentTopics hash), highlighting the LaTeX
corresponding to that topic, and hitting the save
button. latexSplitter will save the highlighted fragment, update the
hash, and remove it from the text box, along with backing the text box
up in a file called "latexSplitterTempResults".

---simpleEdit.py---

simpleEdit is a quick Python/Tk script to join a file together based
on a texxml file, and allow you to edit the pieces as if they were all
contiguous. The other feature is a 'find' command. It's simple.

---rebuildLabelHash.pl---

Running this script will rebuild the fragmentLabel.gdbm hash from
scratch. Run this after adding .tex files, so cross-references work. 

---texxml files---

* author.manual.texxml - A texxml file for the author's manual.
* course.manual.texxml - A texxml file for the course coordinator's
                         manual. 

In order to build this file, execute 

perl texxml2latex.pl authot.manual.texxml > author.manual.tex

---Rendering texxml files---

The script render.texxml.pl takes a texxml file on the command line
and will render it to ps and pdf files in the current directory. Run
it from this directory, like so:

perl render.texxml.pl -- author.manual.texxml

Wait, and the ps and pdf files will pop out.

This is usually done by the build system, which will rebuild the files
when the source files have changed.