path: root/macros/latex/contrib/subfiles/subfiles.dtx

% \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, 2019 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}[2019/10/30 v1.5 Multi-file projects]
% \iffalse
\documentclass{ltxdoc}
\GetFileInfo{subfiles.dtx}
\title{A Document Class and a Package\\for Handling Multi-File Projects}
\date{v1.5 2019/10/30}
\author{Federico Garcia, Gernot Salzer}

\begin{document}
\maketitle
 \DocInput{\filename}
\end{document}
%</driver>
% \fi
% \begin{abstract}
%   The |subfiles| package allows authors to split a document into one main file and one and more subsidiary files (subfiles) akin to the |\input| command, with the added benefit of making the subfiles compilable by themselves.
%   This is achieved by reusing the preamble of the main file also for the subfiles.
% \end{abstract}
% \section{Introduction}
% The \LaTeX\ commands |\include| and |\input| allow the user to split the \TeX\ source of a document into several input files.
% This is useful when creating documents with many chapters, but also for handling large tables, figures, and code samples, which require a considerable amount of trial-and-errors.
%
% In this process the rest of the document is of little use, and can even interfere.
% For example, error messages may indicate not only the wrong line number, but may point to the wrong file.
% Frequently, one ends up wanting to work only on the new file:
% 
% \begin{itemize}
% \item Create a new file, and copy-paste the preamble of the main file into it.
% \item Work on this file, typeset it \emph{alone} as many times as necessary.
% \item Finally, when the result is satisfactory, delete the preamble from the file (alongside with |\end{document}|!), and |\include| or |\input| it from the main file.
% \end{itemize}
% 
% It is desirable to reduce these three steps to the interesting, middle one.
% Each new, subordinate file (henceforth `subfile') should behave both as a self-sufficient \LaTeX\ document and as part of the whole project, depending on whether it is \LaTeX ed individually or |\included|/|\input| from the main document.
% This is what the class |subfiles.cls| and the package |subfiles.sty| are intended for. 
% 
% \section{Basic usage}
%
% The main file, i.e., the file with the preamble to be shared with the subfiles, has to load the package |subfiles| \emph{at the end of the preamble}:
% \begin{center}
%   \begin{tabular}{l}
%     |\usepackage{subfiles}|\\
%     |\begin{document}|
%   \end{tabular}
% \end{center}
% Subordinate files (subfiles) are loaded from the main file or from other subfiles with the command
% \begin{center}
%   |\subfile{|\meta{subfile\_name}|}|
% \end{center}
% The subfiles have to start with the line
% \begin{center}
%   |\documentclass[|\meta{main\_file\_name}|]{subfiles}|
% \end{center}
% which loads the class |subfiles|.
% Its only `option', which is actually mandatory, gives the name of the main file.
% This name follows \TeX\ conventions: |.tex| is the default extension, the path has to be provided if the main file is in a different directory, and directories in the path have to be separated by |/| (not |\|).
% Thus, we have the following structure:
% \begin{center}\small
%   \begin{tabular}[t]{l}
%     \multicolumn{1}{c}{main file} \\
%     \hline
%     |\documentclass[...]{...}| \\
%     \meta{shared preamble} \\
%     |\usepackage{subfiles}| \\
%     |\begin{document}| \\
%     \dots \\
%     |\subfile{|\meta{subfile\_name}|}| \\
%     \dots \\
%     |\end{document}| \\
%     \hline 
%   \end{tabular}
%   \hfill  
%   \begin{tabular}[t]{l}
%     \multicolumn{1}{c}{subfile} \\
%     \hline
%     |\documentclass[|\meta{main\_file\_name}|]{subfiles}| \\
%     |\begin{document}| \\
%     \dots \\
%     |\end{document}| \\
%     \hline
%   \end{tabular}
% \end{center}
% Now there are two possibilities.
% \begin{itemize}
% \item If \LaTeX\ is run on the subfile, the line |\documentclass[..]{subfiles}| is replaced by the preamble of the main file (including its |\documentclass| command).
%   The rest of the subfile is processed normally.
% \item If \LaTeX\ is run on the main file, the subfile is loaded like with an |\input| command, except that the three lines |\documentclass[..]{subfiles}|, |\begin{document}|, and |\end{document}| are ignored.
% \end{itemize}
%
% \section{Advanced usage}
%
% \subsection{Hierarchy of directories}
%
% Sometimes it is desirable to put a subfile together with its images and further files into its own directory.
% The difficulty now is that these additional files have to be addressed by different pathes depending on whether the main files or the subfile is typeset.
% As of version 1.3, the |subfiles| package handles this problem by using the |import| package.
%
% As an example, consider the following hierarchy of files:
% \begin{center}\ttfamily
%   \begin{tabular}{l}
%     main.tex\\
%     mypreamble.tex\\
%     dir1/subfile1.tex\\
%     dir1/image1.jpg\\
%     dir1/text1.tex\\
%     dir1/dir2/subfile2.tex\\
%     dir1/dir2/image2.jpg\\
%     dir1/dir2/text2.tex
%   \end{tabular}
% \end{center}
% where |main|, |subfile1|, and |subfile2| have the following contents:
% \begin{center}
% \begin{tabular}[t]{l}
%   \multicolumn{1}{c}{|main.tex|} \\
%   \hline
%   |\documentclass{article}| \\
%   |\input{mypreamble}| \\  
%   |\usepackage{graphicx}| \\
%   |\usepackage{subfiles}| \\
%   |\begin{document}| \\
%   |\subfile{dir1/subfile1}|\\
%   |\end{document}|\\
%   \hline
% \end{tabular}%
% \hfill
% \begin{tabular}[t]{l}
%   \multicolumn{1}{c}{|subfile1.tex|} \\
%   \hline
%   |\documentclass[../main]{subfiles}| \\
%   |\begin{document}| \\
%   |\input{text1}|\\ 
%   |\includegraphics{image1.jpg}|\\ 
%   |\subfile{dir2/subfile2}| \\  
%   |\end{document}| \\
%   \hline
% \end{tabular}\\[2ex]
% \begin{tabular}[t]{l}
%   \multicolumn{1}{c}{|subfile2.tex|} \\
%   \hline
%   |\documentclass[../../main]{subfiles}| \\
%   |\begin{document}| \\
%   |\input{text2}|\\ 
%   |\includegraphics{image2.jpg}|\\ 
%   |\end{document}| \\
%   \hline
% \end{tabular}
% \end{center}
% Then each of the three files can be typeset individually in its respective directory, where \LaTeX\ is able to locate all included text files and images.
%
% \subsection{Including files instead of inputting them}
%
% In plain \LaTeX, you can use either |\input| or |\include| to load a file.
% In most cases the first is appropriate, but sometimes there are reasons to prefer the latter.
% Internally, the |\subfile| command uses |\input|.
% For those cases where you need |\include|, the package provides the command  
% \begin{center}
%   |\subfileinclude{|\meta{subfile\_name}|}|
% \end{center}
%
% \subsection{Bibliographies}
%
% Manual bibliographies with the |thebibliography| environment work as usual.
% Problems may arise if external programs like |bibtex| or |biber| are used to generate the bibliography, in particular when the bibliographies are distributed over subfiles.
% Here are some hints on how it may work.
% \begin{itemize}
% \item Make sure the command |\bibliography| is executed after loading the |subfiles| package.
%   Put the command between |\usepackage{subfiles}| and |\begin{document}| or somewhere into the text part.
% \item When you use the package |biblatex|, and programs like |biber| complain about not being able to find the bibliography files, use |\bibliography| instead of |\addbibresource| for local files (observing the hint above).
% \end{itemize}
% The |subfiles| package has been tested with the packages |biblatex|, |bibunits|, and |chapterbib| as well as the external programs |bibtex| and |biber|. 
% 
% \subsection{Unusual locations for placing definitions and text}
%
% Usually all definitions and packages required by the subfiles should go into the preamble of the main file.
% There are some further locations, though, where one might consider adding definitions and text.
%
% \paragraph{Code after the end of the main document} is added to the preamble of the subfiles, but is ignored when typesetting the main file.
% This happens because a subfile typeset by itself does not really take the preamble of the main file, but \emph{everything outside} of |\begin{document}| and |\end{document}|.
% This has two consequences: \emph{a)}~the user can add some commands to be processed as part of the preamble only when the subfiles are typeset by themselves; but also \emph{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).
%
% \paragraph{Code in the preamble of a subfile} is processed as part of the text when typesetting the main file, but as part of the preamble when typesetting the subfile.
% This means that the preamble of a subfile can only contain stuff that is acceptable for both, the preamble and the text area.
% One should also keep in mind that each subfile is input within a group, so definitions made within may 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 the reader to find them easily.
%
% \paragraph{Code after the end of a subfile} is treated like the code preceding it when the subfile is loaded from the main file, but is ignored when typesetting the subfile.
% The code after |\end{document}| behaves as if following the |\subfile| command in the main file, except that it is still part of the group enclosing the subfile.
% As a consequence, empty lines at the end of the subfile lead to a new paragraph in the main document, even if the |\subfile| command is immediately followed by text.
%
% \subsection{Avoiding extra spaces}
%
% Sometimes you may want to load the contents of a subfile without white space separating it from the contents of the main file.
% In this respect |\subfile| behaves similar to |\input|.
% Any space or newline before and after the |\subfile| command will appear in the typeset document, as will any white space between the last character of the subfile and |\end{document}|.
% Moreover, any stuff after |\end{document}| will end up in the main document, including spurious empty lines, which may lead to a new paragraph.
% Therefore, to load the contents of a subfile without intervening spaces, you have either to add comment signs:
% \begin{center}
%   \begin{tabular}[t]{l}
%       \multicolumn{1}{c}{|main.tex|}\\
%       \hline
%       \dots\\
%       |text before%|\\
%       |\subfile{sub.tex}%|\\
%       |text after|\\
%       \hline
%   \end{tabular}
%   \qquad
%   \begin{tabular}[t]{l}
%       \multicolumn{1}{c}{|sub.tex|}\\
%       \hline
%       |\documentclass[main.tex]{subfiles}|\\
%       |\begin{document}|\\
%       |contents of subfile%|\\
%       |\end{document}|\\
%       |% No empty lines after \end{document}!|\\
%       \hline
%   \end{tabular}
% \end{center}
% or to put everything on the same line:
% \begin{center}
%   |text before\subfile{sub.tex}text after|\\
%   |contents of subfile\end{document}|
% \end{center}
%
% \section{Dependencies}
%
% The |subfiles| package requires the |verbatim| package, whose |comment| environment is used to ignore the text area of the main file when typesetting subfiles separately.
% Moreover, the |import| package is needed to load subfiles and their auxiliary files from different directories.
% Both packages are part of the standard \TeX\ distributions.
%
% \section{Version history}
%
% \begin{description}
% \item[v1.1:]
%   Initial version by Federico Garcia. Further versions by Gernot Salzer.
% \item[v1.2:] \mbox{}
%   \begin{itemize}
%   \item Incompatibility with classes and packages removed that modify the |\document| command, like the class |revtex4|.
%   \end{itemize}
% \item[v1.3:] \mbox{}
%   \begin{itemize}
%   \item Use of |import| package to handle directory hierarchies.
%   \item |\ignorespaces| added to avoid spurious spaces.
%   \item Incompatibility with commands removed that expect |\document| to be equal to |\@onlypreamble| after the preamble (thanks to Eric Domenjoud for analysing the problem).
%   \end{itemize}
% \item[v1.4:] \mbox{}
%   \begin{itemize}
%   \item Incompatibility with |memoir| class and |comment| package removed.
%   \item Bug `|\unskip| cannot be used in vertical mode` fixed.
%   \end{itemize}
% \item[v1.5:] \mbox{}
%   \begin{itemize}
%   \item Command |\subfileinclude| added.
%   \item Basic support for |bibtex| related bibliographies in subfiles added.
%      Seems to suffice also for sub-bibliographies with the package |chapterbib|.
%   \item Support for sub-bibliographies with package |bibunits| added.
%   \end{itemize}
% \end{description}
%
%\section{The Implementation}
%\subsection{The class}
%    \begin{macrocode}
%<*class>
\NeedsTeXFormat{LaTeX2e}
\ProvidesClass{subfiles}[2019/10/30 v1.5 Multi-file projects (class)]
\DeclareOption*{\typeout{Preamble taken from file `\CurrentOption'}%
    \let\preamble@file\CurrentOption}
\ProcessOptions
%    \end{macrocode}
%
% We start by saving the regular \LaTeX\ definition of |\documentclass|:
% 
%    \begin{macrocode}
\let\subfiles@documentclass\documentclass
%    \end{macrocode}
%
% Now |\documentclass| is set equal to |\LoadClass| such that the class and the options of the main file will be loaded as usual.
%
%    \begin{macrocode}
\let\documentclass\LoadClass\relax
%    \end{macrocode}
%
% When typesetting a subfile, we have to skip the |document| environment of the main file.
% This is done with the commands |\comment| and |\endcomment| from the |verbatim| package.
% Now there is a problem:
% If we load |verbatim| here, the definition of the commands may be overwritten if the user loads e.g.\ the |comment| package.
% Loading |verbatim| in |subfiles.sty| at the latest possible moment is not reliable, either.
% On the one hand we may overwrite macros required later by the user, on the other hand the |memoir| class contains a copy of |verbatim|, so a later |\RequirePackage| refuses to reload the package.
% Thus, in the case of a document loading the |memoir| class and the |comment| package, we end up with the wrong definition of |\comment| in any case.
%
% Therefore we load the |verbatim| package here and save the contents of the crucial commands |\comment| and |\endcomment| under a different name.
%    \begin{macrocode}
\RequirePackage{verbatim}
\let\subfiles@comment\comment
\let\subfiles@endcomment\endcomment
%    \end{macrocode}
% 
% To handle subfiles in separate directories, we load the |import| package.
% 
%    \begin{macrocode}
\RequirePackage{import}
%    \end{macrocode}
%
% The |\subimport| command requires the path and the basename of the file to be loaded in separate arguments.
% Therefore we have to split file names into these two components.
% 
%    \begin{macrocode}
\def\subfiles@split#1{%
  \edef\subfiles@filename{#1}%
  \def\subfiles@dir{}%
  \def\subfiles@base{}%
  \def\subfiles@sep{}%
  \expandafter\subfiles@split@\subfiles@filename/\@nil/%
}
\def\subfiles@split@#1/{%
  \def\tmp{#1}%
  \ifx\tmp\@nnil
    \let\subfiles@next\relax
  \else
    \edef\subfiles@dir{\subfiles@dir\subfiles@base\subfiles@sep}%
    \def\subfiles@base{#1}%
    \def\subfiles@sep{/}%
    \let\subfiles@next\subfiles@split@
  \fi
  \subfiles@next  
}
%    \end{macrocode}
%
% After executing e.g.\ |\subfiles@split{../dir1/dir2/file.tex}|, the commands |\subfiles@dir| and |\subfiles@base| expand to |../dir1/dir2/| and |file.tex|, respectively.
%
% Now we split the name of the main file that has been provided as optional argument of the document class, and |\subimport| the main file.
%
%    \begin{macrocode}
\subfiles@split{\preamble@file}
\subimport{\subfiles@dir}{\subfiles@base}
%    \end{macrocode}
%
% The main file loads the package |subfiles| as part of the preamble, which saves the contents of |\document| and |\enddocument| as |\subfiles@document| and |\subfiles@enddocument|, respectively.
% Then we restore the original values of |\document|, |\enddocument|, and |\documentclass|. The backup commands are |\undefined| to save memory. That's it.
%
%    \begin{macrocode}
{\catcode`\@=11
\global\let\document\subfiles@document
\global\let\enddocument\subfiles@enddocument
\global\let\documentclass\subfiles@documentclass
\global\let\subfiles@document\undefined
\global\let\subfiles@enddocument\undefined
\global\let\subfiles@documentclass\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}[2019/10/30 v1.5 Multi-file projects (package)]
\DeclareOption*{\PackageWarning{\CurrentOption ignored}}
\ProcessOptions
%    \end{macrocode}
%
% If the initial document class was |subfiles|, then the main file is loaded as part of a subfile.
% In this case anything between |\begin{document}| and |\end{document}| has to be skipped, while the contents of the commands |\document| and |\enddocument| has to be retained for later use in the subfile.
% Therefore we save the contents of the two commands as |\subfiles@document| and |\subfiles@enddocument|, respectively.
% Now the |document| environment is redefined to become the saved |comment| environment from the |verbatim| package.
% Consequently, the body of the main file is ignored by \LaTeX, and only the preamble is read (as well as anything that comes after |\end{document}|!).
%
%    \begin{macrocode}
\@ifclassloaded{subfiles}{%
  \let\subfiles@document\document
  \let\subfiles@enddocument\enddocument
  \let\document\subfiles@comment
  \let\enddocument\subfiles@endcomment
%    \end{macrocode}
%
% By loading the |subfiles| package immediately before |\begin{document}| we ensure that |\subfiles@document| and |\subfiles@enddocument| contain all modifications that the class and the preamble of the main file may have applied to the |document| environment.
% This happens e.g.\ with the class |revtex4| and the package |pythontex|.
%
% We use the |import| package to handle subfiles in separate directories.
% The |\subimport| command requires the path and the basename of files as separate arguments.
% Therefore we split file names into these two components using a macro |\subfiles@split|.
% Both things, loading the package and defining the command, is also done in |subfiles.cls|, so we have to execute this code only if we are typesetting the main file.
% 
%    \begin{macrocode}
}{% subfiles class not loaded
  \RequirePackage{import}
  \def\subfiles@split#1{%
    \edef\subfiles@filename{#1}%
    \def\subfiles@dir{}%
    \def\subfiles@base{}%
    \def\subfiles@sep{}%
    \expandafter\subfiles@split@\subfiles@filename/\@nil/%
  }%
  \def\subfiles@split@#1/{%
    \def\tmp{#1}%
    \ifx\tmp\@nnil
      \let\subfiles@next\relax
    \else
      \edef\subfiles@dir{\subfiles@dir\subfiles@base\subfiles@sep}%
      \def\subfiles@base{#1}%
      \def\subfiles@sep{/}%
      \let\subfiles@next\subfiles@split@
    \fi
    \subfiles@next
  }%
}
%    \end{macrocode}
%
% After executing e.g.\ |\subfiles@split{../dir1/dir2/file.tex}|, the commands |\subfiles@dir| and |\subfiles@base| expand to |../dir1/dir2/| and |file.tex|, respectively.
%
% \DescribeMacro{\subfile}
% The command |\subfile| specifies the command |\subimport| for |\input|ing the subfile, and then calls |\subfiles@subfile|.
%    \begin{macrocode}
\newcommand\subfile{%
  \let\subfiles@loadfile\subimport
  \subfiles@subfile
}
%    \end{macrocode}
%
% \DescribeMacro{\subfileinclude}
% The command |\subfileinclude| specifies the command |\subincludefrom| for |\include|ing the subfile, and then calls |\subfiles@subfile|.
%    \begin{macrocode}
\newcommand\subfileinclude{%
  \let\subfiles@loadfile\subincludefrom
  \subfiles@subfile
}
%    \end{macrocode}
%
% The main functionality of the two |\subfile| commands is implemented in |\subfiles@subfile|.
% It redefines |\documentclass| and the |document| environment to do nothing except avoiding spurious spaces.
% Moreover, |\document| has to be set to the value it usually has after the end of the preamble, since some commands check this value and may raise an error otherwise.
%
%    \begin{macrocode}
\newcommand\subfiles@subfile[1]{%
  \begingroup
  \renewcommand\documentclass[2][subfiles]{\ignorespaces}%
  \renewenvironment{document}{%
    \let\document\@onlypreamble
    \ignorespaces
  }{%
    \@ignoretrue
  }%
%    \end{macrocode}
% Now we split the file name into path and base name and load the file.
%
%    \begin{macrocode}
  \subfiles@split{#1}%
  \subfiles@loadfile{\subfiles@dir}{\subfiles@base}%
  \endgroup
}
%    \end{macrocode}
%
% Note that the changes to |\documentclass| and the |document| environment happen \emph{within a group}, so they are undone after inclusion of the subfile.
%
% To let external programs find files, we have to add the |\import@path| to file names.
% This is accomplished with the command |\subfiles@addimportpath|.
%    \begin{macrocode}
\def\subfiles@addimportpath#1{%
  \def\subfiles@filelist{}%
  \def\subfiles@sep{}%
  \@for\subfiles@filename:=#1\do{%
    \edef\subfiles@filelist{\subfiles@filelist\subfiles@sep\import@path\subfiles@filename}%
    \def\subfiles@sep{,}%
  }
}
%    \end{macrocode}
%
% We redefine the |\bibliography| command such that the import path is added to the file names before the original command is called.
%    \begin{macrocode}
\let\subfiles@bibliography\bibliography
\renewcommand\bibliography[1]{%
  \subfiles@addimportpath{#1}%
  \expandafter\subfiles@bibliography\expandafter{\subfiles@filelist}%
}
%    \end{macrocode}
%
% The |bibunits| package uses its own command to specify bib files, we have to patch it separately.
%    \begin{macrocode}
\@ifpackageloaded{bibunits}{%
  \let\subfiles@putbib\@putbib
  \def\@putbib[#1]{%
    \subfiles@addimportpath{#1}%
    \expandafter\subfiles@putbib\expandafter[\subfiles@filelist]%
  }%
}{}
%    \end{macrocode}