summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/newverbs/newverbs.dtx
blob: e1d8ef78ff9b154fbc243e9e69138d6b242828e2 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
% \iffalse
%<*copyright>
%% Copyright (c) 2010 by Martin Scharrer <martin@scharrer-online.de>
%% WWW: http://latex.scharrer-online.de/
%%
%% This work may be distributed and/or modified under the
%% conditions of the LaTeX Project Public License, either version 1.3
%% 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.3 or later is part of all distributions of LaTeX
%% version 2005/12/01 or later.
%%
%% This work has the LPPL maintenance status `maintained'.
%%
%% The Current Maintainer of this work is Martin Scharrer.
%%
%% This work consists of the files newverbs.dtx and newverbs.ins
%% and the derived file newverbs.sty.
%</copyright>
%<*!copyright>
%
%% $Id: newverbs.dtx 1816 2010-04-05 18:03:28Z martin $
%
%<*driver>
\ProvidesFile{newverbs.dtx}
%</driver>
%<package>\ProvidesPackage{newverbs}
%<*package|driver>
  [2010/04/05 v1.0 Define new 'verb' commands and short verb. characters]
%</package|driver>
%
%<*driver>
\documentclass{ltxdoc}
\usepackage{hyperref}
\usepackage{xcolor}

\GetFileInfo{newverbs.dtx}
\usepackage{newverbs}[\filedate]
\usepackage{shortvrb}

\MakeSpecialShortVerb{\qverb}{\"}

%\EnableCrossrefs
%\CodelineIndex
%\RecordChanges
\providecommand*{\pkg}{\texttt}
\providecommand*{\optstar}{\textcolor{gray}{\texttt{*}}}
\begin{document}
  \DocInput{newverbs.dtx}
  %\PrintChanges
  %\PrintIndex
\end{document}
%</driver>
% \fi
%
% \CheckSum{58}\relax
%
% \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}{2010/04/05}{Initial version}
%
% \DoNotIndex{\newcommand,\newenvironment,\providecommand}
%
% \GetFileInfo{newverbs.dtx}
% \title{The \textsf{newverbs} package}
% \author{Martin Scharrer \\ \texttt{martin@scharrer-online.de}}
% \date{\fileversion\ from \filedate}
%
% \maketitle
% \begin{abstract}
% This package allows the definition of \cs{verb} variants which add \TeX\ code before and after the verbatim text.
% When used together with the \pkg{shortvrb} package it allows the definition of short verbatim characters which use this variants
% instead of the normal \cs{verb}.
% \end{abstract}
%
% \section{Usage}
%
% \subsection{Defining new variants of \texorpdfstring{\cs{verb}}{'verb'}}
%
% \DescribeMacro\newverbcommand
% \DescribeMacro\renewverbcommand
% \DescribeMacro\provideverbcommand
% This macros allow the definition of \cs{verb} variants. The verbatim content is processed using \cs{verb}, but the
% variants can add \TeX\ code before and after it.
% The syntax is \cs{\ldots verbcommand}\marg{macro}\marg{code before}\marg{code after}.
% The three definition macros use |\newcommand*|, |\renewcommand*| and |\providecommand*| internal to define \meta{macro}, respectively.
% Afterwards \meta{macro} can be used like \cs{verb}. The star version of \meta{macro} will use \cs{verb}|*|.
%
% See the implementation of \cs{qverb} in section~\ref{sec:impl} for an example.
%
%
% \subsection{Provided \texorpdfstring{\cs{verb}}{'verb'} variants}
%
% Two \cs{verb} variants are provided (i.e. with \cs{provideverbcommand}) by default.
%
% \DescribeMacro\qverb
% This macro adds quote characters around the verbatim material.
% Two macros are used to insert the quotes: \cs{qverbbeginquote} (`) and \cs{qverbendquote} (').
% They can be redefined by the user if required.
%
% Using \cs{qverb}\meta{char}\meta{verbatim material}\meta{char} is equal to \\
% \cs{qverbbeginquote}\cs{verb}\meta{char}\meta{verbatim material}\meta{char}\cs{qverbbeginquote}, or\\
% |`|\cs{verb}\meta{char}\meta{verbatim material}\meta{char}|'|\\
% when the default definition of the quote macros is used.
%
% \DescribeMacro\fverb
% This macro adds a frame (|\fbox{}|) around the verbatim text (|\fverb+$&^_%$+| $\to$ \fverb+$&^_$+).
% A \TeX\ box is used to store the content first, then the box is framed.
% The user can define similar command using the following code:\\
% {\ttfamily
% \hspace*{2.5em}|\newverbcommand{\myverb}{\begin{lrbox}{\verbbox}}|\\
% \hspace*{10em}|{\end{lrbox}\mycommand{\usebox{\verbbox}}}|}\\
% The temporary box \cs{verbbox} is only provided inside a |\...verbcommand|.
%
% \subsection{Using \texorpdfstring{\cs{verb}}{'verb'} variants with short verbatim character}
%
% \DescribeMacro\MakeSpecialShortVerb
% This package also defines a special version of the \cs{MakeShortVerb} macro from the \pkg{shortvrb} package.
% The orignal command \cs{MakeShortVerb}\optstar|{\|\meta{char}|}| changes the meaning of \meta{char} so that 
% \meta{char}\meta{verbatim material}\meta{char} is a shorter alternative to
% \cs{verb}\optstar\meta{char}\meta{verbatim material}\meta{char}.
%
% The new macro \cs{MakeSpecialShortVerb}\optstar\marg{\cs{verb} variant}|{\|\meta{char}|}| does the same, but 
% instead of \cs{verb}\optstar\ it uses a \meta{\cs{verb} variant} which needs to be defined using \cs{newverbcommand}.
% The package \pkg{shortvrb} must be loaded by the user in order to make this macro work. It is not loaded automatically by \pkg{newverbs}.
%
% The special meaning of \meta{char} can be removed using \pkg{shortvrb}'s \cs{DeleteShortVerb}, i.e.\ the same way as for 
% characters defined with the normal \cs{MakeShortVerb}.
% If a character was already made a short verbatim character it must be ``deleted'' before it can be redefined by \cs{MakeShortVerb} or
% \cs{MakeSpecialShortVerb}.
%
% \bigskip\noindent\textbf{Examples:}\\
% |\MakeSpecialShortVerb{\qverb}{\"}| will make `|"|' a short, quoting verbatim character: |"$^&$"| $\to$ "$^&$".\\
% |\DeleteShortVerb{\"}\MakeSpecialShortVerb{\fverb}{\"}| will change it definition to use \cs{fverb}: \fverb+$^&$+.
%
%
% \section{Compatibility with other verbatim packages}
% The compatibility with other verbatim packages is not tested yet. This package relies on the normal internal definition of \cs{verb}
% and \cs{MakeShortVerb}. Any package which changes these might break this package.
% Users which encounter incapabilities should not hesitate to contact the package author (with details!).
%
% \StopEventually{}
% \section{Implementation}
% \iffalse
%<*package>
% \fi
%
% \subsection{Verb Definition Commands}
%
% \begin{macro}{\newverbcommand}
% \begin{macro}{\renewverbcommand}
% \begin{macro}{\provideverbcommand}
% This macro calls the real macro with the to be used definition macro.
%    \begin{macrocode}
\newcommand*\newverbcommand{\new@verbcommand\newcommand}
\newcommand*\renewverbcommand{\new@verbcommand\renewcommand}
\newcommand*\provideverbcommand{\new@verbcommand\providecommand}
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\new@verbcommand}
% Depending on |#1| a macro given by |#2| is (re-)defined/provided.
% The code given by |#3| and |#4| is placed before and after the verb command.
% The trailing code is inserted by patching \cs{verb@egroup} which is called by \cs{verb}
% after the verbatim content.
%    \begin{macrocode}
\def\new@verbcommand#1#2#3#4{%
  #1*#2{%
    \begingroup
    \newverbcommand@settings
    \def\verb@egroup{\verb@orig@egroup#4\endgroup}%
    #3\verb
  }%
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\newverbcommand@settings}
% Some settings required for all new \cs{verb}-like commands.
% The original end group macro from \cs{verb} is saved away.
% Also the temp box a is provided with a user friendly name.
%    \begin{macrocode}
\def\newverbcommand@settings{%
  \let\verb@orig@egroup\verb@egroup
  \let\verbbox\@tempboxa
}
%    \end{macrocode}
% \end{macro}
%
% \subsection{Provided New Verb Commands}\label{sec:impl}
%
% \begin{macro}{\qverb}
% Quoting version of \cs{verb}. Places a quote character before and after the verbatim content: "verb".
%    \begin{macrocode}
\provideverbcommand{\qverb}{\qverbbeginquote}{\qverbendquote}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\qverbbeginquote}
% \begin{macro}{\qverbendquote}
% This macros insert the actual quotes. They can be redefined by the user to contain the required quotes.
%    \begin{macrocode}
\def\qverbbeginquote{`}
\def\qverbendquote{'}
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\fverb}
% A framed version of \cs{verb}. Stores the verbatim content first into a box. Then the box content is framed.
%    \begin{macrocode}
\newverbcommand{\fverb}
  {\setbox\verbbox\hbox\bgroup\color@setgroup}
  {\color@endgroup\egroup\fbox{\box\verbbox}}
%    \end{macrocode}
% \end{macro}
%
%
% \subsection{Make Special Short Verbatim Characters}
%
% \begin{macro}{\MakeSpecialShortVerb}
% Uses the definition of \cs{MakeShortVerb} from \pkg{shortvrb} except with \cs{verb} replaced with the first argument.
% The second argument is then read by \cs{@MakeShortVerb}.
%    \begin{macrocode}
\newcommand*\MakeSpecialShortVerb[1]{%
  \@ifstar
    {\def\@shortvrbdef{#1*}\@MakeShortVerb}%
    {\def\@shortvrbdef{#1}\@MakeShortVerb}%
}
%    \end{macrocode}
% \end{macro}
%
% \iffalse
%</package>
% \fi
% \Finale
\endinput