Return to README CVS log

Up to [LON-CAPA] / doc / help

Annotation of doc/help/README, revision 1.2

1.1       bowersj2    1: This directory contains utilities for manipulating the .tex help
                      2: system file used by LON-CAPA, information about that system, and the
                      3: source files to re-construct paper manuals.
                      4: 
                      5: All scripts in this directory are coded to expect the tex files and
                      6: other help information is in loncapa/loncom/html/adm/help/, and to be
                      7: run from this directory. So you'll see references to
                      8: ../../loncom/html/adm/help/* in these programs.
                      9: 
                     10: SECTIONS: (dashes to help with using search)
                     11: 
                     12: * ---texxml---
                     13: * ---fragmentLabels.gdbm---
                     14: * ---latexSplitter.py---
                     15: * ---simpleEdit.py---
                     16: * ---rebuildLabelHash.pl---
                     17: * ---texxml files---
                     18: 
                     19: ---texxml---
                     20: 
                     21: texxml is a quick little XML thing to reconstruct the original XML
                     22: documents as given in user manual tutorial and such. This file
                     23: documents the format.
                     24: 
                     25: The texxml format is the following:
                     26: 
                     27: * A root <texxml> document, which contains the following children:
                     28:   * <tex content=""/> will place the referenced tex directly into the
                     29:     file.   
                     30:   * <section name=""/>, <subsection name=""/>, and <subsubsection
                     31:     name=""/>, all of which drop \section, \subsection, and
                     32:     \subsubsections into the tex file with that name.
                     33: 
                     34:   * <file name=""/> drops the named file directly into the
                     35:     reconstruction.
                     36: 
                     37:   * <topic name=""/> drops the named topic into the
                     38:     reconstruction. Recommended over use of file.
                     39: 
                     40: *section contain as children the subsections they have. tex, file, and
                     41: topic do not have children, or indeed content at all.
                     42: 
                     43: In order to reconstruct the Latex document, walk the XML file with the
                     44: texxml2latex perl script, which accepts a texxml file on <>, and
                     45: outputs the latex to std.output.. Then you can render the resulting .tex
                     46: however you want.
                     47: 
1.2     ! bowersj2   48: Note that the current user needs to be able to read the tex files in
        !            49: /home/httpd/html/adm/help/tex/, or the script will not work properly
        !            50: (and does not currently have any failure messages).
1.1       bowersj2   51: 
                     52: ---fragmentLabels.gdbm---
                     53: 
                     54: LaTeX supports the idea of cross-references, which on the web is
                     55: equivalent to a link. The idea in LaTeX is that you drop \label{}
                     56: commands where you want to link to later, placing some descriptive
                     57: text in the {}. Later, you can cross-reference that label, which will
                     58: print the chapter the reference is used on.
                     59: 
                     60: TtH contains full support for this usage, but unfortunately, when
                     61: chopping something like a user manual into this many pieces,
                     62: cross-references are in completely seperate files, which does TtH no
                     63: good. Therefore, we store what file has what labels ourself.
                     64: 
                     65: The GDBM file fragmentLabels.gdbm contains a hash of labels to files
                     66: they are included in. This allows the help script, when it encounters
                     67: a label, to know what to link to. Additionally, the help script should
                     68: drop HTML anchors in the test, so the link can go directly to the
                     69: label.
                     70: 
                     71: This should allow us to reap the benefits of a labelling scheme.
                     72: 
                     73: A similar scheme could be used to take advantage of the \index tags in
                     74: the LaTeX, which allow you to create indexes.
                     75: 
                     76: The perl script rebuildLabelHash.pl will walk through all the files in
                     77: the directory, extracting the labels and storing it in the
                     78: hash. Errors will be printed out if multiple files have the same
                     79: label. This is an error in LaTeX, too. (Essentially, it must be
                     80: possible to think of the concatenation of all files, with the header
                     81: and the footer in the right place, as a legitimate .tex file.) It
                     82: takes no arguements.
                     83: 
                     84: ---latexSplitter.py---
                     85: 
                     86: latexSplitter is a quick Python script to assist with chopping a large
                     87: .tex file into a series of smaller, more managable tex files. You can
                     88: paste a file into the text box, or load a file into latexSplitter
                     89: using a command-line argument. 
                     90: 
                     91: Then, you can break that file down by giving a section a title (which
                     92: will be entered into the fragmentTopics hash), highlighting the LaTeX
                     93: corresponding to that topic, and hitting the save
                     94: button. latexSplitter will save the highlighted fragment, update the
                     95: hash, and remove it from the text box, along with backing the text box
                     96: up in a file called "latexSplitterTempResults".
                     97: 
                     98: ---simpleEdit.py---
                     99: 
                    100: simpleEdit is a quick Python/Tk script to join a file together based
                    101: on a texxml file, and allow you to edit the pieces as if they were all
                    102: contiguous. The other feature is a 'find' command. It's simple.
                    103: 
                    104: ---rebuildLabelHash.pl---
                    105: 
                    106: Running this script will rebuild the fragmentLabel.gdbm hash from
                    107: scratch. Run this after adding .tex files, so cross-references work. 
                    108: 
                    109: ---texxml files---
                    110: 
                    111: * author.manual.texxml - A texxml file for the author's manual.
1.2     ! bowersj2  112: * course.manual.texxml - A texxml file for the course coordinator's
        !           113:                          manual. 
1.1       bowersj2  114: 
                    115: In order to build this file, execute 
                    116: 
                    117: perl texxml2latex.pl authot.manual.texxml > author.manual.tex
                    118: 
1.2     ! bowersj2  119: ---Rendering texxml files---
        !           120: 
        !           121: The script render.texxml.pl takes a texxml file on the command line
        !           122: and will render it to ps and pdf files in the current directory. Run
        !           123: it from this directory, like so:
        !           124: 
        !           125: perl render.texxml.pl -- author.manual.texxml
        !           126: 
        !           127: Wait, and the ps and pdf files will pop out.
        !           128: 
        !           129: This is usually done by the build system, which will rebuild the files
        !           130: when the source files have changed.
        !           131: