summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/childdoc
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2017-06-06 21:56:06 +0000
committerKarl Berry <karl@freefriends.org>2017-06-06 21:56:06 +0000
commitae5c3b73315e3e216f364fa80bc292037be5f590 (patch)
treeb5776df6912612108fa86512b5387a084ebdf9f4 /Master/texmf-dist/source/latex/childdoc
parent5974e2228b3df4e0ad1256bec5eacef9e0b4842e (diff)
childdoc (22may17)
git-svn-id: svn://tug.org/texlive/trunk@44512 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex/childdoc')
-rw-r--r--Master/texmf-dist/source/latex/childdoc/childdoc.dtx265
1 files changed, 199 insertions, 66 deletions
diff --git a/Master/texmf-dist/source/latex/childdoc/childdoc.dtx b/Master/texmf-dist/source/latex/childdoc/childdoc.dtx
index bf2880d658b..d000d60cb22 100644
--- a/Master/texmf-dist/source/latex/childdoc/childdoc.dtx
+++ b/Master/texmf-dist/source/latex/childdoc/childdoc.dtx
@@ -18,10 +18,11 @@
% and the derived files childdoc.def and cdocsamp.tex with
% cdocsch1.tex, cdocsch2.tex, cdocsdrf.tex, cdocsfn1.tex, cdocsfn2.tex.
%
-%<package>\ProvidesFile{childdoc.def}[2017/04/27 v1.0 child document driver]
-%<samplemain>\ProvidesFile{cdocsamp.tex}[2017/04/27 v1.0 sample for childdoc]
+%<package>\ifdefined\childdocmain\endinput\fi
+%<package>\ProvidesFile{childdoc.def}[2017/05/21 v1.5 child document driver]
+%<samplemain>\ProvidesFile{cdocsamp.tex}[2017/05/21 v1.5 sample for childdoc]
%<*driver>
-%\ProvidesFile{childdoc.drv}[2017/04/27 v1.0 childdoc reference manual file]
+%\ProvidesFile{childdoc.drv}[2017/05/21 v1.5 childdoc reference manual file]
\PassOptionsToClass{10pt,a4paper}{article}
\documentclass{ltxdoc}
@@ -45,7 +46,7 @@
{\texttt{nbeisert@itp.phys.ethz.ch}}}
\hypersetup{pdfauthor={Niklas Beisert}}
\hypersetup{pdfsubject={Manual for the LaTeX2e Package childdoc}}
-\date{27 April 2017, \textsf{v1.0}}
+\date{21 May 2017, \textsf{v1.5}}
\maketitle
\begin{abstract}\noindent
@@ -128,28 +129,35 @@ To use the package add the commands
\begin{center}
\begin{tabular}{l}
|\input{childdoc.def}|\\
-|\childdoc{|\textit{main}|}|\\
+|\childdocmain{|\textit{main}|}|\\
\end{tabular}
\end{center}
at the very top of your main \LaTeX{} file,
in particular \emph{before} the |\documentclass| statement!
Furthermore, you must add the command
\begin{center}
-|\input{|\textit{main}|}|
+\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|
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 |\childdoc|.
+is broken by |\childdocmain|.
Please note the following restrictions:
\begin{itemize}
\item
-The argument \textit{main} of |\childdoc| must match the
+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|.
@@ -164,11 +172,11 @@ 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 |\childdoc| must be followed by a whitespace.
+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 |\childdoc| and puts it
+the argument of |\childdocmain| and puts it
at the beginning of every child section;
however, a whitespace is ignored.
\end{itemize}
@@ -283,7 +291,7 @@ Here one could write a message such as:
\end{center}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\subsection{Flags and Redirection}
+\subsection{Flags and Forwarding}
The package allows to easily generate different versions
of the main or child documents
@@ -303,7 +311,7 @@ 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 |\childdoc| directive):
+(below the |\childdocmain| directive):
%
\begin{center}
\begin{tabular}{l}
@@ -322,7 +330,7 @@ We can thus add further statements
before the above code to override it.
For the main file, one might add a line
-(between |\childdoc| and the above block)
+(between |\childdocmain| and the above block)
%
\begin{center}
|%\ifchilddoc\||else\providecommand{\version}{draft}\||fi|
@@ -330,7 +338,7 @@ For the main file, one might add a line
%
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 |\input{|\textit{main}|}| directive)
+(above the |\childdocof{|\textit{main}|}| directive)
%
\begin{center}
|%\providecommand{\version}{final}|
@@ -339,7 +347,7 @@ 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{Redirection.}
+\paragraph{Forwarding.}
Once compilation flags are defined, we can permanently set up files
to produce certain versions of the documents.
@@ -349,18 +357,22 @@ to pass on compilation to a different file:
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\medskip
\noindent
-\DescribeMacro{\childdocredirect}
+\DescribeMacro{\childdocforward}
+\DescribeMacro{\childdocforwardprefix}
The command |\childdocredirect| redirects processing to
the another source file:
%
\begin{center}
-|\childdocredirect[|\textit{prefix}|]{|\textit{dest}|}|
+\begin{tabular}{l}
+|\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.
-When the optional argument \textit{prefix} is given,
+In the second form,
the destination file is determined by a pattern
depending on the current file:
To make this work, the current file must be called
@@ -370,11 +382,14 @@ and processing is passed on to the file
Surely, the same effect is achieved by
directly specifying the
argument `{\textit{dest}\hspace{0.2em}\textit{suffix}}'
-without optional argument.\
+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.
+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|
compiles the main document as a draft:
@@ -415,7 +430,7 @@ 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 |\childdoc{|\textit{main}|}| add the following code
+Instead of |\childdocmain{|\textit{main}|}| add the following code
to the top of the main file:
%
\begin{center}
@@ -427,14 +442,21 @@ to the top of the main file:
\end{tabular}
\end{center}
%
-A simple redirection |\childdocredirect{|\textit{dest}|}| is achieved by:
+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 by pattern
-|\childdocredirect[|\textit{prefix}|]{|\textit{dest}|}|
+The redirection with prefix
+|\childdocforwardprefix[|\textit{prefix}|]{|\textit{dest}|}|
is accomplished by:
%
\begin{center}
@@ -473,7 +495,7 @@ 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 |\childdoc|
+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
@@ -559,6 +581,37 @@ 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
@@ -573,6 +626,21 @@ distribution, e.g.\ \textit{texmf-root}|/tex/latex/childdoc|.
\subsection{Revision History}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\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}
@@ -604,7 +672,7 @@ functionality in definition file
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\appendix
-\settowidth\MacroIndent{\rmfamily\scriptsize 00\ }
+\settowidth\MacroIndent{\rmfamily\scriptsize 000\ }
\parskip1ex
\parindent0pt
@@ -622,16 +690,16 @@ functionality in definition file
%\fi
%
% Here we present a sample document with two chapters, a title page,
-% a compile flag as well as three redirection files to set the flag.
+% a compile flag as well as three forwarding files to set the flag.
% It consists of six |.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\\
-% |cdocsdrf.tex|&redirection file for main file in draft mode\\
-% |cdocsfi1.tex|&redirection file for final version of chapter 1\\
-% |cdocsfi2.tex|&redirection file for final version of chapter 2\\
+% |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.
@@ -645,7 +713,7 @@ functionality in definition file
% declare the filename for the main document:
% \begin{macrocode}
\input{childdoc.def}
-\childdoc{cdocsamp}
+\childdocmain{cdocsamp}
% \end{macrocode}
% Optional override for |\version| flag:
@@ -721,12 +789,14 @@ version: \version\par
% Include the main document:
% \begin{macrocode}
-\input{cdocsamp}
+\input{childdoc.def}
+\childdocof{cdocsamp}
% \end{macrocode}
+
%\iffalse
%</samplechap1|samplechap2>
%\fi
-
+%
%\iffalse
%<*samplechap1>
%\fi
@@ -753,9 +823,9 @@ more text in chapter two
%\fi
%
% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-% \paragraph{Redirection for a Complete Draft.}
+% \paragraph{Forwarding for a Complete Draft.}
%
-% The following redirection file |cdocsdrf.tex|
+% The following forwarding file |cdocsdrf.tex|
% compiles the main document in draft mode:
%\iffalse
%<*sampledraft>
@@ -763,7 +833,7 @@ more text in chapter two
% \begin{macrocode}
\def\version{draft}
\input{childdoc.def}
-\childdocredirect{cdocsamp}
+\childdocforward{cdocsamp}
% \end{macrocode}
%\iffalse
@@ -771,9 +841,9 @@ more text in chapter two
%\fi
%
% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-% \paragraph{Redirection for Final Version of the Chapters.}
+% \paragraph{Forwarding for Final Version of the Chapters.}
%
-% The following redirection files |cdocsfn1.tex| and |cdocsfn2.tex|
+% 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:
@@ -783,7 +853,7 @@ more text in chapter two
% \begin{macrocode}
\def\version{final}
\input{childdoc.def}
-\childdocredirect[cdocsfn]{cdocsch}
+\childdocforwardprefix[cdocsamp]{cdocsfn}{cdocsch}
% \end{macrocode}
%\iffalse
@@ -798,15 +868,15 @@ more text in chapter two
%\fi
%
% In this section we describe 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:
% \begin{macrocode}
-\ifdefined\childdoc\endinput\fi
+%\ifdefined\childdocmain\endinput\fi
% \end{macrocode}
-
+%
% \begin{macro}{\ifchilddoc}
% The conditional |\ifchilddoc| tells whether a
% child (true) or main (false) document is being compiled.
@@ -829,28 +899,34 @@ more text in chapter two
% \end{macrocode}
% \end{macro}
-% \begin{macro}{\childdoc}
-% The macro |\childdoc| is to be called at the top of the
+% \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|
+% 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
+% In that case |\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}[1]
+\newcommand{\childdocmain}[1]
{
- \def\childdoc##1{\endinput}
- {
+ \def\childdocmain##1{\endinput}
+ \def\childdocof##1{}
+ \begingroup
\def\childdoctmp{#1}
- \ifx\childdocname\childdoctmp\else
- \global\childdoctrue
+ \ifx\childdocname\childdoctmp
+ \def\childdoctmp{\childdocfalse}
+ \else
+ \def\childdoctmp{\childdoctrue}
\fi
- }
+ \expandafter
+ \endgroup
+ \childdoctmp
\ifchilddoc
\includeonly{\childdocname}
\def\jobname{#1}
@@ -859,31 +935,88 @@ more text in chapter two
% \end{macrocode}
% \end{macro}
-% \begin{macro}{\childdocredirect}
-% The command |\childdocredirect| redirects
-% compilation to the main or a child file |#2|.
-% If the optional argument |#1| is given,
-% the prefix |#1| in the current filename is replaced by |#2|
+% \begin{macro}{\childdoc}
+% The deprecated macro |\childdoc| is a legacy version of |\childdocmain|:
+% \begin{macrocode}
+\newcommand{\childdoc}{\childdocmain}
+% \end{macrocode}
+% \end{macro}
+
+% \begin{macro}{\childdocof}
+% The command |\childdocof| redirects
+% compilation to the main file |#1|.
+% \begin{macrocode}
+\newcommand{\childdocof}[1]
+{
+ \input{#1}
+}
+% \end{macrocode}
+% \end{macro}
+
+% \begin{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:
+% \begin{macrocode}
+\newcommand{\childdocforward}[2][]
+{
+ \def\jobname{#2}
+ \def\childdocname{#2}
+ \begingroup
+ \def\childdoctmp{#1}
+ \def\childdocempty{}
+ \ifx\childdoctmp\childdocempty
+ \def\childdoctmp{\input{#2}}
+ \else
+ \def\childdoctmp{\input{#1}}
+ \fi
+ \expandafter
+ \endgroup
+ \childdoctmp
+ \endinput
+}
+% \end{macrocode}
+% \end{macro}
+
+% \begin{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).
-% Finally, |\jobname| and |\childdocname| are set to the new filename
-% and compilation is handed over to the new file:
+% 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}
+% \end{macro}
+
+% \begin{macro}{\childdocredirect}
+% The deprecated command |\childdocredirect| is a legacy version
+% of |\childdocforward| and |\childdocforwardprefix|:
% \begin{macrocode}
\newcommand{\childdocredirect}[2][]
{
- {
+ \begingroup
\def\childdoctmp{#1}
\def\childdocempty{}
\ifx\childdoctmp\childdocempty
- \gdef\jobname{#2}
+ \def\childdoctmp{\childdocforward{#2}}
\else
- \def\childdocextract #1##1~~~{\gdef\jobname{#2##1}}
- \expandafter\childdocextract\childdocname~~~
+ \def\childdoctmp{\childdocforwardprefix{#1}{#2}}
\fi
- }
- \let\childdocname\jobname
- \input{\jobname}
- \endinput
+ \expandafter
+ \endgroup
+ \childdoctmp
}
% \end{macrocode}
% \end{macro}