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 document, which contains the following children: * will place the referenced tex directly into the file. *
, , and , all of which drop \section, \subsection, and \subsubsections into the tex file with that name. * drops the named file directly into the reconstruction. * 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.