% Save file as: EXAMPLE.STY            Source: FILESERV@SHSU.BITNET  
% example.sty                                   20 May 91
%------------------------------------------------------------
% Copyright (c) 1988, 1991 by J.Schrod.
%       Distributed under the terms of the GNU General Public License.

%
% LaTeX style option example
% tested with style article, should also work with other styles
% don't use it with twoside or twocolumn option
%
% [LaTeX in MAKEPROG]


%
% Author
%       js: Joachim Schrod      <xitijsch@ddathd21.bitnet>
% Contributors
%       (** enough place for your name **)
%

%
%       VERSION HISTORY  (MSCF -- most significant change first)
%
% DATE     WHO  REMARKS
% 91-05-20 js   documentation added for distribution
% 88-06-29 js   created it for THD LaTeX tutorial




%%%%
%%%%
%%%% These TeX macros were documented with the documentation system
%%%% MAKEPROG and automatically converted to the current form.
%%%% If you have MAKEPROG available you may transform it back to
%%%% the original input: Remove every occurence of three percents
%%%% and one optional blank from the beginning of a line and remove
%%%% every line which starts with four percents.  The following lex
%%%% program will do this:
%%%%
%%%%    %%
%%%%
%%%%    ^%%%\ ?   ;
%%%%    ^%%%%.*\n ;
%%%%
%%%% MAKEPROG may be obtained over the net from the Bitnet-Listserver
%%%% LISTSERV@DHDURZ1 (filelist WEBWARE), from tuglib@science.utah.edu,
%%%% or via ftp from june.cs.washington.edu.
%%%%
%%%%
%%% \documentstyle[progltx,example]{article}


%%% \nofiles            % don't need an aux file
%%% \hfuzz=18pt         % expected overfull hboxes in code


%%% \begin{document}


%%% \title{The {\tt example\/} Style Option}
%%% \author{%                   % LaTeX does not discard unnecessary glue...
%%%    Joachim Schrod%
%%%    \thanks{%
%%%       TU~Darmstadt, Alexanderstr.~10, D-6100 Darmstadt, Germany.\hfil\break
%%%       Email: {\tt xitijsch@ddathd21.bitnet}.%
%%%       }%
%%%    }
%%% \date{20 May 91}

%%% \maketitle



%%% \chap What's this style option for?.

%%% This style option makes it easier to produce examples for \TeX{}
%%% courses. It realizes an |example| environment; the text within such
%%% an environment is typeset two times: On the left side just like any
%%% ordinary text, on the right side verbatim. So an author can be sure
%%% that the verbatim and the typeset part of an \TeX{} example is
%%% consistent. The usage is simple: Type
%%% %
%%%  \begin{quote}
%%%  |\begin{example}|
%%%  |Some \TeX{} text.|
%%%  |\end{example}|
%%%  \end{quote}
%%% %
%%%  and you get
%%% %
%%%  \begin{example}
%%% Some \TeX{} text.
%%% \end{example}
%%% %
%%%  Just note one important point: {\it The end of the environment must
%%% be on a line of it's own, there must be no space in front of the
%%% |\end|, and there must be no text -- even no comment -- behind}. For
%%% further information have a look at the section on possible
%%% enhancements.


%%% \sect This program is free software; you can redistribute it and/or
%%% modify it under the terms of the GNU General Public License as
%%% published by the Free Software Foundation; either version~1, or (at your
%%% option) any later version.

%%% This program is distributed in the hope that it will be useful, but
%%% {\bf without any warranty\/}; without even the implied warranty of
%%% {\bf merchantability\/} or {\bf fitness for a particular purpose}.  See
%%% the GNU General Public License for more details.

%%% You should have received a copy of the GNU General Public License
%%% along with this program; if not, write to the Free Software Foundation,
%%% Inc., 675~Mass Ave, Cambridge, MA~02139, USA.


%%% \sect The implementation uses an auxiliary file. This file has the
%%% extension |tmp|. Be aware of this if you use such a file name in other
%%% options. The file is not needed outside of the environment.

%%% All public markups start with |Example|, all private ones with
%%% |example_|. These two prefixes are reserved.

%%% The width of an example column is available for inspection and change
%%% in the dimension register |\ExampleWidth|.


%%% \sect This style option still has at least one problem which you
%%% should be aware of: I've encountered false indentation while I've
%%% used it within an item of a |list| environment. I remember that there
%%% was a difference if it was used with or without text in front of it.
%%% But I didn't needed this stuff so I decided not to look at.

%%% Might be, that |\everypar| is not handled correctly or that some flags
%%% should be looked at. (Remember that an |\item| in \LaTeX{} does not
%%% set anything -- it just stores it away until the start of the next
%%% paragraph!)

%%% Furthermore I set |\oddsidemargin| and |\evensidemargin| to 0\,pt, but
%%% I do not remember why. Is this really necessary? (I should have
%%% documented it in the beginning, nothing lives longer than a
%%% provision\,\dots)


%%% \sect And some future enhancements would be easy to make:
%%% %
%%%  \begin{itemize}

%%% \item The algorithm for typesetting the verbatim text should be those
%%% of |progltx|. Then tabulators and all those stuff would be handled
%%% right.

%%% \item The algorithm for detecting the environment end should be those
%%% of |progltx|, too. It would allow for comments; a markup which forbids
%%% a comment behind it should be forbidden.

%%% \item There should be a way to specify texts which are only printed in
%%% the \TeX{} part resp.\ the verbatim part. This would be helpful for
%%% inserting help lines, additional information etc. (Implementation is
%%% straightforward.)

%%% \item The implementation does not care for the |twoside| option. Then
%%% the order should be mirrored. I.e., verbatim left and \TeX{} text
%%% right.

%%% \item Other arrangements of \TeX{} text and verbatim text should be
%%% possible. E.g., on a slide there should not be beside each other but
%%% below. Perhaps also on a multi-column layout.

%%%  \end{itemize}


%%% \sect Before we start we declare some shorthands for category codes.
%%% By declaring the underscore~`(|_|)' as letters we can use it in our
%%% macros. (I agree with {\sc D.~Knuth} that
%%% |\identifier_several_words_long| is more readable than
%%% |\IdentifierSeveralWordsLong| and in every case better than
%%% |\p@@@s|.) As this is a \LaTeX{} style option the at sign is a letter
%%% anyhow; so we can use the ``private'' Plain and \LaTeX{} macros; and
%%% with the underscore we can make our own macros more readable.  But as
%%% we have to restore this category code at the end of this macro file
%%% we store its former value in the control sequence |\uscode|. This
%%% method is better than to use a group because not all macros have to
%%% be defined global this way.

%%% \beginprog
\chardef\escape=0
\chardef\open=1
\chardef\close=2
\chardef\letter=11
\chardef\other=12
%\chardef\active=13              % is defined in Plain already

\chardef\uscode=\catcode`\_      % top level macro file!

\catcode`\_=\letter
%%% \endprog


%%% \sect Now some setup where I don't remember why I've done them,
%%% perhaps it was only needed in our tutorials. -- But never change a
%%% running program by yourself, let others do the work\,\dots

%%% \beginprog
\oddsidemargin=0pt
\evensidemargin=\oddsidemargin
%%% \endprog




%%% \chap The Work is Simple.

%%% Guess, the problem of implementation is no problem: We write the whole
%%% stuff to a file and read it back twice. One time for typesetting it as
%%% it is, second time for typesetting it verbatim. That's all.

%%% So let's define our file variable and name first:

%%% \beginprog
\newwrite\example_file
\def\example_name{\jobname.tmp }        % <-- space!
%%% \endprog


%%% \sect Both parts of one example will be placed besides each other. We
%%% use the margin for the example, too. (There is not much place anyhow.)
%%% Between the two parts there is |\columnsep| space left.

%%% \beginprog
\newdimen\ExampleWidth
      \ExampleWidth=\textwidth
      \advance\ExampleWidth by \marginparwidth  % stick into margins
      \advance\ExampleWidth by -\columnsep      % between columns
      \divide\ExampleWidth by 2
%%% \endprog


%%% \sect When we're about, we may specify how to set the two parts. We
%%% may assume that the complete text is in the file |\example_name|. Both
%%% parts are typeset as minipages (it's better than vtop's for
%%% |\footnote| examples and such like). Sectioning markups and other
%%% stuff which setup things must behave as if they were not there --
%%% nobody wants an entry in his table of contents because he has used a
%%% |\section| markup in an example.

%%% The horizontal rules are needed for a better (still not correct)
%%% interline spacing.

%%% {\it FIXME: How about index and glossary entries?}

%%% \beginprog
\def\ExampleSet{%
   \begin{minipage}[t]{\ExampleWidth}%
      \hrule height\z@
      \def\markboth##1##2{}%
      \def\markright##1{}%
      \def\addcontentsline##1##2##3{}%
      \input \example_name
      \par
      \hrule height\z@
   \end{minipage}%
   }
%%% \endprog


%%% \sect Grmpfh, the \LaTeX{} |verbatim| environment is sloppy
%%% implemented (to say it polite). I will establish at least that a tab
%%% is typeset as 8~spaces; this will help some people.

%%% {\it FIXME: other\/ |verbatim| implementation!}

%%% \beginprog
\begingroup
   \catcode`\^^I=\active
   \gdef\@vobeytabs{\catcode`\^^I\active \let^^I\@xobeytab}
   \global\let^^I=\@xobeytab%           % for \write's
\endgroup
\def\@xobeytab{\space\space\space\space\space\space\space\space}
%%% \endprog


%%% \sect The verbatim code is taken from \LaTeX{}:

%%% \beginprog
\def\ExampleVerb{%
   \begin{minipage}[t]{\ExampleWidth}%
      \hrule height\z@
      \begingroup
         \small
         \parindent\z@
         \rightskip\@flushglue
         \@makeother\"\@verbatim
         \frenchspacing \@vobeyspaces \@vobeytabs
         \input \example_name
         \endverbatim
      \endgroup
      \hrule height\z@
   \end{minipage}%
   }
%%% \endprog




%%% \chap Writing the example to the auxiliary file.

%%% Now we come to the real environment: We open our auxiliary file and
%%% start copying line by line afterwards. When we see the environment
%%% end we will finish. As a convenience for input we will ignore empty
%%% lines at the beginning of the example, this is flagged by |@ignore|.

%%% \beginprog
\def\example{
   \par
   \immediate\openout\example_file\example_name
   \begingroup
      \@makeother\"\let\do\@makeother \dospecials
      \obeylines \obeyspaces
      \@ignoretrue \copy_line
   }
%%% \endprog


%%% \sect We need a reference line of the example end to compare against.
%%% This line we call |\end_of_example|. Of course all catcodes have to
%%% set up appropriately.

%%% \beginprog
\begingroup
   \catcode`\|=\escape  % | is temporary escape character
   \catcode`\[=\open    % [ and ] are temporary grouping symbols
   \catcode`\]=\close
   \catcode`\{=\other   % these are `other' in verbatim mode
   \catcode`\}=\other
   \catcode`\\=|other
   |gdef|end_of_example[\end{example}]
|endgroup
%%% \endprog


%%% \sect Following the ``golden rules of \TeX{} macro coding,'' we will
%%% split gathering of the next line and working with it. If the line
%%% equals our reference line we will stop our envirenment. Of course, we
%%% must call |\end| ourselves as we have just read it from the input and
%%% it is already tokenized.

%%% If we are inmidst the example we write the line to the auxiliary file,
%%% if we shall not skip empty lines as indicated by |@ignore|.

%%% {\it FIXME: The comparison should not be so rude!}

%%% \beginprog
\begingroup
   \obeylines \gdef\copy_line#1^^M{\write_line{#1}}%
\endgroup

\def\write_line#1{%
   \def\Next{#1}%
   \ifx \Next\end_of_example
      \def\Next{\end{example}}% % finish example
   \else
      \ifx \Next\empty
         \if@ignore             % ignore empty lines at the beginning
         \else                  % but write them out later
            \immediate\write\example_file{\Next}%
         \fi
      \else
         \immediate\write\example_file{\Next}%
         \@ignorefalse          % at least one non-empty line written
      \fi
      \let\Next\copy_line       % next line of example
   \fi
   \Next
   }
%%% \endprog


%%% \sect Now we may handle our real work: The example text is written
%%% out, we just have to set it two times. But first we must close the
%%% file. Both parts are set by a |\leftline| which inserts glue by |\hss|
%%% and will not yield an overfull hbox this way, it just sticks out to
%%% the right.

%%% We try to mimic a displayed equation in spacing -- it's better than
%%% nothing (polishing needed).

%%% \beginprog
\def\endexample{%
   \endgroup
   \immediate\closeout\example_file
   \penalty \predisplaypenalty
   \vskip \abovedisplayskip
   \leftline{\ExampleSet \hskip\columnsep \ExampleVerb}%
   \penalty \postdisplaypenalty
   \vskip \belowdisplayskip
   }
%%% \endprog


%%% \sect We must restore our catcode and are finished.

%%% \beginprog
\catcode`\_=\uscode

\endinput
%%% \endprog



%%% \end{document}