Debian Codegraph @

texmf-dist/source/latex/docmute/docmute.dtx

raw
1 % \iffalse
2 %<*internal>
3 \iffalse
4 % !TEX program = pdflatex
5 %</internal>
6 %
7 %<*license>
8 Copyright (C) 2009 by T.M. Trzeciak <[email protected]>
9
10 This work may be distributed and/or modified under the
11 conditions of the LaTeX Project Public License (LPPL), either
12 version 1.3c of this license or (at your option) any later
13 version. The latest version of this license is in the file:
14
15 http://www.latex-project.org/lppl.txt
16
17 This work is "maintained" (as per LPPL maintenance status) by
18 T.M. Trzeciak.
19
20 This work consists of the file docmute.dtx
21 and the derived files docmute.ins,
22 docmute.pdf,
23 docmute.sty.
24 %</license>
25 %
26 %<*readme>
27 Input or include stand-alone LaTeX documents. Only the content
28 of the document environment is retained and the rest is
29 discarded.
30
31 To install the package you only need to put docmute.sty style
32 file where LaTeX can find it. To extract the files and typeset
33 the documentation run pdflatex on docmute.dtx. Alternatively,
34 run tex on it to extract only.
35 %</readme>
36 %
37 %<*internal>
38 \fi
39 \def\nameofplainTeX{plain}
40 \ifx\fmtname\nameofplainTeX\else
41 \expandafter\begingroup
42 \fi
43 %</internal>
44 %
45 %<*batchfile>
46 \input docstrip.tex
47 \keepsilent\askforoverwritefalse
48 \nopreamble\nopostamble
49 \generate{\file{\jobname.sty}{\from{\jobname.dtx}{package}}}
50 %</batchfile>
51 %<batchfile>\endbatchfile
52 %
53 %<*internal>
54 \generate{\file{\jobname.ins}{\from{\jobname.dtx}{batchfile}}}
55 \generate{\file{README.TXT}{\from{\jobname.dtx}{readme}}}
56 \ifx\fmtname\nameofplainTeX
57 \expandafter\endbatchfile
58 \else
59 \expandafter\endgroup
60 \fi
61 %</internal>
62 % \fi
63 %
64 % \begin{comment}
65 %
66 %<*documentation>
67 \documentclass{ltxdoc}
68 \usepackage{verbatim}
69 \usepackage{docmute}
70 \EnableCrossrefs
71 \CodelineIndex
72 \RecordChanges
73 %\OnlyDescription
74 %
75 \begin{document}
76
77 \GetFileInfo{docmute.sty}
78 \title{The \textsf{docmute} package%
79 \thanks{This file describes version \fileversion, last revised \filedate.}}
80 \author{Tomasz M. Trzeciak\thanks{E-mail: \texttt{[email protected]}}}
81 \date{\filedate}
82 \maketitle
83
84 \section{Intoduction}
85
86 The structure of \LaTeX\ documents doesn't allow one document to be included as a part of another. This package tries to remedy this limitation and enables standalone documents to be used with the standard |\input| and |\include| commands just as if they had no preamble.
87
88 This package is intentionally kept simple. If you require more smarts, there are other possibilities that might suit you better, such as the \textsf{standalone} package and document class by M.\ Scharrer or the \textsf{combine} class by W.\ Robertson and P.\,R.\ Wilson.
89
90 \section{Usage}
91
92 The package is loaded with the usual |\usepackage{docmute}|. It redefines the |\documentclass| command in such a way that everything between this command and the |\begin{document}| is skipped, as well as everything after the |\end{document}|. No attempts are made to analyse the actual content of the preamble---it is simply discarded. It is up to the user to ensure that the main document loads all packages required by subsidiary documents. To easily share (part of) a preamble between documents, simply put it in a separate file and |\input| it in each document.
93
94 \DescribeMacro{\docmute}
95 In rare cases there might be some commands present already before the |\documentclass| command and these commands will be executed then by the main document. You can prevent that by putting |\csname docmute\endcsname| at the top of the inputted document. The |\docmute| command has the same effect as the redefined |\documentclass|. Executing it through the control sequence forming primitive rather than directly ensures that standalone compilation is still possible, even though the |\docmute| command is not defined yet (in which case |\csname docmute\endcsname| will have the same effect as |\relax|).
96
97 Starting with version v1.2 nesting of inputted documents is allowed by default and doesn't require an explicit option nor does it introduce an additional level of grouping as in previous versions. For backwards compatibility the |nested| option is still accepted but it has no effect.
98
99 \section{Known limitations}
100
101 The |\documentclass| and/or |\csname docmute\endcsname| command has to be in the same file as |\begin{document}|. This is due to employed preamble gobbling method, which relies on scanning for delimited macro arguments and which doesn't work across the file boundaries.
102
103 \DocInput{\jobname.dtx}
104
105 \end{document}
106 %</documentation>
107 %
108 % \end{comment}
109 %
110 % \StopEventually{}
111 %
112 % \section{Implementation}
113 %
114 % \iffalse
115 %<*package>
116 % \fi
117 %
118 % Initial boilerplate code.
119 %
120 % \begin{macrocode}
121 \NeedsTeXFormat{LaTeX2e}
122 \ProvidesPackage{docmute}[2012/03/22 v1.4 Input stand-alone documents]
123 % \end{macrocode}
124 %
125 % Macro used for comparison to see if we already reached
126 % |\begin{document}|.
127 %
128 % \begin{macrocode}
129 \def\docmute@docenv{document}
130 % \end{macrocode}
131 %
132 % The main macro of this package. Grab everything before the
133 % |\begin| command and check what argument was passed to it.
134 %
135 % \begin{macrocode}
136 \long\def\docmute@gobblepreamble#1\begin#2{%
137 \def\docmute@thisenv{#2}%
138 % \end{macrocode}
139 %
140 % \noindent If |\begin{document}| was reached we can stop
141 % gobbling, otherwise we continue with tail recursive call.
142 %
143 % \begin{macrocode}
144 \ifx\docmute@thisenv\docmute@docenv
145 \begin{document}%
146 \else
147 \expandafter\docmute@gobblepreamble
148 \fi
149 }
150 % \end{macrocode}
151 %
152 % Save the original definitions of |\document| and
153 % |\enddocument|
154 %
155 % \begin{macrocode}
156 \let\docmute@document=\document
157 \let\docmute@enddocument=\enddocument
158 % \end{macrocode}
159 %
160 % Define the |\docmute| command.
161 %
162 % \begin{macrocode}
163 \let\docmute=\docmute@gobblepreamble
164 % \end{macrocode}
165 %
166 % Redefine the |\documentclass| command and |document|
167 % environment at the beginning of the document.
168 % |\AtBeginDocument| happens to early to be useful for that,
169 % so we need to append directly to the |\document|.
170 %
171 % \begin{macrocode}
172 \def\document{%
173 \docmute@document
174 \newcount\docmute@nestinglevel
175 \docmute@nestinglevel=0\relax
176 \let\documentclass=\docmute
177 \renewenvironment{document}{%
178 % \end{macrocode}
179 %
180 % Avoid grouping coming from the environment, keep track
181 % of document nesting level and take care of excess spaces.
182 %
183 % \begin{macrocode}
184 \endgroup
185 \advance \docmute@nestinglevel 1\relax
186 \ignorespaces
187 }{%
188 % \end{macrocode}
189 %
190 % At the top level execute the original |\enddocument|.
191 %
192 % \begin{macrocode}
193 \ifnum\docmute@nestinglevel=0
194 \expandafter\docmute@enddocument
195 % \end{macrocode}
196 %
197 % Otherwise, decrement nesting level, match the grouping
198 % from |\end|, set ignore blanks switch to true, redefine
199 % |\@currenvir| to |document| to keep the check at
200 % |\end{document}| happy and finally |\endinput|.
201 %
202 % \begin{macrocode}
203 \else
204 \advance \docmute@nestinglevel -1\relax
205 \begingroup
206 \@ignoretrue
207 \def\@currenvir{document}%
208 \endinput
209 \fi
210 }%
211 \ignorespaces
212 }
213 % \end{macrocode}
214 %
215 % Handle options.
216 %
217 % \begin{macrocode}
218 \DeclareOption{nested}{}% for backwards compatibility only
219 \ProcessOptions
220 % \end{macrocode}
221 % \iffalse
222 %</package>
223 % \fi
224 %
225 % \Finale
226