Return to README CVS log

Up to [LON-CAPA] / doc / help

Updated information for accuracy.

    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: 
   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).
   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.
  112: * course.manual.texxml - A texxml file for the course coordinator's
  113:                          manual. 
  114: 
  115: In order to build this file, execute 
  116: 
  117: perl texxml2latex.pl authot.manual.texxml > author.manual.tex
  118: 
  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: