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