%% BEGIN xcomment.tex
%%
\def\FileVersion{1.2}
\def\FileDate{93/02/12}
%%
%% This file prints out the documentation for xcomment.sty by
%% setting up a few things and then inputting xcomment.doc.
%% Use with LaTeX, with or without the NFSS.
%%
%% You must Frank Mittelbach's
%%     doc.sty and gind.ist
%% (tested with v1.7k of doc.sty). These are available from
%%     rusmv1.rus.uni-stuttgart.de
%% and
%%     ymir.claremont.edu
%%
%% gind.ist is for making an index. After resolving cross-references,
%% give the command
%%      makeindex -s gind.ist xcomment.idx
%% and run the file again.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\documentstyle[doc]{article}

\makeatletter

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%%  Page Parameters:
%%
%  \onecolumn
\sloppy
\setlength{\columnsep}{1.5pc}        % space between columns
\setlength{\columnwidth}{18.75pc}    % width of each column
\setlength{\parindent}{20pt}         % paragraph indent
\setlength{\parskip}{0pt}            % no inter-paragraph space
\setlength{\leftmargini}{2em}        % unchanged
\setlength{\leftmarginv}{.5em}       % unchanged
\setlength{\leftmarginvi}{.5em}      % unchanged
\setlength{\oddsidemargin}{0pt}      % was 42pt
\setlength{\evensidemargin}{0pt}     % was 84pt
\setlength{\topmargin}{-2.5pc}       % was 0pt
\setlength{\headheight}{12pt}        % height of running head, unchanged
\setlength{\headsep}{20pt}           % distance between header and text
\setlength{\marginparwidth}{70pt}    % Big enough for using DescribeMacro.
\setlength{\marginparsep}{10pt}      %  in TUGboat
\setlength{\textheight}{54pc}        % height of text on page
\setlength{\textwidth}{39pc}         % total width of a page
\twocolumn              % two columns %FMi placed after setting of \textwidth
%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%  And finally some definitions for the doc style
%%  to get this special article right.
%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\def\expanddate#1/#2/#3/{%
  \number#3{}
  \month=#2
  \ifcase\month\or
    January \or February \or March \or April \or May \or June \or
    July \or August \or September \or October \or November \or December
  \fi
  19#1}

\def\thefiledate{\expandafter\expanddate\FileDate/}

\pagestyle{myheadings}

\def\section{\@startsection {section}{1}{\z@}{-8pt}{4pt}%
  {\normalsize\bf\raggedright}}

\def\subsection{\@startsection{subsection}{2}{\z@}{-8pt}{4pt}%
  {\normalsize\bf\raggedright}}

\def\subsubsection
  {\@startsection{subsubsection}{3}{\z@}{-8pt}{4pt}{\normalsize\bf}}

\def\@maketitle{%
  \newpage
  \null
  \begin{center}
    {\Large\bf \@title \par}
    \vskip .5em
    \bf
    Version \FileVersion\\
    \thefiledate\par
    \vskip 1.2em
    {\lineskip .5em \begin{tabular}[t]{c}\@author\end{tabular}\par}
  \end{center}
  \par
  \vskip .5em}

\catcode`\@=12

\newcommand{\SelfDocumenting}{%
  \setlength{\textwidth}{31pc}
  \onecolumn
  \setlength{\parindent}{0pt}
  \setlength{\parskip}{2pt plus 1pt minus 1pt}
  \setlength{\oddsidemargin}{8pc}
  \setlength{\evensidemargin}{8pc}}

\setcounter{IndexColumns}{2}               % two column index

\renewcommand{\theCodelineNo}{{\rm\tiny\arabic{CodelineNo}}}

\MakeShortverb{\|}

%\DisableCrossrefs                         % Runs faster
\EnableCrossrefs

%\OnlyDescription                         % Full article

\CodelineIndex                            % Code lines numbered

% INDEX STUFF
\DoNotIndex{\ ,\!,\[,\\,\],\^,\`,\{,\},\~,\z@}
\DoNotIndex{\@ifundefined,\@namedef,\@spaces,\@tempa,\@tempb}
\DoNotIndex{\@warning,\active,\global,\rule,\ifnum,\include,\jobname}
\DoNotIndex{\begingroup,\catcode,\char,\csname,\def,\do,\endinput}
\DoNotIndex{\docdate,\dospecials,\edef,\else,\endcsname,\endgroup}
\DoNotIndex{\expandafter,\fi,\filedate,\fileversion,\@temptokena,\end}
\DoNotIndex{\gdef,\if,\ifcat,\closeout,\@testfalse,\@testtrue,\if@test}
\DoNotIndex{\ifx,\immediate,\lccode,\let,\@nnil,\@tempd,\begin,\closein}
\DoNotIndex{\lowercase,\next,\noexpand,\@empty,\@for,\@ifnextchar,\@nil}
\DoNotIndex{\relax,\space,\the,\bgroup,\egroup,\@@input,\@bsphack,\@esphack}
\DoNotIndex{\toks@,\count@,\dimen@,\dime,\medbreak,\newread,newwrite}
\DoNotIndex{\openin,\openout,\par,\read,\typeout,\vbox,\vfill,\write}
\DoNotIndex{\hrule,\newwrite,\@captype,\nobreak}

\SelfDocumenting

\markboth{\hfill Documentation for xcomment.sty \hfill \thefiledate}%
  {\thefiledate \hfill Documentation for xcomment.sty \hfill}

\title{\vspace*{-.5in}Documentation for xcomment.sty%
   \thanks{This file borrows much from verbatim.sty, v.1.4c (90/10/18)
  Copyright (C) 1989, 1990 by Rainer Sch\"opf.}}

\author{Timothy Van Zandt%
  \thanks{Author's address: Department of Economics, Princeton University,
  Princeton, NJ 08544-1021, USA. Internet: {\tt tvz@Princeton.EDU}}}%

\begin{document}

\maketitle

\vspace*{-.2in}
\section*{Abstract}
The \LaTeX{} style option verbatim.sty, by Rainer Sch\"opf, allows one to
redefine an environment to be a comment, and thereby selectively omit
certain environments when typesetting a document.
Suppose instead that one wants to typeset only selected environments? For
example, one might want to print only a document's tables and figures,
without having to enclose all the text outside these environments within
comments. This style option allows such selection.

\section{Usage notes}

This style file defines a new environment, |xcomment|, which permits one to
typeset only selected environments, without having to enclose all the text
outside these environments within comments. The main interest in such a
feature is that it allows document styles to have great control over what
parts of a document are typeset, thus extending the modularity of \LaTeX.
For example, this option was originally written for use in a document style
for seminar notes and slides. The main text of the input file consists of
the notes for a seminar, and each slide goes in a |slide| environment. A
simple modification of the style options allows one to typeset only the
slides, only the notes, or both together, in a variety of styles.


\DescribeMacro{\xcomment}
\DescribeEnv{xcomment}
The |xcomment| environment has as a single mandatory argument a list
(possibly empty) of environments, separated by commas and with no spaces.
Within the |xcomment| environment, only text within each of the specified
environments is typeset.
The |\xcomment| command can also be used directly, with the same argument,
and it would typically go in the preamble. Invoking the |\xcomment| command
is equivalent to putting |\begin{xcomment}| at the invocation of the command
or immediately after |\begin{document}|, whichever occurs later in the
document, and |\end{xcomment}| just before the end of the document.

For example, if |\xcomment{table,figure}| is put in the preamble, only
tables and figures are typeset (but see |\nofloat| below). If the list of
environments is empty, as in |\begin{xcomment}{}|, the |xcomment|
environment is essentially like the |comment| environment in verbatim.sty.

|xcomment| environments can be nested, but if the nested environments
have the same name, the inner environments must be inside text that is
typeset as specified by the |xcomment| environment the next level up.

Here is an example of such nesting. Suppose we want to include only figures,
but we also want to be able to comment out some of the figures so that they
are not included. This is achieved in the following example:
\begin{verbatim}
    \newxcomment[]{mycomment}
    \begin{xcomment}{figure,mycomment}
      This is stuff that is not included.
      \begin{figure}
        This figure is included.
      \end{figure}
      More stuff that is not included.
      \begin{mycomment}               Out and back into comment mode
        \begin{figure}                Ignored by mycomment envir.
          This figure is NOT included.
        \end{figure}                  Also ignored by mycomment envir.
      \end{mycomment}                 In and back out of comment mode.
      More stuff that is not included.
    \end{xcomment}
\end{verbatim}

|xcomment| will follow |\input| and |\include| commands. You must use the
\LaTeX{} syntax |\input{file}| (as opposed to \verb*+\input file +), and the
inputted file must end with |\endinput|.
You should be in |xcomment| mode when the |\endinput| command occurs
if and only if you were in |\xcomment| mode when the |\input| or |\include|
command was found.

  |xcomment| is searching literally for |\begin{foo}| and |\end{foo}| when
determining whether to switch in or out of comment mode. It will not find,
e.g., |!begin[foo]|, even if |!|, |[| or |]| have category codes 0, 1 and 2,
respectively. (If you don't understand this, you can safely ignore it.)

\DescribeMacro{\xcommentchar}
The comment character, |%|, is still a comment character in |xcomment|
environments (even if used with |\%|). You can change the command character by
redefining |\xcommentchar|. For example, if I want to use |"| as a comment
character:
\begin{verbatim}
    \renewcommand{\xcommentchar}{\"}
\end{verbatim}
If you define |\xcommentchar| to be empty, then no comment character is used.

\DescribeMacro{\rescanfile}
\DescribeMacro{\norescanfile}
In the |xcomment| environment, text is processed a line at a time and
discarded until |\end{xcomment}| or |\begin{|\meta{environment}|}| is
encountered, where {\em environment} is to be included. The remaining text
on the line is not thrown away, as it is in verbatim.sty. Instead, it is
rescanned, and the only restrictions are that it have balanced braces and
that it not contain commands that again shift into {\em and} out of
``comment'' mode.

This is an important feature, because the included environments may have
arguments that are best placed on the same line as the
|\begin{|\meta{environment}|}| command. However, the rescanning creates a
temporary file. By default, the file is |\jobname.tmp|. The command
|\rescanfile{|\meta{file}|}| causes \meta{file} to be created instead.
|\rescanfile{}| suppresses the creation of a temporary file; the leftover
text is simply discarded. |\norescanfile| also suppresses the creation
of a temporary file, but in this case the text is simply inserted
without being rescanned (i.e., with category codes 0 (escape
|\|), 1 (begin group |{|), 2 (end group |}|) and 6 (parameter |#|) switched
to 12 (other).

\DescribeMacro{\envirsep}
The command |\envirsep| is executed between the environments that are
typeset. Its default definition is |\par|.

\DescribeMacro{\newxcomment}
The command
\begin{verbatim}
    \newxcomment[|\meta{environment list}|]{|\meta{name}|}
\end{verbatim}
defines |\name| and the |name| environment to work like |\xcomment| and the
|xcomment| environment. A list of environments to be included can be given
as an optional first argument to |\newxcomment|, in which case the new
command and environment do not take an argument. For example, if you put
|\newxcomment[]{mycomment}| in the preamble, the |mycomment| environment
works like the |comment| environment in verbatim.sty, except for the
rescanning.

\DescribeMacro{\nofloat}
The command |\nofloat{|\meta{environment list}|}| is provided to disable the
floating of environments in the list (also separated by commas and without
spaces), since if there are only floats and no text, the floats will
accumulate to the end of the document and \TeX{} may run out of memory.

\paragraph{Caveats:}
\begin{itemize}
\item If |\xcomment| is invoked in the preamble, |\document| should not be
subsequently redefined.
\item Be careful what argument you give to |\rescanfile|, since any existing
file with that name will be destroyed, and the extension |tex| is added if
no extension is given.
\end{itemize}

\paragraph{Changes to v1.2:}
\begin{itemize}
\item |\include| now allowed.
\item Comment characters not obeyed, as determined by |\xcommentchar|.
\end{itemize}

\paragraph{Changes to v1.1:}
\begin{itemize}
\item Fixed bug in |\@xcomment| that caused problems when invoking |\xcomment|
in the preamble.
\end{itemize}

\paragraph{Changes to v1.0:}
\begin{itemize}
\item Main loop rewritten.
\item |\rescanfile{trash}| changed to |\rescanfile{}|.
\item |\rescanfile{bounce}| no longer supported. Use |\norescanfile|.
\item |\input| now allowed.
\end{itemize}

  \DocInput{xcomment.doc}
  \newpage
  \PrintIndex
\end{document}
%% END xcomment.tex