summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/frankenstein/newclude.sty
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /macros/latex/contrib/frankenstein/newclude.sty
Initial commit
Diffstat (limited to 'macros/latex/contrib/frankenstein/newclude.sty')
-rw-r--r--macros/latex/contrib/frankenstein/newclude.sty959
1 files changed, 959 insertions, 0 deletions
diff --git a/macros/latex/contrib/frankenstein/newclude.sty b/macros/latex/contrib/frankenstein/newclude.sty
new file mode 100644
index 0000000000..759797767c
--- /dev/null
+++ b/macros/latex/contrib/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