1TEXEXPAND(1) User Contributed Perl Documentation TEXEXPAND(1)
2
6 texexpand - expand \input and \include statements in a TeX file
7
9 General translation mechanism:
10 The main program latex2html calls texexpand with the document name in
12 order to expand some of its \input and \include statements, here also
13 called 'merging', and to write a list of sensitized style, class,
14 input, or include file names. When texexpand has finished, all is
15 contained in one file, TMP_foo. (assumed foo.tex is the name of the
16 document to translate).
17 In this version, texexpand cares for following environments that may
19 span include files / section boundaries: a) \begin{comment} b)
20 %begin{comment} c) \begin{any} introduced with \excludecomment d)
21 %begin{any} e) \begin{verbatim} f) \begin{latexonly} g)
22 %begin{latexonly}
23 e) - g) prevent texexpand from expanding input files, but the
25 environment content goes fully into the output file.
26 Together with each merging of \input etc. there are so-called
28 %%%texexpand markers accompanying the boundary.
29 When latex2html reads in the output file, it uses these markers to
31 write each part to a separate file, and process them further.
32 DDeettaaiilleedd tteecchhnniiccaall nnootteess::
34 1. %begin{latexonly} and %end{latexonly} have to be on a separate line.
36 Anything between these tags (including the tags) is discarded.
37 2. \begin{latexonly} and \end{latexonly} have to be on a separate line.
39 Anything between these tags (including the tags) is not expanded.
40 3. [%\]begin{"to exclude"} and [%\]end{"to exclude"} have to be on a
42 separate line. Anything between these tags (including the tags) is
43 discarded.
44 4. \begin{verbatim/verbatim*} and \end{verbatim/verbatim*} have to be
46 on a separate line. Anything between these tags (including the tags)
47 is not expanded.
48 5. The scope of any such tags may extend over several files. The
50 opening tag for latexonly may occur on a different include level than
51 the closing tag. The opening tag for verbatim/"to exclude" must occur
52 within the same file than the closing tag.
53 6. Warnings are printed when the document has been parsed and open tags
55 remain.
56 7. When in a "to exclude"/verbatim environment, texexpand won't
58 recognize ANY command except the corresponding closing tag. There
59 cannot be any nested constructions. This behaviour is identical to
60 that of LaTeX.
61 8. \begin{latexonly},\end{latexonly} may be nested, whereas
63 %begin{latexonly},%end{latexonly} may not be nested.
64 9. A "%" tag cannot close a "\" tag, and vice versa.
66 10. Every \document(class⎪style), \usepackage, \input and \include
68 command has to be on a separate line.
69 11. Everything behind a `%' that isn't preceded by a `\' is regarded as
71 a comment, i.e. it is printed but not interpreted.
72 12. If any command listed in 10. is preceded by an occurence of `\verb'
74 or `\latex' then it is NOT interpreted. This crashes on lines like
75 this: blah blah \verb+foo foo+ \input{bar} % bar won't be loaded!
76 13. Packages provided via \usepackage are handled the same way as
78 `options' in \document(class⎪style), i.e. they are included when
79 -auto_exclude is off, the package isn't in @dont_include *OR* the
80 package is in @do_include (new). They are added to the style file
81 together with their options if the file itself hasn't been merged.
82 \documentclass[options]{class} searches for every option.clo,
83 \documentstyle[options]{style} searches for every option.sty.
84 \usepackage[options]{packages} searches for every package.sty.
85 14. Each texinputs directory is searched for input files/styles. If it
87 ends in `//', the whole subdirectory tree is searched.
88 15. \input / \include merge the given file (if found under the given
90 name or with .tex extension) if its basename is in @do_include or if it
91 isn't in @dont_include or if the given filename doesn't end in
92 .sty/.clo/.cls when -auto_exclude is set.
93 NNootteess
95 Recognizes \documentclass, \documentstyle, \usepackage,
97 \RequirePackage, \begin{verbatim}...\end{verbatim},
98 %begin{latexonly}...%end{latexonly},
99 \begin{latexonly}...\end{latexonly}, \input, \include, \verb, \latex
100 \endinput, \end{document} \includecomment, \excludecomment \begin{"to
101 exclude"}, \end{"to exclude"} %begin{"to exclude"}, %end{"to exclude"}
102
104 Include and parse a file. This routine is recursive, see also
105 &process_input_include_file, &process_document_header, and
106 &process_package_cmd.
107 Two global flags control the states of texexpand.
109 o $active is true if we should interprete the lines to expand files,
110 check for packages, etc.
111 o $mute is true if we should prevent the lines from going into the out
112 file.
113 We have three general states of texexpand:
115 1) interprete the lines and pass them to the out file This is the
116 normal case. Corresponding: $active true, $mute false
117 2) interprete minimal and suppress them
119 This is when parsing inside a comment environment, which
120 also would retain its body from LaTeX. => $active false, $mute true
121 3) interprete minimal and pass the lines to the out file
123 This is inside a verbatim or latexonly environment.
124 The line of course must be at least interpreted to determine the closing tag.
125 => $active false, $mute false
126 Any environment may extend over several include files. Any
128 environement except verbatim and latexonly may have its opening or
129 closing tag on different input levels. The comment and verbatim
130 environments cannot be nested, as is with LaTeX. We must at least
131 parse verbatim/comment environments in latexonly environments, to catch
132 fake latexonly tags.
133 The work scheme: Five functions influence texexpand's behavior. o
135 &process_file opens the given file and parses the non-comment part in
136 order to set $active and $mute (see above). It calls &interprete to
137 interprete the non-comment content and either continues with the next
138 line of its file or terminates if &interprete detected the
139 \end{document} or an \endinput.
140 o &interprete handles some LaTeX tags with respect to the three states
142 controlled by $active and $mute. Regarding to \input⎪include,
143 \document(class⎪style), and \(use⎪Require)package the functions
144 &process_input_include_file, &process_document_header, and
145 &process_package_cmd are called respectively.
146 o These three functions check if the file name or option files are
148 enabled or disabled for merging (via TEXE_DO_INCLUDE or
149 TEXE_DONT_INCLUDE). Any file that is to include will be 'merged' into
150 the current file, i.e. the function &process_file is called at this
151 place in time (recursively). This will stop interpretation at the
152 current line in file, start with the new file to process and continues
153 with the next line as soon as the new file is interpreted to its end.
154 The call tree (noweb+xy.sty would be handy here):
156 main
158 ⎪
159 v
160 +->process_file
161 ⎪ ⎪
162 ⎪ v
163 ⎪ interprete (with respect to the current line, one of that three)
164 ⎪ ⎪ ⎪ ⎪
165 ⎪ v v v
166 ⎪ process_input_include_file process_document_header process_package_cmd
167 ⎪ ⎪ ⎪ ⎪
168 ⎪ v v v
169 +----+---------------------------+------------------------+
170 Bugs: o Since the latexonly environment is not parsed, its contents
172 might introduce environments which are not recognized.
173 o The closing tag for latexonly is not found if hidden inside an input
175 file.
176 o One environment tag per line, yet!
178 o If I would have to design test cases for this beast I would
180 immediately desintegrate into a logic cloud.
181 Notes:
183 o Ok, I designed test cases for it. Please refer to test 'expand' of
185 the regression test suite in the developers' module of the l2h
186 repository.
187 o -unsegment feature: In this (rare) case, the user wants to translate
189 a segmented document not in segments but in a whole (for testing, say).
190 We enable this by recognizing the \segment command in &interprete,
191 causing the segment file to be treated like \input but loosing the
192 first lines prior to \startdocument (incl.), as controlled via
193 $segmentfile. On how to segment a document you are best guided by
194 section ``Document Segmentation'' of the LaTeX2HTML manual.
195
197 This utility is automatically configured and built to work on the local
198 setup. If this setup changes (e.g. some of the external commands are
199 moved), the script has be be reconfigured.
200
202 Based on texexpand by Robert Thau, MIT AI lab, including modifications by
203 Franz Vojik <vojik@de.tu-muenchen.informatik>
204 Nikos Drakos <nikos@cbl.leeds.ac.uk>
205 Sebastian Rahtz <spqr@uk.ac.tex.ftp>
206 Maximilian Ott <max@com.nec.nj.ccrl>
207 Martin Boyer
208 Herbert Swan
209 Jens Lippmann
2103rd Berkeley Distribution perl 5.005, patch 03 TEXEXPAND(1)