diff options
Diffstat (limited to 'Master/texmf-dist/source/latex/phfquotetext/phfquotetext.dtx')
-rw-r--r-- | Master/texmf-dist/source/latex/phfquotetext/phfquotetext.dtx | 363 |
1 files changed, 363 insertions, 0 deletions
diff --git a/Master/texmf-dist/source/latex/phfquotetext/phfquotetext.dtx b/Master/texmf-dist/source/latex/phfquotetext/phfquotetext.dtx new file mode 100644 index 00000000000..fda41bdd5a2 --- /dev/null +++ b/Master/texmf-dist/source/latex/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 |