From 2cea258fda0365adce50be5a29fcd9d87fb6868f Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Fri, 12 Aug 2011 15:32:52 +0000 Subject: new latex package quoting (11aug11) git-svn-id: svn://tug.org/texlive/trunk@23512 c570f23f-e606-0410-a88d-b1316a301751 --- Master/texmf-dist/source/latex/quoting/quoting.dtx | 548 +++++++++++++++++++++ Master/texmf-dist/source/latex/quoting/quoting.ins | 52 ++ 2 files changed, 600 insertions(+) create mode 100644 Master/texmf-dist/source/latex/quoting/quoting.dtx create mode 100644 Master/texmf-dist/source/latex/quoting/quoting.ins (limited to 'Master/texmf-dist/source/latex/quoting') diff --git a/Master/texmf-dist/source/latex/quoting/quoting.dtx b/Master/texmf-dist/source/latex/quoting/quoting.dtx new file mode 100644 index 00000000000..94fb880630c --- /dev/null +++ b/Master/texmf-dist/source/latex/quoting/quoting.dtx @@ -0,0 +1,548 @@ +% \iffalse meta-comment +% +% This is file `quoting.dtx'. +% +% Copyright (C) 2011 by Thomas Titz +% +% Permission is granted to distribute and/or modify this work under the +% terms of the LaTeX Project Public License (LPPL), version 1.3c or +% later. +% +% The LPPL maintenance status of this work is "maintained". +% +% This work consists of the files quoting.dtx, quoting.ins and README +% and the derived files quoting.pdf and quoting.sty. +% +% \fi +% +% \iffalse +% +%<*driver> +\documentclass{ltxdoc} +\EnableCrossrefs +\CodelineIndex +\RecordChanges +% \OnlyDescription +\GlossaryPrologue{% + \section*{{Change History}}% + \markboth{{Change History}}{{Change History}}% + \vspace{-\multicolsep}% +} +\newcommand*{\SpecialOptIndex}[1]{% + \index{#1={\protect\sffamily#1} (option)|usage}% + \index{options:>#1={\protect\sffamily#1}|usage}% +} +\usepackage{quoting} +\usepackage{csquotes} +\SetBlockEnvironment{quoting} +\usepackage[bottom]{footmisc} +\addtolength{\skip\footins}{5pt} +\usepackage{cite,enumitem,url} +\frenchspacing +\def\quo/{\textsf{quoting}} +\def\quoa/{\textsf{quotation}} +\def\quoe/{\textsf{quote}} +\begin{document} +\DocInput{quoting.dtx} +\end{document} +% +% +% \fi +% +% \CheckSum{120} +% +% \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{v0.1}{2011/08/08}{Initial public release} +% +% \GetFileInfo{quoting.sty} +% +% \DoNotIndex{\boolfalse,\booltrue,\csname,\def,\endcsname,\endinput} +% \DoNotIndex{\ifbool,\item,\@M,\NeedsTeXFormat,\newbool,\newcommand} +% \DoNotIndex{\newenvironment,\newlength,\par,\ProvidesPackage,\relax} +% \DoNotIndex{\RequirePackage,\setlength,\z@} +% +% \title{The \quo/ package\thanks{This document corresponds to +% \quo/~\fileversion, dated \filedate.}} +% \author{Thomas Titz\thanks{E-mail: \texttt{thomas.titz@chello.at}}} +% \maketitle +% +% \begin{abstract} +% \noindent As an alternative to the \LaTeX\ standard environments +% \quoa/ and \quoe/, the \quo/ package provides a consolidated +% environment for displayed text. First-line indentation is activated by +% adding a blank line before the \quo/ environment. A key--value +% interface allows to configure font properties and spacing and to +% control orphans within and after the environment. +% \end{abstract} +% +% \section{Introduction} +% +% The \LaTeX\ standard classes as well as many custom classes provide +% two environments for displayed text: \quoa/ and \quoe/. They can be +% described as follows: \blockcquote[p.~480]{Kop04}{\textins{In} the +% \quoa/ environment \textelp{} text is indented on both sides relative +% to the normal page margins. Paragraphs within the environment are +% marked with an additional indentation of the first line. +% +% \textins{The \quoe/ environment is} \textins*{t}he same as the \quoa/ +% environment except that the first line of a paragraph is not indented; +% instead, additional line spacing comes between paragraphs.} +% +% So when to prefer one environment to the other? A common suggestion is +% to use the \quoa/ environment for quotes extending to several +% paragraphs so that the paragraph indentation matches that of the +% surrounding text \cite{Kot11,Lam94,Oet11}. For single-paragraph quotes +% one may either use \quoe/ or, in case the quoted text starts a new +% paragraph (which should be indicated by indentation), \quoa/. +% +% Why didn't Leslie Lamport, the initial developer of \LaTeX, implement +% a single environment for displayed text and provide control over its +% first-line indentation by other means, e.\,g. the presence of a blank +% line (or a |\par| command) before the environment? The likely reason +% is that Lamport envisaged an additional application of the \quoe/ +% environment, namely \blockcquote[p.~24]{Lam94}{a sequence of short +% quotations, separated by blank lines}. But such a sequence (which +% seems to be of limited use) could also be put into effect by stringing +% together several instances of a consolidated quoting environment. +% +% Some unfavourable effects of \quoa/ and \quoe/ in their present form +% are: +% +% \begin{itemize} +% +% \item The \quoa/ environment isn't suited for documents which use +% vertical spacing instead of indentation to denote the start of new +% paragraphs. If one retroactively adopts such a layout, one should +% change the definition of |\quotation| and |\endquotation| to |\quote| +% resp. |\endquote|. +% +% \item The side-by-side existence of two environments for displayed +% text narrows the utility of the \textsf{csquotes} package which +% provides higher-level wrapper environments, e.g. for quoting in a +% foreign language and specifying the source of citations. Currently, +% \textsf{csquotes} uses \quoe/ as a backend environment, but with +% \LaTeX's default settings, this is not appropriate for multi-paragraph +% quotes. +% +% \end{itemize} +% +% \section{Using the \quo/ package} +% +% As an alternative to \quoa/ and \quoe/, the \quo/ package provides a +% consolidated environment for displayed text. Besides being indented +% relative to the normal page margins, the \quo/ environment behaves as +% follows: +% +% \begin{itemize} +% +% \item A blank line before the environment marks a new paragraph, +% i.\,e. the environment's first line will be (additionally) indented in +% this case (assuming a positive |\parindent|). The mechanism also works +% for adjoining \quo/ environments of the same depth and for nested +% quotes.\footnote{See \cite[p.~120--121]{Fis95} for an example of +% nested quotes.} +% +% \item If a \quo/ environment directly follows a sectioning command +% (which may or may not be considered good style), its first line won't +% be indented.\footnote{That is, unless the |@afterindent| switch was +% set to true, e.g. by loading the \textsf{indentfirst} package. In this +% case, the quote's first line will be indented.} +% +% \item As the start of a new paragraph is already indicated by +% first-line indentation, the vertical space before and after the \quo/ +% environment is kept constant (contrary to list environments like +% \textsf{itemize} and \textsf{enumerate}). +% +% \item Because the \quo/ environment uses a custom mechanism to control +% orphans\footnote{If a page break occurs after the first line of a +% paragraph, that line is referred to as \enquote{orphan}.} within and +% after it, it is not affected by \LaTeX\ bug 4065 (|\clubpenalty| not +% always being reset after list environments). +% +% \end{itemize} +% +% The options provided by \quo/ use the key--value interface +% `\meta{key}=\meta{value}'. Set them globally with +% |\usepackage[|\meta{options}|]{quoting}| or for single environments +% with |\begin{quoting}[|\meta{options}|]|. For boolean options, the +% default value is \textsf{false}, and specifying \meta{key} is +% equivalent to \meta{key}\textsf{=true}. +% +% \begin{description}[font=\sffamily] +% +% \item[font]\SpecialOptIndex{font} The font used for typesetting the +% contents of a \quo/ environment. Permitted values are the names +% (without preceding backslash) of \LaTeX's font-switching/formatting +% commands; e.\,g, use \textsf{font=itshape} to typeset quotes in +% italics. (By default, \quo/ uses the font/formatting of the +% surrounding text.) To specify several font properties, invoke +% \textsf{font+} in addition to \textsf{font}. +% +% \item[font+]\SpecialOptIndex{font+} Font properties used for +% typesetting the contents of a \quo/ environment in addition to those +% properties specified by \textsf{font} (and previous calls of +% \textsf{font+}). +% +% \item[leftmargin]\SpecialOptIndex{leftmargin} The width of the +% environment's left-hand indentation relative to the surrounding text. +% The default value is |\leftmargin|.\footnote{Note that the value of +% \texttt{\textbackslash leftmargin} depends on the depth of the \quo/ +% environment, i.\,e. nested quotes will feature smaller indentation by +% default.} +% +% \item[rightmargin]\SpecialOptIndex{rightmargin} The width of the +% environment's right-hand indentation relative to the surrounding text. +% By default, \textsf{rightmargin} matches \textsf{leftmargin}. +% +% \item[vskip]\SpecialOptIndex{vskip} The vertical space before and +% after a \quo/ environment. The default value is the sum of |\topsep| +% and |\partopsep|. +% +% \item[listvskip]\SpecialOptIndex{listvskip} A boolean option that, if +% enabled, adjusts \quo/'s vertical spacing to that of list environments +% (and ignores \textsf{vskip} in the process). +% +% \item[noorphanfirst]\SpecialOptIndex{noorphanfirst} A boolean option +% that controls whether orphans are prohibited in the first paragraph of +% a \quo/ environment. +% +% \item[noorphanafter]\SpecialOptIndex{noorphanafter} A boolean option +% that controls whether orphans are prohibited directly after a \quo/ +% environment. +% +% \item[noorphans]\SpecialOptIndex{noorphans} A shortcut boolean option +% enabling both \textsf{noorphanfirst} and \textsf{noorphanafter}. +% +% \end{description} +% +% \DescribeMacro{\quotingsetup} +% The command |\quotingsetup|, which takes a comma-separated list of +% key--value options as argument, allows to change the attributes of the +% \quo/ environment mid-document. +% +% \DescribeMacro{\quotingfont} +% The options \textsf{font} and \textsf{font+} do not accept values +% which itself take an argument. In such cases you must resort to +% redefining the command |\quotingfont|, e.\,g. by including +% |\renewcommand*{\quotingfont}{\setstretch{1.5}}| in your document +% preamble (with the \textsf{setspace} package loaded). +% +% \StopEventually{% +% +% \bibliographystyle{plain} +% +% \begin{thebibliography}{9} +% +% \bibitem{Bra09} +% Braams, Johannes, David Carlisle, Alan Jeffrey, Leslie Lamport, +% Frank Mittelbach, Chris Rowley, and Rainer Sch\"opf. +% \emph{The \LaTeXe\ sources}. +% 2009/09/24. +% \url{http://www.tug.org/texlive/Contents/live/texmf-dist/doc/latex/base/source2e.pdf} +% (accessed August 2, 2011). +% +% \bibitem{Fis95} +% Fischel, William~A. +% \emph{Regulatory takings: Law, economics, and politics}. +% Cambridge, \textsc{ma}: Harvard University Press, 1995. +% +% \bibitem{Kop04} +% Kopka, Helmut and Patrick~W. Daly. +% \emph{Guide to \LaTeX}. 4\textsuperscript{th} edition. +% Boston: Addison-Wesley, 2004. +% +% \bibitem{Kot11} +% Kottwitz, Stefan. +% \emph{\LaTeX\ beginner's guide}. +% Birmingham: Packt Publishing, 2011. +% +% \bibitem{Lam94} +% Lamport, Leslie. +% \emph{\LaTeX: A document preparation system}. +% 2\textsuperscript{nd} edition. +% Boston: Addison-Wesley, 1994. +% +% \bibitem{Oet11} +% Oetiker, Tobias, Hubert Partl, Irene Hyna, and Elisabeth Schlegl. +% \emph{The not so short introduction to \LaTeXe}. +% Version 5.01, April 6, 2011. +% \url{http://mirror.ctan.org/info/lshort/english/lshort.pdf} +% (accessed August 2, 2011). +% +% \end{thebibliography} +% +% \PrintIndex +% \PrintChanges +% +% } +% +% \section{The package code} +% +% Announce the name and version of the package, which requires \LaTeXe. +% \begin{macrocode} +\NeedsTeXFormat{LaTeX2e} +\ProvidesPackage{quoting} + [2011/08/08 v0.1 Consolidated environment for displayed text] +% \end{macrocode} +% We require the packages \textsf{kvoptions} (to conveniently specify +% options as key--value pairs) and \textsf{etoolbox} (e.\,g. for length +% assignments and boolean switch handling). +% \begin{macrocode} +\RequirePackage{etoolbox,kvoptions} +% \end{macrocode} +% We use \texttt{quo@} as a short prefix to internal macros defined by +% \textsf{kvoptions}. +% \begin{macrocode} +\SetupKeyvalOptions{family=quo,prefix=quo@} +% \end{macrocode} +% \begin{macro}{\quotingfont} +% The \textsf{keyval} command |\define@key| is used to define the keys +% \textsf{font} and \textsf{font+}. We convert their value to a command +% and use this command to define |\quotingfont| resp. to append its +% definition. +% \begin{macrocode} +\newcommand*{\quotingfont}{} +\define@key{quo}{font}{% + \def\quotingfont{\csname #1\endcsname}% +} +\define@key{quo}{font+}{% + \appto{\quotingfont}{\csname #1\endcsname}% +} +% \end{macrocode} +% \end{macro} +% \begin{macro}{\quo@leftmargin} +% \begin{macro}{\quo@rightmargin} +% We use \textsf{kvoptions} to define the keys \textsf{leftmargin} and +% \textsf{rightmargin} and to set their default values. +% \begin{macrocode} +\DeclareStringOption[\leftmargin]{leftmargin} +\DeclareStringOption[\quo@leftmargin]{rightmargin} +% \end{macrocode} +% \end{macro} +% \end{macro} +% \begin{macro}{\quo@toppartop} +% \begin{macro}{\quo@vskip} +% The length |\quo@toppartop| is set to the sum of |\topsep| and +% |\partopsep| and used as the default value of the key \textsf{vskip}. +% \begin{macrocode} +\newlength{\quo@toppartop} +\deflength{\quo@toppartop}{\topsep + \partopsep} +\DeclareStringOption[\quo@toppartop]{vskip} +% \end{macrocode} +% \end{macro} +% \end{macro} +% We define the boolean options \textsf{listvskip}, +% \textsf{noorphanfirst}, and \textsf{noorphanafter}. +% \begin{macrocode} +\DeclareBoolOption{listvskip} +\DeclareBoolOption{noorphanfirst} +\DeclareBoolOption{noorphanafter} +% \end{macrocode} +% The shortcut boolean option \textsf{noorphans} will pass its value to +% |quo@noorphanfirst| and |quo@noorphanafter|. We then process our +% options. +% \begin{macrocode} +\define@key{quo}{noorphans}[true]{% + \setbool{quo@noorphanfirst}{#1}% + \setbool{quo@noorphanafter}{#1}% +} +\ProcessKeyvalOptions* +% \end{macrocode} +% \begin{macro}{\quotingsetup} +% We define |\quotingsetup| as an alias of |\setkeys{quo}|. +% \begin{macrocode} +\newcommand*{\quotingsetup}[1]{\setkeys{quo}{#1}} +% \end{macrocode} +% \end{macro} +% The boolean switch |quo@afterquo| stores whether we are immediately +% (without a paragraph in between) following a \quo/ environment; the +% |quo@afterquoclub| switch stores whether an orphan is permitted after +% the environment. (For the latter task, we don't use +% |quo@noorphanafter| directly because its state needs to be forwarded +% outside the group established by the current environment.) +% \begin{macrocode} +\newbool{quo@afterquo} +\newbool{quo@afterquoclub} +% \end{macrocode} +% \begin{macro}{\quo@doendquoclub} +% If the |quo@afterquoclub| switch is set to false, |\quo@doendquoclub| +% will set |\clubpenalty| to 10\,000. It will restore |\everypar| and +% the default value of |\clubpenalty| in the next paragraph. +% \begin{macrocode} +\newcommand*{\quo@doendquoclub}{% + \ifbool{quo@afterquoclub}{% + \clubpenalty=\@clubpenalty + \everypar{}% + }{% + \booltrue{quo@afterquoclub}% + \clubpenalty=\@M + }% +} +% \end{macrocode} +% \end{macro} +% \begin{macro}{\quo@doendquo} +% The macro |\quo@doendquo| is an extended version of the \LaTeX\ kernel +% macro |\@doendpe|. In the original, +% \blockcquote[p.~227]{Bra09}{\textins*{t}o suppress the paragraph +% indentation in text immediately following a paragraph-making +% environment, \texttt{\textbackslash everypar} is changed to remove the +% space, and \texttt{\textbackslash par} is redefined to restore +% \texttt{\textbackslash everypar}.} |\quo@doendquo| adds the following +% changes to |\par|/|\everypar| over and above |\@doendpe|: +% \begin{itemize} +% +% \item |\quo@doendquoclub| is executed; +% +% \item At the end, the |quo@afterquo| switch is globally set to false. +% +% \end{itemize} +% \begin{macrocode} +\newcommand*{\quo@doendquo}{% + \booltrue{@endpe}% + \def\par{% + \@restorepar + \everypar{\quo@doendquoclub}% + \par + \boolfalse{@endpe}% + \global\boolfalse{quo@afterquo}% + }% + \everypar{% + {\setbox\z@\lastbox}% + \quo@doendquoclub + \boolfalse{@endpe}% + \global\boolfalse{quo@afterquo}% + }% +} +% \end{macrocode} +% \end{macro} +% \begin{environment}{quoting} +% The definition of the \quo/ environment includes an optional argument +% which may be used to change package settings locally. +% \begin{macrocode} +\newenvironment{quoting}[1][]{% + \setkeys{quo}{#1}% +% \end{macrocode} +% \end{environment} +% We start a \textsf{list} environment and (unless the boolean switch +% \textsf{listvskip} is set to true) use the value of \textsf{vskip} for +% vertical spacing. +% \begin{macrocode} + \list{}{% + \ifbool{quo@listvskip}{% + }{% + \setlength{\topsep}{\quo@vskip}% + \setlength{\partopsep}{\z@}% + }% +% \end{macrocode} +% The length |\itemindent| is responsible for the first-line indentation +% of \quo/. |\itemindent| will be set to |\parindent| if the following +% conditions are met: +% \begin{itemize} +% +% \item We are in vertical mode (which usually means that a blank line +% or a |\par| command is present before the environment~-- but see +% below); +% +% \item The boolean switch |quo@afterquo| is set to false (i.\,e., +% vertical mode does not stem from a preceding \quo/ environment of the +% same depth); +% +% \item The \LaTeX\ kernel switch |@nobreak| is either set to false (the +% \quo/ environment does not directly follow a sectioning command), or +% both |@nobreak| and |@afterindent| are set to true. +% +% \end{itemize} +% Otherwise, |\itemindent| will be set to 0\,pt. +% \begin{macrocode} + \setlength{\itemindent}{% + \ifbool{vmode}{% + \ifbool{quo@afterquo}{% + \z@ + }{% + \ifbool{@nobreak}{% + \ifbool{@afterindent}{% + \parindent + }{% + \z@ + }% + }{% + \parindent + }% + }% + }{% + \z@ + }% + }% +% \end{macrocode} +% The lengths |\leftmargin|, |\rightmargin|, |\listparindent|, and +% |\parsep| are set, the latter two in accordance with the settings for +% normal running text. +% \begin{macrocode} + \setlength{\leftmargin}{\quo@leftmargin}% + \setlength{\rightmargin}{\quo@rightmargin}% + \setlength{\listparindent}{\parindent}% + \setlength{\parsep}{\parskip}% + }% +% \end{macrocode} +% We issue the necessary |\item| command, disable orphans in the +% environment's first paragraph when indicated, and switch to +% |\quotingfont|. (With regard to orphans, we make use of |\@item|'s +% internal mechanism to prevent orphans directly after sectioning +% commands \cite[p.~229]{Bra09}.) +% \begin{macrocode} + \item\relax + \ifbool{quo@noorphanfirst}{% + \global\booltrue{@nobreak}% + }{% + }% + \quotingfont +% \end{macrocode} +% At the end of \quo/, the following actions are taken: +% \begin{itemize} +% +% \item The \LaTeX\ kernel switch |@endpe| is set to false (so that +% |\@doendpe| won't be executed); +% +% \item The state of the |quo@noorphanafter| switch is forwarded outside +% the current group (using \TeX\ syntax); +% +% \item |quo@afterquo| is globally set to true; +% +% \item |\quo@doendquo| is executed after the current group. +% +% \end{itemize} +% \begin{macrocode} +}{% + \endlist + \boolfalse{@endpe}% + \ifbool{quo@noorphanafter}{% + \aftergroup\quo@afterquoclubfalse + }{% + \aftergroup\quo@afterquoclubtrue + }% + \global\booltrue{quo@afterquo}% + \aftergroup\quo@doendquo +} +% \end{macrocode} +% The end of the package. +% \begin{macrocode} +\endinput +% \end{macrocode} +% +% \Finale +\endinput diff --git a/Master/texmf-dist/source/latex/quoting/quoting.ins b/Master/texmf-dist/source/latex/quoting/quoting.ins new file mode 100644 index 00000000000..a3bfa8d0751 --- /dev/null +++ b/Master/texmf-dist/source/latex/quoting/quoting.ins @@ -0,0 +1,52 @@ +%% +%% This is file `quoting.ins'. +%% +%% Copyright (C) 2011 by Thomas Titz +%% +%% Permission is granted to distribute and/or modify this work under the +%% terms of the LaTeX Project Public License (LPPL), version 1.3c or +%% later. +%% +%% The LPPL maintenance status of this work is "maintained". +%% +%% This work consists of the files quoting.dtx, quoting.ins and README +%% and the derived files quoting.pdf and quoting.sty. +%% +\input docstrip.tex +\keepsilent + +\usedir{tex/latex/quoting} + +\preamble + +Copyright (C) 2011 by Thomas Titz + +Permission is granted to distribute and/or modify this work under the +terms of the LaTeX Project Public License (LPPL), version 1.3c or +later. + +The LPPL maintenance status of this work is "maintained". + +This work consists of the files quoting.dtx, quoting.ins and README +and the derived files quoting.pdf and quoting.sty. + +\endpreamble + +\generate{\file{quoting.sty}{\from{quoting.dtx}{package}}} + +\obeyspaces +\Msg{****************************************************} +\Msg{* *} +\Msg{* To finish the installation you have to move the *} +\Msg{* following file into a directory searched by TeX: *} +\Msg{* *} +\Msg{* quoting.sty *} +\Msg{* *} +\Msg{* To produce the documentation run the file *} +\Msg{* quoting.dtx through LaTeX. *} +\Msg{* *} +\Msg{* Happy TeXing! *} +\Msg{* *} +\Msg{****************************************************} + +\endbatchfile -- cgit v1.2.3