diff options
author | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
---|---|---|
committer | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
commit | e0c6872cf40896c7be36b11dcc744620f10adf1d (patch) | |
tree | 60335e10d2f4354b0674ec22d7b53f0f8abee672 /macros/latex/contrib/mdwtools/sverb.dtx |
Initial commit
Diffstat (limited to 'macros/latex/contrib/mdwtools/sverb.dtx')
-rw-r--r-- | macros/latex/contrib/mdwtools/sverb.dtx | 1186 |
1 files changed, 1186 insertions, 0 deletions
diff --git a/macros/latex/contrib/mdwtools/sverb.dtx b/macros/latex/contrib/mdwtools/sverb.dtx new file mode 100644 index 0000000000..df12c8c1df --- /dev/null +++ b/macros/latex/contrib/mdwtools/sverb.dtx @@ -0,0 +1,1186 @@ +% \begin{meta-comment} +% +% $Id: sverb.dtx,v 1.3 1996/11/19 21:01:18 mdw Exp $ +% +% Verbatim typesetting done properly (ahem) +% +% (c) 1996 Mark Wooding +% +%----- Revision history ----------------------------------------------------- +% +% $Log: sverb.dtx,v $ +% Revision 1.3 1996/11/19 21:01:18 mdw +% Entered into RCS +% +% +% \end{meta-comment} +% +% \begin{meta-comment} <general public licence> +%% +%% sverb package -- handling of verbatim text +%% Copyright (c) 1996 Mark Wooding +%% +%% 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 2 of the License, or +%% (at your option) any later version. +%% +%% This program is distributed in the hope that it will be useful, +%% but WITHOUT ANY WARRANTY; without even the implied warranty of +%% MERCHANTABILITY or 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. +%% +% \end{meta-comment} +% +% \begin{meta-comment} <Package preamble> +%<+package>\NeedsTeXFormat{LaTeX2e} +%<+package>\ProvidesPackage{sverb} +%<+package> [1996/05/08 1.3 Verbatim typesetting] +% \end{meta-comment} +% +% \CheckSum{651} +%% \CharacterTable +%% {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z +%% Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z +%% Digits \0\1\2\3\4\5\6\7\8\9 +%% Exclamation \! Double quote \" Hash (number) \# +%% Dollar \$ Percent \% Ampersand \& +%% Acute accent \' Left paren \( Right paren \) +%% Asterisk \* Plus \+ Comma \, +%% Minus \- Point \. Solidus \/ +%% Colon \: Semicolon \; Less than \< +%% Equals \= Greater than \> Question mark \? +%% Commercial at \@ Left bracket \[ Backslash \\ +%% Right bracket \] Circumflex \^ Underscore \_ +%% Grave accent \` Left brace \{ Vertical bar \| +%% Right brace \} Tilde \~} +%% +% +% \begin{meta-comment} +% +%<*driver> +\input{mdwtools} +\describespackage{sverb} +\mdwdoc +%</driver> +% +% \end{meta-comment} +% +% \section{User guide} +% +% The \package{sverb} package provides some useful commands and environments +% for doing things with verbatim text. I prefer this code to the standard +% \package{verbatim} package (by Rainer Sch\"opf et al.)\ although I'm +% biased. +% +% The package was written to fulfil a particular purpose: I wanted to be able +% to typeset ARM assembler code, 77~columns wide, on A5~paper, with the +% fields separated by \textit{tab} characters. It's grown up fairly +% organically from that, and I've tidied it when I've seen the code get too +% ugly. +% +% The current features are: +% +% \begin{itemize} +% +% \item A `listing' environment which typesets verbatim text nicely. +% +% \item A command to read verbatim text from an external file. +% +% \item Support for arbitrary-sized chunks of text without overflowing \TeX's +% memory. +% +% \item Support for \textit{tab} characters in the verbatim text. +% +% \item An environment for typesetting demonstrations of \LaTeX\ markup. +% +% \item It all works correctly with the \package{doc} system for documenting +% \LaTeX\ packages. +% +% \item A fairly hairy but quite powerful programmer interface to the yukky +% bits of the package. +% +% \end{itemize} +% +% The interface is described in its own section, so that more timid readers +% can avoid it. That said, some of the stuff in this section gets rather +% technical. +% +% Note that this package doesn't even try to do anything with short bits of +% verbatim text (as handled by the |\verb:...:| command). I have a separate +% package (\package{syntax}) which does all sorts of horrible things along +% those lines. +% +% \subsection{The \env{listing} environment} +% +% \DescribeEnv{listing} +% The main method for typesetting verbatim text is the \env{listing} +% environment. This works pretty much the same as the standard +% \env{verbatim} environment, with some exceptions, which are described +% below. +% +% So that you know exactly what you're getting, here are the rules by which +% \package{sverb} decides what the verbatim text actually is: +% +% \begin{itemize} +% +% \item If there's any text, other than spaces, on the same line as the +% `|\begin{listing}|', then the contents of the environment begins +% immediately after the closing brace (with all leading spaces +% preserved). Otherwise, the text begins on the following line. +% +% \item If there is any text, other than spaces, before the +% `|\end{listing}|', but on the same line, this is considered to be the +% last line of the text; otherwise the text is presumed to have ended +% at the end of the previous line. +% +% \item Any text following the |\end{listing}| on the same line is thrown +% away. There are good reasons for this, but they're technical. +% Essentially there's nothing I can do about it. +% +% \end{itemize} +% +% \begin{figure} +% \begin{demo}[w]{The \env{listing} environment} +%\dots in the following code: +% +%\begin{listing} +%init MOV R0,#200 ;Version 2.00 please +% LDR R1,=&4B534154 ;Magic number (`TASK') +% ADR R2,appName ;Find application name +% SWI Wimp_Initialise ;Register as a WIMP task +%\end{listing} +% +%The next step is to \dots +% \end{demo} +% \end{figure} +% +% Tab characters are supported within the environment: tab stops are set +% every eighth column, although this can be modified. +% +% \subsubsection{Configuring the \env{listing} environment} +% +% The text size used in the \env{listing} environment is set by the +% |\listingsize| command. By default, this is set to |\small|, although you +% can redefine it in the document preamble, or it can be set in the document +% class. +% +% The amount by which the listing text is indented is controlled by the +% |\listingindent| length parameter. This is a fixed length, whose default +% value is 1\,em. +% +% \subsubsection{Choosing a different end-text} +% +% \DescribeEnv{listing*} +% The \env{listing} environment is terminated by the exact character sequence +% `|\end{listing}|'. This isn't too much of a problem, unless you want to +% include this string in the text. This is achieved by the \env{listing$*$} +% environment, which allows you to specify the end-text to find as an +% argument. +% +% For example: +% +% \begin{demo}{The \env{listing$*$} environment} +%Type a listing as follows: +% +%\begin{listing*}{<end-listing*>} +%\begin{listing} +%This is a listing. Yes. +%\end{listing} +%<end-listing*> +%\end{demo} +% +% Don't include `special' characters in your chosen end-text unless you know +% what you're doing. +% +% \subsection{Writing text to a file} +% +% \DescribeEnv{verbwrite} +% You can write verbatim text to a file using the \env{verbwrite} +% environment. The syntax is fairly straightforward: +% +% \begin{quote} +% \syntax{"\\begin{verbwrite}{"<file-name>"}" \dots "\\end{verbwrite}"} +% \end{quote} +% +% The text of the environment is written to the named file. The rules about +% where the text actually starts and ends are the same as for the +% \env{listing} environment. +% +% There is also a $*$-variant, like \env{listing$*$}, which allows you to +% choose the end-text. The end-text is the first argument, the filename +% comes second. +% +% There is a restriction on the characters you can write to the file: they +% must all be considered `printable' by \TeX; otherwise they will be read +% back in as `\syntax{"^^"<chars>}' which isn't too good. Unfortunately, +% this includes tab characters, so you can't write them.\footnote{^^A +% Well, not without doing serious surgery on \TeX\ itself, anyway. } +% +% \iffalse [Example time... Ho hum. There is evilness here.] \fi +%\begin{verbwrite*}{<end-write>}{wrdemo1.tmp} +%\begin{verbwrite}{wrdemo.tmp} +%This is some text written to +%a file near the beginning of +%the file. +%\end{verbwrite} +%<end-write> +% +% For example: \verbinput{wrdemo1.tmp} +% +% \input{wrdemo1.tmp} \iffalse [Now build the file ;-) ] \fi +% +% \subsection{The \cmd\verbinput\ command} +% +% \DescribeMacro{\verbinput} +% You can input a pre-prepared text file exactly as it is in the input using +% the |\verbinput| command. The filename is given as an argument. For +% example: +% +% \begin{demo}{The \cmd\verbinput\ command} +%\verbinput{wrdemo.tmp} +% \end{demo} +% +% \subsection{The \env{demo} environment} +% +% Package authors need to document their packages, and it's common to want +% to display examples showing the original text and the output side-by-side +% (or, when space doesn't permit this, one above the other). Both the +% \LaTeX\ book and \textit{The \LaTeX\ Companion} contain such examples. +% +% The \env{demo} environment allows such displays to be created easily. The +% syntax of the environment is as follows: +% +% \begin{quote} +% \syntax{"\\begin{demo}["<shape>"]{"<title>"}" \dots "\\end{demo}"} +% \end{quote} +% +% The optional \synt{shape} argument can be either `|w|' (wide), or `|n|' +% (narrow). A `wide' shape places the input and output one above the other, +% while the `narrow' shape puts them side-by-side. The default shape is +% `narrow'. An attractive border is drawn around the display to finish it +% off nicely. +% +% An example: +% +%\begin{demo*}{<end-demo>}[w]{The \env{demo} environment} +%\begin{demo}{From the \textit{\TeX book}} +%\[ \sum_{p\;\rm prime} +% f(p) = \int_{t>1} +% f(t)\,{\rm d}\pi(t) \] +%\end{demo} +%<end-demo> +% +% \DescribeEnv{demo*} +% As with the other environments created by this package, there's a +% $*$-variant which takes the end-text as an argument. +% +% +% \section{Programmer interface} +% +% This section describes the publicly available routines provided by the +% \package{sverb} package. Routines not described here are libable to be +% changed or even removed without warning, so don't use them. +% +% \subsection{Environment hooks} +% +% Each of the environments created here works in the same way. For each +% environment \env{foo}, there's a main command responsible for doing the +% work, called |\sv@foo|. This is given all the arguments of the normal +% environment, and two more: +% +% \begin{itemize} +% +% \item The `end-text' to search for, which marks the end of the environment. +% +% \item Some actions to perform after the text has been read and processed. +% This allows the calling macro to do some extra actions, like closing +% boxes, etc. +% +% \end{itemize} +% +% All the environments do is call the main command with appropriate +% arguments. +% +% \subsection{Reading the verbatim text} +% +% \DescribeMacro{\sv@read} +% The main scanning routine is |\sv@read|. It is called with three +% arguments: +% +% \begin{itemize} +% +% \item The end-text marking the end of the environment. +% +% \item The name of a macro (which must be a single token) which is called +% with a line of text as its single argument. This is given each +% line of text which is read from the environment in turn. +% +% \item A macro, or other sort of action, which is to be done when the text +% has been read and processed. +% +% \end{itemize} +% +% The macro |\sv@read| assumes that the caller has already made some +% provision for removing the category codes of the following text, by either +% calling |\@verbatim| or using the construction +% \begin{listing} +%\let\do=\@makeother +%\dospecials +% \end{listing} +% +% \DescribeMacro{\sv@safespc} +% Note that any space characters you read using |\sv@read| will be catcoded +% as |\active|. Normally this is OK because |\obeyspaces| (or +% |\@vobeyspaces|) will be in effect. If you're doing something more exotic, +% like writing text to a file or building a command string, you can call +% |\sv@safespc| which defines the active-space character to be a normal +% whitespace-space when expanded. +% +% \implementation +% +% \section{Implementation} +% +% This section defines several macros and environments which allow verbatim +% typing, with a high degree of configurability. OK, so this sort of +% thing's been done so often before that it isn't true, but I don't really +% care. +% +% \begin{macrocode} +%<*package> +% \end{macrocode} +% +% \subsection{Simple things} +% +% To help us build funny macros which involve strange and different category +% codes, I'll write some simple macros which I can use while building my +% complicated and clever ones. +% +% \begin{macro}{\@cspecials} +% +% This macro is used to assist the definition of some of the environments. +% It makes `|\|', `|{|' and `|}|' into `other' characters, and replaces them +% with `\verb"|"', `|<|' and `|>|' respectively. Note that `|[|' and `|]|' +% aren't used, because they make defining commands which take optional +% arguments awkward. Note that we open a group here. This should be closed +% using \verb"|endgroup" at the end of the special section. +% +% \begin{macrocode} +\def\@cspecials{% + \begingroup% + \catcode`|0% + \catcode`<1% + \catcode`>2% + \catcode`\{12% + \catcode`\}12% + \catcode`\\12% +} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\sv@startlisting} +% +% This macro sets everything up nicely for a \env{listing}-type verbatim +% environment. +% +% \begin{macrocode} +\def\sv@startlisting{% + \def\par{\@@par\penalty\interlinepenalty}% + \@@par% + \leftskip\@totalleftmargin% + \obeylines% + \@noligs% + \let\do\@makeother\dospecials% + \verbatim@font% + \frenchspacing% + \@vobeyspaces% + \settabwidth% + \catcode9\active% + \lccode`\~9\lowercase{\let~\sv@vtab}% + \lccode`\~13\lowercase{\let~\vinput@cr}% + \interlinepenalty500% +} +% \end{macrocode} +% +% \end{macro} +% +% \subsection{Tab character handling} +% +% One of the things we want to do here is handle tab characters properly. +% (Here, `properly' means `moving to the next column which is a multiple of +% eight', the way these things were always meant to.) +% +% \begin{macro}{\settabwidth} +% +% The tabs used by our tabbed verbatim environments are set up by this +% routine. It sets the tab width parameter |\svtab| to 8 times the width +% of a |\tt| space. If you really want, you can redefine this macro. +% +% \begin{macrocode} +\newdimen\svtab +\def\settabwidth{\setbox\z@\hbox{\texttt{\space}}\svtab8\wd\z@} +% \end{macrocode} +% +% \end{macro} +% +% \begin{macro}{\sv@vtab} +% +% Here we handle tabs inside verbatim environments. We expect each line to +% be typeset as a box, using something like +% +% \begin{listing} +%\setbox0\hbox{#1} +%\leavevmode +%\box0 +%\par +% \end{listing} +% +% The idea is that you make tab active, and set it to this macro. We stop +% the current box, stretch it to the right width, and start another one +% straight after, so nobody know the difference. The code here is straight +% from Appendix~D of \textit{The \TeX book}. +% +% \begin{macrocode} +\def\sv@vtab{% + \hfill\egroup% + \@tempdima\wd\z@% + \divide\@tempdima\svtab% + \multiply\@tempdima\svtab% + \advance\@tempdima\svtab% + \wd\z@\@tempdima% + \leavevmode\box\z@% + \setbox\z@\hbox\bgroup% +} +% \end{macrocode} +% +% \end{macro} +% +% \begin{macro}{\verbinput} +% +% We allow input from a file, by the |\verbinput| command. We display the +% text pretty much the same as the \env{listing} environment below. +% +% We set tab and return active, and get them to do appropriate things. This +% isn't actually all that hard. +% +% \begin{macrocode} +\def\verbinput#1{% + \begin{listinglist}% + \listingsize% + \sv@startlisting% + \setbox\z@\hbox\bgroup% + \input{#1}% + \sv@stripspc% + \egroup% + \ifdim\wd\z@=\z@% + \ifhmode\par\fi% + \else% + \leavevmode\box\z@\par% + \fi% + \end{listinglist}% +} +% \end{macrocode} +% +% \end{macro} +% +% \begin{macro}{\vinput@cr} +% +% This macro handles return characters while inputting text in |\verbinput|. +% We just output our current box, and start another. +% +% \begin{macrocode} +\def\vinput@cr{% + \egroup% + \leavevmode\box\z@% + \par% + \setbox\z@\hbox\bgroup% +} +% \end{macrocode} +% +% \end{macro} +% +% \subsection{Reading verbatim text} +% +% The traditional way of reading verbatim text is to use a delimited +% argument, as described in the \textit{\TeX book}. This works well-ish if +% the text isn't very long. A better solution would be to pick out the text +% line-by-line and process it like that. So this is what we do. +% +% \begin{macro}{\matcher} +% +% For long verbatim environments, we need to be able to find the end text. +% This is rather tricky. The solution here is rather horrible. The +% environment picks out each line of the text at a time, as an argument, and +% tests to see if it contains the text we're after. We do the test in a +% particularly yukky way: we add the actual target text to the end of the +% line, and inspect the text following the match to see if the match is at +% the end. +% +% The |\matcher| macro creates a `matcher' which will test strings to see if +% they contain something interesting. +% +% To create a matcher, say +% \syntax{"\\matcher{"<cmd-name>"}{"<target>"}{"<process-cmd>"}"}. The +% command \synt{cmd-name} accepts a line of text as an argument and calls +% the \synt{process-cmd} with the text of the line before the match, or the +% whole lot. It also sets |\@ifmatched| appropriately. +% +% (Having spent ages coming up with this cruft myself, I found some very +% similar, but slightly better, code in Appendix~D. So I've changed mine to +% match Donald's. Anyway, credit where it's due: cheers Don.) +% +% \begin{macrocode} +\newif\if@matched +\def\matcher#1#2#3{% + \expandafter\def\csname\string#1$match\endcsname##1#2##2##3\end{% + \ifx##2\relax% + \@matchedfalse% + \else% + \@matchedtrue% + \fi% + #3{##1}% + }% + \expandafter\def\expandafter#1\expandafter##\expandafter1\expandafter{% + \csname\string#1$match\endcsname##1#2\relax\end% + }% +} +% \end{macrocode} +% +% \end{macro} +% +% \begin{macro}{\sv@stripspc} +% +% This macro strips any trailing glue in the current horizontal list. This +% is fairly simple, actually: we just loop while glue is the last item. It's +% slightly complicated by penalties which \TeX\ puts into the list between +% the glue items, but we just remove them too. +% +% \begin{macrocode} +\def\sv@stripspc{% + \unpenalty% + \ifdim\lastskip=\z@\else% + \unskip\expandafter\sv@stripspc% + \fi% +} +% \end{macrocode} +% +% \end{macro} +% +% \begin{macro}{\sv@percent} +% +% This macro strips a single leading percent character if there is one, and +% if the \env{doc} package is loaded. We store the possibly stripped text in +% |\@tempa|. +% +% \begin{macrocode} +\begingroup +\catcode`\%=12 +\gdef\sv@percent#1#2\relax + {\ifx\check@percent\@@undefined + \ifx#1\relax\def\@tempa{}\else + \def\@tempa{#1#2}\fi\else + \ifx#1\relax\def\@tempa{}\else + \ifx#1%\def\@tempa{#2}\else + \def\@tempa{#1#2}\fi\fi\fi} +\endgroup +% \end{macrocode} +% +% \end{macro} +% +% \begin{macro}{\@isspaces} +% +% We want to avoid writing the first and last lines of the environment to the +% file if there's nothing in them. To do this, we need to know whether a +% piece of text contains only space characters. This macro does this, in a +% rather nasty way. See the other macros below for details of how this +% works. +% +% We define |\sv@safespc| at the same time: this makes space active and +% expand to a space character which is not active. Neat, huh? +% +% \begin{macrocode} +\lccode`\~32 +\lccode`\!32 +\lowercase{% + \def\@isspaces#1{% + \ifx#1\relax% + \def\@tempb{\@tempswafalse}% + \else\ifx#1~% + \let\@tempb\@isspaces% + \else% + \def\@tempb##1\relax{}% + \fi\fi% + \@tempb% + } + \def\sv@safespc{% + \catcode32\active% + \def~{ }% + } +} +% \end{macrocode} +% +% \end{macro} +% +% \begin{macro}{\sv@read} +% +% This macro does the main job of reading a chunk of verbatim text. You call +% it like this: +% +% \begin{quote} +% \syntax{"\\sv@read{"<end-text>"}{"<process-line-proc>"}{"<end-proc>"}"} +% \end{quote} +% +% The \synt{end-text} is the text to find at the end of the `environment': we +% stop when we find it. +% +% The \synt{process-line-proc} is a macro which is passed as an argument each +% line which we read from the text. +% +% The \synt{end-proc} is a macro to call once we've finished reading all of +% the text. This can tidy up an environment or close a file or whatever. +% +% We read the text by picking out newlines using a delimited macro. We have +% to be a little clever, because newlines are active in verbatim text. +% +% We will also strip `|%|' signs off the beginning if the \package{doc} +% package is here (\package{doc} tries to play with \LaTeX's verbatim stuff, +% and doesn't understand the way we do things). +% +% \begin{macrocode} +\def\sv@read#1#2#3{% +% \end{macrocode} +% +% This code does all sorts of evil things, so I'll start by opening a group. +% +% \begin{macrocode} + \begingroup% +% \end{macrocode} +% +% So that I can spot the end-text, I'll create a matcher macro. +% +% \begin{macrocode} + \matcher\@match{#1}\sv@read@ii% +% \end{macrocode} +% +% So that I can identify line ends, I'll make them active. I'll also make +% spaces active so that they can expand to whatever they ought to expand +% to (spaces in files, or funny \verb*" " characters or whatever. +% +% \begin{macrocode} + \catcode13\active% + \catcode32\active% +% \end{macrocode} +% +% I'll use the |\if@tempswa| flag to tell me whether I ought to output the +% current line. This is a little messy, so I'll describe it later. I'll +% initialise it to false because this is the correct thing to do. +% +% \begin{macrocode} + \@tempswafalse% +% \end{macrocode} +% +% Most of the job is done by two submacros. I'll define them in terms of +% my current arguments (to save lots of token munging). The first just +% extracts the next line (which ends at the next newline character) and +% tries to match it. +% +% \begin{macrocode} + \lccode`\~13\lowercase{% + \def\sv@read@i##1~{\@match{##1}}% + }% +% \end{macrocode} +% +% The results of the match get passed here, along with the text of the +% line up to the matched text. +% +% \begin{macrocode} + \def\sv@read@ii##1{% +% \end{macrocode} +% +% The first job to do is to maybe strip off percent signs from the beginning, +% to keep \package{doc} happy. +% +% \begin{macrocode} + \sv@percent##1\relax\relax% +% \end{macrocode} +% +% Now I need to decide whether I ought to output this line. The method goes +% like this: if this is the first line (|\if@tempswa| is false) or the last +% (|\if@matched| is true), \emph{and} the text consists only of spaces, then +% I'll ignore it. +% +% The first thing to do is to notice the last line -- if |\if@matched| is +% true, then I'll make |\if@tempswa| false to make the first-line and +% last-line cases work the same way. +% +% \begin{macrocode} + \if@matched\@tempswafalse\fi% +% \end{macrocode} +% +% Now if this is the first or last line, I'll examine it for spaces. This +% is done in a separate macro. It will set |\if@tempswa| false if the +% text contains only spaces. +% +% \begin{macrocode} + \if@tempswa\else\@tempswatrue\expandafter\@isspaces\@tempa\relax\fi% +% \end{macrocode} +% +% Now, if |\if@tempswa| is still true, perform the \<process-line-proc> on +% the line of text. I'll provide a group, so that it doesn't upset me +% too much. +% +% \begin{macrocode} + \if@tempswa% + \begingroup% + \expandafter#2\expandafter{\@tempa}% + \endgroup% + \fi% +% \end{macrocode} +% +% The next line won't be the first one, so I'll set the flag true in +% readiness. +% +% \begin{macrocode} + \@tempswatrue% +% \end{macrocode} +% +% Now, if that wasn't the last line, go round again; otherwise end the group +% I started ages ago, and do the user's \<end-proc>. +% +% \begin{macrocode} + \if@matched\def\@tempa{\endgroup#3}\else\let\@tempa\sv@read@i\fi% + \@tempa% + }% +% \end{macrocode} +% +% Now to start the thing up. I'll read the first line. +% +% \begin{macrocode} + \sv@read@i% +} +% \end{macrocode} +% +% \end{macro} +% +% \begin{macro}{\sv@readenv} +% +% This macro works out an appropriate end-text for the current environment. +% If you say \syntax{"\\sv@readenv{"<macro-name>"}"}, it will expand do +% \begin{listinglist} \listingsize \synshorts +% <macro-name>"{\\"$_{12}$"end{"$_{12}$<current-env-name>"}"$_{12}$"}"^^A +% "{\\end{"<current-env-name>"}}" +% \end{listinglist} +% Easy, no? +% +% This is all done with mirrors. No, err\dots\ it's done with +% |\expandafter|. +% +% \begin{macrocode} +\begingroup +\lccode`\<=`\{ +\lccode`\>=`\} +\lccode`\|=`\\ +\lowercase{\endgroup +\def\sv@readenv#1{% + \expandafter\expandafter\expandafter% + #1\expandafter\sv@readenv@i\@currenvir\@@% +} +\def\sv@readenv@i#1\@@{{|end<#1>}{\end{#1}}} +} +% \end{macrocode} +% +% \end{macro} +% +% \begin{macro}{\sv@verbline} +% +% This macro typesets a line in a verbatim way, so you can construct a real +% verbatim environment from it. It's a bit tricky in the way that it catches +% the last line. Don't worry about this: it's easy really. Note the +% |\relax| after the |\par| -- this is because \package{doc} tries to do +% clever things with |\par| to strip `|%|' signs out. +% +% \begin{macrocode} +\def\sv@verbline#1{% + \setbox\z@\hbox{#1\sv@stripspc}% + \ifdim\wd\z@=\z@% + \if@matched\ifhmode\par\relax\fi\else\leavevmode\par\relax\fi% + \else% + \leavevmode\box\z@\par\relax% + \fi% +} +% \end{macrocode} +% +% \end{macro} +% +% \subsection{Listing environments} +% +% The \env{listing} environment is our equivalent of the standard +% \env{verbatim} environment. We do some slightly cleverer things, though, +% to make sure (for example) that even text which contains |\end{listing}| +% can be typeset. +% +% \begin{macro}{\listinglist} +% \begin{environment}{listinglist} +% +% This defines the layout for the \env{listing} environment. It starts a +% list with the appropriate shape. It's also made into an environment, so +% that the end-paragraph-environment bits work correctly. +% +% The |\listingindent| length parameter sets up the indentation of the +% listings. If there's a |\parindent| setting, I'll line listings up with +% that; otherwise I'll just choose something which looks right. +% +% \begin{macrocode} +\newdimen\listingindent +\AtBeginDocument{% + \ifdim\parindent=\z@\listingindent1em\else\listingindent\parindent\fi% +} +% \end{macrocode} +% +% Now to define a size hook for the environment. This is fairly simple +% stuff. +% +% \begin{macrocode} +\ifx\listingsize\@@undefined + \let\listingsize\small +\fi +% \end{macrocode} +% +% Now to define the environment itself. Suppress the indentation if we're +% first thing on a new list item, so that the listing lines up with +% everything else. +% +% \begin{macrocode} +\def\listinglist{% + \list{}{% + \if@inlabel% + \leftmargin\z@% + \else% + \leftmargin\listingindent% + \fi% + \rightmargin\z@% + \labelwidth\z@% + \labelsep\z@% + \itemindent\z@% + \listparindent\z@% + \let\makelabel\relax% + \parsep\z@skip% + }% + \parfillskip\@flushglue% + \item\relax% +} +\let\endlistinglist\endlist +% \end{macrocode} +% +% \end{environment} +% \end{macro} +% +% \begin{environment}{listing} +% +% The \env{listing} environment is the only real verbatim-like environment we +% create will all this kit, although it does the job very nicely. +% +% The environment indents its contents slightly, unlike \env{verbatim}, and +% uses a smaller typeface in an attempt to fit 77-column text on an A5~page. +% There is also a $*$-variant, which allows you to specify the terminating +% text. This enables you to include absolutely any text in the environment, +% including |\end{listing}|. +% +% First, we must define the |\listing| command. +% +% \begin{macrocode} +\def\listing{% + \listinglist% + \listingsize% + \sv@readenv\sv@listing% +} +% \end{macrocode} +% +% Now we define the |\@listing| command, which does most of the work. We +% base the \env{listing} environment on a \env{list}. +% +% \begin{macrocode} +\def\sv@listing#1#2{% + \sv@startlisting% + \sv@read{#1}\sv@verbline{\endlistinglist#2}% +} +% \end{macrocode} +% +% Now we define the starred version. The command name needs to include the +% `|*|' character, so we must use |\csname|. There's some hacking here to +% allow us to read the name using the appropriate catcodes for otherwise +% normal characters: \LaTeX\ activates some characters and makes them typeset +% themselves to suppress some ligaturing. +% +% \begin{macrocode} +\expandafter\def\csname listing*\endcsname{% + \listinglist% + \listingsize% + \begingroup% + \@noligs% + \def\@tempa##1{\endgroup\sv@listing{##1}{\end{listing*}}}% + \@tempa% +} +% \end{macrocode} +% +% \end{environment} +% +% \begin{environment}{ignore} +% +% The \env{ignore} environment entirely ignores its contents. Anything at +% all may be put into the environment: it is discarded utterly. +% +% We define some macros for defining ignoring environments, because this can +% be useful for version control, possibly. +% +% \begin{macrocode} +\def\sv@ignore#1#2{% + \@bsphack% + \let\do\@makeother\dospecials% + \sv@read{#1}\@gobble{\@esphack#2}% +} +\def\ignore{\sv@readenv\sv@ignore} +\def\ignoreenv#1{% + \expandafter\let\csname #1\endcsname\ignore% +} +\def\unignoreenv#1{% + \expandafter\def\csname #1\endcsname{\endgroup}% + \expandafter\def\csname end#1\endcsname% + {\begingroup\def\@currenvir{#1}}% +} +% \end{macrocode} +% +% \end{environment} +% +% \subsection{The \env{verbwrite} environment} +% +% The \env{verbwrite} environment allows text to be written to a file in a +% verbatim way. Note that tab characters don't work, because \TeX\ refuses +% to be nice. +% +% \begin{macro}{\sv@write} +% +% As seems to be traditional now, we first define a general hookable macro +% which allows a caller to specify the end-text and what to do afterwards. +% +% \begin{macrocode} +\newwrite\sv@writefile +\def\sv@write#1#2{% + \begingroup% + \@bsphack% + \let\do\@makeother\dospecials% + \sv@safespc% + \sv@read{#1}\sv@writeline{\sv@endwrite#2}% +} +\def\sv@writeline#1{% + \immediate\write\sv@writefile{#1}% +} +\def\sv@endwrite{% + \@esphack% + \endgroup% +} +% \end{macrocode} +% +% \end{macro} +% +% \begin{environment}{verbwrite} +% +% Now we can define the actual environment. We define a $*$-variant which +% allows the user to specify the end-text, just to make sure. +% +% \begin{macrocode} +\def\verbwrite#1{% + \immediate\openout\sv@writefile#1\relax% + \sv@readenv\sv@write% +} +\def\endverbwrite{\immediate\closeout\sv@writefile} +\expandafter\def\csname verbwrite*\endcsname#1#2{% + \immediate\openout\sv@writefile#2\relax% + \sv@write{#1}{\immediate\closeout\sv@writefile\end{verbwrite*}}% +} +% \end{macrocode} +% +% \end{environment} +% +% \subsection{The \env{demo} environment} +% +% By way of tying all of this together, I present an environment for +% displaying demonstrations of \LaTeX\ markup. We read the contents of the +% environment, write it to a temporary file, and read it back twice, +% typesetting it the first time and displaying it verbatim the second time. +% +% \begin{macro}{\sv@demoname} +% +% This macro expands to the filename to use for the temporary data. To +% allow the package documentation to demonstrate the \env{demo} environment +% itself, we need to keep a nesting count. This avoids too much hackery, +% which unfortunately appears to plague all of my \TeX\ code. +% +% \begin{macrocode} +\newcount\sv@nestcount +\def\sv@demoname{demo\number\sv@nestcount.tmp} +% \end{macrocode} +% +% \end{macro} +% +% \begin{macro}{\sv@demo} +% +% As for listing, we do all the business through a private macro. This is +% good because it means we can leave the main macro readable. The argument +% is the end-text to spot. +% +% \begin{macrocode} +\def\sv@demo#1#2{% + \@ifnextchar[{\sv@demo@i{#1}{#2}}{\sv@demo@i{#1}{#2}[n]}% +} +\def\sv@demo@i#1#2[#3]#4{% + \advance\sv@nestcount by\@ne% + \immediate\openout\sv@writefile\sv@demoname\relax% + \sv@write{#1}{% + \immediate\closeout\sv@writefile% + \sv@dodemo{#2}{#3}{#4}% + }% +} +% \end{macrocode} +% +% \end{macro} +% +% \begin{environment}{demo} +% +% This is the real environment. We provide \env{demo$*$} too, to allow the +% user to choose the end-text. +% +% \begin{macrocode} +\def\demo{\sv@readenv\sv@demo} +\expandafter\def\csname demo*\endcsname#1{\sv@demo{#1}{\end{demo*}}} +% \end{macrocode} +% +% \end{environment} +% +% \begin{macro}{\sv@dodemo} +% +% First, let's define some common bits of code in the stuff below. The +% minipages used to typeset the material has some clever stuff to avoid +% strange spacing in the output. +% +% \begin{macrocode} +\def\sv@demosmp{% + \begin{minipage}[t]{\@tempdima}% + \vskip8\p@% + \hrule\@height\z@% + \raggedright% + \vbox\bgroup% +} +\def\sv@demoemp{% + \par\unpenalty\unskip% + \egroup% + \vskip8\p@% + \hrule\@height\z@% + \end{minipage}% +} +% \end{macrocode} +% +% This is the macro which actually typesets the demonstration. +% +% \begin{macrocode} +\def\sv@dodemo#1#2#3{% +% \end{macrocode} +% +% Now work out some values. We set |\hsize| to the line width leaving 2\,em +% of space on either side. The size of the minipages is calculated depending +% on the shape of the demonstration. This is all fairly simple. +% +% \begin{macrocode} + \begingroup% + \@tempdima\linewidth% + \advance\@tempdima-2em% + \hsize\@tempdima% + \if#2w% + \advance\@tempdima-2em% + \else% + \advance\@tempdima-3em% + \divide\@tempdima2% + \fi% +% \end{macrocode} +% +% Now we open a big vertical box, and put in a header to mark off the +% demonstration. +% +% \begin{macrocode} + \par% + \setbox\z@\hbox{\strut\enspace#3\enspace\strut}% + \@tempdimb.5\dp\z@% + \advance\@tempdimb-.5\ht\z@% + \ht\z@\@tempdimb\dp\z@\@tempdimb% + \noindent\hskip1em\vtop{% + \hb@xt@\hsize{% + \hrulefill% + \raise\@tempdimb\box\z@% + \hrulefill% + }% + \nointerlineskip% + \hb@xt@\hsize{\vrule\@height5\p@\hfil\vrule\@height5\p@}% + \nointerlineskip% +% \end{macrocode} +% +% Now we insert the output text in the first minipage. I'll force `|%|' +% to be a comment character, in case something like \package{doc} has had its +% wicked way. +% +% \begin{macrocode} + \vskip-\parskip% + \noindent\hbox{}\hskip1em% + \sv@demosmp% + \catcode`\%14\relax% + \input{\sv@demoname}% + \sv@demoemp% +% \end{macrocode} +% +% Insert some kind of separation between the two. In `wide' format, we start +% a new line, and put a ruleoff between the two. In `narrow' format, we just +% leave some space. +% +% \begin{macrocode} + \if#2w% + \vskip8\p@\hrule\vskip8\p@% + \noindent\hbox{}% + \fi% + \hskip1em% +% \end{macrocode} +% +% Now we put the verbatim copy of the text in the other minipage. +% +% \begin{macrocode} + \sv@demosmp% + \listingindent\z@% + \verbinput\sv@demoname% + \sv@demoemp% + \par% + \nointerlineskip% + \hb@xt@\hsize{\vrule\@height5\p@\hfil\vrule\@height5\p@}% + \hrule% + }% + \endgroup% + \par% + \vskip\baselineskip% + #1% +} +% \end{macrocode} +% +% \end{macro} +% +% That's all there is. Have fun. +% +% \begin{macrocode} +%</package> +% \end{macrocode} +% +% \hfill Mark Wooding, \today +% +% \Finale +% +\endinput |