split old example.sty from misc209

git-svn-id: svn://tug.org/texlive/trunk@33388 c570f23f-e606-0410-a88d-b1316a301751

1 files changed, 412 insertions, 0 deletions

diff --git a/Master/texmf-dist/tex/latex/example/example.sty b/Master/texmf-dist/tex/latex/example/example.sty
new file mode 100644
index 00000000000..bdab7fa1921
--- /dev/null
+++ b/Master/texmf-dist/tex/latex/example/example.sty
@@ -0,0 +1,412 @@
+% 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}