diff options
Diffstat (limited to 'Master/texmf-dist/tex/latex/frankenstein/newclude.sty')
-rw-r--r-- | Master/texmf-dist/tex/latex/frankenstein/newclude.sty | 959 |
1 files changed, 959 insertions, 0 deletions
diff --git a/Master/texmf-dist/tex/latex/frankenstein/newclude.sty b/Master/texmf-dist/tex/latex/frankenstein/newclude.sty new file mode 100644 index 00000000000..759797767c8 --- /dev/null +++ b/Master/texmf-dist/tex/latex/frankenstein/newclude.sty @@ -0,0 +1,959 @@ +%^^A* legal notices +% \iffalse +% +% This program is part of the Frankenstein bundle for LaTeX. +% +% Copyright 1995-2001 Matt Swift <swift@alum.mit.edu>. +% +% This file contains both the code and documentation for the +% newclude LaTeX package. It will work ONLY if it is placed in a +% proper directory. Files called README, INSTALL, newclude.tex +% and newclude.ins should have also been distributed to you +% with this file. See them for more information on how to typeset +% the documentation with LaTeX and how to generate a version of this +% file that will work faster than this one. +% +% This program is free software; you may redistribute it and/or +% modify it under the conditions of the LaTeX Project Public +% License, either version 1.2 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.2 or later is +% part of all distributions of LaTeX version 1999/12/01 or later. +% +% This program is distributed in the hope that it will be useful, +% but without any warranty; without even the implied warranty of +% merchantability or fitness for a particular purpose. See the +% LaTeX Project Public License for more details. +% +% \fi +% +%^^A* checks +% +%^^A NOTE: The character table, with two %'s, will get written to all files. +%% \CharacterTable +%% {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z +%% Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z +%% Digits \0\1\2\3\4\5\6\7\8\9 +%% Exclamation \! Double quote \" Hash (number) \# +%% Dollar \$ Percent \% Ampersand \& +%% Acute accent \' Left paren \( Right paren \) +%% Asterisk \* Plus \+ Comma \, +%% Minus \- Point \. Solidus \/ +%% Colon \: Semicolon \; Less than \< +%% Equals \= Greater than \> Question mark \? +%% Commercial at \@ Left bracket \[ Backslash \\ +%% Right bracket \] Circumflex \^ Underscore \_ +%% Grave accent \` Left brace \{ Vertical bar \| +%% Right brace \} Tilde \~} +% +% \CheckSum{208} +% +% \begin{abstract} +% \package{Newclude} is a backwards-compatible reimplementation of the +% \LaTeX{} system for including files. The princpal new features are: (1) +% the restriction that \cs\clearpage{}s must surround an included file is +% removed, (2) the restriction that \cs\include{}s cannot be nested is +% removed, and (3) the provision of hooks executed before and after the +% contents of an included file. Newclude accomplishes the first two by using +% a single \ext{aux} file instead of many. +% +% Still in development, but already useful in many situations, are new +% commands that include partial contents of independent \LaTeX{} files, which +% can also be processed on their own (that is, files that contain +% \cs\documentclass, |\begin{document}|, etc.). \package{Newclude} absorbs +% and supersedes the former package \package{includex}. +% \end{abstract} +% \clearpage +% \tableofcontents +% +% \part{Discussion} +% +% \section{Introduction} +% +% Let us call a file that might be included into another document with a +% command in the \cs\include family a \term{part}. When a part is actually +% included during a particular processing run, let us call it an \term{included +% part}, and when it is not included, let us call it an \term{unincluded part}. +% Notice that an unincluded part is \emph{not} the same as a file that was +% never a candidate for inclusion with a command in the \cs\include family. +% +% The \package{newclude} package adds these features to the standard LaTeX{} +% inclusion system: +% \begin{enumerate} +% \item\label{item:hooks} Hooks \cs\AtBeginInclude and \cs\AtEndInclude are provided. +% \item\label{item:hooks:opt} Optional arguments to \cs\include and friends +% override current values of \cs\AtBeginInclude and \cs\AtEndInclude. +% \item \cname{include*} is like \cs\include but with arbitrary commands +% rather than \cs\clearpage{}s surrounding the part. +% \item \cs\include and friends can be nested. +% \item \cs\includeall cancels the effect of \cs\includeonly. +% \item \cs\IfAllowed\meta{filename} is a new conditional that branches, +% depending on what has been declared in an \cs\includeonly. +% \item Commands \cs\includedoc etc.\ include a part that can be processed +% independently. These features are in development. +% \end{enumerate} +% +% \package{Newclude} accepts three mutually-exclusive package options, with +% \option{tag} the default when no package option is given. +% +% Loading \package{newclude} with the \option{simple} option provides only +% features \ref{item:hooks} and~\ref{item:hooks:opt}. If you don't use either +% of these new features, the standard \LaTeX{} and \package{newclude} inclusion +% systems will behave identically except in some unusual and benign odd cases +% relating the the parsing of the new optional arguments to \cs\include, which +% are discussed below in that command's documentation. +% +% The options \option{tag} and \option{allocate} each implement all the above +% features with a different method. Each method introduces different +% discrepancies from standard \LaTeX{} which are discussed below in sections +% \ref{opt:tag} and~\ref{opt:allocate}. If I discover how to make one method +% never inferior to the other, I will remove the other option from the package. +% +% \section{Usage} +% +% \DescribeMacro\include +% \DescribeMacro\AtBeginInclude +% \DescribeMacro\AtEndInclude +% \cs\include\oarg{prehook}\marg{filename}\oarg{posthook} behaves like +% standard \LaTeX{}'s \cs\include except that it can be nested and the +% contents of the two hook arguments, when they are given, are inserted at +% the beginning and end of the part whenever it is included, overriding the +% current values of \cs\AtBeginInclude and \cs\AtEndInclude. +% +% \caveat{Right square braces (|]|s) in the optional arguments must be +% surrounded by curly braces to avoid confusing the argument parser.} +% +% \caveat{A left square brace (|[|) that immediately follows an +% \cs\include command's mandatory \meta{filename} argument (after optional +% whitespace) will be considered to delimit the beginning of the +% \meta{posthook} argument. If you want an actual left brace character in +% this position, you must precede it with something that will terminate +% \TeX's search for an optional argument, such as \cs\relax, |{}|, or a +% paragraph division (explicit or implicit).} +% +% The commands \cs\AtBeginInclude\meta{tokens} and +% \cs\AtEndInclude\meta{tokens} are analagous to standard \LaTeX{}'s commands +% \cs\AtBeginDocument\meta{tokens} and \cs\AtEndDocument\meta{tokens}. +% +% FIX: multiple instances concatenate? +% +% FIX give name to what's held by atbegininclude so that an override can mention it +% +% When the optional argument \meta{prehook} is given to \cs\include, its +% contents will be used instead of whatever has been specified with +% \cs\AtBeginInclude, for that one inclusion. Likewise, \meta{posthook} will +% be used in place of whatever has been specified with \cs\AtEndInclude for +% that one inclusion. +% +% For example, putting the \cs\chapter declaration in the \meta{prehook} +% argument allows the chapter name, and, optionally, a corresponding \LaTeX{} +% label, to be kept in the including file, rather than the included file: +% \begin{codeexample} +% \include [\chapter{Whales} +% \label{ch:whales}] +% {big-cetecea} +% \end{codeexample} +% +% The \meta{posthook} argument can be used, for example, to delimit or undo +% declarations made in the \meta{prehook} or the included file: FIX: better +% example, since these coudl simple appear before/after the \cs\include +% without ill effect. +% \begin{codeexample} +% \include [\begingroup\larger] % this part in larger type +% {manifesto} +% [\endgroup] +% \end{codeexample} +% +% \DescribeMacro{\include*} +% \DescribeMacro\IncludeSurround +% \DescribeMacro\DefaultIncludeSurround +% \cname{include*}\oarg{prehook}\marg{filename}\oarg{posthook} is like +% \cs\include but omits the usual \cs\clearpage{}s that surround an included +% part, replacing them with \cs\IncludeSurround, which defaults to +% \cs\DefaultIncludeSurround. The contents of \cs\IncludeSurround are +% inserted before the \meta{prehook} or whatever has been specified with +% \cs\AtBeginInclude, and after the \meta{posthook} or whatever has been +% specified with \cs\AtEndInclude. +% +% \caveat{A space gets inserted after an \cname{include*} unless it is +% suppressed by a |%| immediately following. Combined with trailing spaces +% in the included file, this may lead to unwanted spaces. For this reason, +% \cs\DefaultIncludeSurround is initialized to \cname{par}. When the user +% must explicitly change \cs\IncludeSurround to achieve totally smooth flow +% from main file to included file, they are more likely to consult this +% documentation if they spot a problem. Package and class writers should +% take this difficulty into account when changing \cs\DefaultIncludeSurround.} +% +% \DescribeMacro\includeonly +% The \cs\includeonly command is reimplemented, but its usage and behavior is +% the same as the standard \LaTeX{} version. +% +% \DescribeMacro\includeall +% The \cs\includeall command cancels the effect of any \cs\includeonly +% command presently in effect. +% +% If you write an \cs\includeonly so that each file appears on its own line, +% it is particularly easy to add and remove files to include by commenting +% out their lines, but it becomes laborious to comment out the entire +% \cs\includeonly command. It's easy, however, to uncomment a single +% \cs\includeall command when you want to process the entire document. (Or +% \cs\includeall could be inserted from the command line that invokes +% \LaTeX{}, and so on.) +% +% \section{Experimental features} +% +% \DescribeMacro\includeenv +% \cs\includeenv\oarg{prehook}\marg{filename}\marg{environment name}% +% \marg{instance}\oarg{posthook} +% \cs\includeenv*\oarg{prehook}\marg{filename}\marg{environment name}% +% \marg{instance}\oarg{posthook} +% +% \cs\includeenv includes the contents of a single \LaTeX{} environment that +% appears in \meta{filename}. The environment is specified by giving its +% name (\meta{environment}) and an instance of that environment in the file +% (\meta{instance}). Presently, \meta{instance} is ignored, so that it will +% always be the contents of the first occurrence in \meta{filename} of a +% \LaTeX{} environment with the name \meta{environment} that will be +% included. In the future, the \meta{instance} argument may be used to +% specify the $n$th instance of the environment within the file, or further +% specify the environment to be extracted in some other way. +% +% FIX: right now they're required; skip text up to documentclass OR the target, +% then branch? +% +% Good preamble syntactic sugar: |\let\TheMarkupDeclarations\begin| +% +% \todo{You can insert a \cs\usepackage into the main aux file and have it +% loaded properly. If we discover a \cs\usepackage that is not a formatting +% package, one strategy is to insert a corresponding \cs\usepackage into the +% (main) aux file and then bail after the preamble.} +% +% \todo{You can't skip verbatim text via macro argument processing and sugar. +% this means that a major reimplementation of skipping using verbatim methods +% will have to be done.} +% +% The included file is permitted (but not required) to have its own +% \cs\documentclass command and \code{\begin{document}}\lips +% \cs{\end{document}} pair. \cs\includeenv extracts the specified +% environment by processing the preamble if one exists, skipping text up +% until the beginning of the specified environment, processing the contents +% of the environment, and skipping the rest of the included part. +% +% Notice that while a \code{\begin{document}}\lips\code{\end{document}} pair +% may not technically delimit a \LaTeX{} environment, you may nevertheless +% (because it looks exactly like an environment) set \meta{environment} to +% |document| to extract the contents of the \env{document} ``environment'' of +% \meta{filename}. +% +% Consider the following issues when you are tempted to use this +% command. Maybe the \cs\usepackage you are about to disregard is necessary +% to processing the part's contents. Maybe it conflicts with a package +% already loaded at top level. Maybe both! The same holds of course for the +% defining commands like \cs\newcommand that one expects to find in a +% package. +% +% A deep problem with the design of a \LaTeX{} source file exists with +% respect to the function of the preamble. The preamble contains +% declarations that determine how the document below will be formatted. +% Unfortunately, there is no way to make the distinction between: +% \begin{enumerate} +% \item +% declarations that signal that certain markup will appear in the document +% that are either not defined in the \LaTeX{} kernel or are used with a +% different syntax +% \item declarations that describe how a certain instance +% of the document should be formatted +% \end{enumerate} +% Examples in the first category are \code{\usepackage{url}} and \code{FIX +% example}, and examples in the second are \code{\usepackage{times}} and +% \code{FIX}. When you want to include the document or a part of it in +% another document, it is absolutely necessary to make this distinction so +% that declarations in category (1) can be processed and declarations in +% category (2) can be ignored. ^^A FIX: \cat{} is a compsci command? +% +% Adopting a convention on the use of the preamble can overcome this design +% problem, but it will not fix the problem for legacy files whose preambles +% do not obey the convention. Legacy files that contain category (1) +% declarations in their preambles must either be altered or specifically +% accommodated with additional commands. +% +% The convention I suggest is to |\usepackage{preamble}|. \cs\beginmarkup +% \cs\endmarkup. FIX. Can we arrange to load +% +% When \cs\includeenv encounters a \cs\usepackage command in the included +% part, it looks at the packages in the argument of \cs\usepackage and issues +% a warning if the package is not already loaded and does not appear on a +% list of packages known whose use falls entirely within category (2). (See +% the \cs\DeclareFormattingPackage command below.) +% +% The \cs\documentclass command is of course also a category (1) declaration. +% Presently, if \cs\includeenv detects that the arguments to an included +% \cs\documentclass command differ from the arguments of the +% \cs\documentclass command of the including document, it will issue a +% warning, and continue. In the future, I hope to make this behavior smarter +% by having \cs\includeenv take specific actions for specific combinations of +% arguments. For example, if the included document's class implies the use +% of markup not defined in the parent's class, an appropriate action would be +% to define the missing markup commands. A document of class \class{report} +% and a document of class \class{article}, on the other hand, do not (I don't +% think) declare different markup, so that there should be no warning in this +% case. +% +% \DescribeMacro{\includeenv*} +% \cname{includeenv*} is analogous to \cname{include*}, that is, it surrounds +% the included part with \cs\IncludeSurround rather than \cs\clearpage. +% +% \DescribeMacro\includedoc +% \DescribeMacro{\includedoc*} +% \cs\includedoc\oarg{prehook}\marg{file name}\oarg{posthook} is shorthand +% for +% \cs\includeenv\oarg{prehook}\marg{filename}\marg{|document|}\marg{}\oarg{posthook}. +% +% \cname{includedoc*} is analogous to \cname{includeenv*}. +% +% \section{Options} +% +% \subsection{Simple}\label{opt:simple} +% +% If the \option{simple} option is given, the only new feature provided is the +% hooks (features \ref{item:hooks} and~\ref{item:hooks:opt} above). As +% with standard \LaTeX{}, \cs\clearpage{}s surround an \cs\include and nesting +% \cs\include{}s gives an error. \package{Newclude} will only behave +% differently than standard \LaTeX{} command scans for +% possible optional arguments will make a different. +% + +% +% \subsection{Tag}\label{opt:tag} +% The \option{tag} option causes \LaTeX{} to use just one \ext{aux} file. +% This option, which is the default, works well. I am aware of the following +% two differences from the kernel's including system: +% +% \begin{enumerate} +% \item +% If the \LaTeX{} process is stopped during the processing of a part, all +% information normally stored in an \ext{aux} file from that point in the +% document forward is lost. In the kernel's system, processing the document +% twice more would recover any \ext{aux} information previously generated for +% parts. +% +% If \LaTeX{} is always invoked in \cs\nonstopmode (e.g., by \auctex), then +% this difference is only going to occur when there are catastrophic errors +% that cause even \cs\nonstopmode to terminate processing. +% +% \item Other packages and classes that redefine kernel commands that write to +% \cname{@auxout} will cause problems. +% \end{enumerate} +% +% The first difference must be accepted. The second difference can be removed +% on a case by case basis, by specifically coding compatibility with such +% packages and classes. I intend to do this. Here is a list of such packages +% and classes known to me: +% +% \begin{tabular}{l} +% \meta{none so far} +% \end{tabular} +% If you discover any more for this list, please write me! +% +% It's also very easy to revise the other package to be compatible with +% \package{newclude} as it is now. See section~\ref{adapt} below, which +% includes a list of relevant kernel commands. +% +% \subsection{Allocate}\label{opt:allocate} +% +% The second way (the \option{allocate} option) represents my first attempt at +% a solution, and until I am sure it has no advantages over \option{tag} under +% any circumstances, it will continue to be an option. +% +% The \option{allocate} option causes \LaTeX{} to dynamically allocate \TeX{} +% output streams to each part as they are needed. Streams are allocated when +% processing of the part begins, and are reclaimed after the ejection of the +% last page to which the part has contributed. Like the old system, a separate +% \ext{aux} file is created for each part. The limitation of this +% implementation is that \TeX{} only possesses 16 output streams. Each of the +% commands \cs\tableofcontents, \cs\listoffigures, \cs\listoftables, +% \cs\makeglossary, and \cs\makeindex causes \LaTeX{} to use one output stream. +% The remainder (minus any streams required by packages and classes) are +% available for the including system. If $n$ streams are available, the level +% of nesting possible is $n - 1$ minus the maximum number of parts that occur +% on the same page. For example, if 10 streams are available and the parts +% never appear on the same page (the old behavior required by the +% \cs\clearpage{}s), then 8 levels of nesting are possible (which is 8, not 7 +% more than with the old system). The maximum number of parts that may +% contribute the to same page is calculated with the same equation. Note: +% \TeX's page-breaking algorithm looks ahead until it has more than enough +% material to fill one page. You must count all the new \ext{aux} files that +% are opened during a look-ahead as contributing to the page in question, even +% if some of the later ones do not actually contribute to the page after the +% break is chosen. +% +% The \option{allocate} solution is itself implemented in two ways. The system +% either reserves a fixed number of output streams from the start, or will +% dynamically claim and free them as needed. The dynamic solution is the +% default. I do not see much use for the static solution at present. If the +% dynamic system claims streams that are later required, then it is simply a +% question of whether \package{newclude} or the other feature is going to +% signal an error about having no more streams to allocate. +% +% \section{Programmers' interface} +% +% \DescribeMacro\IfAllowed +% \cs\IfAllowed\marg{part name}\marg{true}\marg{false} executes \meta{true} +% if \meta{part-name} is on the list of files to be included and \meta{false} +% otherwise. If there is no list, executes \meta{true}. +% +% \DescribeMacro\IncludeName +% \cs\IncludeName expands to the name of the part currently being processed. +% In the toplevel source file, it will expand to \cs\jobname. +% +% \DescribeMacro\ParentName +% \cs\ParentName expands to the name of the part that includes the part +% currently being processed. In the toplevel source file, expanding +% \cs\ParentName will generate a warning and expand to \cs\jobname (which is +% also what \cs\IncludeName expands to). +% +% FIX: root source file? toplevel? master? principle source? glossary! +% +% \DescribeMacro\DeclareFormattingPackage +% \cs\DeclareFormattingPackage\marg{package name} declares \meta{package +% name} to be a package that only makes formatting declarations, that is, the +% effect of using it falls entirely within category (2). If a formatting +% package occurs in a \cs\usepackage declaration in the preamble of a part +% included by \cs\includeenv, no warning will be given. An example of a +% formatting package is the \package{times} package. No facility is provided +% to distinguish the case when a package is used with or without certain +% package options, so do not declare a package as a formatting package unless +% it is so regardless of the options it is passed. +% +% If you send me the names of formatting packages, I will include them in the +% next release of \package{newclude}. Meanwhile, you may declare them in +% \file{newclude.cfg}. Do the same for your local formatting packages if you +% wish. It does no harm to declare a package as a formatting package more +% than once. +% +% \DescribeMacro\ifSkipPreamble +% \DescribeMacro\SkipPreambletrue +% \DescribeMacro\SkipPreamblefalse +% +% \DescribeMacro\Disable +% \DescribeMacro\DisableAll +% \cs\Disable\marg{tokens} provides a way to ignore additional commands when +% using \cs\includeenv and friends. If you want to cause the macro \cs\foo +% which takes no arguments to be entirely ignored in parts, issue the command +% \code{\Disable{\let\foo\relax}} any time before including the parts you +% want to affect. If \cs\foo takes one mandatory argument, write +% \code{\let\foo\Gobble} instead. If \cs\foo takes one optional and one +% mandatory, write \code{\let\foo\GobbleOM}. And so on. For other examples, +% see the gobbling commands in the \package{moredefs} package (which +% \package{newclude} requires), or write your own. +% +% The arguments to \cs\Disable are accumulated and executed by the command +% \cs\DisableAll, which is executed inside a group that contains a part when +% it is included. +% +% There is no way to undo the effect of issuing a \cs\Disable command. +% +% \section{How to play nicely with \package{newclude}}\label{adapt} +% +% To adapt a package or class for use with the \option{tag} option of +% \package{newclude}: +% \begin{enumerate} +% \item replace |\immediate\write\@auxout| with \cs{\@writeaux} +% \item replace |\protected@write\@auxout| with \cs{\protected@writeaux} +% \item add +% \begin{codeexample} +% \providecommand\@writeaux {% +% \immediate\write\@auxout +% } +% \providecommand\protected@writeaux {% +% \protected@write\@auxout +% } +% \end{codeexample} +% \end{enumerate} +% +% \StopEventually{} +% +% \part{Implementation} +% +% \section{Version control} +% +% \begin{macro}{\fileinfo} +% \begin{macro}{\DoXUsepackagE} +% \begin{macro}{\HaveECitationS} +% \begin{macro}{\fileversion} +% \begin{macro}{\filedate} +% \begin{macro}{\docdate} +% \begin{macro}{\PPOptArg} +% These definitions must be the first ones in the file. +% \begin{macrocode} +\def\fileinfo{A new system for including files (Frankenstein's backbone)} +\def\DoXPackageS {} +\def\fileversion{v2} +\def\filedate{1999/11/02} +\def\docdate{1999/11/02} +\edef\PPOptArg {% + \filedate\space \fileversion\space \fileinfo +} +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% +% If we're loading this file from a \cs\ProcessDTXFile command (see the +% \package{compsci} package), then \cs\JusTLoaDInformatioN will be defined; +% othewise we assume it is not (that's why the FunkY NamE). +% +% If we're loading from \cs\ProcessDTXFile, we want to load the packages listed +% in \cs\DoXPackageS (needed to typeset the documentation for this file) and +% then bail out. Otherwise, we're using this file in a normal way as a +% package, so do nothing. \cs\DoXPackageS, if there are any, are declared in +% the \ext{dtx} file, and, if you're reading the typeset documentation of this +% package, would appear just above. (It's OK to call \cs\usepackage with an +% empty argument or \cs\relax, by the way.) +% \begin{macrocode} +\makeatletter% A special comment to help create bst files. Don't change! +\@ifundefined{JusTLoaDInformatioN} {% + }{% ELSE (we know the compsci package is already loaded, too) + \UndefineCS\JusTLoaDInformatioN + \SaveDoXVarS + \eExpand\csname DoXPackageS\endcsname\In {%use \csname in case it's undefined + \usepackage{#1}% + }% + \RestoreDoXVarS + \makeatother + \endinput +}% A special comment to help create bst files. Don't change! +% \end{macrocode} +% +% Now we check for \LaTeX2e and declare the LaTeX package. +% \begin{macrocode} +\NeedsTeXFormat{LaTeX2e} +\ProvidesPackage{newclude}[\PPOptArg] +% \end{macrocode}^^A special comment to help create bst files. Don't change! +% +% ^^A NOTE: We have to compensate for the above backslashes, which are not +% ^^A actually in the .dtx file the author works on, by adding to the +% ^^A CheckSum. +%% +% \AddToCheckSum{17}^^A `dtx-update-checksum' automatically handles this. +% \AddToCheckSum{7}^^A The half a macrocode env. at the top is missed, however... +% \AddToCheckSum{10}^^A ... and so are the 5 \defs from the .dtx file +% ^^A that precede it. +% \IfCitations {% +% \AddToCheckSum{2}^^A When \initelyHavECitationS is defined in +% } ^^A the .dtx file, we need 2 more in the CheckSum. +% +% +% \section{Review of the kernel's inclusion system} +% +% One \ext{aux} file is written to disk for the \term{principle source} and one +% for each of the included \term{parts}. The reason to have a separate ones +% for the parts is so that information from the last time the part was included +% is retained in subsequent runs even when the part is excluded by +% \cs\includeonly. Suppose a part is processed once, and on a subsequent run +% its name is removed from the \cs\includeonly list. This run will still read +% in the part's \ext{aux} file, since the \ext{aux} file of any part that was +% \cs\included during the last run is always read. But the information therein +% is not going to be regenerated in this run, since the part will not be +% processed. The main \ext{aux} file is created anew with each run, so this +% information would be lost if it resided there. +% +% To handle writing these multiple \ext{aux} files, the kernel uses two of +% \TeX's output streams. When a routine writes to an auxiliary file, it writes +% to \cname{@auxout}, which is \cs\let to either \cname{@mainaux}, the +% \ext{aux} file for the principle source, or \cname{@partaux} the \ext{aux} +% file for all the parts each in turn. +% +% When encountering an \cs\include command, but before deciding whether or not +% to actually load the part, the kernel writes a command to \cname{@mainaux} +% that will load the part's \ext{aux} file. The main \ext{aux} +% file is loaded by \cs\document, so that \emph{all} \ext{aux} files are read +% in every time the principle source is processed. +% +% If a part is actually loaded, a \term{checkpoint} is written to the part's +% \ext{aux} file consisting of a snapshot of the counters (a record of the +% values of all \LaTeX{} counters). On the next run, if the part is not +% actually loaded, the information in its \ext{aux} file has nevertheless +% already been processed by \cs\document. Processing the checkpoint causes a +% macro to be defined that when invoked restores the counter state. When +% \cs\include does not actually load a part it calls this checkpoint macro +% instead to alter the present counter state. +% +% This system has pitfalls as well as benefits. It is useful to keep the +% bibliography, citations, cross references, and page numbers up to date in +% certain situations, but the results can be confusing sometimes, because +% checkpoints are not documented. (Perhaps this is remedied in the 2d edition +% of the \LaTeX{} manual.) How, besides reading the code, or finding out the +% hard way, is anyone supposed to guess that rearranging two ``deactivated'' +% \cs\include statements in a principle source will bring havoc on the page +% numbers? +% +% \section{Discussion of \package{newclude}'s inclusion system} +% +% The simple removal of the \cs\clearpage{}s that surround an included part +% would cause a problem involving the delayed action of \cs\write commands. +% Suppose a part ending with a \cs\write command ends halfway down a page, and +% another \cs\write occurs in the principle source immediately (or soon) after +% the inclusion. The first must be written to \cname{@partaux} and the second +% to \cname{@mainaux}. If we close \cname{@partaux} while the first \cs\write +% is still pending, that is, before the current page has been shipped out, then +% the \cs\write will be destined for a closed stream and therefore go to the +% log file and terminal. The \cs\clearpage{}s solve this by flushing all +% pending \cs\writes. Then we can close \cname{@partaux} immediately and +% reopen \cname{@mainaux}. +% +% Successful removal of the \cs\clearpage{}s can be accomplished either by +% having the entire document use just one auxiliary file, or by allocating +% additional output streams so that it becomes possible to avoid closing +% \cname{@partaux} until after the current page is shipped out when all the +% \cs\write{}'s to it have been completed. +% +% \section{Package initialization} +% +% \begin{macrocode} +\RequirePackage{moredefs} +% \end{macrocode} +% +% \begin{macrocode} +\InitCS\sc@t@a +\DeclareOption{simple} {% + \input{simple.sto} + \let\sc@t@a\endinput +} +%^^A\DeclareOption{group} {% +%^^A \AtEndOfPackage {\input{group.sto}} +%^^A} +\DeclareOption{tag} {% + \AtEndOfPackage {\input{tag.sto}} +} +\DeclareOption{allocate} {% + \AtEndOfPackage {\input{allocate.sto}} +} +\DeclareBooleanOptions{dynamic}{static} +\ExecuteOptions{tag} +\ProcessOptions +% \end{macrocode} +% If the \option{simple} option has been given, end right here. +% \begin{macrocode} +\sc@t@a +% \end{macrocode} +% +% \section{Simple} +% +% The above option processing causes the file \file{simple.sto} to be loaded +% when the \option{simple} is given. After it is loaded, processing stops. +% When the \option{simple} option is not given, \package{newclude} package code +% continues in section~\ref{sec:common}. +% +% \input{simple.sto} +% +% \section{Common}\label{sec:common} +% +% The code in this section is common to the \option{tag} and \option{allocate} +% options. +% +% \begin{macro}{\nc@t@a} +% \begin{macro}{\nc@t@b} +% \begin{macro}{\nc@t@c} +% \begin{macro}{\nc@toks@a} +% Scratch variables. +% \begin{macrocode} +\ReserveCS\nc@t@a +\ReserveCS\nc@t@b +\ReserveCS\nc@t@c +\newtokens\nc@toks@a +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\IncludeSurround} +% \begin{macro}{\DefaultIncludeSurround} +% \mbox{} +% \begin{macrocode} +\newcommand\DefaultIncludeSurround {% + \par +} +\newlet\IncludeSurround\DefaultIncludeSurround +% \end{macrocode} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\c@IncludeDepth} +% With nested \cs\include{}s, we need some way for the various ones to +% distinguish themselves, so we keep track of the nested depth with the +% |IncludeDepth| counter. +% \begin{macrocode} +\newcounter{IncludeDepth} % starts at 0 +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\IfAllowed} +% \begin{macro}{\includeonly} +% \begin{macro}{\includeall} +% I think it's more efficient to define a macro for each included part on the +% list than it is to search through the list possibly twice for each one. +% Other opinions on making this whole thing more efficient? +% +% We are using the usual \LaTeX{} trick of undefined control sequences +% comparing equally with \cs\relax. Empty control sequences are \emph{not} +% the same. Should be followed by \meta{true clause} then \meta{false +% clause}. +% \begin{macrocode} +\newcommand\IfAllowed [1] {% + \@firstoftwo +} +\newcommand\includeall {% + \let\includeonly\Gobble +} +\defcommand\includeonly [1] {% + \@partswtrue +% \DTypeout{INCLUDEONLY}% + \edef\@partlist {\zap@space#1 \@empty}% + \@for\nc@t@a:=\@partlist \do {% + \InitName*{nc@part@\nc@t@a}% + }% + \defcommand\IfAllowed [1] {% args: part-name + \@ifundefined{nc@part@##1} {% +% \DTypeout{##1 NOTALLOWED}% + \let\nc@t@c\@secondoftwo + }{% ELSE +% \DTypeout{##1 ALLOWED}% + \let\nc@t@c\@firstoftwo + }% + \nc@t@c + }% +% \DTypeout{ENDINCLUDEONLY}% +} +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\include} +% \begin{macro}{\include*} +% This is the principle user command. The scratch variable \cname{nc@t@b} +% contains what really surrounds the included file. +% \begin{macrocode} +\def\include {% + \@ifstar {% + \let\nc@t@b\IncludeSurround + \nc@include + }{% ELSE + \let\nc@t@b\clearpage + \nc@include + }% +} +% \end{macrocode} +% \end{macro} +% \end{macro} +% +% +% \section{Experimental common} +% +% \begin{macro}{\Disable} +% \begin{macro}{\DisableAll} +% This allows the disabling hacks. +% \begin{macrocode} +\ReserveCS\DisableAll +\newcommand\Disable [1] {% + \g@addto@macro\DisableAll{#1}% +} +% \end{macrocode} +% \end{macro} +% \end{macro} +% +% We start with considering how to quit inputting a file. The idea is to make +% the \code{\end{document}} command of the part call \cs\endinput. But there +% is a hitch that characters on the line after the \code{\end{document}} get +% inserted when you don't want them to. To beat that limitation, we have to do +% some work. +% +% \begin{macro}{\nc@radical@shutdown} +% We will add a bunch of commands to this macro, with the idea of \cs\catcode{}ing +% everything and its brother to a comment. This would be a brute force +% method! +% \begin{macrocode} +\ReserveCS\nc@radical@shutdown +% \end{macrocode} +% First log a message that we're about to do some crazy things. In case +% something goes wrong, this might help. +% \begin{macrocode} +\addto@macro\nc@radical@shutdown {% + \MonsterInfo{newclude} + {\protect\nc@radical@shutdown\space beginning}} +% \end{macrocode} +% Now we start adding \cs\catcode commands. These first two should be +% redundant; but just in case someone changed things\lips. +% \begin{macrocode} +\addto@macro\nc@radical@shutdown{\catcode`\%=14} % 14 = comment +\addto@macro\nc@radical@shutdown{\catcode`\^=7} % 7 = superscript +% \end{macrocode} +% \begin{macro}{\nc@disable@char} +% Next, we define a command we weill use in a loop in a moment. +% \begin{macrocode} +\newcommand\nc@disable@char[1] {% + \addto@macro\nc@radical@shutdown + {\catcode`#1=14}} % 14 = comment +% \end{macrocode} +% The following list contains every keyboard char except these three, which are +% treated specially: |%#|. +% The first is already a comment, and we handle the second in a moment. Each +% character in the following list is \cs\catcode{}d to a comment: +% \begin{macrocode} +\@tfor\sc@t@a:=abcdefghijklmnopqrstuvwxyz% + ABCDEFGHIJKLMNOPQRSTUVWXYZ% + ~!@$&*()_+-=[]|/?.,<>% + 1234567890% + `'";:% + \^\\\{\}\ % this is really the chars "^\{}" and space + \do {\expandafter\nc@disable@char\sc@t@a} +% \end{macrocode} +% We add |#| separately, because it's tricky or impossible to put it into the +% list we just used. +% \begin{macrocode} +\nc@disable@char\# +% \end{macrocode} +% \end{macro} +% We end the macro with \cs\endinput. This has to come after all the previous, +% otherwise, \TeX{} goes ahead and reads to the end of the line immediately, +% with regular catcodes. This is a good theory, I'm not sure it's necessary. +% \begin{macrocode} +\addto@macro\nc@radical@shutdown{\endinput} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\nc@radical@shutdown@aftergroup} +% We need to use \cname{nc@radical@shutdown} this way. +% \begin{macrocode} +\newcommand\nc@radical@shutdown@aftergroup {% + \aftergroup\nc@radical@shutdown +} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\includedoc} +% \begin{macro}{\includedoc*} +% \mbox{} +% \begin{macrocode} +\newcommand\includedoc {% + \md@check@star + \Expand \sc@star@nothing\In {% + \IncludeEnv##1{document}{}% + }% +} +% \end{macrocode} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\includedocskip} +% \begin{macro}{\includedocskip*} +% \mbox{} +% \begin{macrocode} +\newcommand\includedocskip {% + \md@check@star + \Expand \sc@star@nothing\In {% + \IncludeEnvSkip##1{document}{}% + }% +} +% \end{macrocode} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\IncludeEnv} +% \begin{macro}{\nc@includeenv} +% \begin{macro}{\nc@@includeenv} +% \mbox{} +% \begin{macrocode} +\newcommand\IncludeEnv [2] {% args: environment instance + \md@check@star + \@ifnextchar [ {% ^^A for Emacs: ] + \nc@includeenv{#1}{#2}% + }{% ELSE + \nc@includeenv{#1}{#2}[]% + }% +} +\NewName{nc@includeenv} {#1#2[#3]} {% args: environment instance [prehook] + \@ifnextchar [ {% ^^A for Emacs: ] + \nc@@includeenv {#1}{#2}{#3}% + }{% ELSE + \nc@@includeenv {#1}{#2}{#3}[]% + }% +} +\NewName{nc@@includeenv} {#1#2#3[#4]} {% args: environment instance prehook [posthook] + \begingroup + \DisableAll + \let\documentclass\GobbleOM + \let\usepackage\GobbleOM + \expandafter\def\csname end#1\endcsname {% + \makeatletter + % POSTHOOK + \nc@radical@shutdown@aftergroup + }% + \expandafter\def\csname #1\endcsname {} % PREHOOK + \endgroup + \par + \Expand \sc@star@nothing\In {% + \include##1{#2}% + }% +} +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% +% \begin{macrocode} +\NewName {nc@@includeenvskip} {#1#2#3[#4]} {% args: environment instance prehook [posthook] + \begingroup + \DisableAll + \expandafter\def\csname end#1\endcsname {% + \makeatletter + % POSTHOOK + \nc@radical@shutdown@aftergroup + }% + \expandafter\def\csname #1\endcsname {} % PREHOOK + \long\def\documentclass ##1\begin{document}{% + \begingroup + \def\@currenvir{document}% + } + \endgroup + \par + #1% +} +% \end{macrocode} +% +% \section{Tag} +% +% The code in this section is processed when the \option{tag} package option is +% given (or, because the \option{tag} option is the default, when no package +% options are given.) +% +% \input{tag.sto} +% +% \section{Allocate} +% +% The code in this section is processed when the \option{allocate} package +% option is given. +% +% \input{allocate.sto} +% +% \section{Benign packages} +% +% \begin{macro}{\DeclareFormattingPackage} +% \begin{macro}{\nc@formatting@packages} +% \mbox{} +% \begin{macrocode} +\newcommand\DeclareFormattingPackage [1] {% + \addto@macro\nc@formatting@packages{,#1}% +} +\newcommand\nc@formatting@packages {times,helvetic} +% \end{macrocode} +% \end{macro} +% \end{macro} +% +% \Finale |