Return to README CVS log

Up to [LON-CAPA] / doc / help

This commit implements the .tex-based online help system in LON-CAPA. It
may be necessary to manually run loncom/build/help_graphics_converter.pl
and doc/help/rebuildLabelHash.pl after a cvs update, and
loncapa_apache.conf may need to be manually copied to /etc. (The
loncapafiles.lpml has been updated.)

After merging this, the URL http://[loncapahost]/adm/help/Foils.hlp
should display a help file.

Also, some *very* out-of-date files have been removed from the /doc
directory.

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---
* ---fragmentTopics.gdbm---
* ---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.

---fragmentTopics.gdbm---

The has fragmentTopics.dbm is a DBM hash that maps topics to the files
that contain those topics. Obviously, the topics are thus case
sensitive. Each topic can only go to one file, but multiple topics can
point to the same file.

---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.

In order to build this file, execute 

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

In order to build this file with LaTeX correctly, the images used in
the manual need to be in the current directory. The images will be
installed in /home/httpd/html/adm/help/eps , so you can either move
the LaTeX file in to that directory and build the author manual, or
copy the LaTeX file and the .eps files in that directory to another
directory to build. The latter is recommended.