diff options
Diffstat (limited to 'macros/latex/contrib/childdoc/childdoc.dtx')
| -rw-r--r-- | macros/latex/contrib/childdoc/childdoc.dtx | 1385 |
1 files changed, 1385 insertions, 0 deletions
diff --git a/macros/latex/contrib/childdoc/childdoc.dtx b/macros/latex/contrib/childdoc/childdoc.dtx new file mode 100644 index 0000000000..1d4c1c8715 --- /dev/null +++ b/macros/latex/contrib/childdoc/childdoc.dtx @@ -0,0 +1,1385 @@ +% \iffalse +% +% childdoc.dtx Copyright (C) 2017-2018 Niklas Beisert +% +% This work may be distributed and/or modified under the +% conditions of the LaTeX Project Public License, either version 1.3 +% of this license or (at your option) any later version. +% The latest version of this license is in +% http://www.latex-project.org/lppl.txt +% and version 1.3 or later is part of all distributions of LaTeX +% version 2005/12/01 or later. +% +% This work has the LPPL maintenance status `maintained'. +% +% The Current Maintainer of this work is Niklas Beisert. +% +% This work consists of the files childdoc.dtx and childdoc.ins +% and the derived files childdoc.def and cdocsamp.tex with +% cdocsch1.tex, cdocsch2.tex, cdocsdrf.tex, cdocsfn1.tex, cdocsfn2.tex. +% +%<package>\ifdefined\childdocmain\endinput\fi +%<package>\ProvidesFile{childdoc.def}[2018/12/30 v2.0 child document driver] +%<samplemain>\ProvidesFile{cdocsamp.tex}[2018/12/30 v2.0 sample for childdoc] +%<*driver> +%\ProvidesFile{childdoc.drv}[2018/12/30 v2.0 childdoc reference manual file] +\PassOptionsToClass{10pt,a4paper}{article} +\documentclass{ltxdoc} + +\usepackage[margin=35mm]{geometry} +\usepackage{hyperref} +\usepackage{hyperxmp} +\usepackage[usenames]{color} + +\hypersetup{colorlinks=true} +\hypersetup{pdfstartview=FitH} +\hypersetup{pdfpagemode=UseNone} +\hypersetup{pdfsource={}} +\hypersetup{pdflang={en-UK}} +\hypersetup{pdfcopyright={Copyright 2017-2018 Niklas Beisert. + This work may be distributed and/or modified under the + conditions of the LaTeX Project Public License, either version 1.3 + of this license or (at your option) any later version.}} +\hypersetup{pdflicenseurl={http://www.latex-project.org/lppl.txt}} +\hypersetup{pdfcontactaddress={ETH Zurich, ITP, HIT K, + Wolfgang-Pauli-Strasse 27}} +\hypersetup{pdfcontactpostcode={8093}} +\hypersetup{pdfcontactcity={Zurich}} +\hypersetup{pdfcontactcountry={Switzerland}} +\hypersetup{pdfcontactemail={nbeisert@itp.phys.ethz.ch}} +\hypersetup{pdfcontacturl={http://people.phys.ethz.ch/\xmptilde nbeisert/}} + +\newcommand{\secref}[1]{\hyperref[#1]{section \ref*{#1}}} + +\parskip1ex +\parindent0pt +\let\olditemize\itemize +\def\itemize{\olditemize\parskip0pt} + +\begin{document} + +\title{The \textsf{childdoc} Package} +\hypersetup{pdftitle={The childdoc Package}} +\author{Niklas Beisert\\[2ex] + Institut f\"ur Theoretische Physik\\ + Eidgen\"ossische Technische Hochschule Z\"urich\\ + Wolfgang-Pauli-Strasse 27, 8093 Z\"urich, Switzerland\\[1ex] + \href{mailto:nbeisert@itp.phys.ethz.ch} + {\texttt{nbeisert@itp.phys.ethz.ch}}} +\hypersetup{pdfauthor={Niklas Beisert}} +\hypersetup{pdfsubject={Manual for the LaTeX2e Package childdoc}} +\date{30 December 2018, \textsf{v2.0}} +\maketitle + +\begin{abstract}\noindent +\textsf{childdoc} is a \LaTeXe{} package +that enables the direct compilation +of document sections included by |\include| +to individual files. +\end{abstract} + +\begingroup +\parskip0ex +\tableofcontents +\endgroup + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\section{Introduction} + +\LaTeX{} provides a mechanism to structure a large document (such as a book) +into a main file and several child files (containing the chapters) +using the |\include| command. +This mechanism is beneficial for documents +which span hundreds of pages in order to +make the source file(s) more manageable. +Moreover, compilation can be restricted to +selected child files by means of the |\includeonly| command. +The latter feature can be used to reduce the compilation time while editing +(this was significantly more useful in the earlier days of \LaTeX{}) +or to generate a smaller document which is easier to navigate. +Another application of |\includeonly| is to generate +documents consisting of selected parts of the complete document. + +However, there are a few drawbacks of the plain |\include| mechanism: +\begin{itemize} +\item +The child files cannot be compiled on their own, +they can only be compiled via the main file. +A naive editing environment +(such as a text editor with an option +to have the current file processed by \LaTeX) +may require one to switch to the main file before compiling; +attempting to compile the child file produces errors. +\item +The main file must be modified (each time) +to adjust the |\includeonly| command +to the present needs. This easily leaves the main file in a messy state. +\item +The generated document will always carry the filename +of the main document. This is inconvenient if +several child files are to be compiled and +to be kept for distribution. +\end{itemize} + +The present package provides a simple interface +to make child files individually compilable by \LaTeX{}. +Compiling a child file then has the same effect as compiling +the main file with an |\includeonly| command +to select the appropriate child. +Moreover the generated document will carry the name of the child +rather than the main file. +This resolves all three above issues. + +This feature is meant to make the editing of books, +thesis documents and lecture notes somewhat more convenient. +However, the package can also be used efficiently for +composing a series of documents (such as exercise sheets) +which are typically distributed individually. +It then assists the author in generating the individual documents +(potentially in different versions) +as well as a document containing the collected series. +Another application is in developing style files +or other kinds of included material +where compilation of the style file could redirect +to a sample or test file. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\section{Usage} + +First of all, the package \textsf{childdoc} is \emph{not} a standard +\LaTeXe{} |.sty| style file! Therefore it needs to be invoked in +a non-standard way. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Included Files} +\label{sec:include} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\DescribeMacro{\childdocmain} +To use the package, add the commands +\begin{center} +\begin{tabular}{l} +|\input{childdoc.def}|\\ +|\childdocmain{}|\\ +\end{tabular} +\end{center} +at the very top of the main \LaTeX{} file, +in particular \emph{before} the |\documentclass| statement! +The argument of |\childdocmain| should be left empty +(but it must be present). + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\DescribeMacro{\childdocof} +Furthermore, add the commands +\begin{center} +\begin{tabular}{l} +|\input{childdoc.def}|\\ +|\childdocof{|\textit{main}|}|\\ +\end{tabular} +\end{center} +at the top of every child file \textit{child} +which is included by |\include{|\textit{child}|}| +from within the main file +(or at least for those files to be compiled individually). +The argument \textit{main} must be the filename of the main file. + +There are a couple of +considerations in setting up the main and child documents: + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\paragraph{Restrictions.} + +Please note the following restrictions: +\begin{itemize} +\item +|\childdocmain| must be called with one argument \textit{main} +to ensure compatibility with earlier version of the package. +It must either be empty (|\childdocmain{}|) +or precisely match the filename of the main file in which it is specified. +See \secref{sec:detection} for further information. +\item +The filename \textit{main} must be specified without the |.tex| extension. +\item +The filename \textit{main} is case sensitive +(even in case-insensitive file systems) +due to internal string comparison. +\item +The argument \textit{main} should be fully expanded, it cannot be a macro. +\item +Subdirectories and special characters should be avoided in filenames. +\item +The command |\childdocmain{|\textit{main}|}| must be followed by a whitespace. +It should not be followed immediately by another command +or by a comment mark `|%|'. +This is because the \TeX{} parser reads the token immediately following +the argument of |\childdocmain| and puts it +at the beginning of every child section; +however, a white\-space is ignored. +\end{itemize} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\paragraph{Content of Main File.} + +It is advisable to place all content in the child files included by |\include|. +Any output contained in the main file will appear in all child documents +unless suppressed manually; +it cannot be suppressed automatically by the |\includeonly| directive +and thus should normally be avoided. +A method to include some content in the main file +by means of conditional processing is described in \secref{sec:conditional}. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\paragraph{Page Numbering.} + +When only a part of the document is compiled, +the appropriate numbering of pages +(as well as other status parameters) +is determined from the |.aux| files. +The latter contain information from previous passes. +However this information needs to propagate through +all intermediate child documents. +Therefore the page numbering in child documents may well +be inconsistent until the complete document is compiled at least once. + +A useful (if unconventional) way to always ensure a consistent +page numbering is to restart the numbering in each child document +and denote the pages by `\textit{child}|.|\textit{page}' +where \textit{child} represents the chapter/section number of the child file. +This can be achieved by the command +|\numberwithin{page}{|\textit{child}|}| +of the \textsf{amsmath} package +where \textit{child} can be |chapter| or |section| +depending on the chosen structuring. +Alternatively, one can modify the macro |\thepage| appropriately +and reset the counter |page| at the start of each child file. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Conditional Processing} +\label{sec:conditional} + +The package provides a mechanism to compile different versions +of a document. To customise the versions further some conditional processing +can come in handy to distinguish which version is being compiled. +The package provides two macros to describe the compilation context: + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\DescribeMacro{\ifchilddoc} +The conditional |\ifchilddoc| distinguishes between the compilation of +child documents and the main document: +% +\begin{center} +|\ifchilddoc |\textit{child-code}| |[|\||else |\textit{main-code}]| \||fi| +\end{center} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\DescribeMacro{\childdocname} +\DescribeMacro{\childdocjob} +The macro |\childdocname| contains the filename (without extension) +of the main or child file being processed. +Note that |\childdocjob| will always contain the name of the main file. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\paragraph{Title Page.} + +Conditional processing can be used to include a title or banner page +in the main document when proper precautions are taken. +Importantly, the code in the main file should ensure that the page counter +(as well as other status parameters which are stored in the |.aux| files) +takes the same value after the conditional processing. +Otherwise the page numbers may take divergent values +depending on which part is compiled. + +For example, a title page could be declared by: +% +\begin{center} +\begin{tabular}{l} +|\ifchilddoc\||else|\\ +|\addtocounter{page}{-1}|\\ +\textit{code for title page}\\ +|\newpage|\\ +|\||fi| +\end{tabular} +\end{center} +% +A banner page for the child documents can be generated by: +% +\begin{center} +\begin{tabular}{l} +|\ifchilddoc|\\ +|\addtocounter{page}{-1}|\\ +\textit{code for banner page}\\ +|\newpage|\\ +|\||fi| +\end{tabular} +\end{center} +% +Here one could write a message such as: +\begin{center} +|This is the part \childdocname{} of \childdocjob{}.| +\end{center} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Flags} +\label{sec:flags} + +The package makes it easy to generate different versions +of the main or child documents. +To this end compilation flags can be defined +and assigned different default values. +They will be particularly useful in conjunction +with the forwarding mechanism described in \secref{sec:forward}. + +For example, it may be useful to have a flag |\version| +which can be set to |draft| or |final|. +The document source will contain some conditional code +depending on the value of |\version|. +Suppose further, the flag should default to |final| for the main file +and to |draft| for child files +which is a natural assignment for editing the document. +This is achieved by placing the following code +in the preamble of the main document +(below the |\childdocmain| directive): +% +\begin{center} +\begin{tabular}{l} +|\ifchilddoc|\\ +|\providecommand{\version}{draft}|\\ +|\||else|\\ +|\providecommand{\version}{final}|\\ +|\||fi| +\end{tabular} +\end{center} +% +The definition by |\providecommand| makes sure +that previous definitions are not overwritten. +Further statements |\providecommand{\version}{...}| +can thus be added before the above code to override it. + +For the main file, one might add a line +(between |\childdocmain| and the above block) +% +\begin{center} +|%\ifchilddoc\||else\providecommand{\version}{draft}\||fi| +\end{center} +% +which can be uncommented to produce a draft version. +Likewise one can add a line to the very top of a child file +(above the |\childdocof{|\textit{main}|}| directive) +% +\begin{center} +|%\providecommand{\version}{final}| +\end{center} +% +which can be uncommented to produce the final version of this child document. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Forwarding} +\label{sec:forward} + +Different versions of the main or child documents +using compilation flags as described in \secref{sec:flags} +can be (permanently) stored in different files +for convenient compilation, viewing and distribution. +To this end, the package defines a command +to pass on compilation to a different file: + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\DescribeMacro{\childdocforward} +The command |\childdocforward| redirects processing to +another source file: +% +\begin{center} +\begin{tabular}{l} +|\input{childdoc.def}|\\ +|\childdocforward[|\textit{main}|]{|\textit{dest}|}|\\ +\end{tabular} +\end{center} +% +The argument \textit{dest} is the destination file +(without extension). +It should be the main file or one of the child files. +Note that further \textsf{childdoc} directives +such as |\childdocof| and |\childdocforward| +in the indicated file will be processed in this form. +The optional argument \textit{main} +passes on directly to the main file \textit{main} +while pretending to compile the child \textit{dest}. +This form behaves as if \textit{dest} +issues |\childdocof{|\textit{main}|}| right away, +and no further \textsf{childdoc} directives will be processed. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\DescribeMacro{\...prefix} +In the alternative form |\childdocforwardprefix|, +% +\begin{center} +\begin{tabular}{l} +|\input{childdoc.def}|\\ +|\childdocforwardprefix[|\textit{main}|]{|\textit{prefix}|}{|\textit{dest}|}| +\end{tabular} +\end{center} +% +the destination file is determined by a pattern +depending on the current file: +To make this work, the current file must be called +`{\textit{prefix}\hspace{0.2em}\textit{suffix}}' +with \textit{prefix} matching precisely the argument. +Processing is then passed on to the file +`{\textit{dest}\hspace{0.2em}\textit{suffix}}'. +Surely, the same effect is achieved by +directly specifying the +argument `{\textit{dest}\hspace{0.2em}\textit{suffix}}' +in the first form. +However, that requires to set up a different file +for each child. With the alternative form of the command +all these files can have exactly the same content +which simplifies setting them up and maintaining them. + +For example, the following file |draft.tex| +with a compilation flag |\version| as described in \secref{sec:flags} +compiles the main document as a draft: +% +\begin{center} +\begin{tabular}{l} +|\def\version{draft}|\\ +|\input{childdoc.def}|\\ +|\childdocforward{|\textit{main}|}| +\end{tabular} +\end{center} +% +Likewise, the following files |final|\textit{nn}|.tex| +compile the final version of the child document +|child|\textit{nn}|.tex|: +% +\begin{center} +\begin{tabular}{l} +|\def\version{final}|\\ +|\input{childdoc.def}|\\ +|\childdocforwardprefix{final}{child}| +\end{tabular} +\end{center} +% + +Note that when several versions of a main file and/or of each child file +are to be generated, it may be convenient to set up a |Makefile| or +shell script to automatise the process. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Command Line Processing} +\label{sec:commandline} + +The effect of redirection files can also be achieved by invoking +the \LaTeX{} compiler with a more elaborate command line. +Most conveniently this should be done as part +of a shell script or a |Makefile|. + +When using \textsf{childdoc} in the main file, the following +command lines effectively perform a redirection +(note that depending on the shell being used, +backslashes may have to be doubled: `|\|' $\to$ `|\\|'): +% +\begin{center} +|... -jobname "|\textit{target}|" |\\|"|[\textit{flags}]% +|\input{childdoc.def}\childdocforward[|\textit{main}|]{|\textit{dest}|}"| +\end{center} +% +Here \textit{target} is the name of the output file, +\textit{main} is the name of the main file +and \textit{dest} is the name of the main or child file to be processed +(all filenames without extensions). +The optional argument \textit{main} can be omitted +if \textit{main} matches \textit{dest}. +Optionally, compilation \textit{flags} can be defined via |\def| commands. +This command line makes the \TeX{} engine believe +it is compiling the file \textit{target} +whose content is specified as the latter parameter. +The provided code then forwards the processing to +\textit{main} or \textit{dest} as described in \secref{sec:forward}. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Include by Input} +\label{sec:input} + +Including child documents by |\include| has some restrictions by design. +Most notably, the content of a child document always occupies +its own set of pages; pages cannot be shared between child documents. +Usually, this behaviour makes perfect sense +because each child document contain an essential part of the document. +However, in some situations it may be desirable to compose +a document from a collection of parts +without having mandatory page breaks between then. +For this case, the package +provides a mechanism to include parts +by |\input| which can also be processed individually. +However, by construction this mechanism +requires manual handling of the content to be output. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\DescribeMacro{\ifchilddocmanual} +The main file should be prepared as usual, see \secref{sec:include}. +However, the document body must make a distinction +between processing of an individual part and of the main document, e.g.: +% +\begin{center} +\begin{tabular}{l} +|\ifchilddocmanual|\\ +|\input{\childdocname}|\\ +|\||else|\\ +\textit{document body with }|\input{|\textit{part}|}|\\ +|\||fi| +\end{tabular} +\end{center} +% +The conditional |\ifchilddocmanual| is true whenever +a part to be included by |\input| is being compiled, +and the name of the part is stored in |\childdocname|. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\DescribeMacro{\childdocby} +Each part to be included by |\input| should start with: +% +\begin{center} +\begin{tabular}{l} +|\input{childdoc.def}|\\ +|\childdocby{|\textit{main}|}|\\ +\end{tabular} +\end{center} +% +The directive |\childdocby| is similar to |\childdocof| +described in \secref{sec:include}, +but the subsequent selection of content must be done manually. +To that end, both |\ifchilddoc| and |\ifchilddocmanual| +will be true upon processing of a part, +and the name of the part is stored in |\childdocname|. +Note that |\jobname| will be set to the filename of the current part +so that each part receives an individual |.aux| file +that does not interfere with the |.aux| file(s) of the main document. +This behaviour can be altered by the alternative form +|\childdocby[*]{|\textit{main}|}| (with a non-empty optional argument) +which uses the |.aux| file of the main document +by setting |\jobname| to \textit{main}. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Driver Development} +\label{sec:driver} + +The \textsf{childdoc} mechanism can also be use for the development +of definition files such as \LaTeX{} styles or classes. +This case differs from the above setup with multiple parts +included by |\include| in that no |\includeonly| should be invoked. +This can be achieved by starting the include file +(before |\ProvidesPackage|) with: +% +\begin{center} +\begin{tabular}{l} +|\input{childdoc.def}|\\ +|\childdocforward{|\textit{main}|}|\\ +\end{tabular} +\end{center} +% +or alternatively with: +% +\begin{center} +\begin{tabular}{l} +|\input{childdoc.def}|\\ +|\childdocby{|\textit{main}|}|\\ +\end{tabular} +\end{center} +% +Both forms have slightly different effects as described above. +The main file is prepared as usual, see \secref{sec:include}. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Legacy Detection} +\label{sec:detection} + +The directive |\childdocmain| in the main file can detect +whether the complete document or merely a child is to be compiled +even without using the directive |\childdocof|. +This method is deprecated because it is less robust +and there is no compelling reason to use it; +it is merely provided for backward compatibility +and it may be removed in future versions. + +If the detection mechanism is to be used, +it is mandatory to correctly specify +the filename of the main file as the argument of |\childdocmain|: +% +\begin{center} +\begin{tabular}{l} +|\input{childdoc.def}|\\ +|\childdocmain{|\textit{main}|}|\\ +\end{tabular} +\end{center} +% +If |\jobname| does not match the argument \textit{main} of |\childdocmain|, +it is assumed that |\jobname| points to the child file to be compiled. +When using |\childdocmain| with the main file specified as argument, +it suffices to start a child file +with just |\input{|\textit{main}|}| +without loading of the package and using |\childdocof|. +If instead all processing is done +with the appropriate \textsf{childdoc} directives, +the argument of \textit{main} of |\childdocmain| can be empty. + +An alternative version of the command line processing described +in \secref{sec:commandline} using the detection mechanism reads: +% +\begin{center} +|... -jobname "|\textit{target}|" "|[\textit{flags}]% +[|\def\jobname{|\textit{dest}|}|]|\input{|\textit{main}|}"| +\end{center} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Manual Code} +\label{sec:manual} + +In case one cannot be certain whether the definitions file |childdoc.def| +is installed on the target \TeX{} distribution +and one prefers not to ship it, +it is conceivable to paste a few relevant commands into the sources. + +To that end, drop all statements |\input{childdoc.def}| +and perform the replacements as outlined below. +Instead of |\childdocmain{|\textit{main}|}| add the following code +to the top of the main file: +% +\begin{center} +\begin{tabular}{l} +|\||ifdefined\childdocname\endinput\||fi\newif\ifchilddoc|\\ +|\edef\childdocname{\scantokens\expandafter{\jobname\noexpand}}|\\ +|\def\childdocmain{|\textit{main}|}\||ifx\childdocmain\childdocname\||else|\\ +|\childdoctrue\includeonly{\childdocname}\let\jobname\childdocmain\||fi|\\ +\end{tabular} +\end{center} +% +Instead of |\childdocof{|\textit{main}|}| just include the main file +at the top of each child file: +% +\begin{center} +|\input{|\textit{main}|}| +\end{center} +% +A simple redirection |\childdocforward{|\textit{dest}|}| is achieved by: +% +\begin{center} +|\def\jobname{|\textit{dest}|}\input{\jobname}| +\end{center} +% +The redirection with prefix +|\childdocforwardprefix[|\textit{prefix}|]{|\textit{dest}|}| +is accomplished by: +% +\begin{center} +\begin{tabular}{l} +|{\edef\jobname{\scantokens\expandafter{\jobname\noexpand}}|\\ +|\def\redirectjob |\textit{prefix}|#1~~~{\gdef\jobname{|\textit{dest}|#1}}|\\ +|\expandafter\redirectjob\jobname~~~}\input{\jobname}| +\end{tabular} +\end{center} + +In an alternative approach, +child documents can be compiled by a specific command line +without additional code or specific definitions: +% +\begin{center} +|... -jobname "|\textit{target}|" "|[\textit{flags}]% +|\includeonly{|\textit{dest}|}\input{|\textit{main}|}"| +\end{center} +% + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\section{Information} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Copyright} + +Copyright \copyright{} 2017--2018 Niklas Beisert + +This work may be distributed and/or modified under the +conditions of the \LaTeX{} Project Public License, either version 1.3 +of this license or (at your option) any later version. +The latest version of this license is in + \url{http://www.latex-project.org/lppl.txt} +and version 1.3 or later is part of all distributions of \LaTeX{} +version 2005/12/01 or later. + +This work has the LPPL maintenance status `maintained'. + +The Current Maintainer of this work is Niklas Beisert. + +This work consists of the files |README.txt|, |childdoc.ins| and |childdoc.dtx| +as well as the derived files |childdoc.def|, |cdocsamp.tex| +with |cdocsch1.tex|, |cdocsch2.tex|, |cdocspt3.tex|, |cdocspt4.tex|, +|cdocsdrf.tex|, |cdocsfn1.tex|, |cdocsfn2.tex| +as well as |childdoc.pdf|. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Files and Installation} + +The package consists of the files: +% +\begin{center} +\begin{tabular}{ll} + |README.txt| & readme file \\ + |childdoc.ins| & installation file \\ + |childdoc.dtx| & source file \\ + |childdoc.def| & definition file \\ + |cdocsamp.tex| & sample main file \\ + |cdocsch1.tex| & sample include file \\ + |cdocsch2.tex| & sample include file \\ + |cdocspt3.tex| & sample part file \\ + |cdocspt4.tex| & sample part file \\ + |cdocsdrf.tex| & sample redirection file \\ + |cdocsfn1.tex| & sample redirection file \\ + |cdocsfn2.tex| & sample redirection file \\ + |childdoc.pdf| & manual +\end{tabular} +\end{center} +% +The distribution consists of the files +|README.txt|, |childdoc.ins| and |childdoc.dtx|. +% +\begin{itemize} +\item +Run (pdf)\LaTeX{} on |childdoc.dtx| +to compile the manual |childdoc.pdf| (this file). +\item +Run \LaTeX{} on |childdoc.ins| to create the definitions file |childdoc.def| +and the sample |cdocsamp.tex| with include files +|cdocsch1.tex|, |cdocsch2.tex|, |cdocspt3.tex|, |cdocspt4.tex|, +|cdocsdrf.tex|, |cdocsfn1.tex|, |cdocsfn2.tex|. +Then copy the file |childdoc.def| to an appropriate directory of your \LaTeX{} +distribution, e.g.\ \textit{texmf-root}|/tex/latex/childdoc|. +\end{itemize} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Related CTAN Packages} + +There are several other packages which offer a similar functionality: +% +\begin{itemize} +\item +The packages +\href{http://ctan.org/pkg/docmute}{\textsf{docmute}}, +\href{http://ctan.org/pkg/includex}{\textsf{includex}} and +\href{http://ctan.org/pkg/standalone}{\textsf{standalone}} +provide commands to include only the document body of +a child file thus allowing both files to be compiled individually. +\item +The packages \href{http://ctan.org/pkg/subdocs}{\textsf{subdocs}} +and \href{http://ctan.org/pkg/subfiles}{\textsf{subfiles}} +provide structures in which the main and child documents can be +encapsulated and allowing them to be compiled individually. +The inclusion mechanism is different from the conventional |\include|. +\item +The package \href{http://ctan.org/pkg/combine}{\textsf{combine}} +is an elaborate solution to combine several documents into one. +\end{itemize} +% +See also the CTAN topic \href{http://ctan.org/topic/subdocs}{\textsf{subdocs}} +for further related packages. +The present package differs from the above solutions in that +a document structure constructed with the conventional |\include| mechanism +just needs two extra commands at the top of every file +such that all constituent files can be compiled individually. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%\subsection{Feature Suggestions} +% +%The following is a list of features which may be useful for future +%versions of this package: +%% +%\begin{itemize} +%\item +%\ldots +%\end{itemize} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Revision History} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\paragraph{v2.0:} 2018/12/30 + +\begin{itemize} +\item +immediate forward processing +\item +added |\childdocby| mechanism +\item +manual restructured +\end{itemize} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\paragraph{v1.6:} 2018/01/17 + +\begin{itemize} +\item +application for development of include files +\item +corrections to manual +\end{itemize} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\paragraph{v1.5:} 2017/05/21 + +\begin{itemize} +\item +more complete structuring introduced +\item +|\childdocof| introduced +\item +|\childdoc| renamed to |\childdocmain| +\item +|\childredirect| renamed to |\childdocforward| and |\childdocforwardprefix| +and functionality expanded +\end{itemize} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\paragraph{v1.0:} 2017/04/27 + +\begin{itemize} +\item +manual and install package +\item +first version published on CTAN +\end{itemize} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\paragraph{v0.6:} 2017/04/26 + +\begin{itemize} +\item +redirection mechanism added +\end{itemize} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\paragraph{v0.5:} 2017/04/26 + +\begin{itemize} +\item +functionality in definition file +\end{itemize} + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\appendix + +\settowidth\MacroIndent{\rmfamily\scriptsize 000\ } + + \DocInput{childdoc.dtx} + +\end{document} +%</driver> +% \fi +% +% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% \section{Sample} +%\iffalse +%<*samplemain> +%\fi +% +% The following presents a sample document +% with two chapters, two parts, a title page, +% a compile flag as well as three forwarding files to set the flag. +% It consists of eight |.tex| files: +% \begin{center} +% \begin{tabular}{ll} +% |cdocsamp.tex|&main file\\ +% |cdocsch1.tex|&include file for chapter 1\\ +% |cdocsch2.tex|&include file for chapter 2\\ +% |cdocspt3.tex|&include file for part 3\\ +% |cdocspt4.tex|&include file for part 4\\ +% |cdocsdrf.tex|&forwarding file for main file in draft mode\\ +% |cdocsfi1.tex|&forwarding file for final version of chapter 1\\ +% |cdocsfi2.tex|&forwarding file for final version of chapter 2\\ +% \end{tabular} +% \end{center} +% Each of the eight files can be compiled directly by the \LaTeX{} compiler. +% +% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% \paragraph{Main File.} +% +% The main file is called |cdocsamp.tex|. +% +% Load the \textsf{childdoc} definitions and +% declare the filename for the main document: +% \begin{macrocode} +\input{childdoc.def} +\childdocmain{} +% \end{macrocode} + +% Optional override for |\version| flag: +% \begin{macrocode} +%%\ifchilddoc\else\providecommand{\version}{draft}\fi +% \end{macrocode} + +% Define the default values for the |\version| flag +% (|final| for the main file and |draft| for childs): +% \begin{macrocode} +\ifchilddoc +\providecommand{\version}{draft} +\else +\providecommand{\version}{final} +\fi +% \end{macrocode} + +% Load the standard document class: +% \begin{macrocode} +\documentclass[12pt]{article} +% \end{macrocode} + +% Start the document body: +% \begin{macrocode} +\begin{document} +% \end{macrocode} + +% Declare a title page. +% Print title, part of document being processed and version flag: +% \begin{macrocode} +\addtocounter{page}{-1} +\begin{center} +{\LARGE\bfseries{}childdoc example\par} +\vspace{1cm} +\ifchilddoc +\ifchilddocmanual part\else chapter\fi: +`\childdocname' of `\childdocjob'\par +\else +main document: `\childdocjob'\par +\fi +version: \version\par +\end{center} +\newpage +% \end{macrocode} + +% Manually include selected file, +% otherwise process as usual: +% \begin{macrocode} +\ifchilddocmanual +\section*{part `\childdocname'} +\input{\childdocname} +\else +% \end{macrocode} + +% Include the two chapters: +% \begin{macrocode} +\include{cdocsch1} +\include{cdocsch2} +% \end{macrocode} + +% Include the two parts unless only chapters should be displayed: +% \begin{macrocode} +\ifchilddoc\else +\section{part three} +\input{cdocspt3} +\section{part four} +\input{cdocspt4} +\fi +% \end{macrocode} + +% Process as usual until here: +% \begin{macrocode} +\fi +% \end{macrocode} + +% End of document body: +% \begin{macrocode} +\end{document} +% \end{macrocode} +%\iffalse +%</samplemain> +%\fi +% +% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% \paragraph{Chapter Include Files.} +% +% The include files are called |cdocsch1.tex| and |cdocsch2.tex|. +% +%\iffalse +%<*samplechap1|samplechap2> +%\fi + +% Optional override for |\version| flag: +% \begin{macrocode} +%%\providecommand{\version}{final} +% \end{macrocode} + +% Include the main document: +% \begin{macrocode} +\input{childdoc.def} +\childdocof{cdocsamp} +% \end{macrocode} + +%\iffalse +%</samplechap1|samplechap2> +%\fi +% +%\iffalse +%<*samplechap1> +%\fi +% Some text for chapter 1: +% \begin{macrocode} +\section{one} +some text in chapter one +% \end{macrocode} + +%\iffalse +%</samplechap1> +%\fi +% Some text for chapter 2: +%\iffalse +%<*samplechap2> +%\fi +% \begin{macrocode} +\section{two} +more text in chapter two +% \end{macrocode} + +%\iffalse +%</samplechap2> +%\fi +% +% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% \paragraph{Part Include Files.} +% +% The include files are called |cdocspt3.tex| and |cdocspt4.tex|. +% +%\iffalse +%<*samplepart3|samplepart4> +%\fi + +% Optional override for |\version| flag: +% \begin{macrocode} +%%\providecommand{\version}{final} +% \end{macrocode} + +% Include the main document: +% \begin{macrocode} +\input{childdoc.def} +\childdocby{cdocsamp} +% \end{macrocode} + +%\iffalse +%</samplepart3|samplepart4> +%\fi +% +%\iffalse +%<*samplepart3> +%\fi +% Some text for part 3: +% \begin{macrocode} +some text in part three +% \end{macrocode} + +%\iffalse +%</samplepart3> +%\fi +% Some text for part 4: +%\iffalse +%<*samplepart4> +%\fi +% \begin{macrocode} +more text in part four +% \end{macrocode} + +%\iffalse +%</samplepart4> +%\fi +% +% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% \paragraph{Forwarding for a Complete Draft.} +% +% The following forwarding file |cdocsdrf.tex| +% compiles the main document in draft mode: +%\iffalse +%<*sampledraft> +%\fi +% \begin{macrocode} +\def\version{draft} +\input{childdoc.def} +\childdocforward{cdocsamp} +% \end{macrocode} + +%\iffalse +%</sampledraft> +%\fi +% +% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% \paragraph{Forwarding for Final Version of the Chapters.} +% +% The following forwarding files |cdocsfn1.tex| and |cdocsfn2.tex| +% (with identical content) +% compile the final versions of the child documents +% |cdocsch1.tex| and |cdocsch2.tex|, respectively: +%\iffalse +%<*samplefinal> +%\fi +% \begin{macrocode} +\def\version{final} +\input{childdoc.def} +\childdocforwardprefix[cdocsamp]{cdocsfn}{cdocsch} +% \end{macrocode} + +%\iffalse +%</samplefinal> +%\fi +% +% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% \paragraph{Command Line Processing.} +% +% The following three command lines generate the output files +% |cdocscld|, |cdocscl1| and |cdocscl2| +% which should be identical to +% |cdocsdrf|, |cdocsch1| and |cdocsfn2|, respectively: +% \begin{center} +% \begin{tabular}{l} +% |latex -jobname cdocscld \|\\ +% | "\def\version{draft}\input{childdoc.def}\childdocforward{cdocsamp}"|\\ +% |latex -jobname cdocscl1 \|\\ +% | "\input{childdoc.def}\childdocforward[cdocsamp]{cdocsch1}"|\\ +% |latex -jobname cdocscl2 \|\\ +% | "\def\version{final}\input{childdoc.def}\childdocforward{cdocsch2}"| +% \end{tabular} +% \end{center} +% Note that the trailing backslash on each first line +% merely continues the input to the second line +% (for convenient cut ant paste). +% Furthermore, the command |latex| can be replaced by any +% of its alternative versions such as |pdflatex|. +% +% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% \section{Implementation} +%\iffalse +%<*package> +%\fi +% +% This section describes the definitions file |childdoc.def|. + +% The definitions cannot be loaded using |\usepackage| or |\RequirePackage| +% which has a mechanism to prevent loading a style file more than once. +% When loading the definitions by means of |\input| +% multiple instances have to be prevented manually: +%\iffalse +%This code needs to be before the `\ProvidesFile' directive +%which is defined at the beginning of this file. +%Therefore it is also placed there and commented out here. +%</package> +%<*discard> +%\fi +% \begin{macrocode} +\ifdefined\childdocmain\endinput\fi +% \end{macrocode} +%\iffalse +%</discard> +%<*package> +%\fi +% +% \macro{\ifchilddoc} +% \macro{\ifchilddocmanual} +% The conditional |\ifchilddoc| tells whether a +% child (true) or main (false) document is being compiled. +% The conditional |\ifchilddocmanual| tells whether +% the |\includeonly| mechanism is used (false) or +% the selection of child files must be performed manually (true). +% The definitions initialise to false: +% \begin{macrocode} +\newif\ifchilddoc +\newif\ifchilddocmanual +% \end{macrocode} + +% \macro{\childdocname} +% \macro{\childdocjob} +% The macro |\childdocname| stores the name of the main document +% to be compiled. The macro |\childdocjob| stores the name of +% the document on which the \LaTeX{} compiler was originally invoked. +% The content of |\jobname| cannot be compared +% to filenames specified in the source due to different catcodes. +% The following code rescans |\jobname|, stores the result +% in |\childdocname| and saves a copy in |\childdocjob|: +% \begin{macrocode} +\edef\childdocname{\scantokens\expandafter{\jobname\noexpand}} +\let\childdocjob\childdocname +% \end{macrocode} + +% \macro{\childdocdisable} +% The macro |\childdocdisable| prevents the main file +% from being processed more than once. +% At this stage, the main document command |\childdocmain| +% is assumed to be called once again where it should do nothing. +% Any subsequent call to it should prevent +% a secondary processing of the main document +% It overwrites the forwarding commands +% |\childdocof| and |\childdocforward| +% with empty macros to prevent further inclusions of the main document: +% \begin{macrocode} +\newcommand{\childdocdisable} +{ + \renewcommand{\childdocmain}[1]{\renewcommand{\childdocmain}[1]{\endinput}} + \renewcommand{\childdocof}[1]{} + \renewcommand{\childdocby}[2][]{} + \renewcommand{\childdocforward}[2][]{} + \renewcommand{\childdocdisable}{} +} +% \end{macrocode} + +% \macro{\childdocmain} +% The macro |\childdocmain| is to be called at the top of the main file +% with nothing or the main filename (without extension) as argument. +% First, it breaks loops. +% If the argument is not empty and does not match |\childdocname| +% (which is set by the first inclusion of |childdoc.def|), +% |\ifchilddoc| is set to true, |\includeonly| is applied to the child file +% and |\jobname| is set to the main file +% (for proper handling of |.aux| files): +% \begin{macrocode} +\newcommand{\childdocmain}[1] +{ + \childdocdisable\childdocmain{} + \if?#1?\else + \begingroup + \def\childdoctmp{#1} + \ifx\childdoctmp\childdocname + \def\childdoctmp{} + \else + \def\childdoctmp + { + \childdoctrue + \includeonly{\childdocname} + \def\childdocjob{#1} + \def\jobname{#1} + } + \fi + \expandafter + \endgroup + \childdoctmp + \fi +} +% \end{macrocode} + +% \macro{\childdocof} +% The command |\childdocof| redirects +% compilation to the main file |#1|. +% \begin{macrocode} +\newcommand{\childdocof}[1] +{ + \childdocdisable + \childdoctrue + \includeonly{\childdocname} + \def\jobname{#1} + \def\childdocjob{#1} + \input{#1} +} +% \end{macrocode} + +% \macro{\childdocby} +% The command |\childdocby| .... +% \begin{macrocode} +\newcommand{\childdocby}[2][] +{ + \childdocdisable + \childdoctrue + \childdocmanualtrue + \if?#1?\else + \def\jobname{#2} + \fi + \def\childdocjob{#2} + \input{#2} + \endinput +} +% \end{macrocode} + +% \macro{\childdocforward} +% The command |\childdocforward| redirects +% compilation to the main file or +% (if the optional argument is given) a child file. +% Parameters are set as if the main file +% or a child file starting with |\childdocof| was compiled. +% Then compilation is handed over to the main file: +% \begin{macrocode} +\newcommand{\childdocforward}[2][] +{ + \begingroup + \if?#1? + \def\childdoctmp + { + \def\childdocname{#2} + \def\childdocjob{#2} + \def\jobname{#2} + \input{#2} + \endinput + } + \else + \def\childdoctmp + { + \childdocdisable + \def\childdocname{#2} + \childdoctrue + \includeonly{#2} + \def\childdocjob{#1} + \def\jobname{#1} + \input{#1} + \endinput + } + \fi + \expandafter + \endgroup + \childdoctmp +} +% \end{macrocode} + +% \macro{\childdocforwardprefix} +% The command |\childdocforwardprefix| redirects +% compilation to the main or a child file by means of a pattern. +% The prefix |#1| in the current filename is replaced by |#2| +% and the suffix of the current filename is kept +% (it is assumed that the filename does not contain the substring `|~~~|' +% which is used as a delimiter). +% Compilation is handed over to the new file by |\childdocforward|: +% \begin{macrocode} +\newcommand{\childdocforwardprefix}[3][] +{ + \begingroup + \def\childdocextract #2##1~~~{\def\childdoctmp{\childdocforward[#1]{#3##1}}} + \expandafter\childdocextract\childdocname~~~ + \expandafter + \endgroup + \childdoctmp +} +% \end{macrocode} + +% \macro{\childdoc} +% The deprecated macro |\childdoc| is a legacy version of |\childdocmain|: +% \begin{macrocode} +\newcommand{\childdoc}{\childdocmain} +% \end{macrocode} + +% \macro{\childdocredirect} +% The deprecated macro |\childdocredirect| is a legacy version +% of |\childdocforward| and |\childdocforwardprefix|: +% \begin{macrocode} +\newcommand{\childdocredirect}[2][] +{ + \begingroup + \if?#1? + \def\childdoctmp{\childdocforward{#2}} + \else + \def\childdoctmp{\childdocforwardprefix{#1}{#2}} + \fi + \expandafter + \endgroup + \childdoctmp +} +% \end{macrocode} + +%\iffalse +%</package> +%\fi +% +\endinput |