path: root/Master/texmf-dist/doc/latex/frankenstein/unsupported/includex.sty

%^^A* legal notices
% \iffalse
%
%   This file is part of the Frankenstein bundle, comprising the
%   files listed in the file Manifest.txt.  You should have
%   received the complete bundle when you received this file. 
%
%   Copyright 1995-2001 Matt Swift <swift@alum.mit.edu>.
%
%   This file contains both the code and documentation for the
%   includex LaTeX package.  It will work ONLY if it is placed in
%   a proper directory.  Files called README, INSTALL,
%   includex.tex includex.ins, and includex.dvi
%   should have also been distributed to you with this file.  See
%   README for more information on 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{227}
% 
% \begin{abstract}
%   Includex allows you to include just the contents of one source file into
%   another, ignoring the text outside the
%   \code{\begin{document}}\lips\code{\end{document}} in the included file.
%
%   This package is useful but may have problems and is unsupported.
%
%   See also the \package{newclude} package.
% \end{abstract}
% \tableofcontents
%
% \part{Discussion}
% \section{Including Files}
%
% \DescribeMacro{\include*}
% \cs\include was always pretty useless to me because it did a \cs\clearpage
% before and after the \cs\input.  The macro |\include*| is defined below to be
% like \cs\include but without the \cs\clearpage s.
%
% The other thing we do is define a command \cs\includedoc, which includes a
% file which is allowed to have its own \cs\documentclass and |\begin{document}|
% and |\end{document}| and \cs\usepackage commands.  
%
% This opens up a whole new world of truly modular \LaTeX{} files.  There is
% even nothing special about extracting the |document| environment, we can
% extract \emph{any} environment, or perhaps even other things.
%
% There are some problems, however.  Maybe the \cs\usepackage is necessary,
% maybe it would conflict.  Same with other commands like the \cs\newcommand
% family. It is simply not (yet) an issue in \LaTeX{} design to consider the
% implications of parent files.  The problems are not insurmountable.  We can
% begin by working with a convention, and ultimately maybe make some changes in
% certain macros.  I will be getting to all this.  I admit I have not looked
% carefully to see whether the design specifications of \LaTeX3{} address these
% important issues. 
%
% The macros here will be useful in many circumstances, when the included files
% are themselves simple.  
%
% \DescribeMacro{\includedoc}
% \DescribeMacro{\includedoc*}
% \DescribeMacro{\includedocskip}
% \DescribeMacro{\includedocskip*}
%   There are now two main commands, \cs\includedoc and \cs\includedocskip,
%   each with a |*| version analogous to the new \cmd{include*}.  Each take a
%   filename as an argument just like \cs\include.
%
%   \cs\includedoc\marg{filename} reads everything in the file except for
%   \cs\documentclass, \cs\usepackage, |\begin{document}|, |\end{document}|
%   (and whatever follows it).
%
%   \cs\includedocskip\marg{filename} does the same except it also skips
%   everything between \cs\documentclass and |\begin{document}|.
%
% \DescribeMacro{\disable}
%   At present there is a makeshift way to ignore additional commands when
%   using \cs\includedoc and \cs\includedocskip. If you want to cause \cs\foo
%   which takes no arguments to be disabled, say |\disable{\let\foo\relax}|. If
%   \cs\foo takes one mandatory argument, say |\let\foo\Gobble| instead.  If
%   \cs\foo takes one optional and one mandatory, say |\let\foo\GobbleOM|.  If
%   \cs\foo takes two mandatory arguments, say |\let\foo\GobbleMM|.  For other
%   permutations of arguments, you can extrapolate from the macros defined
%   below.
%
% \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{extra ways to include files}
\def\DoXPackageS {}
\def\fileversion{v0.6a}
\def\filedate{1999/02/23}
\def\docdate{1999/02/23}
\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{includex}[\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{Requirements}
%
% Now we declare the package, check for \LaTeX2e, and load the other packages
% needed. 
%    \begin{macrocode}
\NeedsTeXFormat{LaTeX2e}
\ProvidesPackage{includex}
\RequirePackage{moredefs}
%    \end{macrocode}
%
% \section{Disabling things}
%
% \begin{macro}{\disable}
% This allows the disabling hacks.
%    \begin{macrocode}
\ReserveCS\DisableMonster  % This line is elsewhere for main package
\newcommand\disable[1] {%
  \g@addto@macro\DisableMonster{#1}%
}
%    \end{macrocode}
% \end{macro}
%
% \section{New things}
%
% \begin{macro}{\sc@saved@include}
% \begin{macro}{\include}
% \begin{macro}{\sc@include}
% \begin{macro}{\sc@@include}
% This is a simple redefinition of \cs\include without the \cs\clearpage
% commands.  Nothing tricky going on. 
%    \begin{macrocode}
\newlet\sc@saved@include\include
\renewcommand\include {%
  \@ifstar
      \sc@include
    \sc@saved@include
}
\newcommand\sc@include {%
  \relax
  \ifnum\@auxout=\@partaux
    \@latex@error{\string\include\space cannot be nested}\@eha
  \else
    \expandafter\sc@@include
  \fi
}
\newcommand\sc@@include[1] {%
  \if@filesw
    \immediate\write\@mainaux{\string\@input{#1.aux}}%
  \fi
  \@tempswatrue
  \if@partsw 
    \@tempswafalse
    \edef\@tempb{#1}%
    \@for \@tempa:=\@partlist
      \do{\ifx\@tempa
            \@tempb
            \@tempswatrue
          \fi}%
  \fi
  \if@tempswa 
    \let\@auxout\@partaux 
    \if@filesw
      \immediate\openout\@partaux #1.aux%
      \immediate\write\@partaux{\relax}%
    \fi
    \@input@{#1.tex}%
    \@writeckpt{#1}%
    \if@filesw
% NOTE: Robin took out the \immediate here.
%      \immediate\closeout\@partaux 
      \closeout\@partaux 
    \fi
  \else
    \@nameuse{cp@#1}%
  \fi
  \let\@auxout\@mainaux
}
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
%
% Now we start dealing with the much more tricky extraction of the |document|
% environment.
%
% We start with considering how to quit inputting a file.  The idea is to make
% the |\end{document}| command of the included file call \cs\endinput.  But
% there is a hitch that characters on the line after the |\end{document}| get
% inserted when you don't want them to.  To beat that limitation, we have to do
% some work.
%
% \begin{macro}{\sc@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\sc@radical@shutdown
%    \end{macrocode}
% First log a message that we're about to do some crazy things. In case
% something ever goes wrong, this might help.
%    \begin{macrocode}
\addto@macro\sc@radical@shutdown {%
  \PackageInfo{includex}{\protect\sc@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\sc@radical@shutdown{\catcode`\%=14}    % 14 = comment
\addto@macro\sc@radical@shutdown{\catcode`\^=7}     % 7 = superscript
%    \end{macrocode}
% \begin{macro}{\sc@disable@char}
% Next, we define a command we weill use in a loop in a moment.
%    \begin{macrocode}
\newcommand\sc@disable@char[1] {%
  \addto@macro\sc@radical@shutdown
    {\catcode`#1=14}}  % 14 = comment
%    \end{macrocode}
% \end{macro}
% 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\sc@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}
\sc@disable@char\#
%    \end{macrocode}
% 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\sc@radical@shutdown{\endinput}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\sc@radical@shutdown@aftergroup}
% We need to use |\sc@radical@shutdown| this way.
%    \begin{macrocode}
\newcommand\sc@radical@shutdown@aftergroup {%
  \aftergroup\sc@radical@shutdown
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\sc@begindoc@toks}
% \begin{macro}{\sc@enddoc@toks}
% These are for \cs\AtBeginIncludedDocument and \cs\AtEndIncludedDocument.
%    \begin{macrocode}
\newtoks\sc@begindoc@toks
\sc@begindoc@toks{}
\newtoks\sc@enddoc@toks
\sc@enddoc@toks{}
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\AtBeginIncludedDocument}
% The analogue of \cs\AtBeginDocument.
%    \begin{macrocode}
\newcommand\AtBeginIncludedDocument[1] {%
    \sc@begindoc@toks\expandafter{\the\sc@begindoc@toks#1}%
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\AtEndIncludedDocument}
% The analogue of \cs\AtEndDocument
%    \begin{macrocode}
\newcommand\AtEndIncludedDocument[1] {%
    \sc@enddoc@toks\expandafter{\the\sc@enddoc@toks#1}%
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\includedoc}
% \begin{macro}{\includedoc*}
% Now we start from the other end, defining the user command.
%    \begin{macrocode}
\newcommand\includedoc {%
% Robin's new:
  \@ifstar {%
      \def\sc@includebit@cmd{\include*}\sc@includebit
    }{% ELSE
    \let\sc@includebit@cmd\include\sc@includebit
  }%
}

% My old:
%      {\sc@includebit}
%    {\clearpage
%    \sc@includebit[\clearpage]}}
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\sc@includebit}
% The commented-out code is for some eventual extensions.
%
% Interface is \cmd{sc@includebit}\oarg{postlude}\marg{file} (where
% \oarg{postlude} is command(s) to be executed after the inclusion is
% complete); it is assumed that \cmd{sc@includebit@cmd} is either \cs\include
% or \cmd{include*}
%    \begin{macrocode}
\newcounter{sc@count}
\newcounter{bit}
\newcommand\sc@includebit [2] [] {%
  \setcounter{sc@count}{\thebit}%
  \begingroup
    \DisableMonster  
    \let\usepackage\GobbleOM
% Robin's new:
    \def\enddocument {%
      \makeatletter
      \the\sc@enddoc@toks
      \sc@radical@shutdown@aftergroup
    }
% My old:
% \let\enddocument\sc@radical@shutdown@aftergroup
    \let\documentclass\GobbleOM  
    \let\documentstyle\GobbleOM  % why worry about branching if 2.09..
    \def\document {%
      \the\sc@begindoc@toks
    }%
    \def\IncludedJobname {#2}%
    \sc@includebit@cmd{#2}% 
  \endgroup
  \par
  #1
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\includedocskip}
% \begin{macro}{\includedocskip*}
% Now we make a similar command that \emph{entirely} skips the preamble,
% whereas \cs\includedoc only skipped those commands that we specifically
% disabled.  Obviously this whole business of the preamble needs to be
% radically reconceived if convenient modularity of documents is to be had.  At
% the moment, no distinction is made between things like \cs\newcommand and
% \cs\usepackage that should be exported to a parent file, and those things that
% should not.
%    \begin{macrocode}
\newcommand\includedocskip {%
  \@ifstar {%
      \sc@includebitskip
    }{% ELSE
    \clearpage
    \sc@includebitskip[\clearpage]%
  }%
}
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% I tried combining |\sc@includebitskip| and |\sc@includebit| but something
% changed when I used a conditional to do this.  I'm sure the problem could be
% figured out and the two combined.
%
% \begin{macro}{\sc@includebitskip}
% We begin skipping with the \cs\documentclass or \cs\documentstyle command, and
% stop with the |\begin{document}| command.  With some hacking to the new
% |verbatim| environment, this could be done.  I haven't done this yet, so this
% is implemented by stuffing everything into a macro argument.  I can't think
% of a \cs\begin occurring between \cs\documentclass the \cs\begin document, but
% that will screw things up if it does.
%
% The commented lines here are once again for a future extension.
%    \begin{macrocode}
\newcommand\sc@includebitskip [2] [] {%
  \setcounter{sc@count}{\thebit}%
  \begingroup
    \DisableMonster
    \let\enddocument\sc@radical@shutdown@aftergroup
    \long\def\documentclass ##1\begin{%
      \begingroup
      \def\@currenvir{document}%
      \GobbleM
    }% "{document}" is still to be read.
    \let\documentstyle\documentclass
    \include*{#2}%
  \endgroup
  \par
  #1\relax
}
%    \end{macrocode}
% \end{macro}
%
% \Finale