Return to README CVS log

Up to [LON-CAPA] / doc / help

Annotation of doc/help/README, revision 1.1

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