diff options
author | Karl Berry <karl@freefriends.org> | 2019-10-31 22:22:58 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2019-10-31 22:22:58 +0000 |
commit | ffdb01dedec1d0ba5dcf8628279f501ccaf79a3f (patch) | |
tree | 6eee35fc451dbbb85bfc5e5a33b431cb0ee900b2 | |
parent | 96333e9ed5c717cce4e83216a2fe3df6987a3007 (diff) |
subfiles (31oct19)
git-svn-id: svn://tug.org/texlive/trunk@52591 c570f23f-e606-0410-a88d-b1316a301751
-rw-r--r-- | Master/texmf-dist/doc/latex/subfiles/subfiles.pdf | bin | 205122 -> 211014 bytes | |||
-rw-r--r-- | Master/texmf-dist/source/latex/subfiles/subfiles.dtx | 147 | ||||
-rw-r--r-- | Master/texmf-dist/tex/latex/subfiles/subfiles.cls | 2 | ||||
-rw-r--r-- | Master/texmf-dist/tex/latex/subfiles/subfiles.sty | 34 |
4 files changed, 151 insertions, 32 deletions
diff --git a/Master/texmf-dist/doc/latex/subfiles/subfiles.pdf b/Master/texmf-dist/doc/latex/subfiles/subfiles.pdf Binary files differindex a7cd81f7f70..33f39c049ec 100644 --- a/Master/texmf-dist/doc/latex/subfiles/subfiles.pdf +++ b/Master/texmf-dist/doc/latex/subfiles/subfiles.pdf diff --git a/Master/texmf-dist/source/latex/subfiles/subfiles.dtx b/Master/texmf-dist/source/latex/subfiles/subfiles.dtx index 39058604a00..201cfd60107 100644 --- a/Master/texmf-dist/source/latex/subfiles/subfiles.dtx +++ b/Master/texmf-dist/source/latex/subfiles/subfiles.dtx @@ -23,13 +23,13 @@ % %<*driver> % \fi -\ProvidesFile{subfiles.dtx}[2019/10/25 v1.4 Multi-file projects] +\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{\filedate{}} - \author{Federico Garcia, Gernot Salzer} +\date{v1.5 2019/10/30} +\author{Federico Garcia, Gernot Salzer} \begin{document} \maketitle @@ -61,7 +61,7 @@ % % \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 very end of the preamble}: +% 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}|\\ @@ -171,14 +171,36 @@ % \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{Additional definitions for subfiles} +% \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 places, though, where one might consider adding definitions for the subfiles. +% 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 \verb|\begin{document}| and \verb|\end{document}|. +% 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. @@ -186,11 +208,16 @@ % 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 like |\input|. +% 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} @@ -210,6 +237,7 @@ % |\begin{document}|\\ % |contents of subfile%|\\ % |\end{document}|\\ +% |% No empty lines after \end{document}!|\\ % \hline % \end{tabular} % \end{center} @@ -228,16 +256,30 @@ % \section{Version history} % % \begin{description} -% \item[v1.1 (FG):] -% Start of version history. -% \item[v1.2 (GS):] -% The |subfiles| package becomes compatible with classes and packages that modify the |\document| command, like the class |revtex4|. -% \item[v1.3 (GS):] -% Use of |import| package to handle directory hierarchies. -% |\ignorespaces| added to avoid spurious spaces. -% Incompatibility with commands removed that expect |\document| to be equal to |\@onlypreamble| after the preamble (thanks to Eric Domenjoud for analysing the problem). -% \item[v1.3 (GS):] -% Incompatibility with |memoir| class and |comment| package removed. +% \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} @@ -245,10 +287,10 @@ % \begin{macrocode} %<*class> \NeedsTeXFormat{LaTeX2e} -\ProvidesClass{subfiles}[2019/10/25 v1.4 Multi-file projects (class)] +\ProvidesClass{subfiles}[2019/10/30 v1.5 Multi-file projects (class)] \DeclareOption*{\typeout{Preamble taken from file `\CurrentOption'}% \let\preamble@file\CurrentOption} -\ProcessOptions +\ProcessOptions % \end{macrocode} % % We start by saving the regular \LaTeX\ definition of |\documentclass|: @@ -345,7 +387,7 @@ % \begin{macrocode} %<*package> \NeedsTeXFormat{LaTeX2e} -\ProvidesPackage{subfiles}[2019/10/25 v1.4 Multi-file projects (package)] +\ProvidesPackage{subfiles}[2019/10/30 v1.5 Multi-file projects (package)] \DeclareOption*{\PackageWarning{\CurrentOption ignored}} \ProcessOptions % \end{macrocode} @@ -400,12 +442,29 @@ % 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| first redefines |\documentclass| and the |document| environment to do nothing. -% To avoid spurious spaces we |\ignorespaces|. -% Moreover, we have to set |\document| to the value it usually has after the end of the preamble, since some commands check this value and may raise an error. +% 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\subfile[1]{% +\newcommand\subfiles@subfile[1]{% \begingroup \renewcommand\documentclass[2][subfiles]{\ignorespaces}% \renewenvironment{document}{% @@ -415,14 +474,46 @@ \@ignoretrue }% % \end{macrocode} -% -% Now we split the file name into path and base name and |\subimport| the file. +% Now we split the file name into path and base name and load the file. % % \begin{macrocode} \subfiles@split{#1}% - \subimport{\subfiles@dir}{\subfiles@base}% + \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} diff --git a/Master/texmf-dist/tex/latex/subfiles/subfiles.cls b/Master/texmf-dist/tex/latex/subfiles/subfiles.cls index 4837f82d3e3..eed0b1c431f 100644 --- a/Master/texmf-dist/tex/latex/subfiles/subfiles.cls +++ b/Master/texmf-dist/tex/latex/subfiles/subfiles.cls @@ -26,7 +26,7 @@ %% and the derived files subfiles.sty and subfiles.pdf %% \NeedsTeXFormat{LaTeX2e} -\ProvidesClass{subfiles}[2019/10/25 v1.4 Multi-file projects (class)] +\ProvidesClass{subfiles}[2019/10/30 v1.5 Multi-file projects (class)] \DeclareOption*{\typeout{Preamble taken from file `\CurrentOption'}% \let\preamble@file\CurrentOption} \ProcessOptions diff --git a/Master/texmf-dist/tex/latex/subfiles/subfiles.sty b/Master/texmf-dist/tex/latex/subfiles/subfiles.sty index 4a9a89b820a..c2afedb3bad 100644 --- a/Master/texmf-dist/tex/latex/subfiles/subfiles.sty +++ b/Master/texmf-dist/tex/latex/subfiles/subfiles.sty @@ -26,7 +26,7 @@ %% and the derived files subfiles.sty and subfiles.pdf %% \NeedsTeXFormat{LaTeX2e} -\ProvidesPackage{subfiles}[2019/10/25 v1.4 Multi-file projects (package)] +\ProvidesPackage{subfiles}[2019/10/30 v1.5 Multi-file projects (package)] \DeclareOption*{\PackageWarning{\CurrentOption ignored}} \ProcessOptions \@ifclassloaded{subfiles}{% @@ -56,7 +56,15 @@ \subfiles@next }% } -\newcommand\subfile[1]{% +\newcommand\subfile{% + \let\subfiles@loadfile\subimport + \subfiles@subfile +} +\newcommand\subfileinclude{% + \let\subfiles@loadfile\subincludefrom + \subfiles@subfile +} +\newcommand\subfiles@subfile[1]{% \begingroup \renewcommand\documentclass[2][subfiles]{\ignorespaces}% \renewenvironment{document}{% @@ -66,9 +74,29 @@ \@ignoretrue }% \subfiles@split{#1}% - \subimport{\subfiles@dir}{\subfiles@base}% + \subfiles@loadfile{\subfiles@dir}{\subfiles@base}% \endgroup } +\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{,}% + } +} +\let\subfiles@bibliography\bibliography +\renewcommand\bibliography[1]{% + \subfiles@addimportpath{#1}% + \expandafter\subfiles@bibliography\expandafter{\subfiles@filelist}% +} +\@ifpackageloaded{bibunits}{% + \let\subfiles@putbib\@putbib + \def\@putbib[#1]{% + \subfiles@addimportpath{#1}% + \expandafter\subfiles@putbib\expandafter[\subfiles@filelist]% + }% +}{} \endinput %% %% End of file `subfiles.sty'. |