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.
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>