path: root/Master/texmf-dist/tex/latex/frankenstein/newclude.sty

%^^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