From 00c2e60e9bb0df2e2d450bb002812819a8c6212a Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Tue, 31 Jul 2018 20:54:49 +0000 Subject: subfiles (31jul18) git-svn-id: svn://tug.org/texlive/trunk@48323 c570f23f-e606-0410-a88d-b1316a301751 --- .../texmf-dist/source/latex/subfiles/subfiles.dtx | 64 +++++++++++++--------- .../texmf-dist/source/latex/subfiles/subfiles.ins | 7 ++- 2 files changed, 41 insertions(+), 30 deletions(-) (limited to 'Master/texmf-dist/source/latex/subfiles') diff --git a/Master/texmf-dist/source/latex/subfiles/subfiles.dtx b/Master/texmf-dist/source/latex/subfiles/subfiles.dtx index cf604a232d5..1033a03e98c 100644 --- a/Master/texmf-dist/source/latex/subfiles/subfiles.dtx +++ b/Master/texmf-dist/source/latex/subfiles/subfiles.dtx @@ -2,6 +2,7 @@ % % 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 @@ -13,7 +14,7 @@ % % This work has the LPPL maintenance status `maintained'. % -% The Current Maintainer of this work is Federico Garcia. +% 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 @@ -22,13 +23,13 @@ % %<*driver> % \fi -\ProvidesFile{subfiles.dtx}[2012/05/23 v1.1 Multi-file projects] +\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} + \author{Federico Garcia\\{\small (v1.2 update by Gernot Salzer)}} \begin{document} \maketitle @@ -52,7 +53,7 @@ % % 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 `environment' |document|; 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 of conflicting with other packages and/or classes. +% 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} % @@ -65,69 +66,66 @@ % \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}|\\ -% \qquad\meta{more preamble} & \qquad\meta{text, graphics, etc.}\\ -% |\begin{document}|&|\end{document}|\\ -% \qquad\meta{text}\\ +% |\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, 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 following \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). +% 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 the ignores |\end{document}| too. (The body of the file, nothing else, is effectively |\input|.) +% \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} % -% In all truth, a subfile typeset by itself does not exactly take the preamble of the main file, but \emph{anything outside} \verb|\begin{document}| and \verb|\end{document}|. This has two consequences: $a)$~the user can make 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). +% 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 (v.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. +% 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. % -% |subfiles| class and package require 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$. +% 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}[2012/05/23 Federico Garcia] -\RequirePackage{verbatim} +\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\ definitions of |\document|, |\enddocument|, and |\documentclass|: +% The first thing to do is to save the regular \LaTeX\ definition of |\documentclass|: % \begin{macrocode} -\let\old@document@subfiles\document -\let\old@enddocument@subfiles\enddocument \let\old@documentclass@subfiles\documentclass % \end{macrocode} % -% Now the |document| `environment' is redefined and equaled to |comment|. 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}|!). For |\documentclass|, having been already loaded one (|subfiles|), it is redefined and equaled to |\LoadClass|. The class and options of the main file are loaded identically. +% 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\document\comment -\let\enddocument\endcomment \let\documentclass\LoadClass\relax % \end{macrocode} % -% Now it is possible to |\input| the main file, and then restore the original values of |\document|, |\enddocument| and |\documentclass|. The backup commands are |\undefined| to save memory. That's it. +% 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} -% \end{macrocode} -% -% Here it comes something not so obvious. In the usual situations, the |\preamble@file| contains some |\usepackage| commands, which, at the end, make |@| no longer a letter. That is why the next part needs a |\catcode| command, grouping, and |\global|'s. -% \begin{macrocode} {\catcode`\@=11 \global\let\document\old@document@subfiles \global\let\enddocument\old@enddocument@subfiles @@ -138,19 +136,21 @@ % % \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}[2012/05/23 Federico Garcia] +\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 the |\begin| 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|. +% 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% @@ -162,5 +162,15 @@ % 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 +}{} % % \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/Master/texmf-dist/source/latex/subfiles/subfiles.ins b/Master/texmf-dist/source/latex/subfiles/subfiles.ins index 8046269963a..f188c09f376 100644 --- a/Master/texmf-dist/source/latex/subfiles/subfiles.ins +++ b/Master/texmf-dist/source/latex/subfiles/subfiles.ins @@ -1,5 +1,6 @@ % 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 @@ -11,7 +12,7 @@ % % This work has the LPPL maintenance status `maintained'. % -% The Current Maintainer of this work is Federico Garcia. +% 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 @@ -22,7 +23,7 @@ This is a generated file. -Copyright 2002, 2012 Federico Garcia +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 @@ -34,7 +35,7 @@ version 2005/12/01 or later. This work has the LPPL maintenance status `maintained'. -The Current Maintainer of this work is Federico Garcia. +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 -- cgit v1.2.3