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