Penguin
Recent Changes
Blame: texexpand(1)
EditPageHistoryDiffInfoLikePages
Annotated edit history of texexpand(1) version 2, including all changes. View license author blame.
Rev Author # Line
1 perry 1 TEXEXPAND
2 !!!TEXEXPAND
3 N NA AM ME E
4 D DE ES SC CR RI IP PT TI IO ON N
5 T Th he e g go or ry y D De et ta ai il ls s
6 C CA AV VE EA AT TS S
7 A Au ut th ho or rs s
8 ----
9 !!N NA AM ME E
10
11
12 texexpand - expand input and include statements in a TeX file
13 !!D DE ES SC CR RI IP PT TI IO ON N
14
15
16 General translation mechanism:
17
18
19 The main program latex2html calls texexpand with the
20 document name in order to expand some of its input and
21 include statements, here also called `merging', and to write
22 a list of sensitized style, class, input, or include file
23 names. When texexpand has finished, all is contained in one
24 file, TMP_foo. (assumed foo.tex is the name of the document
25 to translate).
26
27
28 In this version, texexpand cares for following environments
29 that may span include files / section boundaries: a)
30 begin{comment} b) %begin{comment} c) begin{any}
31 introduced with excludecomment d) %begin{any} e)
32 begin{verbatim} f) begin{latexonly} g)
33 %begin{latexonly}
34
35
36 e) - g) prevent texexpand from expanding input files, but
37 the environment content goes fully into the output
38 file.
39
40
41 Together with each merging of input etc. there are so-called
42 %%%texexpand markers accompanying the boundary.
43
44
45 When latex2html reads in the output file, it uses these
46 markers to write each part to a separate file, and process
47 them further.
48
49
50 __DDeettaaiilleedd tteecchhnniiccaall
51 nnootteess::__
52
53
54 1. %begin{latexonly} and %end{latexonly}
55 have to be on a separate line. Anything between these tags
56 (including the tags) is discarded.
57
58
59 2. begin{latexonly} and end{latexonly} have to be on a
60 separate line. Anything between these tags (including the
61 tags) is not expanded.
62
63
64 3. [[%]begin{
65
66
67 4. begin{verbatim/verbatim*} and end{verbatim/verbatim*}
68 have to be on a separate line. Anything between these tags
69 (including the tags) is not expanded.
70
71
72 5. The scope of any such tags may extend over several files.
73 The opening tag for latexonly may occur on a different
74 include level than the closing tag. The opening tag for
75 verbatim/
76
77
78 6. Warnings are printed when the document has been parsed
79 and open tags remain.
80
81
82 7. When in a ``to exclude
83 ANY command except
84 the corresponding closing tag. There cannot be any nested
85 constructions. This behaviour is identical to that of
86 LaTeX.
87
88
89 8. begin{latexonly},end{latexonly} may be nested, whereas
90 %begin{latexonly},%end{latexonly} may not be
91 nested.
92
93
94 9. A ``%'' tag cannot close a ``'' tag, and vice
95 versa.
96
97
98 10. Every \''document''(classstyle), usepackage, input
99 and include command has to be on a separate
100 line.
101
102
103 11. Everything behind a `%' that isn't preceded by a `' is
104 regarded as a comment, i.e. it is printed but not
105 interpreted.
106
107
108 12. If any command listed in 10. is preceded by an occurence
109 of `verb' or `latex' then it is NOT
110 interpreted. This crashes on lines like this: blah blah
111 verb+foo foo+ input{bar} % bar won't be loaded!
112
113
114 13. Packages provided via usepackage are handled the same
115 way as `options' in \''document''(classstyle), i.e. they
116 are included when -auto_exclude is off, the package isn't in
117 @dont_include * OR * the package is
118 in @do_include (new). They are added to the style
119 file together with their options if the file itself hasn't
120 been merged. documentclass[[options]{class} searches for
121 every option.clo, documentstyle[[options]{style} searches for
122 every option.sty. usepackage[[options]{packages} searches for
123 every package.sty.
124
125
126 14. Each texinputs directory is searched for input
127 files/styles. If it ends in `//', the whole subdirectory
128 tree is searched.
129
130
131 15. input / include merge the given file (if found under the
132 given name or with .tex extension) if its basename is in
133 @do_include or if it isn't in
134 @dont_include or if the given filename doesn't end
135 in .sty/.clo/.cls when -auto_exclude is set.
136
137
138 __NNootteess__
139
140
141 Recognizes documentclass, documentstyle, usepackage,
2 perry 142 !RequirePackage, begin{verbatim}...end{verbatim},
1 perry 143 %begin{latexonly}...%end{latexonly},
144 begin{latexonly}...end{latexonly}, input, include, verb,
145 latex endinput, end{document} includecomment, excludecomment
146 begin{
147 %begin{
148 %end{
149 !!T Th he e g go or ry y D De et ta ai il ls s
150
151
152 Include and parse a file. This routine is recursive, see
153 also
154
155
156 Two global flags control the states of texexpand. o
157 $active is true if we should interprete the lines
158 to expand files, check for packages, etc. o $mute
159 is true if we should prevent the lines from going into the
160 out file.
161
162
163 We have three general states of texexpand: 1) interprete the
164 lines and pass them to the out file This is the normal case.
165 Corresponding: $active true, $mute
166 false
167
168
169 2) interprete minimal and suppress them
170 This is when parsing inside a comment environment, which
171 also would retain its body from LaTeX. =
172 3) interprete minimal and pass the lines to the out file
173 This is inside a verbatim or latexonly environment.
174 The line of course must be at least interpreted to determine the closing tag.
175 =
176 Any environment may extend over several include files. Any environement except verbatim and latexonly may have its opening or closing tag on different input levels. The comment and verbatim environments cannot be nested, as is with LaTeX. We must at least parse verbatim/comment environments in latexonly environments, to catch fake latexonly tags.
177
178
179 The work scheme: Five functions influence texexpand's
180 behavior. o
181 $active
182 and $mute (see above). It calls
183
184
185 o
186 $active and
187 $mute. Regarding to inputinclude,
188 \''document''(classstyle), and the functions
189 ''
190
191
192 o These three functions check if the file name or option
193 files are enabled or disabled for merging (via
194 TEXE_DO_INCLUDE or TEXE_DONT_INCLUDE). Any file that is to
195 include will be `merged' into the current file, i.e. the
196 function
197
198
199 The call tree (noweb+xy.sty would be handy
200 here):
201
202
203 main
204 v
205 +-
206 Bugs: o Since the latexonly environment is not parsed, its contents might introduce environments which are not recognized.
207
208
209 o The closing tag for latexonly is not found if hidden
210 inside an input file.
211
212
213 o One environment tag per line, yet!
214
215
216 o If I would have to design test cases for this beast I
217 would immediately desintegrate into a logic
218 cloud.
219
220
221 Notes:
222
223
224 o Ok, I designed test cases for it. Please refer to test
225 `expand' of the regression test suite in the developers'
226 module of the l2h repository.
227
228
229 o -unsegment feature: In this (rare) case, the user wants to
230 translate a segmented document not in segments but in a
231 whole (for testing, say). We enable this by recognizing the
232 segment command in
233 $segmentfile. On how to segment a document you are
234 best guided by section ``Document Segmentation'' of the
235 LaTeX2HTML manual.
236 !!C CA AV VE EA AT TS S
237
238
239 This utility is automatically configured and built to work
240 on the local setup. If this setup changes (e.g. some of the
241 external commands are moved), the script has be be
242 reconfigured.
243 !!A Au ut th ho or rs s
244
245
246 Based on texexpand by Robert Thau, MIT AI lab, including modifications by
247 Franz Vojik
248 ----
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.