summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/phfquotetext/phfquotetext.dtx
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /macros/latex/contrib/phfquotetext/phfquotetext.dtx
Initial commit
Diffstat (limited to 'macros/latex/contrib/phfquotetext/phfquotetext.dtx')
-rw-r--r--macros/latex/contrib/phfquotetext/phfquotetext.dtx363
1 files changed, 363 insertions, 0 deletions
diff --git a/macros/latex/contrib/phfquotetext/phfquotetext.dtx b/macros/latex/contrib/phfquotetext/phfquotetext.dtx
new file mode 100644
index 0000000000..fda41bdd5a
--- /dev/null
+++ b/macros/latex/contrib/phfquotetext/phfquotetext.dtx
@@ -0,0 +1,363 @@
+% \iffalse meta-comment
+%
+% Copyright (C) 2016 by Philippe Faist <philippe.faist@bluewin.ch>
+% -------------------------------------------------------
+%
+% This file 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.
+%
+% \fi
+%
+% \iffalse
+%<*driver>
+\ProvidesFile{phfquotetext.dtx}
+%</driver>
+%<package>\NeedsTeXFormat{LaTeX2e}[2005/12/01]
+%<package>\ProvidesPackage{phfquotetext}
+%<*package>
+ [2016/08/15 v1.0 phfquotetext package]
+%</package>
+%
+%<*driver>
+\documentclass{ltxdoc}
+\usepackage{xcolor}
+\usepackage{phfquotetext}
+\usepackage[preset=xpkgdoc]{phfnote}
+\usepackage[normalem]{ulem}
+\EnableCrossrefs
+\CodelineIndex
+\RecordChanges
+\begin{document}
+ \DocInput{phfquotetext.dtx}
+\end{document}
+%</driver>
+% \fi
+%
+% \CheckSum{0}
+%
+% \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}{2016/04/20}{Initial version}
+%
+% \GetFileInfo{phfquotetext.dtx}
+%
+% \DoNotIndex{\newcommand,\newenvironment,\def,\gdef,\edef,\xdef,\if,\else,\fi,\ifx}
+%
+% \title{\phfqitltxPkgTitle{phfquotetext}}
+% \author{Philippe Faist\quad\email{philippe.faist@bluewin.ch}}
+% \date{\pkgfmtdate\filedate}
+% \maketitle
+%
+% \begin{abstract}
+% \pkgname{phfquotetext}---Provides an environment for displaying
+% block text with special characters, such as verbatim quotes from a
+% referee report.
+% \end{abstract}
+%
+% \inlinetoc
+%
+% \section{Introduction}
+%
+% This package provides a quoting environment useful to quote, e.g., email text. It is
+% somewhat like a verbatim environment (for instance, there is no macro expansion), but
+% with also no white space formatting.
+%
+% For instance, you might find this useful for formatting replies to a
+% referee, because any pseudo-\LaTeX{} commands are reproduced
+% verbatim, but the bulk is still nicely formatted:
+%
+% \begin{verbatim}
+% \begin{quotetext}
+% This is some text which was provided in plain text, for example,
+% by the 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}
+% \end{verbatim}
+%
+% \verbdef\tmpA|\quotetextfont|
+% \verbdef\tmpB|\sffamily\color{blue}|
+% The above code gives the following output:\footnote{
+% Here, we've assumed the \tmpA{} was redefined as
+% \tmpB{}. Because it does look nicer. See
+% \autoref{sec:customize-appearance}.}
+%
+% \renewcommand\quotetextfont{\sffamily\color{blue}}
+% \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}
+%
+%
+%
+%
+%
+% \section{Usage}
+%
+% \subsection{The main environment}
+%
+% The main environment is simply |\begin{quotetext} ... \end{quotetext}|.
+%
+% \DescribeEnv{quotetext}
+% Delimit your email quote within this environment:
+%
+% \begin{verbatim}
+% \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}
+% \end{verbatim}
+%
+% The |{quotetext}| environment does not start a paragraph on its own, nor does it end it.
+% You can thus in principle use this environment to quote text inline within a paragraph
+% if you want to, unless you're enforcing new paragraphs in |\quotetextstart| and
+% |\quotetextend|.
+%
+%
+% \subsection{Customize appearance}
+% \label{sec:customize-appearance}
+%
+% \DescribeMacro{\quotetextfont} This macro contains the formatting commands to set up the
+% quote font. By default, the contents is displayed in typewriter font. You may redefine
+% this command to achieve your favorite style:
+% \begin{verbatim}
+% \renewcommand\quotetextfont{\sffamily\color{blue}}
+% \end{verbatim}
+%
+% This macro may also be defined to accept one argument, which is the whole contents of
+% the quoted text. Make sure you define this with |\renewcommand| or |\long\def|, because
+% the argument may contain several paragraphs.
+%
+% \DescribeMacro{\quotetextstart}
+% This command gets called at the beginning of the quote environment. It may be used
+% e.g.\@ to add space, a horizontal rule, or add other formatting goodies. By default, it
+% is empty.
+%
+% \DescribeMacro{\quotetextend}
+% This command gets called at the end of the quote environment. It may be used e.g.\@ to
+% add space, a horizontal rule, or add other formatting goodies. By default, it is empty.
+%
+%
+% The macros |\quotetextfont|, as well as |\quotetextstart| and
+% |\quotetextend| are called within a \TeX{} group, so you don't need
+% to worry that font overrides leak outside of the |quotetext|
+% environment.
+%
+%
+% You may try, for instance, the following to get started with customization:
+% \begin{verbatim}
+% \renewcommand\quotetextstart{%
+% \par\noindent{\color{blue}\hrule height 0.8pt}\vspace{2pt}\vspace{-\parskip}}
+% \renewcommand\quotetextend{%
+% {\color{blue}\vspace{2pt}\hrule height 0.8pt\vspace{2pt}}}
+% % \sout{} requires \usepackage[normalem]{ulem}:
+% \renewcommand\quotetextfont[1]{\color{orange}\itshape\sout{\ignorespaces #1}}
+% \end{verbatim}
+% which gives:
+% \renewcommand\quotetextstart{%
+% \par\noindent{\color{blue}\hrule height 0.8pt}\vspace{2pt}\vspace{-\parskip}}
+% \renewcommand\quotetextend{%
+% {\color{blue}\vspace{2pt}\hrule height 0.8pt\vspace{2pt}}}
+% \renewcommand\quotetextfont[1]{\color{orange}\itshape\sout{\ignorespaces #1}}
+% \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}
+%
+%
+% \subsection{Customize Catcodes---Advanced Usage}
+%
+% \DescribeMacro{\quotetextcatcodedefs}
+% You may redefine this command to set catcodes before parsing the bulk of the
+% |{quotetext}| environment. This macro is called after \TeX's specials are already
+% assigned catcode |12| (other). By default, this macro is empty.
+%
+% \section{Known Caveats}
+%
+% \begin{itemize}
+% \item The leading space in the environment content is not trimmed
+% from the argument passed on to |\quotetextfont|. This just means
+% that if |\quotetextfont| is defined to accept an argument, it must
+% not forget to precede it with |\ignorespaces| as appropriate (as
+% in the example above in \autoref{sec:customize-appearance}).
+% I'm not sure how to remove trailing whitespace.
+% \item By default, the |{quotetext}| environment does not start a new paragraph nor end
+% the paragraph, unless you enforce this explicitly in |\quotetextstart| and
+% |\quotetextend|. This is purposely left as a feature to be aware of.
+% \end{itemize}
+%
+%
+%
+%
+% \StopEventually{\PrintChanges\PrintIndex}
+%
+% \section{Implementation}
+%
+% \subsection{Main Macros and Environment}
+%
+% \begin{macro}{\quotetextcatcodedefs}
+% Allows to set custom catcodes for parsing of quotetext contents.
+%
+% By default, all char catcodes are set as "other" characters, but you may
+% redefine this macro to define you own catcodes.
+%
+% This macro is empty by default.
+% \begin{macrocode}
+\newcommand\quotetextcatcodedefs{}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\quotetextstart}
+% \begin{macro}{\quotetextend}
+% Definitions which are called at the beginning or end of every
+% quote environment. They are empty by default.
+% \begin{macrocode}
+\newcommand\quotetextstart{}
+\newcommand\quotetextend{}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\quotetextfont}
+% Set up the font and display for the quote text environment.
+%
+% This command may also be defined to take one single argument, which will be
+% the whole contents of the quotetext environment.
+% \begin{macrocode}
+\newcommand\quotetextfont{\ttfamily}
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \begin{environment}{quotetext}
+% The main environment. Starts group and relays the call to |\phfquotetext@warg| to
+% start reading the contents of the environment.
+%
+% Start the environment definition.
+% \begin{macrocode}
+\newenvironment{quotetext}{%
+% \end{macrocode}
+% \iffalse meta-comment %} -- for emacs' paren matching
+% \fi
+%
+% Do anything we should do before the |quotetext| environment.
+% \begin{macrocode}
+ \quotetextstart%
+% \end{macrocode}
+%
+% Make sure to enclose the full quote text stuff into its own group to make definitions
+% such as catcode overrides local.
+% \begin{macrocode}
+ \begingroup%
+% \end{macrocode}
+%
+% Finally, relay the call to |\phfquotetext@warg| to read the whole contents of the
+% environment, and finish the environment definition.
+% \begin{macrocode}
+ \phfquotetext@warg%
+}
+% \end{macrocode}
+%
+% Finally, in the closing part of the environment, do anything which
+% needs to be done at the end.
+% \begin{macrocode}
+{%
+ \quotetextend%
+}
+% \end{macrocode}
+% \end{environment}
+%
+%
+%
+% \subsection{Internal Stuff}
+%
+% \begin{macro}{\phfquotetext@warg@}
+% Reads an argument delimited by ....|\end{quotetext}|, ends the current \TeX{} group
+% assumed open (in order to change the catcodes), and calls the start/show/end commands.
+%
+% We need deep catcode dark magic to just even define this command.
+% \begin{macrocode}
+\begingroup
+ \catcode`|=0
+ \catcode`\<=1
+ \catcode`\>=2
+ \catcode`\{=12
+ \catcode`\}=12
+ \catcode`\\=12
+ |long|gdef|phfquotetext@warg@#1\end{quotetext}<|endgroup
+ |phfquotetext@show<#1>>
+|endgroup
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \begin{macro}{\phfquotetext@show}
+% Shows the content given as argument with the proper formatting. Includes an actual
+% call to |\end{quotetext}| to make \LaTeX's bookcounting mechanism for |\begin|/|\end|
+% happy, and which finally also calls |\quotetextend|.
+% \begin{macrocode}
+\newtoks\qtt@mytoks
+\long\def\phfquotetext@show#1{%
+ \qtt@mytoks={#1}%
+ \begingroup%
+% \end{macrocode}
+% Crucially, |\the\toks| only expands once and prohibits further
+% expansion. This way, we may pass the argument directly to
+% |\quotetextfont|, with tokens expanded exactly as they were given:
+% \begin{macrocode}
+ \expandafter\quotetextfont\expandafter{\the\qtt@mytoks}%
+ \endgroup%
+ \end{quotetext}%
+}
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \begin{macro}{\phfquotetext@warg}
+% Prepares to read the contents of the environment. A new \TeX{} group has already been
+% opened by |\begin{quotetext}|.
+% \begin{macrocode}
+\def\phfquotetext@warg{%
+ %
+% \end{macrocode}
+% Set the catcode of all special chars to ``other'' (12). We use |\dospecials| provided
+% by \LaTeX{} itself.\footnote{see \url{http://tex.stackexchange.com/a/12890/32188}} We
+% leave the space token to the ``space'' catcode, so that white space is properly managed
+% by LaTeX. Finally, include any user catcode overrides in |\quotetextcatcodedefs|.
+% \begin{macrocode}
+ \let\do\@makeother%
+ \dospecials%
+ \catcode`\ =10\relax% keep space
+ \quotetextcatcodedefs%
+% \end{macrocode}
+%
+% Finally, relay the call to |\phfquotetext@warg@| to read the contents of the group and
+% close the \TeX{} group.
+%
+% \begin{macrocode}
+ \phfquotetext@warg@%
+}
+% \end{macrocode}
+% \end{macro}
+%
+%
+%\Finale
+\endinput