Debian Codegraph @

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

raw
1 % \iffalse meta-comment
2 %
3 % Copyright (C) 2016 by Philippe Faist <[email protected]>
4 % -------------------------------------------------------
5 %
6 % This file may be distributed and/or modified under the
7 % conditions of the LaTeX Project Public License, either version 1.3
8 % of this license or (at your option) any later version.
9 % The latest version of this license is in:
10 %
11 % http://www.latex-project.org/lppl.txt
12 %
13 % and version 1.3 or later is part of all distributions of LaTeX
14 % version 2005/12/01 or later.
15 %
16 % \fi
17 %
18 % \iffalse
19 %<*driver>
20 \ProvidesFile{phfquotetext.dtx}
21 %</driver>
22 %<package>\NeedsTeXFormat{LaTeX2e}[2005/12/01]
23 %<package>\ProvidesPackage{phfquotetext}
24 %<*package>
25 [2016/08/15 v1.0 phfquotetext package]
26 %</package>
27 %
28 %<*driver>
29 \documentclass{ltxdoc}
30 \usepackage{xcolor}
31 \usepackage{phfquotetext}
32 \usepackage[preset=xpkgdoc]{phfnote}
33 \usepackage[normalem]{ulem}
34 \EnableCrossrefs
35 \CodelineIndex
36 \RecordChanges
37 \begin{document}
38 \DocInput{phfquotetext.dtx}
39 \end{document}
40 %</driver>
41 % \fi
42 %
43 % \CheckSum{0}
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}{2016/04/20}{Initial version}
63 %
64 % \GetFileInfo{phfquotetext.dtx}
65 %
66 % \DoNotIndex{\newcommand,\newenvironment,\def,\gdef,\edef,\xdef,\if,\else,\fi,\ifx}
67 %
68 % \title{\phfqitltxPkgTitle{phfquotetext}}
69 % \author{Philippe Faist\quad\email{[email protected]}}
70 % \date{\pkgfmtdate\filedate}
71 % \maketitle
72 %
73 % \begin{abstract}
74 % \pkgname{phfquotetext}---Provides an environment for displaying
75 % block text with special characters, such as verbatim quotes from a
76 % referee report.
77 % \end{abstract}
78 %
79 % \inlinetoc
80 %
81 % \section{Introduction}
82 %
83 % This package provides a quoting environment useful to quote, e.g., email text. It is
84 % somewhat like a verbatim environment (for instance, there is no macro expansion), but
85 % with also no white space formatting.
86 %
87 % For instance, you might find this useful for formatting replies to a
88 % referee, because any pseudo-\LaTeX{} commands are reproduced
89 % verbatim, but the bulk is still nicely formatted:
90 %
91 % \begin{verbatim}
92 % \begin{quotetext}
93 % This is some text which was provided in plain text, for example,
94 % by the referee. The object \calE should probably be defined with
95 % a factor 1/2 to help the \sum_k \ket{k} states not overwhelm rho
96 % by this and that by more than 50%....
97 % \end{quotetext}
98 % \end{verbatim}
99 %
100 % \verbdef\tmpA|\quotetextfont|
101 % \verbdef\tmpB|\sffamily\color{blue}|
102 % The above code gives the following output:\footnote{
103 % Here, we've assumed the \tmpA{} was redefined as
104 % \tmpB{}. Because it does look nicer. See
105 % \autoref{sec:customize-appearance}.}
106 %
107 % \renewcommand\quotetextfont{\sffamily\color{blue}}
108 % \begin{quotetext} This is some text which was provided in plain text, for example, by a referee. The object \calE should probably be defined with a factor 1/2 to help the \sum_k \ket{k} states not overwhelm rho by this and that by more than 50%.... \end{quotetext}
109 %
110 %
111 %
112 %
113 %
114 % \section{Usage}
115 %
116 % \subsection{The main environment}
117 %
118 % The main environment is simply |\begin{quotetext} ... \end{quotetext}|.
119 %
120 % \DescribeEnv{quotetext}
121 % Delimit your email quote within this environment:
122 %
123 % \begin{verbatim}
124 % \begin{quotetext}
125 % Stuff which you want to display verbatim, but with automatic white
126 % space formatting and text re-flow. \commands will not be
127 % expanded, and will be displayed verbatim. Percent signs also work
128 % 100%.
129 % \end{quotetext}
130 % \end{verbatim}
131 %
132 % The |{quotetext}| environment does not start a paragraph on its own, nor does it end it.
133 % You can thus in principle use this environment to quote text inline within a paragraph
134 % if you want to, unless you're enforcing new paragraphs in |\quotetextstart| and
135 % |\quotetextend|.
136 %
137 %
138 % \subsection{Customize appearance}
139 % \label{sec:customize-appearance}
140 %
141 % \DescribeMacro{\quotetextfont} This macro contains the formatting commands to set up the
142 % quote font. By default, the contents is displayed in typewriter font. You may redefine
143 % this command to achieve your favorite style:
144 % \begin{verbatim}
145 % \renewcommand\quotetextfont{\sffamily\color{blue}}
146 % \end{verbatim}
147 %
148 % This macro may also be defined to accept one argument, which is the whole contents of
149 % the quoted text. Make sure you define this with |\renewcommand| or |\long\def|, because
150 % the argument may contain several paragraphs.
151 %
152 % \DescribeMacro{\quotetextstart}
153 % This command gets called at the beginning of the quote environment. It may be used
154 % e.g.\@ to add space, a horizontal rule, or add other formatting goodies. By default, it
155 % is empty.
156 %
157 % \DescribeMacro{\quotetextend}
158 % This command gets called at the end of the quote environment. It may be used e.g.\@ to
159 % add space, a horizontal rule, or add other formatting goodies. By default, it is empty.
160 %
161 %
162 % The macros |\quotetextfont|, as well as |\quotetextstart| and
163 % |\quotetextend| are called within a \TeX{} group, so you don't need
164 % to worry that font overrides leak outside of the |quotetext|
165 % environment.
166 %
167 %
168 % You may try, for instance, the following to get started with customization:
169 % \begin{verbatim}
170 % \renewcommand\quotetextstart{%
171 % \par\noindent{\color{blue}\hrule height 0.8pt}\vspace{2pt}\vspace{-\parskip}}
172 % \renewcommand\quotetextend{%
173 % {\color{blue}\vspace{2pt}\hrule height 0.8pt\vspace{2pt}}}
174 % % \sout{} requires \usepackage[normalem]{ulem}:
175 % \renewcommand\quotetextfont[1]{\color{orange}\itshape\sout{\ignorespaces #1}}
176 % \end{verbatim}
177 % which gives:
178 % \renewcommand\quotetextstart{%
179 % \par\noindent{\color{blue}\hrule height 0.8pt}\vspace{2pt}\vspace{-\parskip}}
180 % \renewcommand\quotetextend{%
181 % {\color{blue}\vspace{2pt}\hrule height 0.8pt\vspace{2pt}}}
182 % \renewcommand\quotetextfont[1]{\color{orange}\itshape\sout{\ignorespaces #1}}
183 % \begin{quotetext} Stuff which you want to display verbatim, but with automatic white space formatting and text re-flow. \commands will not be expanded, and will be displayed verbatim. Percent signs also work 100%. \end{quotetext}
184 %
185 %
186 % \subsection{Customize Catcodes---Advanced Usage}
187 %
188 % \DescribeMacro{\quotetextcatcodedefs}
189 % You may redefine this command to set catcodes before parsing the bulk of the
190 % |{quotetext}| environment. This macro is called after \TeX's specials are already
191 % assigned catcode |12| (other). By default, this macro is empty.
192 %
193 % \section{Known Caveats}
194 %
195 % \begin{itemize}
196 % \item The leading space in the environment content is not trimmed
197 % from the argument passed on to |\quotetextfont|. This just means
198 % that if |\quotetextfont| is defined to accept an argument, it must
199 % not forget to precede it with |\ignorespaces| as appropriate (as
200 % in the example above in \autoref{sec:customize-appearance}).
201 % I'm not sure how to remove trailing whitespace.
202 % \item By default, the |{quotetext}| environment does not start a new paragraph nor end
203 % the paragraph, unless you enforce this explicitly in |\quotetextstart| and
204 % |\quotetextend|. This is purposely left as a feature to be aware of.
205 % \end{itemize}
206 %
207 %
208 %
209 %
210 % \StopEventually{\PrintChanges\PrintIndex}
211 %
212 % \section{Implementation}
213 %
214 % \subsection{Main Macros and Environment}
215 %
216 % \begin{macro}{\quotetextcatcodedefs}
217 % Allows to set custom catcodes for parsing of quotetext contents.
218 %
219 % By default, all char catcodes are set as "other" characters, but you may
220 % redefine this macro to define you own catcodes.
221 %
222 % This macro is empty by default.
223 % \begin{macrocode}
224 \newcommand\quotetextcatcodedefs{}
225 % \end{macrocode}
226 % \end{macro}
227 %
228 % \begin{macro}{\quotetextstart}
229 % \begin{macro}{\quotetextend}
230 % Definitions which are called at the beginning or end of every
231 % quote environment. They are empty by default.
232 % \begin{macrocode}
233 \newcommand\quotetextstart{}
234 \newcommand\quotetextend{}
235 % \end{macrocode}
236 % \end{macro}
237 % \end{macro}
238 %
239 % \begin{macro}{\quotetextfont}
240 % Set up the font and display for the quote text environment.
241 %
242 % This command may also be defined to take one single argument, which will be
243 % the whole contents of the quotetext environment.
244 % \begin{macrocode}
245 \newcommand\quotetextfont{\ttfamily}
246 % \end{macrocode}
247 % \end{macro}
248 %
249 %
250 % \begin{environment}{quotetext}
251 % The main environment. Starts group and relays the call to |\phfquotetext@warg| to
252 % start reading the contents of the environment.
253 %
254 % Start the environment definition.
255 % \begin{macrocode}
256 \newenvironment{quotetext}{%
257 % \end{macrocode}
258 % \iffalse meta-comment %} -- for emacs' paren matching
259 % \fi
260 %
261 % Do anything we should do before the |quotetext| environment.
262 % \begin{macrocode}
263 \quotetextstart%
264 % \end{macrocode}
265 %
266 % Make sure to enclose the full quote text stuff into its own group to make definitions
267 % such as catcode overrides local.
268 % \begin{macrocode}
269 \begingroup%
270 % \end{macrocode}
271 %
272 % Finally, relay the call to |\phfquotetext@warg| to read the whole contents of the
273 % environment, and finish the environment definition.
274 % \begin{macrocode}
275 \phfquotetext@warg%
276 }
277 % \end{macrocode}
278 %
279 % Finally, in the closing part of the environment, do anything which
280 % needs to be done at the end.
281 % \begin{macrocode}
282 {%
283 \quotetextend%
284 }
285 % \end{macrocode}
286 % \end{environment}
287 %
288 %
289 %
290 % \subsection{Internal Stuff}
291 %
292 % \begin{macro}{\phfquotetext@warg@}
293 % Reads an argument delimited by ....|\end{quotetext}|, ends the current \TeX{} group
294 % assumed open (in order to change the catcodes), and calls the start/show/end commands.
295 %
296 % We need deep catcode dark magic to just even define this command.
297 % \begin{macrocode}
298 \begingroup
299 \catcode`|=0
300 \catcode`\<=1
301 \catcode`\>=2
302 \catcode`\{=12
303 \catcode`\}=12
304 \catcode`\\=12
305 |long|gdef|phfquotetext@warg@#1\end{quotetext}<|endgroup
306 |phfquotetext@show<#1>>
307 |endgroup
308 % \end{macrocode}
309 % \end{macro}
310 %
311 %
312 % \begin{macro}{\phfquotetext@show}
313 % Shows the content given as argument with the proper formatting. Includes an actual
314 % call to |\end{quotetext}| to make \LaTeX's bookcounting mechanism for |\begin|/|\end|
315 % happy, and which finally also calls |\quotetextend|.
316 % \begin{macrocode}
317 \newtoks\qtt@mytoks
318 \long\def\phfquotetext@show#1{%
319 \qtt@mytoks={#1}%
320 \begingroup%
321 % \end{macrocode}
322 % Crucially, |\the\toks| only expands once and prohibits further
323 % expansion. This way, we may pass the argument directly to
324 % |\quotetextfont|, with tokens expanded exactly as they were given:
325 % \begin{macrocode}
326 \expandafter\quotetextfont\expandafter{\the\qtt@mytoks}%
327 \endgroup%
328 \end{quotetext}%
329 }
330 % \end{macrocode}
331 % \end{macro}
332 %
333 %
334 % \begin{macro}{\phfquotetext@warg}
335 % Prepares to read the contents of the environment. A new \TeX{} group has already been
336 % opened by |\begin{quotetext}|.
337 % \begin{macrocode}
338 \def\phfquotetext@warg{%
339 %
340 % \end{macrocode}
341 % Set the catcode of all special chars to ``other'' (12). We use |\dospecials| provided
342 % by \LaTeX{} itself.\footnote{see \url{http://tex.stackexchange.com/a/12890/32188}} We
343 % leave the space token to the ``space'' catcode, so that white space is properly managed
344 % by LaTeX. Finally, include any user catcode overrides in |\quotetextcatcodedefs|.
345 % \begin{macrocode}
346 \let\do\@makeother%
347 \dospecials%
348 \catcode`\ =10\relax% keep space
349 \quotetextcatcodedefs%
350 % \end{macrocode}
351 %
352 % Finally, relay the call to |\phfquotetext@warg@| to read the contents of the group and
353 % close the \TeX{} group.
354 %
355 % \begin{macrocode}
356 \phfquotetext@warg@%
357 }
358 % \end{macrocode}
359 % \end{macro}
360 %
361 %
362 %\Finale
363 \endinput