summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/subfiles
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /macros/latex/contrib/subfiles
Initial commit
Diffstat (limited to 'macros/latex/contrib/subfiles')
-rw-r--r--macros/latex/contrib/subfiles/README7
-rw-r--r--macros/latex/contrib/subfiles/subfiles.dtx176
-rw-r--r--macros/latex/contrib/subfiles/subfiles.ins60
-rw-r--r--macros/latex/contrib/subfiles/subfiles.pdfbin0 -> 231568 bytes
4 files changed, 243 insertions, 0 deletions
diff --git a/macros/latex/contrib/subfiles/README b/macros/latex/contrib/subfiles/README
new file mode 100644
index 0000000000..ef27bf62ee
--- /dev/null
+++ b/macros/latex/contrib/subfiles/README
@@ -0,0 +1,7 @@
+subfiles - class and package for multi-file projects in LaTeX
+
+Author: Federico Garcia
+
+This material is subject to the LaTeX Project Public License. See
+http://www.ctan.org/tex-archive/help/Catalogue/licenses.lppl.html
+for the details of that license.
diff --git a/macros/latex/contrib/subfiles/subfiles.dtx b/macros/latex/contrib/subfiles/subfiles.dtx
new file mode 100644
index 0000000000..1033a03e98
--- /dev/null
+++ b/macros/latex/contrib/subfiles/subfiles.dtx
@@ -0,0 +1,176 @@
+% \iffalse meta-comment
+%
+% subfiles - class and package for multi-file projects in LaTeX
+% Copyright 2002, 2012 Federico Garcia (feg8@pitt.edu, fedegarcia@hotmail.com)
+% Copyright 2018 Gernot Salzer (salzer@logic.at)
+%
+% 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 Gernot Salzer.
+%
+% This work consists of the files subfiles.dtx and subfiles.ins
+% and the derived files subfiles.sty and subfiles.pdf
+%
+% -------------------------------------------
+%
+%<*driver>
+% \fi
+\ProvidesFile{subfiles.dtx}[2018/07/31 v1.2 Multi-file projects]
+% \iffalse
+\documentclass{ltxdoc}
+\GetFileInfo{subfiles.dtx}
+\title{A Document Class and a Package for handling multi-files projects}
+\date{\filedate{}}
+ \author{Federico Garcia\\{\small (v1.2 update by Gernot Salzer)}}
+
+\begin{document}
+\maketitle
+ \DocInput{\filename}
+\end{document}
+%</driver>
+% \fi
+% \begin{abstract}
+% With the |subfiles| set, the typesetting of a multi-file project consisting of one main file and one or more subsidiary files (subfiles) is more comfortable, since the user can \LaTeX\ either the main file, which will |\input| the subfiles normally, or the subfiles by themselves, which take the preamble of the main file and become self-sufficient \LaTeX\ documents.
+% \end{abstract}
+% \section{Introduction}
+% \LaTeX\ commands |\include| and |\input| allow for the creation of different input files to be typeset jointly into a single output. The advantages of this are evident in the creation of large documents with many chapters, but there are also other circumstances in which the author might want to use this feature. I have used it particularly for long-coded examples, tables, figures, etc\@.\footnote{In my case most times it has been musical examples, whose code in MusiX\TeX\ is long, intrincate, and barely readable.}, which require a considerable amount of trial-and-error.
+%
+% In this process the rest of the document is of little use, and it can even disturb.\footnote{For example, the error messages indicate not only a wrong line number, but even the wrong file.} Frequently, one ends up wanting to work \emph{only} on the new file, which means following three steps:
+%
+% \begin{itemize}
+% \item Create a new file, and copy-paste in it the preamble of the main file;
+% \item Work in the example, typeset it \emph{alone} as many times as necessary;
+% \item When the result is satisfactory, delete the preamble from the new file (and the |\end{document}|!), and |\include| or (more frequently) |\input| it from the main file.
+% \end{itemize}
+%
+% It is desirable to reduce these three steps to the only interesting one, the middle one. This would mean that each new, subordinated file (henceforth, `subfile') should be \emph{both} part of a project and a self-sufficient \LaTeX\ document, depending on whether it is \LaTeX ed or |\included|/|\input|. This is what the set of class and package under the name |subfiles| is intended for.
+%
+% The main idea behind it is the redefinition of |\documentclass| and the |document| environment; while these two features of \LaTeX\ are important to keep unchanged, |subfiles| changes them, as far as I know, harmlessly, and I have took care of undoing the changes when finished. This is the first version of |subfiles|, and although I have tried it a few times, it is still susceptible to conflicts with other packages and/or classes. (In fact, a conflict with the |revtex4| class later gave rise to version 1.2 of the package.)
+%
+% \section{Usage}
+%
+% \subsection{Setting up}
+%
+% The files involved have the following basic structures:
+%
+% \begin{center}\small
+% \begin{tabular}{ll}
+% \multicolumn{1}{c}{\emph{MAIN FILE}} & \multicolumn{1}{c}{\emph{SUBFILE}}\\
+% \qquad\meta{some preamble} & |\documentclass[|\meta{main\_file\_name}|]{subfiles}|\\
+% |\usepackage{subfiles}| & |\begin{document}|\\
+% |\begin{document}| & \qquad\meta{text, graphics, etc.}\\
+% \qquad\meta{text}&|\end{document}|\\
+% |\subfile{|\meta{subfile\_name}|}|\\
+% \qquad\meta{more text}\\
+% |\end{document}|
+% \end{tabular}
+% \end{center}
+%
+% The |subfiles| package is to be loaded in the main file of a \LaTeX\ project at the end of the preamble, and the |subfiles| class is to be loaded by each subordinate file. Note that the |subfiles| class handles only \emph{one} `option' (whose presence is actually mandatory), the name of the main file. The name should be given according to \TeX\ conventions: |.tex| is the default extension; the path has to be indicated (|/|, not |\|) if the main file is in a different directory from the subfile; spaces are gobbled (at least under Windows).
+%
+% \subsection{Results}
+% This done, \LaTeX ing either the main or the subordinate file produces the following results:
+% \begin{itemize}
+% \item If the subfile is typeset by itself, it takes as preamble the one of the main file (including its |\documentclass|). The rest is typeset normally.
+% \item If the subordinated file was |\subfile|'d, it ignores everything before and including |\begin{document}|, and then ignores |\end{document}| too. (The body of the file, nothing else, is effectively |\input|.)
+% \end{itemize}
+%
+% The |\subfile| command is more like |\input| than |\include| in the sense that it does not start a new page. It allows nesting, but there is no exclusion mechanism analogous to |\includeonly|.
+%
+% \subsection{Further details and warnings}
+%
+% To be precise, a subfile typeset by itself does not exactly take the preamble of the main file, but \emph{everything outside} \verb|\begin{document}| and \verb|\end{document}|. This has two consequences: $a)$~the user can add some commands to be read only when the subfiles are typeset by themselves---which in any case are processed as part of the preamble; but also $b)$~the user has to be careful even \emph{after} |\end{document}| (in the main file), for any syntax error there will ruin the \LaTeX ing of the subfile(s).
+%
+% The preamble of the main file can |\input| (not |\include| nor |\subfile|) other files (e.g.\ files with definitions and shorthand-commands), and the subfiles will too. But it has to be kept in mind that each subfile is |\input| within a group, so definitions made within them might not work outside. A good practice when using |subfiles| (and also when not using it) is to make any definitions in the preamble of the main file, avoiding confusion and allowing to find them easily.
+%
+% In principle, nesting files with |\subfile| should work and has worked in my tries, as far as every subfile loads the main file as its option to the |subfiles| class. However, who knows, the behavior can be unpredictable in weird situations. In any case, |subfiles| does \emph{not} disable |\include| nor |\input|, which remain available for free use.
+%
+% The |subfiles| package requires the |verbatim| package (whose |comment| environment is used to ignore the different parts of different files); this should not be a problem since it makes part of the standard distribution of \LaTeX $2_\varepsilon$.
+%
+% \subsection{Version history}
+%
+% \begin{description}
+% \item[v1.1:] Start of version history. Written by Federico Garcia.
+% \item[v1.2:] The |subfiles| package is now compatible with classes and packages that modify the |\document| command, like the class |revtex4|. Modification by Gernot Salzer.
+% \end{description}
+%
+%\section{The Implementation}
+%\subsection{The class}
+% \begin{macrocode}
+%<*class>
+\NeedsTeXFormat{LaTeX2e}
+\ProvidesClass{subfiles}[2018/07/31 Federico Garcia, Gernot Salzer]
+\DeclareOption*{\typeout{Preamble taken from file `\CurrentOption'}%
+ \let\preamble@file\CurrentOption}
+\ProcessOptions
+% \end{macrocode}
+%
+% The first thing to do is to save the regular \LaTeX\ definition of |\documentclass|:
+% \begin{macrocode}
+\let\old@documentclass@subfiles\documentclass
+% \end{macrocode}
+%
+% Now |\documentclass|, after having already loaded |subfiles.cls|, is set equal to |\LoadClass| such that the class and the options of the main file will be loaded identically.
+% \begin{macrocode}
+\let\documentclass\LoadClass\relax
+% \end{macrocode}
+%
+% Now it is possible to |\input| the main file. The main file loads the package |subfiles| as part of the preamble, which saves the contents of |\document| and |\enddocument| as |\old@document@subfiles| and |\old@enddocument@subfiles|, respectively. After having loaded the main file, we can restore the original values of |\document|, |\enddocument| and |\documentclass|. The backup commands are |\undefined| to save memory. That's it.
+% \begin{macrocode}
+\input{\preamble@file}
+{\catcode`\@=11
+\global\let\document\old@document@subfiles
+\global\let\enddocument\old@enddocument@subfiles
+\global\let\documentclass\old@documentclass@subfiles
+\global\let\old@document@subfiles\undefined
+\global\let\old@enddocument@subfiles\undefined
+\global\let\old@documentclass@subfiles\undefined}
+%</class>
+% \end{macrocode}
+%
+% It may not be obvious why |@| has to be catcoded to a letter, since we are in a style file anyway. However, the |\preamble@file| occasionally contains |\usepackage| commands that make |@| a non-letter. This is why the part after loading the main preamble needs a |\catcode| command, grouping, and |\global|'s.
+%
+% \subsection{The package}
+% Any option will be ignored.
+% \begin{macrocode}
+%<*package>
+\NeedsTeXFormat{LaTeX2e}
+\ProvidesPackage{subfiles}[2018/07/31 Federico Garcia, Gernot Salzer]
+\DeclareOption*{\PackageWarning{\CurrentOption ignored}}
+\ProcessOptions
+\RequirePackage{verbatim}
+% \end{macrocode}
+%
+% \DescribeMacro{\skip@preamble}
+% The core of the package. It works by redefining the |document| environment, thus making |\begin{document}| and |\end{document}| of the subfile transparent to the inclusion. The redefinition of |\documentclass| is analogous, just having a required and an optional arguments which mean nothing to |\subfile|.
+% \begin{macrocode}
+\newcommand{\skip@preamble}{%
+ \let\document\relax\let\enddocument\relax%
+ \newenvironment{document}{}{}%
+ \renewcommand{\documentclass}[2][subfiles]{}}
+% \end{macrocode}
+%
+% \DescribeMacro{\subfile}
+% Note that the new command |\subfile| calls for |\skip@preamble| \emph{within a group}. The changes to |document| and |\documentclass| are undone after the inclusion of the subfile.
+% \begin{macrocode}
+\newcommand\subfile[1]{\begingroup\skip@preamble\input{#1}\endgroup}
+% \end{macrocode}
+% If the package is being processed as part of the main file, then we are done. However, if the initial document class was |subfiles|, then the main file is loaded as part of a subfile. In this case the subsequent text between |\begin{document}| and |\end{document}| has to be skipped, but the contents of the commands |\document| and |\enddocument| has to be retained for using it with the contents of the subfile. Therefore we save the contents of the two commands as |\old@document@subfiles| and |\old@enddocument@subfiles|, respectively. Now the |document| environment is redefined to become the |comment| environment from the |verbatim| package. As a consequence, the body of the main file is ignored by \LaTeX, and only the preamble is read (and anything that comes after |\end{document}|!).
+% \begin{macrocode}
+\@ifclassloaded{subfiles}{%
+ \let\old@document@subfiles\document
+ \let\old@enddocument@subfiles\enddocument
+ \let\document\comment
+ \let\enddocument\endcomment
+}{}
+%</package>
+% \end{macrocode}
+% By loading the |subfiles| package immediately before |\begin{document}| we ensure that |\old@document@subfiles| and |\old@enddocument@subfiles| contain all modifications that the class and the preamble of the main file may have applied to the |document| environment. E.g., the class |revtex4| prepends some commands to |\document|. \ No newline at end of file
diff --git a/macros/latex/contrib/subfiles/subfiles.ins b/macros/latex/contrib/subfiles/subfiles.ins
new file mode 100644
index 0000000000..f188c09f37
--- /dev/null
+++ b/macros/latex/contrib/subfiles/subfiles.ins
@@ -0,0 +1,60 @@
+% subfiles - class and package for multi-file projects in LaTeX
+% Copyright 2002, 2012 Federico Garcia (feg8@pitt.edu, fedegarcia@hotmail.com)
+% Copyright 2018 Gernot Salzer (salzer@logic.at)
+%
+% 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 Gernot Salzer.
+%
+% This work consists of the files subfiles.dtx and subfiles.ins
+% and the derived files subfiles.sty and subfiles.pdf
+\input docstrip.tex
+
+\keepsilent
+\preamble
+
+This is a generated file.
+
+Copyright 2002, 2012 Federico Garcia; 2018 Gernot Salzer
+
+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 Gernot Salzer (salzer@logic.at).
+
+This work consists of the files subfiles.dtx and subfiles.ins
+and the derived files subfiles.sty and subfiles.pdf
+
+\endpreamble
+\generate{\file{subfiles.cls}{\from{subfiles.dtx}{class}}
+ \file{subfiles.sty}{\from{subfiles.dtx}{package}}
+ }
+
+\Msg{***********************************************************}
+\Msg{*}
+\Msg{* To finish the installation you have to move the files}
+\Msg{* `subfiles.cls' and `subfiles.sty' into a directory}
+\Msg{* searched by TeX.}
+\Msg{*}
+\Msg{* To produce the documentation run the file `subfiles.dtx'}
+\Msg{* through LaTeX.}
+\Msg{*}
+\Msg{***********************************************************}
+
+
+\endbatchfile
diff --git a/macros/latex/contrib/subfiles/subfiles.pdf b/macros/latex/contrib/subfiles/subfiles.pdf
new file mode 100644
index 0000000000..b3c3d0fcf1
--- /dev/null
+++ b/macros/latex/contrib/subfiles/subfiles.pdf
Binary files differ