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