| 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 |