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.

    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.