1 % \begin{meta-comment} <general public licence>
3 %% sverb package -- handling of verbatim text
4 %% Copyright (c) 1996, 2003, 2007, 2020 Mark Wooding
6 %% This program is free software; you can redistribute it and/or modify
7 %% it under the terms of the GNU General Public License as published by
8 %% the Free Software Foundation; either version 2 of the License, or
9 %% (at your option) any later version.
11 %% This program is distributed in the hope that it will be useful,
12 %% but WITHOUT ANY WARRANTY; without even the implied warranty of
13 %% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 %% GNU General Public License for more details.
16 %% You should have received a copy of the GNU General Public License
17 %% along with this program; if not, write to the Free Software
18 %% Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
22 % \begin{meta-comment} <Package preamble>
23 %<+package>\NeedsTeXFormat{LaTeX2e}
24 %<+package>\ProvidesPackage{sverb}
25 %<+package> [2020/09/06 1.14.0 Verbatim typesetting]
26 %<+colour>\NeedsTeXFormat{LaTeX2e}
27 %<+colour>\ProvidesPackage{svcolour}
28 %<+colour> [2020/09/06 1.14.0 Colour support for sverb]
29 %<+color>\NeedsTeXFormat{LaTeX2e}
30 %<+color>\ProvidesPackage{svcolor}
31 %<+color> [2020/09/06 1.14.0 Fix for people who can't spell]
32 %<+split>\NeedsTeXFormat{LaTeX2e}
33 %<+split>\ProvidesPackage{svsplit}
34 %<+split> [2020/09/06 1.14.0 Verbatim, but with line breaking]
39 %% {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
40 %% 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
41 %% Digits \0\1\2\3\4\5\6\7\8\9
42 %% Exclamation \! Double quote \" Hash (number) \#
43 %% Dollar \$ Percent \% Ampersand \&
44 %% Acute accent \' Left paren \( Right paren \)
45 %% Asterisk \* Plus \+ Comma \,
46 %% Minus \- Point \. Solidus \/
47 %% Colon \: Semicolon \; Less than \<
48 %% Equals \= Greater than \> Question mark \?
49 %% Commercial at \@ Left bracket \[ Backslash \\
50 %% Right bracket \] Circumflex \^ Underscore \_
51 %% Grave accent \` Left brace \{ Vertical bar \|
52 %% Right brace \} Tilde \~}
55 % \begin{meta-comment}
59 \describespackage{sverb}
60 \describespackage{svcolour}
61 \describespackage{svsplit}
67 % \section{User guide}
69 % The \package{sverb} package provides some useful commands and environments
70 % for doing things with verbatim text. I prefer this code to the standard
71 % \package{verbatim} package (by Rainer Sch\"opf et al.)\ although I'm
74 % The package was written to fulfil a particular purpose: I wanted to be able
75 % to typeset ARM assembler code, 77~columns wide, on A5~paper, with the
76 % fields separated by \textit{tab} characters. It's grown up fairly
77 % organically from that, and I've tidied it when I've seen the code get too
80 % The current features are:
84 % \item A `listing' environment which typesets verbatim text nicely.
86 % \item A command to read verbatim text from an external file.
88 % \item Support for arbitrary-sized chunks of text without overflowing \TeX's
91 % \item Support for \textit{tab} characters in the verbatim text.
93 % \item An environment for typesetting demonstrations of \LaTeX\ markup.
95 % \item It all works correctly with the \package{doc} system for documenting
98 % \item A fairly hairy but quite powerful programmer interface to the yukky
99 % bits of the package.
103 % The interface is described in its own section, so that more timid readers
104 % can avoid it. That said, some of the stuff in this section gets rather
107 % Note that this package doesn't even try to do anything with short bits of
108 % verbatim text (as handled by the |\verb:...:| command). I have a separate
109 % package (\package{syntax}) which does all sorts of horrible things along
112 % \subsection{The \env{listing} environment}
114 % \DescribeEnv{listing}
115 % The main method for typesetting verbatim text is the \env{listing}
116 % environment. This works pretty much the same as the standard
117 % \env{verbatim} environment, with some exceptions, which are described
120 % So that you know exactly what you're getting, here are the rules by which
121 % \package{sverb} decides what the verbatim text actually is:
125 % \item If there's any text, other than spaces, on the same line as the
126 % `|\begin{listing}|', then the contents of the environment begins
127 % immediately after the closing brace (with all leading spaces
128 % preserved). Otherwise, the text begins on the following line.
130 % \item If there is any text, other than spaces, before the
131 % `|\end{listing}|', but on the same line, this is considered to be the
132 % last line of the text; otherwise the text is presumed to have ended
133 % at the end of the previous line.
135 % \item Any text following the |\end{listing}| on the same line is thrown
136 % away. There are good reasons for this, but they're technical.
137 % Essentially there's nothing I can do about it.
142 % \begin{demo}[w]{The \env{listing} environment}
143 %\dots in the following code:
146 %init MOV R0,#200 ;Version 2.00 please
147 % LDR R1,=&4B534154 ;Magic number (`TASK')
148 % ADR R2,appName ;Find application name
149 % SWI Wimp_Initialise ;Register as a WIMP task
152 %The next step is to \dots
156 % Tab characters are supported within the environment: tab stops are set
157 % every eighth column, although this can be modified.
159 % \subsubsection{Configuring the \env{listing} environment}
161 % \DescribeMacro\listingsize
162 % The text size used in the \env{listing} environment is set by the
163 % |\listingsize| command. By default, this is set to |\footnotesize|,
164 % although you can redefine it in the document preamble, or it can be set in
165 % the document class. You can put other declarations (e.g., colours) here if
168 % \DescribeMacro\listingindent
169 % The amount by which the listing text is indented is controlled by the
170 % |\listingindent| length parameter. This is a fixed length, whose default
173 % \DescribeMacro\listinghook
174 % \DescribeMacro\svafter
175 % \DescribeMacro\svline
176 % \DescribeMacro\svdoline
177 % \DescribeEnv{listinglist}
178 % The |\listinghook| command is called by the \env{listing} environment (and
179 % |\verbinput| and \env{demo}) to set up the formatting of the listing. It
180 % can do any setting up it likes, and may configure |\svline| and |\svafter|
181 % as necessary. The macro |\svline| is run once for each line of verbatim
182 % text, with the line gathered into a box register, the number of which is
183 % given as an argument. The macro |\svafter| is called when processing has
186 % The default setting for |\listinghook| is (similar to)
188 %\newcommand{\listinghook}{%
190 % \begin{listinglist}%
192 % \renewcommand{\svline}{\listingline}%
193 % \renewcommand{\svafter}{\end{listinglist}}%
196 % (see the source for the true definition). The default |\listingline| macro
197 % just writes out the line using |\svdoline|, which is a simple no-nonsense
198 % macro which just writes the text. As an example, you could say
200 %\renewcommand{\listingline}{\leavevmode\llap{\strut\vrule\space}\svdoline}
202 % to put a rule down the left-hand side of your listings.
204 % The \env{listinglist} environment is a relatively straightforward
205 % \env{list}-based environment which sets pu the indentation of a listing.
206 % Feel free to redefine it.
208 % \subsubsection{Choosing a different end-text}
210 % \DescribeEnv{listing*}
211 % The \env{listing} environment is terminated by the exact character sequence
212 % `|\end{listing}|'. This isn't too much of a problem, unless you want to
213 % include this string in the text. This is achieved by the \env{listing$*$}
214 % environment, which allows you to specify the end-text to find as an
219 % \begin{demo}{The \env{listing$*$} environment}
220 %Type a listing as follows:
222 %\begin{listing*}{<end-listing*>}
224 %This is a listing. Yes.
229 % Don't include `special' characters in your chosen end-text unless you know
232 % \subsection{Writing text to a file}
234 % \DescribeEnv{verbwrite}
235 % You can write verbatim text to a file using the \env{verbwrite}
236 % environment. The syntax is fairly straightforward:
239 % \syntax{"\\begin{verbwrite}{"<file-name>"}" \dots "\\end{verbwrite}"}
242 % The text of the environment is written to the named file. The rules about
243 % where the text actually starts and ends are the same as for the
244 % \env{listing} environment.
246 % There is also a $*$-variant, like \env{listing$*$}, which allows you to
247 % choose the end-text. The end-text is the first argument, the filename
250 % There is a restriction on the characters you can write to the file: they
251 % must all be considered `printable' by \TeX; otherwise they will be read
252 % back in as `\syntax{"^^"<chars>}' which isn't too good. Unfortunately,
253 % this includes tab characters, so you can't write them.\footnote{^^A
254 % Well, not without doing serious surgery on \TeX\ itself, anyway. }
256 % \iffalse [Example time... Ho hum. There is evilness here.] \fi
257 %\begin{verbwrite*}{<end-write>}{wrdemo1.tmp}
258 %\begin{verbwrite}{wrdemo.tmp}
259 %This is some text written to
260 %a file near the beginning of
265 % For example: \verbinput{wrdemo1.tmp}
267 % \input{wrdemo1.tmp} \iffalse [Now build the file ;-) ] \fi
269 % \subsection{The \cmd\verbinput\ command}
271 % \DescribeMacro{\verbinput}
272 % You can input a pre-prepared text file exactly as it is in the input using
273 % the |\verbinput| command. The filename is given as an argument. For
276 % \begin{demo}{The \cmd\verbinput\ command}
277 %\verbinput{wrdemo.tmp}
280 % \subsection{The \env{demo} environment}
282 % Package authors need to document their packages, and it's common to want
283 % to display examples showing the original text and the output side-by-side
284 % (or, when space doesn't permit this, one above the other). Both the
285 % \LaTeX\ book and \textit{The \LaTeX\ Companion} contain such examples.
287 % The \env{demo} environment allows such displays to be created easily. The
288 % syntax of the environment is as follows:
291 % \syntax{"\\begin{demo}["<shape>"]{"<title>"}" \dots "\\end{demo}"}
294 % The optional \synt{shape} argument can be either `|w|' (wide), or `|n|'
295 % (narrow). A `wide' shape places the input and output one above the other,
296 % while the `narrow' shape puts them side-by-side. The default shape is
297 % `narrow'. An attractive border is drawn around the display to finish it
302 %\begin{demo*}{<end-demo>}[w]{The \env{demo} environment}
303 %\begin{demo}{From the \textit{\TeX book}}
304 %\[ \sum_{p\;\rm prime}
306 % f(t)\,{\rm d}\pi(t) \]
310 % \DescribeEnv{demo*}
311 % As with the other environments created by this package, there's a
312 % $*$-variant which takes the end-text as an argument.
314 % \DescribeMacro\demohook
315 % The |\demohook| does the same job for \env{demo} environments as
316 % |\listinghook| does for \env{listing}s. The default version just says
318 %\newcommand{\demohook}{\setlength{\listingindent}{0pt}\listinghook}
320 % (near enough), which turns off the indentation for the listing (which would
321 % otherwise look rather odd).
324 % \section{Programmer interface}
326 % This section describes the publicly available routines provided by the
327 % \package{sverb} package. Routines not described here are libable to be
328 % changed or even removed without warning, so don't use them.
330 % \subsection{Environment hooks}
332 % Each of the environments created here works in the same way. For each
333 % environment \env{foo}, there's a main command responsible for doing the
334 % work, called |\sv@foo|. This is given all the arguments of the normal
335 % environment, and two more:
339 % \item The `end-text' to search for, which marks the end of the environment.
341 % \item Some actions to perform after the text has been read and processed.
342 % This allows the calling macro to do some extra actions, like closing
347 % All the environments do is call the main command with appropriate
350 % \subsection{Reading the verbatim text}
352 % \DescribeMacro{\sv@read}
353 % The main scanning routine is |\sv@read|. It is called with three
358 % \item The end-text marking the end of the environment.
360 % \item The name of a macro (which must be a single token) which is called
361 % with a line of text as its single argument. This is given each
362 % line of text which is read from the environment in turn.
364 % \item A macro, or other sort of action, which is to be done when the text
365 % has been read and processed.
369 % The macro |\sv@read| assumes that the caller has already made some
370 % provision for removing the category codes of the following text, by either
371 % calling |\@verbatim| or using the construction
377 % \DescribeMacro{\sv@safespc}
378 % Note that any space characters you read using |\sv@read| will be catcoded
379 % as |\active|. Normally this is OK because |\obeyspaces| (or
380 % |\@vobeyspaces|) will be in effect. If you're doing something more exotic,
381 % like writing text to a file or building a command string, you can call
382 % |\sv@safespc| which defines the active-space character to be a normal
383 % whitespace-space when expanded.
385 % \section{Colour support}
387 % There's now a little colour support in \package{sverb}. To use it, give
388 % the \textsf{colour} (or \textsf{color}) package option, or load the
389 % \package{svcolour} package.
391 % \DescribeMacro\svcolourline
392 % Say \syntax{"\\svcolourline["<model>"]{"<colour>"}{"<box>"}"} to typeset
393 % \<box> against a background of the given colour. This is a good thing to
394 % put in your |\listingline| command.
395 %\begin{demo}{Coloured listings}
396 %\renewcommand{\listingline}
397 % {\svcolourline[rgb]{1, 0.8, 0.9}}
398 %Consider, for example, this more
399 %complicated program.
405 % puts("Hello, world!");
410 % For coloured text rather than background, put a |\color| command in
411 % |\listinghook| itself.
413 % \section{The \package{svsplit} package}
417 % \DescribeEnv{splitverb}
418 % \DescribeEnv{splitverb*}
419 % \DescribeMacro\svsplitchars
420 % The \env{splitverb} environment typesets verbatim material very slowly. On
421 % the plus side, however, it does know how to do simple line-breaking. It
422 % will break lines at spaces or tabs, or after any character listed in
423 % |\svsplitchars|. Continuation lines have the same initial intentation as
424 % the original. If a line has no `good' breaking point, it's broken as late
425 % as possible, and a little hyphen is inserted.
426 %\begin{demo}[w]{The \env{splitverb} environment}
427 %\begin{multicols}{2}
429 %The \package{url} package is rather fine at splitting up long URLs such as
430 % \url{http://www.excessus.demon.co.uk/tex}
431 %though it can't do its thing in the midst of verbatim text. It
432 %also doesn't cope when
433 % allthespacesinalongphrasehavemysteriouslydisappeared!
440 % \section{Implementation}
442 % This section defines several macros and environments which allow verbatim
443 % typing, with a high degree of configurability. OK, so this sort of
444 % thing's been done so often before that it isn't true, but I don't really
451 % \subsection{Options processing}
453 % Notice options, load package.
456 \newif\ifsv@colour\sv@colourfalse
457 \DeclareOption{colour}{\sv@colourtrue}
458 \DeclareOption{color}{\sv@colourtrue}
462 % \subsection{Simple things}
464 % To help us build funny macros which involve strange and different category
465 % codes, I'll write some simple macros which I can use while building my
466 % complicated and clever ones.
468 % \begin{macro}{\@cspecials}
470 % This macro is used to assist the definition of some of the environments.
471 % It makes `|\|', `|{|' and `|}|' into `other' characters, and replaces them
472 % with `\verb"|"', `|<|' and `|>|' respectively. Note that `|[|' and `|]|'
473 % aren't used, because they make defining commands which take optional
474 % arguments awkward. Note that we open a group here. This should be closed
475 % using \verb"|endgroup" at the end of the special section.
490 % \begin{macro}{\sv@addtobox}
492 % Add stuff to a horizontal box.
495 \def\sv@addtobox#1#2{\setbox#1\hbox{\unhbox#1\box#2}}
500 % \begin{macro}{\sv@emptybox}
502 % Clear out a horizontal box.
505 \def\sv@emptybox#1{\setbox#1\hbox{}}
510 % \begin{macro}{\sv@startlisting}
512 % This macro sets everything up nicely for a \env{listing}-type verbatim
516 \def\sv@startlisting{%
517 \def\par{\@@par\penalty\interlinepenalty}%
519 \leftskip\@totalleftmargin%
522 \let\do\@makeother\dospecials%
528 \lccode`\~9\lowercase{\let~\sv@vtab}%
529 \lccode`\~13\lowercase{\let~\vinput@cr}%
530 \interlinepenalty500%
536 % \subsection{Tab character handling}
538 % One of the things we want to do here is handle tab characters properly.
539 % (Here, `properly' means `moving to the next column which is a multiple of
540 % eight', the way these things were always meant to.)
542 % \begin{macro}{\settabwidth}
544 % The tabs used by our tabbed verbatim environments are set up by this
545 % routine. It sets the tab width parameter |\svtab| to 8 times the width
546 % of a |\tt| space. If you really want, you can redefine this macro.
550 \def\settabwidth{\setbox\z@\hbox{\texttt{\space}}\svtab8\wd\z@}
555 % \begin{macro}{\sv@vtab}
557 % Here we handle tabs inside verbatim environments. We expect to be inside
558 % |\box|~0. This is padded to the correct width and contributed to |\box|~2;
559 % |\box|~0 is then cleared and re-entered.
561 % The idea is that you make tab active, and set it to this macro. We stop
562 % the current box, stretch it to the right width, and start another one
563 % straight after, so nobody knows the difference. The code here is straight
564 % from Appendix~D of \textit{The \TeX book}.
570 \divide\@tempdima\svtab%
571 \multiply\@tempdima\svtab%
572 \advance\@tempdima\svtab%
575 \setbox\z@\hbox\bgroup%
581 % \begin{macro}{\verbinput}
583 % We allow input from a file, by the |\verbinput| command. We display the
584 % text pretty much the same as the \env{listing} environment below.
586 % We set tab and return active, and get them to do appropriate things. This
587 % isn't actually all that hard.
590 \def\verbinput{\listinghook\@ifstar{\verbinput@\@input}{\verbinput@\input}}
591 \def\verbinput@#1#2{%
593 \setbox\z@\hbox\bgroup%
598 \ifdim\wd\tw@=\z@\listingline\tw@\fi%
605 % \begin{macro}{\vinput@cr}
607 % This macro handles return characters while inputting text in |\verbinput|.
608 % We just output our current box, and start another.
616 \setbox\z@\hbox\bgroup%
622 % \subsection{Reading verbatim text}
624 % The traditional way of reading verbatim text is to use a delimited
625 % argument, as described in the \textit{\TeX book}. This works well-ish if
626 % the text isn't very long. A better solution would be to pick out the text
627 % line-by-line and process it like that. So this is what we do.
629 % \begin{macro}{\matcher}
631 % For long verbatim environments, we need to be able to find the end text.
632 % This is rather tricky. The solution here is rather horrible. The
633 % environment picks out each line of the text at a time, as an argument, and
634 % tests to see if it contains the text we're after. We do the test in a
635 % particularly yukky way: we add the actual target text to the end of the
636 % line, and inspect the text following the match to see if the match is at
639 % The |\matcher| macro creates a `matcher' which will test strings to see if
640 % they contain something interesting.
642 % To create a matcher, say
643 % \syntax{"\\matcher{"<cmd-name>"}{"<target>"}{"<process-cmd>"}"}. The
644 % command \synt{cmd-name} accepts a line of text as an argument and calls
645 % the \synt{process-cmd} with the text of the line before the match, or the
646 % whole lot. It also sets |\@ifmatched| appropriately.
648 % (Having spent ages coming up with this cruft myself, I found some very
649 % similar, but slightly better, code in Appendix~D. So I've changed mine to
650 % match Donald's. Anyway, credit where it's due: cheers Don.)
655 \expandafter\def\csname\string#1$match\endcsname##1#2##2##3\end{%
663 \expandafter\def\expandafter#1\expandafter##\expandafter1\expandafter{%
664 \csname\string#1$match\endcsname##1#2\relax\end%
671 % \begin{macro}{\sv@stripspc}
673 % This macro strips any trailing glue in the current horizontal list. This
674 % is fairly simple, actually: we just loop while glue is the last item. It's
675 % slightly complicated by penalties which \TeX\ puts into the list between
676 % the glue items, but we just remove them too.
681 \ifdim\lastskip=\z@\else%
682 \unskip\expandafter\sv@stripspc%
689 % \begin{macro}{\sv@percent}
691 % This macro strips a single leading percent character if there is one, and
692 % if the \env{doc} package is loaded. We store the possibly stripped text in
698 \gdef\sv@percent#1#2\relax
699 {\ifx\check@percent\@@undefined
700 \ifx#1\relax\def\@tempa{}\else
701 \def\@tempa{#1#2}\fi\else
702 \ifx#1\relax\def\@tempa{}\else
703 \ifx#1%\def\@tempa{#2}\else
704 \def\@tempa{#1#2}\fi\fi\fi}
710 % \begin{macro}{\@isspaces}
712 % We want to avoid writing the first and last lines of the environment to the
713 % file if there's nothing in them. To do this, we need to know whether a
714 % piece of text contains only space characters. This macro does this, in a
715 % rather nasty way. See the other macros below for details of how this
718 % We define |\sv@safespc| at the same time: this makes space active and
719 % expand to a space character which is not active. Neat, huh?
729 \def\@tempb{\@tempswafalse}%
731 \let\@tempb\@isspaces%
733 \def\@tempb##1\relax{}%
746 % \begin{macro}{\sv@read}
748 % This macro does the main job of reading a chunk of verbatim text. You call
752 % \syntax{"\\sv@read{"<end-text>"}{"<process-line-proc>"}{"<end-proc>"}"}
755 % The \synt{end-text} is the text to find at the end of the `environment': we
756 % stop when we find it.
758 % The \synt{process-line-proc} is a macro which is passed as an argument each
759 % line which we read from the text.
761 % The \synt{end-proc} is a macro to call once we've finished reading all of
762 % the text. This can tidy up an environment or close a file or whatever.
764 % We read the text by picking out newlines using a delimited macro. We have
765 % to be a little clever, because newlines are active in verbatim text.
767 % We will also strip `|%|' signs off the beginning if the \package{doc}
768 % package is here (\package{doc} tries to play with \LaTeX's verbatim stuff,
769 % and doesn't understand the way we do things).
775 % This code does all sorts of evil things, so I'll start by opening a group.
781 % So that I can spot the end-text, I'll create a matcher macro.
784 \matcher\@match{#1}\sv@read@ii%
787 % So that I can identify line ends, I'll make them active. I'll also make
788 % spaces active so that they can expand to whatever they ought to expand
789 % to (spaces in files, or funny \verb*" " characters or whatever.
796 % I'll use the |\if@tempswa| flag to tell me whether I ought to output the
797 % current line. This is a little messy, so I'll describe it later. I'll
798 % initialise it to false because this is the correct thing to do.
804 % Most of the job is done by two submacros. I'll define them in terms of
805 % my current arguments (to save lots of token munging). The first just
806 % extracts the next line (which ends at the next newline character) and
810 \lccode`\~13\lowercase{%
811 \def\sv@read@i##1~{\@match{##1}}%
815 % The results of the match get passed here, along with the text of the
816 % line up to the matched text.
822 % The first job to do is to maybe strip off percent signs from the beginning,
823 % to keep \package{doc} happy.
826 \sv@percent##1\relax\relax%
829 % Now I need to decide whether I ought to output this line. The method goes
830 % like this: if this is the first line (|\if@tempswa| is false) or the last
831 % (|\if@matched| is true), \emph{and} the text consists only of spaces, then
834 % The first thing to do is to notice the last line -- if |\if@matched| is
835 % true, then I'll make |\if@tempswa| false to make the first-line and
836 % last-line cases work the same way.
839 \if@matched\@tempswafalse\fi%
842 % Now if this is the first or last line, I'll examine it for spaces. This
843 % is done in a separate macro. It will set |\if@tempswa| false if the
844 % text contains only spaces.
847 \if@tempswa\else\@tempswatrue\expandafter\@isspaces\@tempa\relax\fi%
850 % Now, if |\if@tempswa| is still true, perform the \<process-line-proc> on
851 % the line of text. I'll provide a group, so that it doesn't upset me
857 \expandafter#2\expandafter{\@tempa}%
862 % The next line won't be the first one, so I'll set the flag true in
869 % Now, if that wasn't the last line, go round again; otherwise end the group
870 % I started ages ago, and do the user's \<end-proc>.
873 \if@matched\def\@tempa{\endgroup#3}\else\let\@tempa\sv@read@i\fi%
878 % Now to start the thing up. I'll read the first line.
887 % \begin{macro}{\sv@readenv}
889 % This macro works out an appropriate end-text for the current environment.
890 % If you say \syntax{"\\sv@readenv{"<macro-name>"}"}, it will expand do
891 % \begin{listinglist} \listingsize \synshorts
892 % <macro-name>"{\\"$_{12}$"end{"$_{12}$<current-env-name>"}"$_{12}$"}"^^A
893 % "{\\end{"<current-env-name>"}}"
897 % This is all done with mirrors. No, err\dots\ it's done with
906 \def\sv@readenv#1{\expandafter\sv@readenv@i\expandafter{\@currenvir}{#1}}
907 \def\sv@readenv@i#1#2{#2{|end<#1>}{\end{#1}}}
913 % \begin{macro}{\sv@verbline}
915 % This macro typesets a line in a verbatim way, so you can construct a real
916 % verbatim environment from it. It's a bit tricky in the way that it catches
917 % the last line. Don't worry about this: it's easy really. Note the
918 % |\relax| after the |\par| -- this is because \package{doc} tries to do
919 % clever things with |\par| to strip `|%|' signs out.
924 \setbox\z@\hbox{#1\sv@stripspc}%
926 \if1\ifdim\wd\tw@=\z@\if@matched0\else1\fi\else1\fi%
934 % \subsection{Listing environments}
936 % The \env{listing} environment is our equivalent of the standard
937 % \env{verbatim} environment. We do some slightly cleverer things, though,
938 % to make sure (for example) that even text which contains |\end{listing}|
941 % \begin{macro}{\listinghook}
943 % Set everything up as required. This is here for customization. The
944 % underlying machinery doesn't mess with this directly, but assumes that
945 % |\svline| and |\svafter| are set up appropriately.
953 \let\svline\listingline%
954 \def\svafter{\endlistinglist\endgroup}%
960 % \begin{macro}{\listinglist}
961 % \begin{environment}{listinglist}
963 % This defines the layout for the \env{listing} environment. It starts a
964 % list with the appropriate shape. It's also made into an environment, so
965 % that the end-paragraph-environment bits work correctly.
967 % The |\listingindent| length parameter sets up the indentation of the
968 % listings. If there's a |\parindent| setting, I'll line listings up with
969 % that; otherwise I'll just choose something which looks right.
972 \newdimen\listingindent
974 \ifdim\parindent=\z@\listingindent1em\else\listingindent\parindent\fi%
978 % Now to define a size hook for the environment. This is fairly simple
982 \ifx\listingsize\@@undefined
983 \let\listingsize\footnotesize
987 % Now to define the environment itself. Suppress the indentation if we're
988 % first thing on a new list item, so that the listing lines up with
997 \leftmargin\listingindent%
1004 \let\makelabel\relax%
1007 \parfillskip\@flushglue%
1010 \let\endlistinglist\endlist
1016 % \begin{macro}{\svline}
1017 % \begin{macro}{\svdoline}
1018 % \begin{macro}{\listingline}
1020 % The simple spit-out-a-line macro.
1023 \def\svdoline#1{\leavevmode\box#1\par}
1024 \let\svline\svdoline
1025 \let\listingline\svline
1032 % \begin{macro}{\svafter}
1034 % This is called when the machinery finishes. A default is set for safety's
1043 % \begin{environment}{listing}
1045 % The \env{listing} environment is the only real verbatim-like environment we
1046 % create will all this kit, although it does the job very nicely.
1048 % The environment indents its contents slightly, unlike \env{verbatim}, and
1049 % uses a smaller typeface in an attempt to fit 77-column text on an A5~page.
1050 % There is also a $*$-variant, which allows you to specify the terminating
1051 % text. This enables you to include absolutely any text in the environment,
1052 % including |\end{listing}|.
1054 % First, we must define the |\listing| command.
1057 \def\listing{\listinghook\sv@readenv\sv@listing}
1060 % Now we define the |\@listing| command, which does most of the work. We
1061 % base the \env{listing} environment on a \env{list}.
1064 \def\sv@listing#1#2{\sv@startlisting\sv@read{#1}\sv@verbline{\svafter#2}}
1067 % Now we define the starred version. The command name needs to include the
1068 % `|*|' character, so we must use |\csname|. There's some hacking here to
1069 % allow us to read the name using the appropriate catcodes for otherwise
1070 % normal characters: \LaTeX\ activates some characters and makes them typeset
1071 % themselves to suppress some ligaturing.
1074 \expandafter\def\csname listing*\endcsname{%
1075 \listinghook\begingroup\@noligs\listing@star%
1077 \def\listing@star#1{\endgroup\sv@listing{#1}{\end{listing*}}}
1082 % \begin{environment}{ignore}
1084 % The \env{ignore} environment entirely ignores its contents. Anything at
1085 % all may be put into the environment: it is discarded utterly.
1087 % We define some macros for defining ignoring environments, because this can
1088 % be useful for version control, possibly.
1091 \def\sv@ignore#1#2{%
1093 \let\do\@makeother\dospecials%
1094 \sv@read{#1}\@gobble{\@esphack#2}%
1096 \def\ignore{\sv@readenv\sv@ignore}
1098 \expandafter\let\csname #1\endcsname\ignore%
1100 \def\unignoreenv#1{%
1101 \expandafter\def\csname #1\endcsname{\endgroup}%
1102 \expandafter\def\csname end#1\endcsname%
1103 {\begingroup\def\@currenvir{#1}}%
1109 % \subsection{The \env{verbwrite} environment}
1111 % The \env{verbwrite} environment allows text to be written to a file in a
1112 % verbatim way. Note that tab characters don't work, because \TeX\ refuses
1115 % \begin{macro}{\sv@write}
1117 % As seems to be traditional now, we first define a general hookable macro
1118 % which allows a caller to specify the end-text and what to do afterwards.
1121 \newwrite\sv@writefile
1125 \let\do\@makeother\dospecials%
1127 \sv@read{#1}\sv@writeline{\sv@endwrite#2}%
1129 \def\sv@writeline#1{%
1130 \immediate\write\sv@writefile{#1}%
1140 % \begin{environment}{verbwrite}
1142 % Now we can define the actual environment. We define a $*$-variant which
1143 % allows the user to specify the end-text, just to make sure.
1147 \immediate\openout\sv@writefile#1\relax%
1148 \sv@readenv\sv@write%
1150 \def\endverbwrite{\immediate\closeout\sv@writefile}
1151 \expandafter\def\csname verbwrite*\endcsname#1#2{%
1152 \immediate\openout\sv@writefile#2\relax%
1153 \sv@write{#1}{\immediate\closeout\sv@writefile\end{verbwrite*}}%
1159 % \subsection{The \env{demo} environment}
1161 % By way of tying all of this together, I present an environment for
1162 % displaying demonstrations of \LaTeX\ markup. We read the contents of the
1163 % environment, write it to a temporary file, and read it back twice,
1164 % typesetting it the first time and displaying it verbatim the second time.
1166 % \begin{macro}{\sv@demoname}
1168 % This macro expands to the filename to use for the temporary data. To
1169 % allow the package documentation to demonstrate the \env{demo} environment
1170 % itself, we need to keep a nesting count. This avoids too much hackery,
1171 % which unfortunately appears to plague all of my \TeX\ code.
1174 \newcount\sv@nestcount
1175 \def\sv@demoname{\jobname-demo\number\sv@nestcount.tmp}
1180 % \begin{macro}{\sv@demo}
1182 % As for listing, we do all the business through a private macro. This is
1183 % good because it means we can leave the main macro readable. The argument
1184 % is the end-text to spot.
1188 \@ifnextchar[{\sv@demo@i{#1}{#2}}{\sv@demo@i{#1}{#2}[n]}%
1190 \def\sv@demo@i#1#2[#3]#4{%
1191 \advance\sv@nestcount by\@ne%
1192 \immediate\openout\sv@writefile\sv@demoname\relax%
1194 \immediate\closeout\sv@writefile%
1195 \sv@dodemo{#2}{#3}{#4}%
1202 % \begin{environment}{demo}
1204 % This is the real environment. We provide \env{demo$*$} too, to allow the
1205 % user to choose the end-text.
1208 \def\demo{\let\@demohook\demohook\sv@readenv\sv@demo}
1209 \expandafter\def\csname demo*\endcsname#1%
1210 {\let\@demohook\demohook\sv@demo{#1}{\end{demo*}}}
1215 % \begin{macro}{\demohook}
1217 % Like |\listinghook|. So much so that we just call it, but first ensure
1218 % that the indent is zero (otherwise it looks really odd!).
1221 \def\demohook{\listingindent\z@\listinghook}
1226 % \begin{macro}{\sv@dodemo}
1228 % First, let's define some common bits of code in the stuff below. The
1229 % minipages used to typeset the material has some clever stuff to avoid
1230 % strange spacing in the output.
1234 \begin{minipage}[t]{\@tempdima}%
1241 \par\unpenalty\unskip%
1249 % This is the macro which actually typesets the demonstration.
1252 \def\sv@dodemo#1#2#3{%
1255 % Now work out some values. We set |\hsize| to the line width leaving 2\,em
1256 % of space on either side. The size of the minipages is calculated depending
1257 % on the shape of the demonstration. This is all fairly simple.
1261 \@tempdima\linewidth%
1262 \advance\@tempdima-2em%
1265 \advance\@tempdima-2em%
1267 \advance\@tempdima-3em%
1272 % Now we open a big vertical box, and put in a header to mark off the
1277 \setbox\z@\hbox{\strut\enspace#3\enspace\strut}%
1279 \advance\@tempdimb-.5\ht\z@%
1280 \ht\z@\@tempdimb\dp\z@\@tempdimb%
1281 \noindent\hskip1em\vtop{%
1284 \raise\@tempdimb\box\z@%
1288 \hb@xt@\hsize{\vrule\@height5\p@\hfil\vrule\@height5\p@}%
1292 % Now we insert the output text in the first minipage. I'll force `|%|'
1293 % to be a comment character, in case something like \package{doc} has had its
1298 \noindent\hbox{}\hskip1em%
1300 \catcode`\%14\relax%
1301 \@input{\sv@demoname}%
1305 % Insert some kind of separation between the two. In `wide' format, we start
1306 % a new line, and put a ruleoff between the two. In `narrow' format, we just
1311 \vskip8\p@\hrule\vskip8\p@%
1317 % Now we put the verbatim copy of the text in the other minipage.
1322 \verbinput@\@input\sv@demoname%
1326 \hb@xt@\hsize{\vrule\@height5\p@\hfil\vrule\@height5\p@}%
1331 \vskip\baselineskip%
1338 % \subsection{Loading the colour package}
1340 % If requested, we load the \package{svcolour} package here. This ensures
1341 % that it can patch this code if it needs to.
1345 \RequirePackage{svcolour}
1349 % That's all there is. Have fun.
1355 % \subsection{The \package{svcolour} package}
1357 % This is in a separate package to avoid dragging in the \package{color}
1358 % package if it's unwanted.
1360 % I prefer English spellings. Here's a trivial redirection for Americans.
1364 \DeclareOption*{\PassOptionsToPackage{\CurrentOption}{svcolour}}
1366 \RequirePackage{svcolour}
1370 % And now we can start the thing properly.
1374 \RequirePackage{color}
1377 % \begin{macro}{\@snarfcolour}
1379 % Reading a colour specification is something we'll need to do a few times,
1380 % so an abstraction is useful. Its single argument is a continuation to
1381 % which we pass a colour-spec acceptable to the |\color| command. (This is
1382 % the same code as found in the \package{mdwtab} package. Remember to keep
1386 \def\@snarfcolour#1{%
1387 \@ifnextchar[{\@snarfcolour@i{#1}}{\@snarfcolour@ii{#1}{}}%
1389 \def\@snarfcolour@i#1[#2]{\@snarfcolour@ii{#1}{[#2]}}
1390 \def\@snarfcolour@ii#1#2#3{#1{#2{#3}}}
1395 % \begin{macro}{\svcolourline}
1396 % \begin{macro}{\svcolorline}
1398 % Snarf the option, and plot the coloured bar. Note the penalties which are
1399 % meant to stick the glue and leaders onto the colour specials.
1402 \def\svcolourline{\@snarfcolour\svcl@i}
1405 \advance\skip@\parfillskip%
1409 \begingroup\color#1\nobreak\leaders\vrule\hskip\skip@\endgroup%
1410 \nobreak\hskip-\skip@%
1413 \nobreak\hskip-\rightskip\vadjust{}%
1416 \let\svcolorline\svcolourline
1428 % \subsection{The \package{svsplit} package}
1432 \RequirePackage{sverb}
1435 % \begin{environment}{splitverb}
1436 % \begin{environment}{splitverb*}
1438 % The basic environments are simple enough.
1441 \def\splitverb{\listinghook\sv@readenv\splitverb@}
1442 \expandafter\def\csname splitverb*\endcsname%
1443 {\listinghook\begingroup\@noligs\svsplit@star}
1444 \def\svsplit@star#1{\endgroup\splitverb@{#1}{\end{splitverb*}}}
1450 % \begin{macro}{\splitverb@}
1452 % Even this isn't so bad, really.
1455 \def\splitverb@#1#2{\sv@startlisting\sv@read{#1}\svsplit@line{\svafter#2}}
1460 % \begin{macro}{\svsplit@line}
1462 % For the sake of readability (and maybe saving a few tokens), we define some
1463 % synonyms for \TeX's scratch registers. |\svsplit@remain| will be a
1464 % |\global| register containing the remaining horizontal space on the line;
1465 % |\svsplit@indent| is a local register containing the amount of initial
1466 % whitespace on the line.
1469 \dimendef\svsplit@remain=1
1470 \dimendef\svsplit@indent=2
1473 % The switch |\svsplit@| is set if we've found a good place to split the
1480 % And finally a delimiter. This is the same one I use everywhere else.
1483 \def\q@delim{\q@delim}
1488 \catcode`\~=\active \lccode`\~=32
1489 \catcode`\!=\active \lccode`\!=9
1490 \lowercase{\endgroup
1493 % So far, so good. The |\svsplit@line| macro is given a line of text. We
1494 % initialize |\svtab| to be a \emph{single} space, |\svsplit@remain| to be
1495 % the text width, and |\svsplit@indent| to zero. Then we embark on the first
1496 % loop, which attempts to find the width of the leading whitespace.
1499 \def\svsplit@line#1{%
1501 \global\svsplit@remain\linewidth%
1504 \let\next@\svsplit@findindent%
1509 % A straightforward tail-recursive loop finds out how much whitespace there
1510 % is at the start of the current line. Note that |\next@| is already set up
1511 % for the optimized case of continuing the loop. Also, if we reach the end
1512 % then this is a blank line, so only emit something if we didn't see the
1513 % end-marker. This is the only place we need to check for this.
1516 \def\svsplit@findindent#1{%
1518 \advance\svsplit@indent\svtab%
1521 \divide\svsplit@indent\dimen@%
1522 \multiply\svsplit@indent\dimen@%
1523 \advance\svsplit@indent\dimen@%
1524 \else\ifx\q@delim#1%
1525 \if@matched\else\svline\tw@\fi%
1528 \def\next@{\svsplit@scanline{#1}}%
1534 % Now we have to actually scan the line to find breakpoints. We build the
1535 % current unbreakable chunk in |\box|~0. When we find a breakpoint, we close
1536 % the box, maybe stretch it to take into account trailing space, and attach
1537 % it to |\box|~2, which is gathering the current line. If |\svsplit@remain|
1538 % hits zero then we flush |\box|~2 to the output and continue on the next
1539 % line with a (more-or-less) clean slate.
1541 % If there's no breakpoint then we're hosed. In that case, we just insert a
1542 % (|\normalfont|) hyphen and eject what we've got.
1544 % Note that this assumes that the indentation will fit. If not, then we're
1548 \def\svsplit@scanline{%
1550 \let\next@\svsplit@char%
1551 \setbox\z@\hbox\bgroup%
1552 \kern\svsplit@indent%
1553 \global\advance\svsplit@remain-\svsplit@indent%
1558 % Scanning a character isn't so bad, if we take it a step at a time.
1561 \def\svsplit@char#1{%
1564 % If the character is a space or a tab, then we call |\svsplit@space| which
1565 % knows about adding breakable whitespace. For tabs, this involves computing
1566 % the correct tab size.
1570 \svsplit@space\svtab%
1572 \@tempdima\linewidth%
1573 \advance\@tempdima-\svsplit@remain%
1574 \@tempdimb\@tempdima%
1576 \divide\@tempdimb\dimen@%
1577 \multiply\@tempdimb\dimen@%
1578 \advance\@tempdimb\dimen@%
1579 \advance\@tempdimb-\@tempdima%
1580 \svsplit@space\@tempdimb%
1583 % We might have reached the end of the line. If so, then we finish off.
1586 \else\ifx\q@delim#1%
1587 \let\next@\svsplit@done%
1590 % Otherwise it's a normal character. If there's not enough space then force
1595 \ifdim\svsplit@remain<2\svtab%
1596 \ifsvsplit@\else\normalfont-\svsplit@break\fi%
1601 % Insert the character and decrement the distance-left register.
1605 \global\advance\svsplit@remain-\svtab%
1608 % Now we see if it's a breakable-after character and if so mark it as being
1612 \def\temp@##1#1##2\q@delim%
1613 {\ifx\q@delim##2\q@delim\else\svsplit@break\fi}%
1614 \expandafter\temp@\svsplitchars#1\q@delim%
1617 % And with that, we're done.
1625 % Our next macro is the break-insertion subroutine, which is quite easy.
1628 \def\svsplit@break{%
1630 \sv@addtobox\tw@\z@%
1632 \setbox\z@\hbox\bgroup%
1636 % Now we add space to the current box. The argument is a dimen register.
1639 \def\svsplit@space#1{%
1640 \ifdim\svsplit@remain>#1\kern#1\global\advance\svsplit@remain-#1\fi%
1642 \ifdim\svsplit@remain>#1\else\svsplit@eject\fi%
1646 % We now come to a slightly involved piece of code, which is how to flush out
1647 % a line, and then fix up the registers for the next line correctly.
1650 \def\svsplit@eject{%
1655 \setbox\z@\hbox\bgroup%
1656 \kern\svsplit@indent%
1657 \global\svsplit@remain\linewidth%
1658 \global\advance\svsplit@remain-\svsplit@indent%
1659 \global\advance\svsplit@remain-\wd\z@%
1664 % Finally, how to finish the line and go home.
1669 \sv@addtobox\tw@\z@%
1674 % End the |\lowercase| hack.
1682 % Finally, set the breakable characters to something plausible.
1685 \def\svsplitchars{:/.}
1688 % And with that, we're done!
1694 % \hfill Mark Wooding, \today