]> git.saurik.com Git - wxWidgets.git/blame - utils/tex2rtf/docs/notes.txt
Removed outdated module definition files for VAC++.
[wxWidgets.git] / utils / tex2rtf / docs / notes.txt
CommitLineData
9a29912f
JS
1Implementation notes
2--------------------
3
4Files
5-----
6
7The library tex2any.lib contains the generic Latex parser.
8It comprises tex2any.cc, tex2any.h and texutils.cc.
9
10The executable Tex2RTF is made up of tex2any.lib,
11tex2rtf.cc (main driver and user interface), and specific
12drivers for generating output: rtfutils.cc, htmlutil.cc
13and xlputils.cc.
14
15Data structures
16---------------
17
18Class declarations are found in tex2any.h.
19
20TexMacroDef holds a macro (Latex command) definition: name, identifier,
21number of arguments, whether it should be ignored, etc. Integer
22identifiers are used for each Latex command for efficiency when
23generating output. A hash table MacroDefs stores all the TexMacroDefs,
24indexed on command name.
25
26Each unit of a Latex file is stored in a TexChunk. A TexChunk can be
27a macro, argument or just a string: a TexChunk macro has child
28chunks for the arguments, and each argument will have one or more
29children for representing another command or a simple string.
30
31Parsing
32-------
33
34Parsing is relatively add hoc. read_a_line reads in a line at a time,
35doing some processing for file commands (e.g. input, verbatiminclude).
36File handles are stored in a stack so file input commands may be nested.
37
38ParseArg parses an argument (which might be the whole Latex input,
39which is treated as an argument) or a single command, or a command
40argument. The parsing gets a little hairy because an environment,
41a normal command and bracketed commands (e.g. {\bf thing}) all get
42parsed into the same format. An environment, for example,
43is usually a one-argument command, as is {\bf thing}. It also
44deals with user-defined macros.
45
46Whilst parsing, the function MatchMacro gets called to
47attempt to find a command following a backslash (or the
48start of an environment). ParseMacroBody parses the
49arguments of a command when one is found.
50
51Generation
52----------
53
54The upshot of parsing is a hierarchy of TexChunks.
55TraverseFromDocument calls the recursive TraverseFromChunk,
56and is called by the 'client' converter application to
57start the generation process. TraverseFromChunk
58calls the two functions OnMacro and OnArgument,
59twice for each chunk to allow for preprocessing
60and postprocessing of each macro or argument.
61
62The client defines OnMacro and OnArgument to test
63the command identifier, and output the appropriate
64code. To help do this, the function TexOutput
65outputs to the current stream(s), and
66SetCurrentOutput(s) allows the setting of one
67or two output streams for the output to be sent to.
68Usually two outputs at a time are sufficient for
69hypertext applications where a title is likely
70to appear in an index and as a section header.
71
72There are support functions for getting the string
73data for the current chunk (GetArgData) and the
74current chunk (GetArgChunk). If you have a handle
75on a chunk, you can output it several times by calling
76TraverseChildrenFromChunk (not TraverseFromChunk because
77that causes infinite recursion).
78
79The client (here, Tex2RTF) also defines OnError and OnInform output
80functions appropriate to the desired user interface.
81
82References
83----------
84
85Adding, finding and resolving references are supported
86with functions from texutils.cc. WriteTexReferences
87and ReadTexReferences allow saving and reading references
88between conversion processes, rather like real LaTeX.
89
90Bibliography
91------------
92
93Again texutils.cc provides functions for reading in .bib files and
94resolving references. The function OutputBibItem gives a generic way
95outputting bibliography items, by 'faking' calls to OnMacro and
96OnArgument, allowing the existing low-level client code to take care of
97formatting.
98
99Units
100-----
101
102Unit parsing code is in texutils.cc as ParseUnitArgument. It converts
103units to points.
104
105Common errors
106-------------
107
1081) Macro not found: \end{center} ...
109
110Rewrite:
111
112\begin{center}
113{\large{\underline{A}}}
114\end{center}
115
116as:
117
118\begin{center}
119{\large \underline{A}}
120\end{center}
121
1222) Tables crash RTF. Set 'compatibility ' to TRUE in .ini file; also
123check for \\ end of row characters on their own on a line, insert
124correct number of ampersands for the number of columns. E.g.
125
126hello & world\\
127\\
128
129becomes
130
131hello & world\\
132&\\
133
1343) If list items indent erratically, try increasing
135listItemIndent to give more space between label and following text.
136A global replace of '\item [' to '\item[' may also be helpful to remove
137unnecessary space before the item label.
138
1394) Missing figure or section references: ensure all labels _directly_ follow captions
140or sections (no intervening white space).