summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/childdoc
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2018-12-30 22:12:08 +0000
committerKarl Berry <karl@freefriends.org>2018-12-30 22:12:08 +0000
commit0632da102dc59ec2ad6a0c69397fd7a3c4a03393 (patch)
treeb069979372d8a5ad481b361e764ccf1b0bf25bcd /Master/texmf-dist/source/latex/childdoc
parent5a8b5044b55dfb4e76f990eb433c7e229906c162 (diff)
childdoc (30dec18)
git-svn-id: svn://tug.org/texlive/trunk@49543 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex/childdoc')
-rw-r--r--Master/texmf-dist/source/latex/childdoc/childdoc.dtx753
-rw-r--r--Master/texmf-dist/source/latex/childdoc/childdoc.ins2
2 files changed, 534 insertions, 221 deletions
diff --git a/Master/texmf-dist/source/latex/childdoc/childdoc.dtx b/Master/texmf-dist/source/latex/childdoc/childdoc.dtx
index fb2c42fb291..1d4c1c87155 100644
--- a/Master/texmf-dist/source/latex/childdoc/childdoc.dtx
+++ b/Master/texmf-dist/source/latex/childdoc/childdoc.dtx
@@ -19,10 +19,10 @@
% cdocsch1.tex, cdocsch2.tex, cdocsdrf.tex, cdocsfn1.tex, cdocsfn2.tex.
%
%<package>\ifdefined\childdocmain\endinput\fi
-%<package>\ProvidesFile{childdoc.def}[2018/01/17 v1.6 child document driver]
-%<samplemain>\ProvidesFile{cdocsamp.tex}[2018/01/17 v1.6 sample for childdoc]
+%<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/01/17 v1.6 childdoc reference manual file]
+%\ProvidesFile{childdoc.drv}[2018/12/30 v2.0 childdoc reference manual file]
\PassOptionsToClass{10pt,a4paper}{article}
\documentclass{ltxdoc}
@@ -41,13 +41,21 @@
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{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}
@@ -60,7 +68,7 @@
{\texttt{nbeisert@itp.phys.ethz.ch}}}
\hypersetup{pdfauthor={Niklas Beisert}}
\hypersetup{pdfsubject={Manual for the LaTeX2e Package childdoc}}
-\date{17 January 2018, \textsf{v1.6}}
+\date{30 December 2018, \textsf{v2.0}}
\maketitle
\begin{abstract}\noindent
@@ -70,7 +78,10 @@ of document sections included by |\include|
to individual files.
\end{abstract}
+\begingroup
+\parskip0ex
\tableofcontents
+\endgroup
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@@ -137,47 +148,57 @@ to a sample or test file.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Usage}
-The package \textsf{childdoc} is \emph{not} a standard
+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.
-\DescribeMacro{\childdoc}
-To use the package add the commands
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Included Files}
+\label{sec:include}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\DescribeMacro{\childdocmain}
+To use the package, add the commands
\begin{center}
\begin{tabular}{l}
|\input{childdoc.def}|\\
-|\childdocmain{|\textit{main}|}|\\
+|\childdocmain{}|\\
\end{tabular}
\end{center}
-at the very top of your main \LaTeX{} file,
+at the very top of the main \LaTeX{} file,
in particular \emph{before} the |\documentclass| statement!
-Furthermore, you must add the command
+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 which is included by |\include|
+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 which you would like to compile individually).
-In each case, the argument \textit{main}
-must be the filename of the main file.
-Alternatively, it suffices to start a child file
-with just |\input{|\textit{main}|}|;
-this has the same effect,
-but the nesting of included files is slightly different.
-Note that the closed loop generated by
-this combination of |\input| and |\include| commands
-is broken by |\childdocmain|.
+(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
-The argument \textit{main} of |\childdocmain| must match the
-filename of the file in which it is specified.
-This is necessary because \TeX{} does not store the name
-of files included via |\input|.
+|\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
@@ -198,21 +219,16 @@ at the beginning of every child section;
however, a white\-space is ignored.
\end{itemize}
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{Considerations}
-
-Let us mentions a couple of
-consideration in setting up the main and child documents:
-
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\paragraph{Content of Main File.}
-It is advisable to place all output in the child files included by |\include|.
-Any output contained in the main file will appear in all child documents;
-it cannot be suppressed by the |\includeonly| directive
+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.
-Below we shall describe a method to include some output in the main file
-by means of conditional processing.
+A method to include some content in the main file
+by means of conditional processing is described in \secref{sec:conditional}.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\paragraph{Page Numbering.}
@@ -239,27 +255,9 @@ 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.
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\paragraph{Include Files.}
-
-The \textsf{childdoc} mechanism can also be use for the development
-of include files such as \LaTeX{} styles or classes,
-but also other material included by |\input|.
-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 by:
-%
-\begin{center}
-\begin{tabular}{l}
-|\input{childdoc.def}|\\
-|\childdocforward{|\textit{main}|}|\\
-\end{tabular}
-\end{center}
-%
-The main file is prepared as described above.
-
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\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
@@ -267,8 +265,6 @@ can come in handy to distinguish which version is being compiled.
The package provides two macros to describe the compilation context:
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\medskip
-\noindent
\DescribeMacro{\ifchilddoc}
The conditional |\ifchilddoc| distinguishes between the compilation of
child documents and the main document:
@@ -278,18 +274,16 @@ child documents and the main document:
\end{center}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\medskip
-\noindent
\DescribeMacro{\childdocname}
+\DescribeMacro{\childdocjob}
The macro |\childdocname| contains the filename (without extension)
of the main or child file being processed.
-Note that |\jobname| will always contain the name of the main file.
+Note that |\childdocjob| will always contain the name of the main file.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\paragraph{Title Page.}
-For example,
-conditional processing can be used to include a title or banner 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)
@@ -323,22 +317,21 @@ A banner page for the child documents can be generated by:
%
Here one could write a message such as:
\begin{center}
-|This is the part \childdocname{} of \jobname.|
+|This is the part \childdocname{} of \childdocjob{}.|
\end{center}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{Flags and Forwarding}
+\subsection{Flags}
+\label{sec:flags}
-The package allows to easily generate different versions
-of the main or child documents
-and to (permanently) store these in different files.
+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}.
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\paragraph{Defining Flags.}
-
-Suppose we want to define a flag |\version|
+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|.
@@ -359,11 +352,10 @@ in the preamble of the main document
\end{tabular}
\end{center}
%
-By using |\providecommand| we make sure that previous definitions
-are not overwritten.
-We can thus add further statements
-|\providecommand{\version}{...}|
-before the above code to override it.
+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)
@@ -382,38 +374,59 @@ Likewise one can add a line to the very top of a child file
%
which can be uncommented to produce the final version of this child document.
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\paragraph{Forwarding.}
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\subsection{Forwarding}
+\label{sec:forward}
-Once compilation flags are defined, we can permanently set up files
-to produce certain versions of the documents.
+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:
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\medskip
-\noindent
\DescribeMacro{\childdocforward}
-\DescribeMacro{\childdocforwardprefix}
-The commands |\childdocforward|[|prefix|] redirect processing to
-the another source file:
+The command |\childdocforward| redirects processing to
+another source file:
%
\begin{center}
\begin{tabular}{l}
+|\input{childdoc.def}|\\
|\childdocforward[|\textit{main}|]{|\textit{dest}|}|\\
-|\childdocforwardprefix[|\textit{main}|]{|\textit{prefix}|}{|\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.
-In the second form,
+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}}'
-and processing is passed on to the file
+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
@@ -423,11 +436,9 @@ 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.
-Finally, the optional argument \textit{main}
-allows to pass on directly to the main file \textit{main}
-while pretending to compile \textit{dest}.
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}
@@ -452,12 +463,178 @@ compile the final version of the child document
%
Note that when several versions of a main file and/or of each child file
-are to be generated, it will be convenient to set up a |Makefile| or
+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
@@ -503,50 +680,15 @@ is accomplished by:
\end{tabular}
\end{center}
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{Command Line Processing}
-
-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 line effectively performs a redirection
-(note that depending on the shell being used,
-backslashes may have to be doubled: `|\|' $\to$ `|\\|')
-%
-\begin{center}
-|... -jobname "|\textit{target}|" "|[\textit{flags}]%
-|\def\jobname{|\textit{dest}|}\input{|\textit{main}|}"|
-\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).
-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 in turn tweaks the definition of |\jobname| to \textit{dest}
-which is later passed on to |\includeonly| by |\childdocmain|
-and then hands over to the main file \textit{main}.
-
-In fact, a similar effect can be achieved
-without the \textsf{childdoc} mechanism
-by using the command line:
+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}
%
-However, some of the functionality of \textsf{childdoc} is lost,
-e.g.\ child documents cannot be processed individually
-and the conditional |\ifchilddoc| is not defined.
-
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@@ -555,10 +697,6 @@ and the conditional |\ifchilddoc| is not defined.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Copyright}
-\begingroup
-\parskip1ex
-\parindent0pt
-
Copyright \copyright{} 2017--2018 Niklas Beisert
This work may be distributed and/or modified under the
@@ -575,11 +713,9 @@ 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|,
+with |cdocsch1.tex|, |cdocsch2.tex|, |cdocspt3.tex|, |cdocspt4.tex|,
|cdocsdrf.tex|, |cdocsfn1.tex|, |cdocsfn2.tex|
-and |childdoc.pdf|.
-
-\endgroup
+as well as |childdoc.pdf|.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Files and Installation}
@@ -595,6 +731,8 @@ The package consists of the files:
|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 \\
@@ -612,8 +750,9 @@ 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|, |cdocsdrf.tex|, |cdocsfn1.tex|, |cdocsfn2.tex|.
-Copy the file |childdoc.def| to an appropriate directory of your \LaTeX{}
+|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}
@@ -656,13 +795,25 @@ such that all constituent files can be compiled individually.
%%
%\begin{itemize}
%\item
-% explain how to use for style files
+%\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}
@@ -706,7 +857,7 @@ redirection mechanism added
\end{itemize}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\paragraph{v0.5:} 2016/04/26
+\paragraph{v0.5:} 2017/04/26
\begin{itemize}
\item
@@ -720,8 +871,6 @@ functionality in definition file
\appendix
\settowidth\MacroIndent{\rmfamily\scriptsize 000\ }
-\parskip1ex
-\parindent0pt
\DocInput{childdoc.dtx}
@@ -736,20 +885,23 @@ functionality in definition file
%<*samplemain>
%\fi
%
-% Here we present a sample document with two chapters, a title page,
+% 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 six |.tex| files:
+% 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 six files can be compiled directly by the \LaTeX{} compiler.
+% Each of the eight files can be compiled directly by the \LaTeX{} compiler.
%
% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% \paragraph{Main File.}
@@ -760,7 +912,7 @@ functionality in definition file
% declare the filename for the main document:
% \begin{macrocode}
\input{childdoc.def}
-\childdocmain{cdocsamp}
+\childdocmain{}
% \end{macrocode}
% Optional override for |\version| flag:
@@ -795,23 +947,47 @@ functionality in definition file
\begin{center}
{\LARGE\bfseries{}childdoc example\par}
\vspace{1cm}
-part:
\ifchilddoc
-`\childdocname' of `\jobname'\par
+\ifchilddocmanual part\else chapter\fi:
+`\childdocname' of `\childdocjob'\par
\else
-main\par
+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}
@@ -870,6 +1046,53 @@ more text in chapter two
%\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|
@@ -907,6 +1130,29 @@ more text in chapter two
%</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}
@@ -914,118 +1160,181 @@ more text in chapter two
%<*package>
%\fi
%
-% In this section we describe the definitions file |childdoc.def|.
+% 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|
-% we have to prevent multiple instances manually:
+% 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
+\ifdefined\childdocmain\endinput\fi
% \end{macrocode}
+%\iffalse
+%</discard>
+%<*package>
+%\fi
%
-% \begin{macro}{\ifchilddoc}
+% \macro{\ifchilddoc}
+% \macro{\ifchilddocmanual}
% The conditional |\ifchilddoc| tells whether a
% child (true) or main (false) document is being compiled.
-% The definition initialises to false:
+% 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}
-% \end{macro}
-% \begin{macro}{\childdocname}
-% The macro |\childdocname| stores the name of the document
-% to be compiled. The content of |\jobname| cannot be compared
+% \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| and stores the result in
-% in |\childdocname|:
+% 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}
-% \end{macro}
-
-% \begin{macro}{\childdocmain}
-% The macro |\childdocmain| is to be called at the top of the
-% main file with the main filename (without extension) as argument.
-% First, it overwrites its own definition to end processing of the
-% present file (|\endinput|) on subsequent calls.
-% It also overwrites the definition of |\childdocof| and |\childdocforward|
-% to prevent further inclusions of the main document.
-% This prevents the main file from being processed more than once.
-% Then the current filename is compared to the main filename
-% and in case of mismatch |\ifchilddoc| is set to true.
-% In that case |\includeonly| is applied to the child file
-% and |\jobname| is set to the main file
-% (for proper handling of |.aux| files):
+
+% \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{\childdocmain}[1]
+\newcommand{\childdocdisable}
{
- \renewcommand{\childdocmain}[1]{\endinput}
+ \renewcommand{\childdocmain}[1]{\renewcommand{\childdocmain}[1]{\endinput}}
\renewcommand{\childdocof}[1]{}
+ \renewcommand{\childdocby}[2][]{}
\renewcommand{\childdocforward}[2][]{}
- \begingroup
- \def\childdoctmp{#1}
- \ifx\childdocname\childdoctmp
- \def\childdoctmp{\childdocfalse}
- \else
- \def\childdoctmp{\childdoctrue}
- \fi
- \expandafter
- \endgroup
- \childdoctmp
- \ifchilddoc
- \includeonly{\childdocname}
- \def\jobname{#1}
- \fi
+ \renewcommand{\childdocdisable}{}
}
% \end{macrocode}
-% \end{macro}
-% \begin{macro}{\childdoc}
-% The deprecated macro |\childdoc| is a legacy version of |\childdocmain|:
+% \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{\childdoc}{\childdocmain}
+\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}
-% \end{macro}
-% \begin{macro}{\childdocof}
+% \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}
-% \end{macro}
-% \begin{macro}{\childdocforward}
+% \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 or a child file.
-% |\jobname| and |\childdocname| are set to the new filename
-% and compilation is handed over to the new file:
+% 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][]
{
- \def\jobname{#2}
- \def\childdocname{#2}
\begingroup
- \def\childdoctmp{#1}
- \def\childdocempty{}
- \ifx\childdoctmp\childdocempty
- \def\childdoctmp{\input{#2}}
+ \if?#1?
+ \def\childdoctmp
+ {
+ \def\childdocname{#2}
+ \def\childdocjob{#2}
+ \def\jobname{#2}
+ \input{#2}
+ \endinput
+ }
\else
- \def\childdoctmp{\input{#1}}
+ \def\childdoctmp
+ {
+ \childdocdisable
+ \def\childdocname{#2}
+ \childdoctrue
+ \includeonly{#2}
+ \def\childdocjob{#1}
+ \def\jobname{#1}
+ \input{#1}
+ \endinput
+ }
\fi
\expandafter
\endgroup
\childdoctmp
- \endinput
}
% \end{macrocode}
-% \end{macro}
-% \begin{macro}{\childdocforwardprefix}
+% \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|
@@ -1044,18 +1353,21 @@ more text in chapter two
\childdoctmp
}
% \end{macrocode}
-% \end{macro}
-% \begin{macro}{\childdocredirect}
+% \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
- \def\childdoctmp{#1}
- \def\childdocempty{}
- \ifx\childdoctmp\childdocempty
+ \if?#1?
\def\childdoctmp{\childdocforward{#2}}
\else
\def\childdoctmp{\childdocforwardprefix{#1}{#2}}
@@ -1065,7 +1377,6 @@ more text in chapter two
\childdoctmp
}
% \end{macrocode}
-% \end{macro}
%\iffalse
%</package>
diff --git a/Master/texmf-dist/source/latex/childdoc/childdoc.ins b/Master/texmf-dist/source/latex/childdoc/childdoc.ins
index 700ec85d111..dbee687c9ef 100644
--- a/Master/texmf-dist/source/latex/childdoc/childdoc.ins
+++ b/Master/texmf-dist/source/latex/childdoc/childdoc.ins
@@ -32,6 +32,8 @@ version 2005/12/01 or later.
\file{cdocsamp.tex}{\from{childdoc.dtx}{samplemain}}
\file{cdocsch1.tex}{\from{childdoc.dtx}{samplechap1}}
\file{cdocsch2.tex}{\from{childdoc.dtx}{samplechap2}}
+\file{cdocspt3.tex}{\from{childdoc.dtx}{samplepart3}}
+\file{cdocspt4.tex}{\from{childdoc.dtx}{samplepart4}}
\file{cdocsdrf.tex}{\from{childdoc.dtx}{sampledraft}}
\file{cdocsfn1.tex}{\from{childdoc.dtx}{samplefinal}}
\file{cdocsfn2.tex}{\from{childdoc.dtx}{samplefinal}}