%% This file is a hack; The author, Matt Swift <swift@bu.edu> plans to
%% provide this functionality in a totally reworked package sometime
%% in the indefinite future.  13 April 1996.
%
%% WARNING:  the *-forms will cause problems with juggling around the
%% location of things written to the .aux files -- such as citations and
%% index entries, when they occur near the junction.  It's best not to
%% use them.
%
% \section{Including Files}
% \DescribeMacro{\include*}
% |\include| was always pretty useless to me because it did a |\clearpage|
% before and after the |\input|.  The macro |\include*| is defined below to be
% like |\include| but without the |\clearpage|s. 
%
% The other thing we do is define a command |\includedoc|, which includes a
% file which is allowed to have its own |\documentclass| and |\begin{document}|
% and |\end{document}| and |\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 |\usepackage| is necessary,
% maybe it would conflict.  Same with other commands like the |\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, |\includedoc| and |includedocskip|, each
% with a |*| version analogous to the new |\include*|.  Each take a filename as
% an argument just like |\include|. 
%
% |\includedoc|\marg{filename} reads everything in the file except for
% |\documentclass|, |\usepackage|, |\begin{document}|, |\end{document}| (and
% whatever follows it).  
%
% |includedocskip|\marg{filename} does the same except it also skips everything
% between |\documentclass| and |\begin{document}|.
%
% \DescribeMacro{\GobbleOM}
% \DescribeMacro{\Gobble}
% \DescribeMacro{\GobbleMM}
% \DescribeMacro{\disable}
% At present there is a makeshift way to ignore additional commands when using
% |\includedoc| and |\includedocskip|. If you want to cause |\foo| which takes
% no arguments to be disabled, say |\disable{\let\foo\relax}|. If |\foo| takes
% one mandatory argument, say |\let\foo\Gobble| instead.  If |\foo| takes one
% optional and one mandatory, say |\let\foo\GobbleOM|.  If |\foo| takes two
% mandatory arguments, say |\let\foo\GobbleMM|.  For other permutations of
% arguments, you can extrapolate from the macros defined below. 
%
% \StopEventually{}
%
% \begin{macro}{\fileinfo}
% \begin{macro}{\fileversion}
% \begin{macro}{\filedate}
% \begin{macro}{\docdate}
% \begin{macro}{\Frankenversion}
% \begin{macro}{\sc@ppoptarg}
%    \begin{macrocode}
\def\fileinfo{extra ways to include files}
\def\fileversion{v0.5}
\def\filedate{1996/04/12}
\def\docdate{1995/03/01}
\def\Frankenversion{\expandafter\@cdr\fileversion\@nil}

\@ifdefinable{PPOptArg}
  {\edef\sc@ppoptarg{\filedate\space \fileversion\space \fileinfo}}
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
%
% Now we declare the package, check for \LaTeX2e, and load the other packages
% needed. 
%    \begin{macrocode}
\NeedsTeXFormat{LaTeX2e}
\ProvidesPackage{includex}
\RequirePackage{moredefs}
%    \end{macrocode}
%
% \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}
%
% \begin{macro}{\sc@saved@include}
% \begin{macro}{\include}
% \begin{macro}{\sc@include}
% \begin{macro}{\sc@@include}
% This is a simple redefinition of |\include| without the |\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
      \immediate\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 |\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 |\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 |\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}
% 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 |\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}
% \end{macro}
% We end the macro with |\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}{\includedoc}
% \begin{macro}{\includedoc*}
% Now we start from the other end, defining the user command.
%    \begin{macrocode}
\newcommand\includedoc
  {\@ifstar
      {\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. 
%    \begin{macrocode}
\newcommand\sc@includebit[2][]
  {%\setcounter{sc@count}{\thebit}%
  \begingroup
  \DisableMonster  
  \let\usepackage\GobbleOM
  \let\enddocument\sc@radical@shutdown@aftergroup
  \let\documentclass\GobbleOM  
  \let\documentstyle\GobbleOM  % why worry about branching if 2.09..
  \renewcommand\document{}%
  \include*{#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 |\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 |\newcommand| and
% |\usepackage| that should be exported to a parent file, and those things that
% should not.
%    \begin{macrocode}
\newcommand\includedocskip
  {\@ifstar
      {\sc@includebitskip}
    {\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 |\documentclass| or |\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 |\begin| occurring between |\documentclass| the |\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}%
    \Gobble}  % "{document}" is still to be read.
  \let\documentstyle\documentclass
  \include*{#2}%
  \endgroup
  \par
  #1}
%    \end{macrocode}
% \end{macro}