Debian Codegraph @

texmf-dist/source/latex/childdoc/childdoc.dtx

raw
1 %
2 % \iffalse meta-comment
3 %
4 % childdoc.dtx Copyright (C) 2017-2025 Niklas Beisert
5 %
6 % This work may be distributed and/or modified under the
7 % conditions of the LaTeX Project Public License, either version 1.3
8 % of this license or (at your option) any later version.
9 % The latest version of this license is in
10 % https://www.latex-project.org/lppl.txt
11 % and version 1.3c or later is part of all distributions of LaTeX
12 % version 2008 or later.
13 %
14 % This work has the LPPL maintenance status `maintained'.
15 %
16 % The Current Maintainer of this work is Niklas Beisert.
17 %
18 % This work consists of the files childdoc.dtx and childdoc.ins
19 % and the derived files childdoc.def and cdocsamp.tex with
20 % cdocsch1.tex, cdocsch2.tex, cdocsdrf.tex, cdocsfn1.tex, cdocsfn2.tex.
21 %
22 %<package>\ifdefined\childdocmain\endinput\fi
23 %<package>\ProvidesFile{childdoc.def}[2025/03/25 v2.0.1 child document driver]
24 %<samplemain>\ProvidesFile{cdocsamp.tex}[2025/03/25 v2.0.1 sample for childdoc]
25 %<*driver>
26 \def\thedate#1{2025/03/25}\def\theversion#1{v2.0.1}
27 \ProvidesFile{childdoc.dtx}[\thedate{} \theversion{} childdoc reference manual file]
28 \PassOptionsToClass{10pt,a4paper}{article}
29 \documentclass{ltxdoc}
30
31 \usepackage[margin=35mm]{geometry}
32 \usepackage[hyperindex=false]{hyperref}
33 \usepackage{hyperxmp}
34 \usepackage[usenames]{color}
35
36 \AddToHook{begindocument/before}{\hypersetup{colorlinks=false}}
37 \hypersetup{urlbordercolor={.5 1 1}}
38 \hypersetup{linkbordercolor={1 .7 .7}}
39 \AddToHook{begindocument/before}{\hypersetup{pdfstartview=FitH}}
40 \hypersetup{keeppdfinfo=true}
41 \hypersetup{pdfsource={}}
42 \hypersetup{pdflang={en-UK}}
43 \hypersetup{pdfurl={https://ctan.org/pkg/childdoc}}
44 \hypersetup{pdfcopyright={Copyright 2017-2025 Niklas Beisert.
45 This work may be distributed and/or modified under the
46 conditions of the LaTeX Project Public License, either version 1.3
47 of this license or (at your option) any later version.}}
48 \hypersetup{pdflicenseurl={https://www.latex-project.org/lppl.txt}}
49 \hypersetup{pdfcontactaddress={ETH Zurich, ITP, HIT K,
50 Wolfgang-Pauli-Strasse 27}}
51 \hypersetup{pdfcontactpostcode={8093}}
52 \hypersetup{pdfcontactcity={Zurich}}
53 \hypersetup{pdfcontactcountry={Switzerland}}
54 \hypersetup{pdfcontactemail={[email protected]}}
55 \hypersetup{pdfcontacturl={https://people.phys.ethz.ch/\xmptilde nbeisert/}}
56
57 \newcommand{\markpkg}[1]{\textsf{#1}}
58 \newcommand{\secref}[1]{\hyperref[#1]{section \ref*{#1}}}
59 \newcommand{\ctanref}[2]{\href{https://ctan.org/#1}{#2}}
60 \newcommand{\ctanpkg}[1]{\ctanref{pkg/#1}{\markpkg{#1}}}
61
62 \def\textvert{\texttt{\char"7C}}
63
64 \parskip1ex
65 \parindent0pt
66 \let\olditemize\itemize
67 \def\itemize{\olditemize\parskip0pt}
68
69 \begin{document}
70
71 \title{The \markpkg{childdoc} Package}
72 \hypersetup{pdftitle={The childdoc Package}}
73 \author{Niklas Beisert\\[2ex]
74 Institut f\"ur Theoretische Physik\\
75 Eidgen\"ossische Technische Hochschule Z\"urich\\
76 Wolfgang-Pauli-Strasse 27, 8093 Z\"urich, Switzerland\\[1ex]
77 \href{mailto:[email protected]}
78 {\texttt{[email protected]}}}
79 \hypersetup{pdfauthor={Niklas Beisert}}
80 \hypersetup{pdfsubject={Manual for the LaTeX2e Package childdoc}}
81 \date{\thedate{}, \theversion{}\\[1ex]
82 \url{https://ctan.org/pkg/childdoc}}
83 \maketitle
84
85 \begin{abstract}\noindent
86 \markpkg{childdoc} is a \LaTeXe{} package
87 that enables the direct compilation
88 of document sections included by |\include|
89 to individual files.
90 \end{abstract}
91
92 \begingroup
93 \parskip0ex
94 \tableofcontents
95 \endgroup
96
97 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
98 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
99 \section{Introduction}
100
101 \LaTeX{} provides a mechanism to structure a large document (such as a book)
102 into a main file and several child files (containing the chapters)
103 using the |\include| command.
104 This mechanism is beneficial for documents
105 which span hundreds of pages in order to
106 make the source file(s) more manageable.
107 Moreover, compilation can be restricted to
108 selected child files by means of the |\includeonly| command.
109 The latter feature can be used to reduce the compilation time while editing
110 (this was significantly more useful in the earlier days of \LaTeX{})
111 or to generate a smaller document which is easier to navigate.
112 Another application of |\includeonly| is to generate
113 documents consisting of selected parts of the complete document.
114
115 However, there are a few drawbacks of the plain |\include| mechanism:
116 \begin{itemize}
117 \item
118 The child files cannot be compiled on their own,
119 they can only be compiled via the main file.
120 A naive editing environment
121 (such as a text editor with an option
122 to have the current file processed by \LaTeX)
123 may require one to switch to the main file before compiling;
124 attempting to compile the child file produces errors.
125 \item
126 The main file must be modified (each time)
127 to adjust the |\includeonly| command
128 to the present needs. This easily leaves the main file in a messy state.
129 \item
130 The generated document will always carry the filename
131 of the main document. This is inconvenient if
132 several child files are to be compiled and
133 to be kept for distribution.
134 \end{itemize}
135
136 The present package provides a simple interface
137 to make child files individually compilable by \LaTeX{}.
138 Compiling a child file then has the same effect as compiling
139 the main file with an |\includeonly| command
140 to select the appropriate child.
141 Moreover the generated document will carry the name of the child
142 rather than the main file.
143 This resolves all three above issues.
144
145 This feature is meant to make the editing of books,
146 thesis documents and lecture notes somewhat more convenient.
147 However, the package can also be used efficiently for
148 composing a series of documents (such as exercise sheets)
149 which are typically distributed individually.
150 It then assists the author in generating the individual documents
151 (potentially in different versions)
152 as well as a document containing the collected series.
153 Another application is in developing style files
154 or other kinds of included material
155 where compilation of the style file could redirect
156 to a sample or test file.
157
158 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
159 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
160 \section{Usage}
161
162 First of all, the package \ctanpkg{childdoc} is \emph{not} a standard
163 \LaTeXe{} |.sty| style file! Therefore it needs to be invoked in
164 a non-standard way.
165
166 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
167 \subsection{Included Files}
168 \label{sec:include}
169
170 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
171 \DescribeMacro{\childdocmain}
172 To use the package, add the commands
173 \begin{center}
174 \begin{tabular}{l}
175 |\input{childdoc.def}|\\
176 |\childdocmain{}|\\
177 \end{tabular}
178 \end{center}
179 at the very top of the main \LaTeX{} file,
180 in particular \emph{before} the |\documentclass| statement!
181 The argument of |\childdocmain| should be left empty
182 (but it must be present).
183
184 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
185 \DescribeMacro{\childdocof}
186 Furthermore, add the commands
187 \begin{center}
188 \begin{tabular}{l}
189 |\input{childdoc.def}|\\
190 |\childdocof{|\textit{main}|}|\\
191 \end{tabular}
192 \end{center}
193 at the top of every child file \textit{child}
194 which is included by |\include{|\textit{child}|}|
195 from within the main file
196 (or at least for those files to be compiled individually).
197 The argument \textit{main} must be the filename of the main file.
198
199 There are a couple of
200 considerations in setting up the main and child documents:
201
202 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
203 \paragraph{Restrictions.}
204
205 Please note the following restrictions:
206 \begin{itemize}
207 \item
208 |\childdocmain| must be called with one argument \textit{main}
209 to ensure compatibility with earlier version of the package.
210 It must either be empty (|\childdocmain{}|)
211 or precisely match the filename of the main file in which it is specified.
212 See \secref{sec:detection} for further information.
213 \item
214 The filename \textit{main} must be specified without the |.tex| extension.
215 \item
216 The filename \textit{main} is case sensitive
217 (even in case-insensitive file systems)
218 due to internal string comparison.
219 \item
220 The argument \textit{main} should be fully expanded, it cannot be a macro.
221 \item
222 Subdirectories and special characters should be avoided in filenames.
223 \item
224 The command |\childdocmain{|\textit{main}|}| must be followed by a whitespace.
225 It should not be followed immediately by another command
226 or by a comment mark `|%|'.
227 This is because the \TeX{} parser reads the token immediately following
228 the argument of |\childdocmain| and puts it
229 at the beginning of every child section;
230 however, a white\-space is ignored.
231 \end{itemize}
232
233 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
234 \paragraph{Content of Main File.}
235
236 It is advisable to place all content in the child files included by |\include|.
237 Any output contained in the main file will appear in all child documents
238 unless suppressed manually;
239 it cannot be suppressed automatically by the |\includeonly| directive
240 and thus should normally be avoided.
241 A method to include some content in the main file
242 by means of conditional processing is described in \secref{sec:conditional}.
243
244 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
245 \paragraph{Page Numbering.}
246
247 When only a part of the document is compiled,
248 the appropriate numbering of pages
249 (as well as other status parameters)
250 is determined from the |.aux| files.
251 The latter contain information from previous passes.
252 However this information needs to propagate through
253 all intermediate child documents.
254 Therefore the page numbering in child documents may well
255 be inconsistent until the complete document is compiled at least once.
256
257 A useful (if unconventional) way to always ensure a consistent
258 page numbering is to restart the numbering in each child document
259 and denote the pages by `\textit{child}|.|\textit{page}'
260 where \textit{child} represents the chapter/section number of the child file.
261 This can be achieved by the \LaTeX\ command
262 |\counterwithin{page}{|\textit{child}|}|
263 where \textit{child} can be |chapter| or |section|
264 depending on the chosen structuring.
265 Alternatively, one can modify the macro |\thepage| appropriately
266 and reset the counter |page| at the start of each child file.
267
268 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
269 \subsection{Conditional Processing}
270 \label{sec:conditional}
271
272 The package provides a mechanism to compile different versions
273 of a document. To customise the versions further some conditional processing
274 can come in handy to distinguish which version is being compiled.
275 The package provides two macros to describe the compilation context:
276
277 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
278 \DescribeMacro{\ifchilddoc}
279 The conditional |\ifchilddoc| distinguishes between the compilation of
280 child documents and the main document:
281 %
282 \begin{center}
283 |\ifchilddoc |\textit{child-code}| |[|\||else |\textit{main-code}]| \||fi|
284 \end{center}
285
286 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
287 \DescribeMacro{\childdocname}
288 \DescribeMacro{\childdocjob}
289 The macro |\childdocname| contains the filename (without extension)
290 of the main or child file being processed.
291 Note that |\childdocjob| will always contain the name of the main file.
292
293 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
294 \paragraph{Title Page.}
295
296 Conditional processing can be used to include a title or banner page
297 in the main document when proper precautions are taken.
298 Importantly, the code in the main file should ensure that the page counter
299 (as well as other status parameters which are stored in the |.aux| files)
300 takes the same value after the conditional processing.
301 Otherwise the page numbers may take divergent values
302 depending on which part is compiled.
303
304 For example, a title page could be declared by:
305 %
306 \begin{center}
307 \begin{tabular}{l}
308 |\ifchilddoc\||else|\\
309 |\addtocounter{page}{-1}|\\
310 \textit{code for title page}\\
311 |\newpage|\\
312 |\||fi|
313 \end{tabular}
314 \end{center}
315 %
316 A banner page for the child documents can be generated by:
317 %
318 \begin{center}
319 \begin{tabular}{l}
320 |\ifchilddoc|\\
321 |\addtocounter{page}{-1}|\\
322 \textit{code for banner page}\\
323 |\newpage|\\
324 |\||fi|
325 \end{tabular}
326 \end{center}
327 %
328 Here one could write a message such as:
329 \begin{center}
330 |This is the part \childdocname{} of \childdocjob{}.|
331 \end{center}
332
333 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
334 \subsection{Flags}
335 \label{sec:flags}
336
337 The package makes it easy to generate different versions
338 of the main or child documents.
339 To this end compilation flags can be defined
340 and assigned different default values.
341 They will be particularly useful in conjunction
342 with the forwarding mechanism described in \secref{sec:forward}.
343
344 For example, it may be useful to have a flag |\version|
345 which can be set to |draft| or |final|.
346 The document source will contain some conditional code
347 depending on the value of |\version|.
348 Suppose further, the flag should default to |final| for the main file
349 and to |draft| for child files
350 which is a natural assignment for editing the document.
351 This is achieved by placing the following code
352 in the preamble of the main document
353 (below the |\childdocmain| directive):
354 %
355 \begin{center}
356 \begin{tabular}{l}
357 |\ifchilddoc|\\
358 |\providecommand{\version}{draft}|\\
359 |\||else|\\
360 |\providecommand{\version}{final}|\\
361 |\||fi|
362 \end{tabular}
363 \end{center}
364 %
365 The definition by |\providecommand| makes sure
366 that previous definitions are not overwritten.
367 Further statements |\providecommand{\version}{...}|
368 can thus be added before the above code to override it.
369
370 For the main file, one might add a line
371 (between |\childdocmain| and the above block)
372 %
373 \begin{center}
374 |%\ifchilddoc\||else\providecommand{\version}{draft}\||fi|
375 \end{center}
376 %
377 which can be uncommented to produce a draft version.
378 Likewise one can add a line to the very top of a child file
379 (above the |\childdocof{|\textit{main}|}| directive)
380 %
381 \begin{center}
382 |%\providecommand{\version}{final}|
383 \end{center}
384 %
385 which can be uncommented to produce the final version of this child document.
386
387 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
388 \subsection{Forwarding}
389 \label{sec:forward}
390
391 Different versions of the main or child documents
392 using compilation flags as described in \secref{sec:flags}
393 can be (permanently) stored in different files
394 for convenient compilation, viewing and distribution.
395 To this end, the package defines a command
396 to pass on compilation to a different file:
397
398 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
399 \DescribeMacro{\childdocforward}
400 The command |\childdocforward| redirects processing to
401 another source file:
402 %
403 \begin{center}
404 \begin{tabular}{l}
405 |\input{childdoc.def}|\\
406 |\childdocforward[|\textit{main}|]{|\textit{dest}|}|\\
407 \end{tabular}
408 \end{center}
409 %
410 The argument \textit{dest} is the destination file
411 (without extension).
412 It should be the main file or one of the child files.
413 Note that further \ctanpkg{childdoc} directives
414 such as |\childdocof| and |\childdocforward|
415 in the indicated file will be processed in this form.
416 The optional argument \textit{main}
417 passes on directly to the main file \textit{main}
418 while pretending to compile the child \textit{dest}.
419 This form behaves as if \textit{dest}
420 issues |\childdocof{|\textit{main}|}| right away,
421 and no further \ctanpkg{childdoc} directives will be processed.
422
423 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
424 \DescribeMacro{\...prefix}
425 In the alternative form |\childdocforwardprefix|,
426 %
427 \begin{center}
428 \begin{tabular}{l}
429 |\input{childdoc.def}|\\
430 |\childdocforwardprefix[|\textit{main}|]{|\textit{prefix}|}{|\textit{dest}|}|
431 \end{tabular}
432 \end{center}
433 %
434 the destination file is determined by a pattern
435 depending on the current file:
436 To make this work, the current file must be called
437 `{\textit{prefix}\hspace{0.2em}\textit{suffix}}'
438 with \textit{prefix} matching precisely the argument.
439 Processing is then passed on to the file
440 `{\textit{dest}\hspace{0.2em}\textit{suffix}}'.
441 Surely, the same effect is achieved by
442 directly specifying the
443 argument `{\textit{dest}\hspace{0.2em}\textit{suffix}}'
444 in the first form.
445 However, that requires to set up a different file
446 for each child. With the alternative form of the command
447 all these files can have exactly the same content
448 which simplifies setting them up and maintaining them.
449
450 For example, the following file |draft.tex|
451 with a compilation flag |\version| as described in \secref{sec:flags}
452 compiles the main document as a draft:
453 %
454 \begin{center}
455 \begin{tabular}{l}
456 |\def\version{draft}|\\
457 |\input{childdoc.def}|\\
458 |\childdocforward{|\textit{main}|}|
459 \end{tabular}
460 \end{center}
461 %
462 Likewise, the following files |final|\textit{nn}|.tex|
463 compile the final version of the child document
464 |child|\textit{nn}|.tex|:
465 %
466 \begin{center}
467 \begin{tabular}{l}
468 |\def\version{final}|\\
469 |\input{childdoc.def}|\\
470 |\childdocforwardprefix{final}{child}|
471 \end{tabular}
472 \end{center}
473 %
474
475 Note that when several versions of a main file and/or of each child file
476 are to be generated, it may be convenient to set up a |Makefile| or
477 shell script to automatise the process.
478
479 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
480 \subsection{Command Line Processing}
481 \label{sec:commandline}
482
483 The effect of redirection files can also be achieved by invoking
484 the \LaTeX{} compiler with a more elaborate command line.
485 Most conveniently this should be done as part
486 of a shell script or a |Makefile|.
487
488 When using \ctanpkg{childdoc} in the main file, the following
489 command lines effectively perform a redirection
490 (note that depending on the shell being used,
491 backslashes may have to be doubled: `|\|' $\to$ `|\\|'):
492 %
493 \begin{center}
494 |... -jobname "|\textit{target}|" |\\|"|[\textit{flags}]%
495 |\input{childdoc.def}\childdocforward[|\textit{main}|]{|\textit{dest}|}"|
496 \end{center}
497 %
498 Here \textit{target} is the name of the output file,
499 \textit{main} is the name of the main file
500 and \textit{dest} is the name of the main or child file to be processed
501 (all filenames without extensions).
502 The optional argument \textit{main} can be omitted
503 if \textit{main} matches \textit{dest}.
504 Optionally, compilation \textit{flags} can be defined via |\def| commands.
505 This command line makes the \TeX{} engine believe
506 it is compiling the file \textit{target}
507 whose content is specified as the latter parameter.
508 The provided code then forwards the processing to
509 \textit{main} or \textit{dest} as described in \secref{sec:forward}.
510
511 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
512 \subsection{Include by Input}
513 \label{sec:input}
514
515 Including child documents by |\include| has some restrictions by design.
516 Most notably, the content of a child document always occupies
517 its own set of pages; pages cannot be shared between child documents.
518 Usually, this behaviour makes perfect sense
519 because each child document contain an essential part of the document.
520 However, in some situations it may be desirable to compose
521 a document from a collection of parts
522 without having mandatory page breaks between then.
523 For this case, the package
524 provides a mechanism to include parts
525 by |\input| which can also be processed individually.
526 However, by construction this mechanism
527 requires manual handling of the content to be output.
528
529 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
530 \DescribeMacro{\ifchilddocmanual}
531 The main file should be prepared as usual, see \secref{sec:include}.
532 However, the document body must make a distinction
533 between processing of an individual part and of the main document, e.g.:
534 %
535 \begin{center}
536 \begin{tabular}{l}
537 |\ifchilddocmanual|\\
538 |\input{\childdocname}|\\
539 |\||else|\\
540 \textit{document body with }|\input{|\textit{part}|}|\\
541 |\||fi|
542 \end{tabular}
543 \end{center}
544 %
545 The conditional |\ifchilddocmanual| is true whenever
546 a part to be included by |\input| is being compiled,
547 and the name of the part is stored in |\childdocname|.
548
549 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
550 \DescribeMacro{\childdocby}
551 Each part to be included by |\input| should start with:
552 %
553 \begin{center}
554 \begin{tabular}{l}
555 |\input{childdoc.def}|\\
556 |\childdocby{|\textit{main}|}|\\
557 \end{tabular}
558 \end{center}
559 %
560 The directive |\childdocby| is similar to |\childdocof|
561 described in \secref{sec:include},
562 but the subsequent selection of content must be done manually.
563 To that end, both |\ifchilddoc| and |\ifchilddocmanual|
564 will be true upon processing of a part,
565 and the name of the part is stored in |\childdocname|.
566 Note that |\jobname| will be set to the filename of the current part
567 so that each part receives an individual |.aux| file
568 that does not interfere with the |.aux| file(s) of the main document.
569 This behaviour can be altered by the alternative form
570 |\childdocby[*]{|\textit{main}|}| (with a non-empty optional argument)
571 which uses the |.aux| file of the main document
572 by setting |\jobname| to \textit{main}.
573
574 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
575 \subsection{Driver Development}
576 \label{sec:driver}
577
578 The \ctanpkg{childdoc} mechanism can also be use for the development
579 of definition files such as \LaTeX{} styles or classes.
580 This case differs from the above setup with multiple parts
581 included by |\include| in that no |\includeonly| should be invoked.
582 This can be achieved by starting the include file
583 (before |\ProvidesPackage|) with:
584 %
585 \begin{center}
586 \begin{tabular}{l}
587 |\input{childdoc.def}|\\
588 |\childdocforward{|\textit{main}|}|\\
589 \end{tabular}
590 \end{center}
591 %
592 or alternatively with:
593 %
594 \begin{center}
595 \begin{tabular}{l}
596 |\input{childdoc.def}|\\
597 |\childdocby{|\textit{main}|}|\\
598 \end{tabular}
599 \end{center}
600 %
601 Both forms have slightly different effects as described above.
602 The main file is prepared as usual, see \secref{sec:include}.
603
604 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
605 \subsection{Legacy Detection}
606 \label{sec:detection}
607
608 The directive |\childdocmain| in the main file can detect
609 whether the complete document or merely a child is to be compiled
610 even without using the directive |\childdocof|.
611 This method is deprecated because it is less robust
612 and there is no compelling reason to use it;
613 it is merely provided for backward compatibility
614 and it may be removed in future versions.
615
616 If the detection mechanism is to be used,
617 it is mandatory to correctly specify
618 the filename of the main file as the argument of |\childdocmain|:
619 %
620 \begin{center}
621 \begin{tabular}{l}
622 |\input{childdoc.def}|\\
623 |\childdocmain{|\textit{main}|}|\\
624 \end{tabular}
625 \end{center}
626 %
627 If |\jobname| does not match the argument \textit{main} of |\childdocmain|,
628 it is assumed that |\jobname| points to the child file to be compiled.
629 When using |\childdocmain| with the main file specified as argument,
630 it suffices to start a child file
631 with just |\input{|\textit{main}|}|
632 without loading of the package and using |\childdocof|.
633 If instead all processing is done
634 with the appropriate \ctanpkg{childdoc} directives,
635 the argument of \textit{main} of |\childdocmain| can be empty.
636
637 An alternative version of the command line processing described
638 in \secref{sec:commandline} using the detection mechanism reads:
639 %
640 \begin{center}
641 |... -jobname "|\textit{target}|" "|[\textit{flags}]%
642 [|\def\jobname{|\textit{dest}|}|]|\input{|\textit{main}|}"|
643 \end{center}
644
645 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
646 \subsection{Manual Code}
647 \label{sec:manual}
648
649 In case one cannot be certain whether the definitions file |childdoc.def|
650 is installed on the target \TeX{} distribution
651 and one prefers not to ship it,
652 it is conceivable to paste a few relevant commands into the sources.
653
654 To that end, drop all statements |\input{childdoc.def}|
655 and perform the replacements as outlined below.
656 Instead of |\childdocmain{|\textit{main}|}| add the following code
657 to the top of the main file:
658 %
659 \begin{center}
660 \begin{tabular}{l}
661 |\||ifdefined\childdocname\endinput\||fi\newif\ifchilddoc|\\
662 |\edef\childdocname{\scantokens\expandafter{\jobname\noexpand}}|\\
663 |\def\childdocmain{|\textit{main}|}\||ifx\childdocmain\childdocname\||else|\\
664 |\childdoctrue\includeonly{\childdocname}\let\jobname\childdocmain\||fi|\\
665 \end{tabular}
666 \end{center}
667 %
668 Instead of |\childdocof{|\textit{main}|}| just include the main file
669 at the top of each child file:
670 %
671 \begin{center}
672 |\input{|\textit{main}|}|
673 \end{center}
674 %
675 A simple redirection |\childdocforward{|\textit{dest}|}| is achieved by:
676 %
677 \begin{center}
678 |\def\jobname{|\textit{dest}|}\input{\jobname}|
679 \end{center}
680 %
681 The redirection with prefix
682 |\childdocforwardprefix[|\textit{prefix}|]{|\textit{dest}|}|
683 is accomplished by:
684 %
685 \begin{center}
686 \begin{tabular}{l}
687 |{\edef\jobname{\scantokens\expandafter{\jobname\noexpand}}|\\
688 |\def\redirectjob |\textit{prefix}|#1~~~{\gdef\jobname{|\textit{dest}|#1}}|\\
689 |\expandafter\redirectjob\jobname~~~}\input{\jobname}|
690 \end{tabular}
691 \end{center}
692
693 In an alternative approach,
694 child documents can be compiled by a specific command line
695 without additional code or specific definitions:
696 %
697 \begin{center}
698 |... -jobname "|\textit{target}|" "|[\textit{flags}]%
699 |\includeonly{|\textit{dest}|}\input{|\textit{main}|}"|
700 \end{center}
701 %
702
703 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
704 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
705 \section{Information}
706
707 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
708 \subsection{Copyright}
709
710 Copyright \copyright{} 2017--2025 Niklas Beisert
711
712 This work may be distributed and/or modified under the
713 conditions of the \LaTeX{} Project Public License, either version 1.3
714 of this license or (at your option) any later version.
715 The latest version of this license is in
716 \url{https://www.latex-project.org/lppl.txt}
717 and version 1.3c or later is part of all distributions of \LaTeX{}
718 version 2008 or later.
719
720 This work has the LPPL maintenance status `maintained'.
721
722 The Current Maintainer of this work is Niklas Beisert.
723
724 This work consists of the files |README.txt|, |childdoc.ins| and |childdoc.dtx|
725 as well as the derived files |childdoc.def|, |cdocsamp.tex|
726 with |cdocsch1.tex|, |cdocsch2.tex|, |cdocspt3.tex|, |cdocspt4.tex|,
727 |cdocsdrf.tex|, |cdocsfn1.tex|, |cdocsfn2.tex|
728 as well as |childdoc.pdf|.
729
730 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
731 \subsection{Files and Installation}
732
733 The package consists of the files:
734 %
735 \begin{center}
736 \begin{tabular}{ll}
737 |README.txt| & readme file \\
738 |childdoc.ins| & installation file \\
739 |childdoc.dtx| & source file \\
740 |childdoc.def| & definition file \\
741 |cdocsamp.tex| & sample main file \\
742 |cdocsch1.tex| & sample include file \\
743 |cdocsch2.tex| & sample include file \\
744 |cdocspt3.tex| & sample part file \\
745 |cdocspt4.tex| & sample part file \\
746 |cdocsdrf.tex| & sample redirection file \\
747 |cdocsfn1.tex| & sample redirection file \\
748 |cdocsfn2.tex| & sample redirection file \\
749 |childdoc.pdf| & manual
750 \end{tabular}
751 \end{center}
752 %
753 The distribution consists of the files
754 |README.txt|, |childdoc.ins| and |childdoc.dtx|.
755 %
756 \begin{itemize}
757 \item
758 Run (pdf)\LaTeX{} on |childdoc.dtx|
759 to compile the manual |childdoc.pdf| (this file).
760 \item
761 Run \LaTeX{} on |childdoc.ins| to create the definitions file |childdoc.def|
762 and the sample |cdocsamp.tex| with include files
763 |cdocsch1.tex|, |cdocsch2.tex|, |cdocspt3.tex|, |cdocspt4.tex|,
764 |cdocsdrf.tex|, |cdocsfn1.tex|, |cdocsfn2.tex|.
765 Then copy the file |childdoc.def| to an appropriate directory of your \LaTeX{}
766 distribution, e.g.\ \textit{texmf-root}|/tex/latex/childdoc|.
767 \end{itemize}
768
769 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
770 \subsection{Related CTAN Packages}
771
772 There are several other packages which offer a similar functionality:
773 %
774 \begin{itemize}
775 \item
776 The packages
777 \ctanpkg{docmute},
778 \ctanpkg{includex} and
779 \ctanpkg{standalone}
780 provide commands to include only the document body of
781 a child file thus allowing both files to be compiled individually.
782 \item
783 The packages \ctanpkg{subdocs}
784 and \ctanpkg{subfiles}
785 provide structures in which the main and child documents can be
786 encapsulated and allowing them to be compiled individually.
787 The inclusion mechanism is different from the conventional |\include|.
788 \item
789 The package \ctanpkg{combine}
790 is an elaborate solution to combine several documents into one.
791 \end{itemize}
792 %
793 See also the CTAN topic \ctanpkg{subdocs}
794 for further related packages.
795 The present package differs from the above solutions in that
796 a document structure constructed with the conventional |\include| mechanism
797 just needs two extra commands at the top of every file
798 such that all constituent files can be compiled individually.
799
800 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
801 %\subsection{Feature Suggestions}
802 %
803 %The following is a list of features which may be useful for future
804 %versions of this package:
805 %%
806 %\begin{itemize}
807 %\item
808 %\ldots
809 %remove legacy argument from |\childdocmain|:
810 %but then should rename command for backward compatibility?!
811 %also make sure no further tokens are injected!
812 %\end{itemize}
813
814 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
815 \subsection{Revision History}
816
817 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
818 \iffalse
819 \paragraph{vN.N.N+:} 20YY/MM/NN
820
821 \begin{itemize}
822 \item
823 \ldots
824 \end{itemize}
825 \fi
826
827 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
828 \paragraph{v2.0.1:} 2025/03/25
829
830 \begin{itemize}
831 \item
832 maintenance and manual update
833 \end{itemize}
834
835 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
836 \paragraph{v2.0:} 2018/12/30
837
838 \begin{itemize}
839 \item
840 immediate forward processing
841 \item
842 added |\childdocby| mechanism
843 \item
844 manual restructured
845 \end{itemize}
846
847 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
848 \paragraph{v1.6:} 2018/01/17
849
850 \begin{itemize}
851 \item
852 application for development of include files
853 \item
854 corrections to manual
855 \end{itemize}
856
857 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
858 \paragraph{v1.5:} 2017/05/21
859
860 \begin{itemize}
861 \item
862 more complete structuring introduced
863 \item
864 |\childdocof| introduced
865 \item
866 |\childdoc| renamed to |\childdocmain|
867 \item
868 |\childredirect| renamed to |\childdocforward| and |\childdocforwardprefix|
869 and functionality expanded
870 \end{itemize}
871
872 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
873 \paragraph{v1.0:} 2017/04/27
874
875 \begin{itemize}
876 \item
877 manual and install package
878 \item
879 first version published on CTAN
880 \end{itemize}
881
882 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
883 \paragraph{v0.6:} 2017/04/26
884
885 \begin{itemize}
886 \item
887 redirection mechanism added
888 \end{itemize}
889
890 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
891 \paragraph{v0.5:} 2017/04/26
892
893 \begin{itemize}
894 \item
895 functionality in definition file
896 \end{itemize}
897
898
899 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
900 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
901 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
902 \appendix
903
904 \settowidth\MacroIndent{\rmfamily\scriptsize 000\ }
905
906 \DocInput{childdoc.dtx}
907
908 \end{document}
909 %</driver>
910 % \fi
911 %
912 % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
913 % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
914 % \section{Sample}
915 %\iffalse
916 %<*samplemain>
917 %\fi
918 %
919 % The following presents a sample document
920 % with two chapters, two parts, a title page,
921 % a compile flag as well as three forwarding files to set the flag.
922 % It consists of eight |.tex| files:
923 % \begin{center}
924 % \begin{tabular}{ll}
925 % |cdocsamp.tex|&main file\\
926 % |cdocsch1.tex|&include file for chapter 1\\
927 % |cdocsch2.tex|&include file for chapter 2\\
928 % |cdocspt3.tex|&include file for part 3\\
929 % |cdocspt4.tex|&include file for part 4\\
930 % |cdocsdrf.tex|&forwarding file for main file in draft mode\\
931 % |cdocsfi1.tex|&forwarding file for final version of chapter 1\\
932 % |cdocsfi2.tex|&forwarding file for final version of chapter 2\\
933 % \end{tabular}
934 % \end{center}
935 % Each of the eight files can be compiled directly by the \LaTeX{} compiler.
936 %
937 % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
938 % \paragraph{Main File.}
939 %
940 % The main file is called |cdocsamp.tex|.
941 %
942 % Load the \ctanpkg{childdoc} definitions and
943 % declare the filename for the main document:
944 % \begin{macrocode}
945 \input{childdoc.def}
946 \childdocmain{}
947 % \end{macrocode}
948
949 % Optional override for |\version| flag:
950 % \begin{macrocode}
951 %%\ifchilddoc\else\providecommand{\version}{draft}\fi
952 % \end{macrocode}
953
954 % Define the default values for the |\version| flag
955 % (|final| for the main file and |draft| for childs):
956 % \begin{macrocode}
957 \ifchilddoc
958 \providecommand{\version}{draft}
959 \else
960 \providecommand{\version}{final}
961 \fi
962 % \end{macrocode}
963
964 % Load the standard document class:
965 % \begin{macrocode}
966 \documentclass[12pt]{article}
967 % \end{macrocode}
968
969 % Start the document body:
970 % \begin{macrocode}
971 \begin{document}
972 % \end{macrocode}
973
974 % Declare a title page.
975 % Print title, part of document being processed and version flag:
976 % \begin{macrocode}
977 \addtocounter{page}{-1}
978 \begin{center}
979 {\LARGE\bfseries{}childdoc example\par}
980 \vspace{1cm}
981 \ifchilddoc
982 \ifchilddocmanual part\else chapter\fi:
983 `\childdocname' of `\childdocjob'\par
984 \else
985 main document: `\childdocjob'\par
986 \fi
987 version: \version\par
988 \end{center}
989 \newpage
990 % \end{macrocode}
991
992 % Manually include selected file,
993 % otherwise process as usual:
994 % \begin{macrocode}
995 \ifchilddocmanual
996 \section*{part `\childdocname'}
997 \input{\childdocname}
998 \else
999 % \end{macrocode}
1000
1001 % Include the two chapters:
1002 % \begin{macrocode}
1003 \include{cdocsch1}
1004 \include{cdocsch2}
1005 % \end{macrocode}
1006
1007 % Include the two parts unless only chapters should be displayed:
1008 % \begin{macrocode}
1009 \ifchilddoc\else
1010 \section{part three}
1011 \input{cdocspt3}
1012 \section{part four}
1013 \input{cdocspt4}
1014 \fi
1015 % \end{macrocode}
1016
1017 % Process as usual until here:
1018 % \begin{macrocode}
1019 \fi
1020 % \end{macrocode}
1021
1022 % End of document body:
1023 % \begin{macrocode}
1024 \end{document}
1025 % \end{macrocode}
1026 %\iffalse
1027 %</samplemain>
1028 %\fi
1029 %
1030 % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1031 % \paragraph{Chapter Include Files.}
1032 %
1033 % The include files are called |cdocsch1.tex| and |cdocsch2.tex|.
1034 %
1035 %\iffalse
1036 %<*samplechap1|samplechap2>
1037 %\fi
1038
1039 % Optional override for |\version| flag:
1040 % \begin{macrocode}
1041 %%\providecommand{\version}{final}
1042 % \end{macrocode}
1043
1044 % Include the main document:
1045 % \begin{macrocode}
1046 \input{childdoc.def}
1047 \childdocof{cdocsamp}
1048 % \end{macrocode}
1049
1050 %\iffalse
1051 %</samplechap1|samplechap2>
1052 %\fi
1053 %
1054 %\iffalse
1055 %<*samplechap1>
1056 %\fi
1057 % Some text for chapter 1:
1058 % \begin{macrocode}
1059 \section{one}
1060 some text in chapter one
1061 % \end{macrocode}
1062
1063 %\iffalse
1064 %</samplechap1>
1065 %\fi
1066 % Some text for chapter 2:
1067 %\iffalse
1068 %<*samplechap2>
1069 %\fi
1070 % \begin{macrocode}
1071 \section{two}
1072 more text in chapter two
1073 % \end{macrocode}
1074
1075 %\iffalse
1076 %</samplechap2>
1077 %\fi
1078 %
1079 % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1080 % \paragraph{Part Include Files.}
1081 %
1082 % The include files are called |cdocspt3.tex| and |cdocspt4.tex|.
1083 %
1084 %\iffalse
1085 %<*samplepart3|samplepart4>
1086 %\fi
1087
1088 % Optional override for |\version| flag:
1089 % \begin{macrocode}
1090 %%\providecommand{\version}{final}
1091 % \end{macrocode}
1092
1093 % Include the main document:
1094 % \begin{macrocode}
1095 \input{childdoc.def}
1096 \childdocby{cdocsamp}
1097 % \end{macrocode}
1098
1099 %\iffalse
1100 %</samplepart3|samplepart4>
1101 %\fi
1102 %
1103 %\iffalse
1104 %<*samplepart3>
1105 %\fi
1106 % Some text for part 3:
1107 % \begin{macrocode}
1108 some text in part three
1109 % \end{macrocode}
1110
1111 %\iffalse
1112 %</samplepart3>
1113 %\fi
1114 % Some text for part 4:
1115 %\iffalse
1116 %<*samplepart4>
1117 %\fi
1118 % \begin{macrocode}
1119 more text in part four
1120 % \end{macrocode}
1121
1122 %\iffalse
1123 %</samplepart4>
1124 %\fi
1125 %
1126 % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1127 % \paragraph{Forwarding for a Complete Draft.}
1128 %
1129 % The following forwarding file |cdocsdrf.tex|
1130 % compiles the main document in draft mode:
1131 %\iffalse
1132 %<*sampledraft>
1133 %\fi
1134 % \begin{macrocode}
1135 \def\version{draft}
1136 \input{childdoc.def}
1137 \childdocforward{cdocsamp}
1138 % \end{macrocode}
1139
1140 %\iffalse
1141 %</sampledraft>
1142 %\fi
1143 %
1144 % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1145 % \paragraph{Forwarding for Final Version of the Chapters.}
1146 %
1147 % The following forwarding files |cdocsfn1.tex| and |cdocsfn2.tex|
1148 % (with identical content)
1149 % compile the final versions of the child documents
1150 % |cdocsch1.tex| and |cdocsch2.tex|, respectively:
1151 %\iffalse
1152 %<*samplefinal>
1153 %\fi
1154 % \begin{macrocode}
1155 \def\version{final}
1156 \input{childdoc.def}
1157 \childdocforwardprefix[cdocsamp]{cdocsfn}{cdocsch}
1158 % \end{macrocode}
1159
1160 %\iffalse
1161 %</samplefinal>
1162 %\fi
1163 %
1164 % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1165 % \paragraph{Command Line Processing.}
1166 %
1167 % The following three command lines generate the output files
1168 % |cdocscld|, |cdocscl1| and |cdocscl2|
1169 % which should be identical to
1170 % |cdocsdrf|, |cdocsch1| and |cdocsfn2|, respectively:
1171 % \begin{center}
1172 % \begin{tabular}{l}
1173 % |latex -jobname cdocscld \|\\
1174 % | "\def\version{draft}\input{childdoc.def}\childdocforward{cdocsamp}"|\\
1175 % |latex -jobname cdocscl1 \|\\
1176 % | "\input{childdoc.def}\childdocforward[cdocsamp]{cdocsch1}"|\\
1177 % |latex -jobname cdocscl2 \|\\
1178 % | "\def\version{final}\input{childdoc.def}\childdocforward{cdocsch2}"|
1179 % \end{tabular}
1180 % \end{center}
1181 % Note that the trailing backslash on each first line
1182 % merely continues the input to the second line
1183 % (for convenient cut ant paste).
1184 % Furthermore, the command |latex| can be replaced by any
1185 % of its alternative versions such as |pdflatex|.
1186 %
1187 % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1188 % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1189 % \section{Implementation}
1190 %\iffalse
1191 %<*package>
1192 %\fi
1193 %
1194 % This section describes the definitions file |childdoc.def|.
1195
1196 % The definitions cannot be loaded using |\usepackage| or |\RequirePackage|
1197 % which has a mechanism to prevent loading a style file more than once.
1198 % When loading the definitions by means of |\input|
1199 % multiple instances have to be prevented manually:
1200 %\iffalse
1201 %This code needs to be before the `\ProvidesFile' directive
1202 %which is defined at the beginning of this file.
1203 %Therefore it is also placed there and commented out here.
1204 %</package>
1205 %<*discard>
1206 %\fi
1207 % \begin{macrocode}
1208 \ifdefined\childdocmain\endinput\fi
1209 % \end{macrocode}
1210 %\iffalse
1211 %</discard>
1212 %<*package>
1213 %\fi
1214 %
1215 % \macro{\ifchilddoc}
1216 % \macro{\ifchilddocmanual}
1217 % The conditional |\ifchilddoc| tells whether a
1218 % child (true) or main (false) document is being compiled.
1219 % The conditional |\ifchilddocmanual| tells whether
1220 % the |\includeonly| mechanism is used (false) or
1221 % the selection of child files must be performed manually (true).
1222 % The definitions initialise to false:
1223 % \begin{macrocode}
1224 \newif\ifchilddoc
1225 \newif\ifchilddocmanual
1226 % \end{macrocode}
1227
1228 % \macro{\childdocname}
1229 % \macro{\childdocjob}
1230 % The macro |\childdocname| stores the name of the main document
1231 % to be compiled. The macro |\childdocjob| stores the name of
1232 % the document on which the \LaTeX{} compiler was originally invoked.
1233 % The content of |\jobname| cannot be compared
1234 % to filenames specified in the source due to different catcodes.
1235 % The following code rescans |\jobname|, stores the result
1236 % in |\childdocname| and saves a copy in |\childdocjob|:
1237 % \begin{macrocode}
1238 \edef\childdocname{\scantokens\expandafter{\jobname\noexpand}}
1239 \let\childdocjob\childdocname
1240 % \end{macrocode}
1241
1242 % \macro{\childdocdisable}
1243 % The macro |\childdocdisable| prevents the main file
1244 % from being processed more than once.
1245 % At this stage, the main document command |\childdocmain|
1246 % is assumed to be called once again where it should do nothing.
1247 % Any subsequent call to it should prevent
1248 % a secondary processing of the main document
1249 % It overwrites the forwarding commands
1250 % |\childdocof| and |\childdocforward|
1251 % with empty macros to prevent further inclusions of the main document:
1252 % \begin{macrocode}
1253 \newcommand{\childdocdisable}
1254 {
1255 \renewcommand{\childdocmain}[1]{\renewcommand{\childdocmain}[1]{\endinput}}
1256 \renewcommand{\childdocof}[1]{}
1257 \renewcommand{\childdocby}[2][]{}
1258 \renewcommand{\childdocforward}[2][]{}
1259 \renewcommand{\childdocdisable}{}
1260 }
1261 % \end{macrocode}
1262
1263 % \macro{\childdocmain}
1264 % The macro |\childdocmain| is to be called at the top of the main file
1265 % with nothing or the main filename (without extension) as argument.
1266 % First, it breaks inclusion loops.
1267 % If the argument is not empty and does not match |\childdocname|
1268 % (which is set by the first inclusion of |childdoc.def|),
1269 % |\ifchilddoc| is set to true, |\includeonly| is applied to the child file
1270 % and |\jobname| is set to the main file
1271 % (for proper handling of |.aux| files):
1272 % \begin{macrocode}
1273 \newcommand{\childdocmain}[1]
1274 {
1275 \childdocdisable\childdocmain{}
1276 \if?#1?\else
1277 \begingroup
1278 \def\childdoctmp{#1}
1279 \ifx\childdoctmp\childdocname
1280 \def\childdoctmp{}
1281 \else
1282 \def\childdoctmp
1283 {
1284 \childdoctrue
1285 \includeonly{\childdocname}
1286 \def\childdocjob{#1}
1287 \def\jobname{#1}
1288 }
1289 \fi
1290 \expandafter
1291 \endgroup
1292 \childdoctmp
1293 \fi
1294 }
1295 % \end{macrocode}
1296
1297 % \macro{\childdocof}
1298 % The command |\childdocof| redirects
1299 % compilation to the main file |#1|.
1300 % \begin{macrocode}
1301 \newcommand{\childdocof}[1]
1302 {
1303 \childdocdisable
1304 \childdoctrue
1305 \includeonly{\childdocname}
1306 \def\jobname{#1}
1307 \def\childdocjob{#1}
1308 \input{#1}
1309 }
1310 % \end{macrocode}
1311
1312 % \macro{\childdocby}
1313 % The command |\childdocby| ....
1314 % \begin{macrocode}
1315 \newcommand{\childdocby}[2][]
1316 {
1317 \childdocdisable
1318 \childdoctrue
1319 \childdocmanualtrue
1320 \if?#1?\else
1321 \def\jobname{#2}
1322 \fi
1323 \def\childdocjob{#2}
1324 \input{#2}
1325 \endinput
1326 }
1327 % \end{macrocode}
1328
1329 % \macro{\childdocforward}
1330 % The command |\childdocforward| redirects
1331 % compilation to the main file or
1332 % (if the optional argument is given) a child file.
1333 % Parameters are set as if the main file
1334 % or a child file starting with |\childdocof| was compiled.
1335 % Then compilation is handed over to the main file:
1336 % \begin{macrocode}
1337 \newcommand{\childdocforward}[2][]
1338 {
1339 \begingroup
1340 \if?#1?
1341 \def\childdoctmp
1342 {
1343 \def\childdocname{#2}
1344 \def\childdocjob{#2}
1345 \def\jobname{#2}
1346 \input{#2}
1347 \endinput
1348 }
1349 \else
1350 \def\childdoctmp
1351 {
1352 \childdocdisable
1353 \def\childdocname{#2}
1354 \childdoctrue
1355 \includeonly{#2}
1356 \def\childdocjob{#1}
1357 \def\jobname{#1}
1358 \input{#1}
1359 \endinput
1360 }
1361 \fi
1362 \expandafter
1363 \endgroup
1364 \childdoctmp
1365 }
1366 % \end{macrocode}
1367
1368 % \macro{\childdocforwardprefix}
1369 % The command |\childdocforwardprefix| redirects
1370 % compilation to the main or a child file by means of a pattern.
1371 % The prefix |#1| in the current filename is replaced by |#2|
1372 % and the suffix of the current filename is kept
1373 % (it is assumed that the filename does not contain the substring `|~~~|'
1374 % which is used as a delimiter).
1375 % Compilation is handed over to the new file by |\childdocforward|:
1376 % \begin{macrocode}
1377 \newcommand{\childdocforwardprefix}[3][]
1378 {
1379 \begingroup
1380 \def\childdocextract #2##1~~~{\def\childdoctmp{\childdocforward[#1]{#3##1}}}
1381 \expandafter\childdocextract\childdocname~~~
1382 \expandafter
1383 \endgroup
1384 \childdoctmp
1385 }
1386 % \end{macrocode}
1387
1388 % \macro{\childdoc}
1389 % The deprecated macro |\childdoc| is a legacy version of |\childdocmain|:
1390 % \begin{macrocode}
1391 \newcommand{\childdoc}{\childdocmain}
1392 % \end{macrocode}
1393
1394 % \macro{\childdocredirect}
1395 % The deprecated macro |\childdocredirect| is a legacy version
1396 % of |\childdocforward| and |\childdocforwardprefix|:
1397 % \begin{macrocode}
1398 \newcommand{\childdocredirect}[2][]
1399 {
1400 \begingroup
1401 \if?#1?
1402 \def\childdoctmp{\childdocforward{#2}}
1403 \else
1404 \def\childdoctmp{\childdocforwardprefix{#1}{#2}}
1405 \fi
1406 \expandafter
1407 \endgroup
1408 \childdoctmp
1409 }
1410 % \end{macrocode}
1411
1412 %\iffalse
1413 %</package>
1414 %\fi
1415 %
1416 \endinput