% 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}
|
