path: root/Master/texmf-dist/source/latex/spverbatim/spverbatim.dtx

% \iffalse meta-comment
%
% Copyright (C) 2009 by Scott Pakin <scott+spverb@pakin.org>
% -------------------------------------------------------
%
% This file may be distributed and/or modified under the conditions of
% the LaTeX Project Public License, either version 1.3c of this license
% or (at your option) any later version.  The latest version of this
% license is in:
%
%    http://www.latex-project.org/lppl.txt
%
% and version 1.3c or later is part of all distributions of LaTeX
% version 2008/05/04 or later.
%
% \fi
%
% \iffalse
%<*driver>
\ProvidesFile{spverbatim.dtx}
%</driver>
%<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
%<package>\ProvidesPackage{spverbatim}
%<*package>
    [2009/08/10 v1.0 Verbatim with breakable spaces]
%</package>
%
%<*driver>
\documentclass{ltxdoc}
\usepackage{spverbatim}[2009/08/10]
\usepackage{hyperref}
\EnableCrossrefs
\CodelineIndex
\RecordChanges
\begin{document}
  \DocInput{spverbatim.dtx}
%  \PrintChanges
  \PrintIndex
\end{document}
%</driver>
% \fi
%
% \CheckSum{36}
%
% \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         \~}
%
%
% \changes{v1.0}{2009/08/10}{Initial version}
%
% \GetFileInfo{spverbatim.dtx}
%
% \DoNotIndex{\begingroup,\bgroup,\catcode,\def,\egroup,\end,\gdef}
% \DoNotIndex{\let,\mbox,\newenvironment,\relax}
%
% \let\pkgname=\textsf
%
%
% \title{The \pkgname{spverbatim} package\thanks{This document
%   corresponds to \pkgname{spverbatim}~\fileversion, dated \filedate.}}
% \author{^^A
%   Scott Pakin \\
%   \href{mailto:scott+spverb@pakin.org}{\textit{scott+spverb@pakin.org}}}
% \hypersetup{^^A
%   pdftitle={The spverbatim package},
%   pdfauthor={Scott Pakin <scott+spverb@pakin.org>},
%   pdfsubject={Package that enables LaTeX to break lines within
%     verbatim text},
%   pdfkeywords={LaTeX, \textbackslash verb macro, verbatim environment,
%     line breaks at spaces}
% }
%
% \maketitle
% \sloppy
%
% \section{Introduction}
% \label{sec:introduction}
%
% \LaTeX's |\verb| macro treats its argument as an unbreakable unit of
% text.  This can lead to poor typesetting, especially when the argument
% is long:
%
% \begin{quote}
%   Be sure to run
%   ``\verb!my_program | awk '$1 ~ /^[0-9]+$/ {printf "%s & %s \\\n", $2, $NF}' > $HOME/.myprogrc!''
%   to extract the data.  Otherwise, when you
%   run ``\verb!bad_program && rm $HOME/.*#backup_file#~!'', the program will
%   delete all of your files.
% \end{quote}
%
% \noindent
% The \pkgname{spverbatim} package enables \LaTeX\ to break lines at
% spaces within verbatim text:
%
% \begin{quote}
%   Be sure to run
%   ``\spverb!my_program | awk '$1 ~ /^[0-9]+$/ {printf "%s & %s \\\n", $2, $NF}' > $HOME/.myprogrc!''
%   to extract the data.  Otherwise, when you
%   run ``\spverb!bad_program && rm $HOME/.*#backup_file#~!'', the program will
%   delete all of your files.
% \end{quote}
%
%
% \section{Usage}
%
% \DescribeMacro{\spverb}
% The \pkgname{spverbatim} package provides an |\spverb| macro that
% resembles |\verb| except that it allows line breaks at space characters.
% Like |\verb|, |\spverb| must be followed by a character that ends the
% verbatim text on its second occurrence:
%
% \begin{center}
%   |\spverb| \meta{char} \meta{literal text} \meta{char}
% \end{center}
%
% \noindent
% The following shows how the final sentence in
% Section~\ref{sec:introduction} was entered:
%
% \begin{verbatim}
%      Otherwise, when you run
%     ``\spverb!bad_program && rm $HOME/.*#backup_file#~!'', the program will
%      delete all of your files.
% \end{verbatim}
%
% Although |\spverb| allows line breaks on \emph{output}, it does not
% allow line breaks on \emph{input} (i.e.,~within \meta{literal text}).
% Hence, the following \LaTeX\ code is \textbf{incorrect}:
%
% \begin{verbatim}
%      Otherwise, when you run ``\spverb!bad_program && rm
%      $HOME/.*#backup_file#~!'', the program will delete all of
%      your files.
% \end{verbatim}
%
% \bigskip
%
% \DescribeEnv{spverbatim}
% In addition to the |\spverb| macro, \pkgname{spverbatim} provides an
% |spverbatim| environment.  |spverbatim| resembles |verbatim| except
% that it allows line breaks at space characters.  For example,
%
% \begin{verbatim}
%      \begin{spverbatim}
%        my_program | awk '$1 ~ /^[0-9]+$/ {printf "%s & %s \\\n", $2, $NF}' > $HOME/.myprogrc
%      \end{spverbatim}
% \end{verbatim}
%
% \noindent
% produces
%
% \begin{verbatim}
%      my_program | awk '$1 ~ /^[0-9]+$/ {printf "%s & %s \\\n", $2, $NF}' >
%      $HOME/.myprogrc
% \end{verbatim}
%
% Unlike |\verb| and |verbatim|, |\spverb| and |spverbatim| do not
% support a |*|-form in which space characters are typeset as
% ``\verb*+ +''.  Please contact the author if this is a feature you'd
% like to see in \pkgname{spverbatim}.
%
%
% \StopEventually{^^A
%   \section{Legal notices}
%
%   \noindent
%   Copyright \textcopyright\ 2009 Scott Pakin,
%   \href{mailto:scott+spverb@pakin.org}{\textit{scott+spverb@pakin.org}}
%
%   \bigskip
%
%   This package may be distributed and/or modified under the
%   conditions of the \LaTeX\ Project Public License, either
%   version~1.3c of this license or (at your option) any later
%   version.  The latest version of this license is in:
%
%   \begin{center}
%     \url{http://www.latex-project.org/lppl.txt}
%   \end{center}
%
%   \noindent
%   and version~1.3c or later is part of all distributions of
%   \LaTeX\ version 2006/05/20 or later.
% }
%
% \section{Implementation}
%
% This section presents the complete source code for the
% \pkgname{spverbatim} package.  Unless you're interested in seeing
% precisely how \pkgname{spverbatim} works, there's no need to read
% any further.
%
% \begin{macro}{\spverb}
% \begin{macro}{\spverb@ve}
% \begin{macro}{\@xobeysp}
% To avoid rewriting |\verb| and all of its helper macros we begin a group;
% locally redefine the nonbreaking space macro, |\@xobeysp|, to produce a
% breaking space; and locally redefine the end-of-|\verb| macro, |\verb@egroup|,
% to end the extra group we began.
%    \begin{macrocode}
\gdef\spverb{%
  \bgroup
  \let\spverb@ve=\verb@egroup
  \def\verb@egroup{\spverb@ve\egroup}%
  \def\@xobeysp{\mbox{}\space}%
  \verb
}
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\spv@xverbatim}
% |verbatim| is no ordinary \LaTeX\ environment.  Because ``|\|'',
% ``|{|'', and ``|}|'' are treated as literals within a |verbatim|
% environment, |\end{verbatim}| can't automatically end the environment.
% Rather, |\begin{verbatim}| invokes the |\@xverbatim| macro, which
% pattern-matches against the literal text ``|\end{verbatim}|'',
% typesets everything it finds up to that text, and finally invokes the
% real ``|\end{verbatim}|'' sequence.  Here, we define an
% |\spv@xverbatim| macro that's just like |\@xverbatim| except that it
% pattern-matches against the literal text ``|\end{spverbatim}|'' and
% ends with a call to the real ``|\end{spverbatim}|'' sequence.
%    \begin{macrocode}
\begingroup
  \catcode`|=0
  \catcode`[=1
  \catcode`]=2
  \catcode`\{=12
  \catcode`\}=12
  \catcode`\\=12
  |gdef|spv@xverbatim#1\end{spverbatim}[#1|end[spverbatim]]
|endgroup
%    \end{macrocode}
% \end{macro}
%
% \begin{environment}{spverbatim}
% Because the |verbatim| environment already begins a new group, all we
% have to do to get it to preserve spaces is locally redefine the
% nonbreaking space macro, |\@xobeysp|, to produce a breaking space;
% and locally redefine |\@xverbatim| as |\spv@xverbatim| (see above) so
% that a |\begin{spverbatim}| is matched by an |\end{spverbatim}|, not
% an |\end{verbatim}|.
%    \begin{macrocode}
\newenvironment{spverbatim}{%
  \def\@xobeysp{\mbox{}\space}%
  \let\@xverbatim=\spv@xverbatim
  \verbatim
}{%
}
%    \end{macrocode}
% \end{environment}
%
% \Finale
\endinput