Debian Codegraph @

texmf-dist/source/latex/spverbatim/spverbatim.dtx

raw
1 % \iffalse meta-comment
2 %
3 % Copyright (C) 2009 by Scott Pakin <[email protected]>
4 % -------------------------------------------------------
5 %
6 % This file may be distributed and/or modified under the conditions of
7 % the LaTeX Project Public License, either version 1.3c of this license
8 % or (at your option) any later version. The latest version of this
9 % license is in:
10 %
11 % http://www.latex-project.org/lppl.txt
12 %
13 % and version 1.3c or later is part of all distributions of LaTeX
14 % version 2008/05/04 or later.
15 %
16 % \fi
17 %
18 % \iffalse
19 %<*driver>
20 \ProvidesFile{spverbatim.dtx}
21 %</driver>
22 %<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
23 %<package>\ProvidesPackage{spverbatim}
24 %<*package>
25 [2009/08/10 v1.0 Verbatim with breakable spaces]
26 %</package>
27 %
28 %<*driver>
29 \documentclass{ltxdoc}
30 \usepackage{spverbatim}[2009/08/10]
31 \usepackage{hyperref}
32 \EnableCrossrefs
33 \CodelineIndex
34 \RecordChanges
35 \begin{document}
36 \DocInput{spverbatim.dtx}
37 % \PrintChanges
38 \PrintIndex
39 \end{document}
40 %</driver>
41 % \fi
42 %
43 % \CheckSum{36}
44 %
45 % \CharacterTable
46 % {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
47 % 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
48 % Digits \0\1\2\3\4\5\6\7\8\9
49 % Exclamation \! Double quote \" Hash (number) \#
50 % Dollar \$ Percent \% Ampersand \&
51 % Acute accent \' Left paren \( Right paren \)
52 % Asterisk \* Plus \+ Comma \,
53 % Minus \- Point \. Solidus \/
54 % Colon \: Semicolon \; Less than \<
55 % Equals \= Greater than \> Question mark \?
56 % Commercial at \@ Left bracket \[ Backslash \\
57 % Right bracket \] Circumflex \^ Underscore \_
58 % Grave accent \` Left brace \{ Vertical bar \|
59 % Right brace \} Tilde \~}
60 %
61 %
62 % \changes{v1.0}{2009/08/10}{Initial version}
63 %
64 % \GetFileInfo{spverbatim.dtx}
65 %
66 % \DoNotIndex{\begingroup,\bgroup,\catcode,\def,\egroup,\end,\gdef}
67 % \DoNotIndex{\let,\mbox,\newenvironment,\relax}
68 %
69 % \let\pkgname=\textsf
70 %
71 %
72 % \title{The \pkgname{spverbatim} package\thanks{This document
73 % corresponds to \pkgname{spverbatim}~\fileversion, dated \filedate.}}
74 % \author{^^A
75 % Scott Pakin \\
76 % \href{mailto:[email protected]}{\textit{[email protected]}}}
77 % \hypersetup{^^A
78 % pdftitle={The spverbatim package},
79 % pdfauthor={Scott Pakin <[email protected]>},
80 % pdfsubject={Package that enables LaTeX to break lines within
81 % verbatim text},
82 % pdfkeywords={LaTeX, \textbackslash verb macro, verbatim environment,
83 % line breaks at spaces}
84 % }
85 %
86 % \maketitle
87 % \sloppy
88 %
89 % \section{Introduction}
90 % \label{sec:introduction}
91 %
92 % \LaTeX's |\verb| macro treats its argument as an unbreakable unit of
93 % text. This can lead to poor typesetting, especially when the argument
94 % is long:
95 %
96 % \begin{quote}
97 % Be sure to run
98 % ``\verb!my_program | awk '$1 ~ /^[0-9]+$/ {printf "%s & %s \\\n", $2, $NF}' > $HOME/.myprogrc!''
99 % to extract the data. Otherwise, when you
100 % run ``\verb!bad_program && rm $HOME/.*#backup_file#~!'', the program will
101 % delete all of your files.
102 % \end{quote}
103 %
104 % \noindent
105 % The \pkgname{spverbatim} package enables \LaTeX\ to break lines at
106 % spaces within verbatim text:
107 %
108 % \begin{quote}
109 % Be sure to run
110 % ``\spverb!my_program | awk '$1 ~ /^[0-9]+$/ {printf "%s & %s \\\n", $2, $NF}' > $HOME/.myprogrc!''
111 % to extract the data. Otherwise, when you
112 % run ``\spverb!bad_program && rm $HOME/.*#backup_file#~!'', the program will
113 % delete all of your files.
114 % \end{quote}
115 %
116 %
117 % \section{Usage}
118 %
119 % \DescribeMacro{\spverb}
120 % The \pkgname{spverbatim} package provides an |\spverb| macro that
121 % resembles |\verb| except that it allows line breaks at space characters.
122 % Like |\verb|, |\spverb| must be followed by a character that ends the
123 % verbatim text on its second occurrence:
124 %
125 % \begin{center}
126 % |\spverb| \meta{char} \meta{literal text} \meta{char}
127 % \end{center}
128 %
129 % \noindent
130 % The following shows how the final sentence in
131 % Section~\ref{sec:introduction} was entered:
132 %
133 % \begin{verbatim}
134 % Otherwise, when you run
135 % ``\spverb!bad_program && rm $HOME/.*#backup_file#~!'', the program will
136 % delete all of your files.
137 % \end{verbatim}
138 %
139 % Although |\spverb| allows line breaks on \emph{output}, it does not
140 % allow line breaks on \emph{input} (i.e.,~within \meta{literal text}).
141 % Hence, the following \LaTeX\ code is \textbf{incorrect}:
142 %
143 % \begin{verbatim}
144 % Otherwise, when you run ``\spverb!bad_program && rm
145 % $HOME/.*#backup_file#~!'', the program will delete all of
146 % your files.
147 % \end{verbatim}
148 %
149 % \bigskip
150 %
151 % \DescribeEnv{spverbatim}
152 % In addition to the |\spverb| macro, \pkgname{spverbatim} provides an
153 % |spverbatim| environment. |spverbatim| resembles |verbatim| except
154 % that it allows line breaks at space characters. For example,
155 %
156 % \begin{verbatim}
157 % \begin{spverbatim}
158 % my_program | awk '$1 ~ /^[0-9]+$/ {printf "%s & %s \\\n", $2, $NF}' > $HOME/.myprogrc
159 % \end{spverbatim}
160 % \end{verbatim}
161 %
162 % \noindent
163 % produces
164 %
165 % \begin{verbatim}
166 % my_program | awk '$1 ~ /^[0-9]+$/ {printf "%s & %s \\\n", $2, $NF}' >
167 % $HOME/.myprogrc
168 % \end{verbatim}
169 %
170 % Unlike |\verb| and |verbatim|, |\spverb| and |spverbatim| do not
171 % support a |*|-form in which space characters are typeset as
172 % ``\verb*+ +''. Please contact the author if this is a feature you'd
173 % like to see in \pkgname{spverbatim}.
174 %
175 %
176 % \StopEventually{^^A
177 % \section{Legal notices}
178 %
179 % \noindent
180 % Copyright \textcopyright\ 2009 Scott Pakin,
181 % \href{mailto:[email protected]}{\textit{[email protected]}}
182 %
183 % \bigskip
184 %
185 % This package may be distributed and/or modified under the
186 % conditions of the \LaTeX\ Project Public License, either
187 % version~1.3c of this license or (at your option) any later
188 % version. The latest version of this license is in:
189 %
190 % \begin{center}
191 % \url{http://www.latex-project.org/lppl.txt}
192 % \end{center}
193 %
194 % \noindent
195 % and version~1.3c or later is part of all distributions of
196 % \LaTeX\ version 2006/05/20 or later.
197 % }
198 %
199 % \section{Implementation}
200 %
201 % This section presents the complete source code for the
202 % \pkgname{spverbatim} package. Unless you're interested in seeing
203 % precisely how \pkgname{spverbatim} works, there's no need to read
204 % any further.
205 %
206 % \begin{macro}{\spverb}
207 % \begin{macro}{\spverb@ve}
208 % \begin{macro}{\@xobeysp}
209 % To avoid rewriting |\verb| and all of its helper macros we begin a group;
210 % locally redefine the nonbreaking space macro, |\@xobeysp|, to produce a
211 % breaking space; and locally redefine the end-of-|\verb| macro, |\verb@egroup|,
212 % to end the extra group we began.
213 % \begin{macrocode}
214 \gdef\spverb{%
215 \bgroup
216 \let\spverb@ve=\verb@egroup
217 \def\verb@egroup{\spverb@ve\egroup}%
218 \def\@xobeysp{\mbox{}\space}%
219 \verb
220 }
221 % \end{macrocode}
222 % \end{macro}
223 % \end{macro}
224 % \end{macro}
225 %
226 % \begin{macro}{\spv@xverbatim}
227 % |verbatim| is no ordinary \LaTeX\ environment. Because ``|\|'',
228 % ``|{|'', and ``|}|'' are treated as literals within a |verbatim|
229 % environment, |\end{verbatim}| can't automatically end the environment.
230 % Rather, |\begin{verbatim}| invokes the |\@xverbatim| macro, which
231 % pattern-matches against the literal text ``|\end{verbatim}|'',
232 % typesets everything it finds up to that text, and finally invokes the
233 % real ``|\end{verbatim}|'' sequence. Here, we define an
234 % |\spv@xverbatim| macro that's just like |\@xverbatim| except that it
235 % pattern-matches against the literal text ``|\end{spverbatim}|'' and
236 % ends with a call to the real ``|\end{spverbatim}|'' sequence.
237 % \begin{macrocode}
238 \begingroup
239 \catcode`|=0
240 \catcode`[=1
241 \catcode`]=2
242 \catcode`\{=12
243 \catcode`\}=12
244 \catcode`\\=12
245 |gdef|spv@xverbatim#1\end{spverbatim}[#1|end[spverbatim]]
246 |endgroup
247 % \end{macrocode}
248 % \end{macro}
249 %
250 % \begin{environment}{spverbatim}
251 % Because the |verbatim| environment already begins a new group, all we
252 % have to do to get it to preserve spaces is locally redefine the
253 % nonbreaking space macro, |\@xobeysp|, to produce a breaking space;
254 % and locally redefine |\@xverbatim| as |\spv@xverbatim| (see above) so
255 % that a |\begin{spverbatim}| is matched by an |\end{spverbatim}|, not
256 % an |\end{verbatim}|.
257 % \begin{macrocode}
258 \newenvironment{spverbatim}{%
259 \def\@xobeysp{\mbox{}\space}%
260 \let\@xverbatim=\spv@xverbatim
261 \verbatim
262 }{%
263 }
264 % \end{macrocode}
265 % \end{environment}
266 %
267 % \Finale
268 \endinput