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