path: root/macros/latex/contrib/quotchap/quotchap.dtx

% \iffalse meta-comment
%
% This file is part of the QUOTCHAP package, a package for creating
% decorative chapter headings with quotations, a postscript output
% device is needed.
% Copyright (C) 1998 - 2010 Karsten Tinnefeld.
% Copyright (C) 2011 - 2020 Jan Klever.
%
% This file is NOT part of the LaTeX2e system, but intended for use with it.
%
% This document is free software; you can redistribute it and/or modify it
% under the terms of the GNU Library General Public License as published by
% the Free Software Foundation; either version 2 of the License, or (at your
% option) any later version.
%
% This document is distributed in the hope that it will be useful, but WITHOUT
% ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
% FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
% more details.
%
% You should have received a copy of the GNU General Public License somehow;
% if not, write to the Free Software Foundation, Inc., 675 Mass Ave,
% Cambridge, MA 02139, USA.
%
% INSTALLATION:
%%%%%%%%%%%%%%%
%
% Install this style by running the file `quotchap.ins' through' TeX. This will
% create the file `quotchap.sty' and, if your docstrip.cfg is set up the right
% way (has a \BaseDirectory{<path to my texmf directory>}, see the
% docstrip-documentation), automatically moved to \$TEXMF/tex/latex/misc.
%
% The documentation is created by running `latex quotchap.dtx`. This
% does not need the file quotchap.sty nor postscript fonts, but Frank
% Mittelbach's multicol package should exist.
%
\NeedsTeXFormat{LaTeX2e}[1996/12/01]
%<*dtx>
\ProvidesFile{quotchap.dtx}
%</dtx>
%<!driver>\ProvidesPackage{quotchap}
%<driver>\ProvidesFile{quotchap.drv}
%  \fi
%  \ProvidesFile{quotchap.dtx}
  [2020/11/13 v1.3 Decorative Chapter Headings with Quotes]
%
% \iffalse
%<*driver>
\documentclass{ltxdoc}
\usepackage{multicol}
\GetFileInfo{quotchap.dtx}
\newcommand*{\docdate}{2020/11/13}
\RecordChanges
\begin{document}
  \DocInput{\filename}
\end{document}
%</driver>
% \fi
%
%  \CheckSum{210}
%
%  \DoNotIndex{\@M,\@afterindentfalse,%
%    \@topnum,\advance,\AtEndOfPackage,\baselineskip,\begin,\bigskip,%
%    \c@secnumdepth,%
%    \cleardoublepage,\clearpage,\color,\copy,\CurrentOption,\DeclareOption,%
%    \def,%
%    \definecolor,\edef,\else,\end,\fi,\fontsize,\footnotesize,%
%    \global,\hbox,\huge,\@ifundefined,\if@mainmatter,\if@openright,%
%    \IfFileExists,\ifnum,\ignorespacesafterend,%
%    \ignorespaces,\interlinepenalty,\leftmargin,\let,\m@ne,%
%    \MessageBreak,\newcommand,\newenvironment,\newif,\newsavebox,%
%    \nobreak,\PackageError,\PackageWarning,\par,\ProcessOptions,%
%    \providecommand,\qquad,%
%    \raggedleft,\relax,\renewcommand,\RequirePackage,\secdef,\selectfont,%
%    \setbox,\slshape,\smallskip,\thechapter,\thispagestyle,\unskip,%
%    \upshape,\usefont,\vbox,\vspace,\vss,\verb,\z@}
%
%  \date{printed \today}
%  \title{The \texttt{quotchap} package\thanks{%
%      This file has version number \fileversion,
%      last revised on \filedate, documentation dated \docdate.}}
%  \author{Karsten Tinnefeld\thanks{%
%      Thanks to Stefan Mintert for the chapter number layout
%      idea basing on his \protect\textsf{iNA}\protect\texttt{book}
%      class.}\and Jan Klever\\\texttt{jasa.klever@gmx.de}}
%  \maketitle
%
%  \begin{abstract}
%    This document describes the \texttt{quotchap} package. This package
%    redefines the |\chapter| and |\chapter*| commands to
%    create fancy chapter head pages with huge chapter numbers
%    (possibly greyed) and provides commands for adding quotations in the
%    upper left corner of these pages. It was written by Karsten Tinnefeld,
%    who abandoned to work on it. This package is now maintained by Jan Klever.
%  \end{abstract}
%
%  \section{Introduction}
%
%  \texttt{quotchap} is designed to do visual formatting and build some fancy
%  and attractive chapter headings for documents. It buries the original
%  |\chapter|[|*|]-commands to provide a new style: Chapter number and title
%  are set flush right, on separate lines, and much huger as normal: The title
%  is to be |\Huge|, the number is set in $100$pt size, and possibly in $60\%$
%  grey (not to blacken the page more than necessary). This means, of course,
%  that some scalable font had to be chosen.  We offer package options for all the
%  postscript fonts in the \textsc{psnfss} package and some other common fonts,
%  defaulting to Adobe's Bookman for matters of personal taste. You can choose
%  any font for the chapter number by using the command |\qsetcnfont|.
%
%  \section{Quotations}
%
%  This package provides the feature to include some quotations right before
%  the beginning of the chapter. An environment is given to save quotes to be
%  used at the beginning of the next chapter, and an additional command gives
%  an easy way to provide author information to the quotes.
%
%  \DescribeEnv{savequote}
%  The |savequote| environment should appear at the top level, not in
%  the document's preamble (i.e., after |\begin{document}|) and before
%  the start of the chapter you want to decorate. It has one optional
%  argument that provides the width
%  of the quotation paragraph. The default is $10$cm (approx.
%  $3.94$in). Possibly you may want to set your quote in ``quotation
%  marks'', as these marks differ from country to country, it is left
%  to you.
%
%  \DescribeMacro{qauthor}
%  Each quotation can consist of several paragraphs, but must end with
%  a |\qauthor{A. U. Thor}| command. This is not only provided to
%  uphold the principles of ``honour whom honour is due'' but to provide
%  the right author name formatting and inter quotation spacing. The
%  quotes can follow each other immediately.
%
%  The whole bunch of quotation is deleted after it has been printed
%  once, so you have to rewrite them when you find no way past
%  repeating them. When you give no quotations for some chapter, the
%  upper left area of the corresponding page will be simply void.
%
%  \DescribeMacro{qsetcnfont}
%  If you want to use a font for the chapter number, that is not
%  available as package optionen, you can set it with
%  |\qsetcnfont{<family>}|. For example: |\qsetcnfont{pzc}|
%  to use Zapf Chancery.
%
%  \DescribeMacro{quotefont}
%  The font for quotations can be set globally with |\quotefont|. For
%  example: |\renewcommand\quotefont{\sffamily\slshape}|. The default
%  is |\slshape|.
%
%  \DescribeMacro{qauthorfont}
%  The font for the author of the quote can be set globally with
%  |\qauthorfont|. For example: |\renewcommand\qauthorfont{\scshape}|.
%  The default ist |\upshape|.
%  \section{Examples}
%
%  Let's take a look at an example:\medskip
%
%  \begin{multicols}{2}
%    \begin{verbatim}
%\begin{savequote}[45mm]
%  ---When shall we three meet again
%  in thunder, lightning, or in rain?
%
%  ---When the hurlyburly's done,
%  when the battle's lost and won.
%  \qauthor{Shakespeare, Macbeth}
%  Cookies! Give me some cookies!
%  \qauthor{Cookie Monster}
%\end{savequote}
%
%\chapter{Classic Sesame Street}
%    \end{verbatim}
%
%  \vfill
%  \begin{minipage}[t]{45mm}\footnotesize\slshape
%      ---When shall we three meet again
%    in thunder, lightning, or in rain?
%
%    ---When the hurlyburly's done,
%    when the battle's lost and won.\par\smallskip
%    {\raggedleft\upshape
%     Shakespeare, Macbeth\qquad\hbox{}\par}\bigskip
%    Cookies! Give me some cookies!\par\smallskip
%    {\raggedleft\upshape
%     Cookie Monster\qquad\hbox{}\par}
%  \end{minipage}\bigskip
%
%  \noindent (chapter start page not demonstrated---try for yourself.)
%  \vfill
%  \end{multicols}
%
%  \section{Document Options}
%    Printing the chapter number in bold and that big a font uses quite
%    some ink on the paper. Thus it is strongly recommended to
%    use the \textbf{grey} option (which is enabled by default and
%    disabled by specifying \textbf{nogrey}) that improves the quality by
%    printing the number in $60\%$ grey. The \texttt{color} package is used to
%    set the colour |chaptergrey|, redefining this colour may produce even more
%    colourful effects.
%
%    The \texttt{color} package is |\Require|d without any option, if
%    you want to specify some, include the color package before the
%    quotchap package.
%
%    The other options are used to select a title font, they are all
%    self-explaining and thus simply listed here:
%    \begin{description}
%    \item[avantgarde] Adobe's Avantgarde
%    \item[beramono] Bera Mono
%    \item[berasans] Bera Sans
%    \item[beraserif] Bera Serif
%    \item[biolinum] Biolinum
%    \item[bookman] Adobe's Bookman (default)
%    \item[charter] Bitstream's Charter BT
%    \item[courier] Adobe's Courier
%    \item[helvetica] Adobe's Helvetica
%    \item[kpfonts] Kp-Fonts
%    \item[libertine] Libertine
%    \item[lmodern] Latin Modern
%    \item[newcentury] Adobe's New Century Schoolbook
%    \item[palatino] Adobe's Palatino
%    \item[times] Adobe's Times
%    \item[utopia] Adobe's Utopia
%    \end{description}
%
%  \StopEventually{}
%
%  \section{Implementation}
%
%  Ok, here comes the code.
%
%  \subsection{Option parsing}
%  The first part is about parsing the options. We may not
%  |\RequirePackage|s in here and thus define a flag: |@usecolor| is
%  true whenever the \textbf{grey} option is specified.
%
%    \begin{macrocode}
\newif\if@usecolor\@usecolortrue
\DeclareOption{grey}{\@usecolortrue}
\DeclareOption{nogrey}{\@usecolorfalse}
%    \end{macrocode}
%
%  For the fonts, there follows a bunch of options that are all meant
%  to be specified exclusively. It would have been possible to use
%  |\newcommand| to ensure this, but it gives cryptic errors. Rather
%  check this first.
%
%    \begin{macrocode}
\newcommand*{\@newfontcmd}{\@ifundefined{@defaultcnfont}{\newcommand*}{%
    \PackageWarning{quotchap}{%
      You have tried to specify more than one font to be\MessageBreak
      used for the chapter numbers. I ignore the font\MessageBreak
      `\CurrentOption'}
    \providecommand*}}
%    \end{macrocode}
%
%  Next is defining the font options. We set |\@defaultcnfont|
%  according to Karl Berry's font name scheme. Providing more than one
%  font gives an error (due to defining an already defined command);
%  the options exclude each other.
%
%    \begin{macrocode}
\DeclareOption{avantgarde}{\@newfontcmd{\@defaultcnfont}{pag}}
\DeclareOption{beramono}{\@newfontcmd{\@defaultcnfont}{fvm}}
\DeclareOption{berasans}{\@newfontcmd{\@defaultcnfont}{fvs}}
\DeclareOption{beraserif}{\@newfontcmd{\@defaultcnfont}{fve}}
\DeclareOption{biolinum}{\@newfontcmd{\@defaultcnfont}{LinuxBiolinumO-LF}}
\DeclareOption{bookman}{\@newfontcmd{\@defaultcnfont}{pbk}}
\DeclareOption{charter}{\@newfontcmd{\@defaultcnfont}{bch}}
\DeclareOption{courier}{\@newfontcmd{\@defaultcnfont}{pcr}}
\DeclareOption{helvetica}{\@newfontcmd{\@defaultcnfont}{phv}}
\DeclareOption{kpfonts}{\@newfontcmd{\@defaultcnfont}{jkp}}
\DeclareOption{libertine}{\@newfontcmd{\@defaultcnfont}{LinuxLibertineO-LF}}
\DeclareOption{lmodern}{\@newfontcmd{\@defaultcnfont}{lmr}}
\DeclareOption{newcentury}{\@newfontcmd{\@defaultcnfont}{pnc}}
\DeclareOption{palatino}{\@newfontcmd{\@defaultcnfont}{ppl}}
\DeclareOption{times}{\@newfontcmd{\@defaultcnfont}{ptm}}
\DeclareOption{utopia}{\@newfontcmd{\@defaultcnfont}{put}}
%    \end{macrocode}
%
%  We can now let the options be processed. If no postscript font has
%  been specified, the default is Adobe's Bookman.
%
%    \begin{macrocode}
\ProcessOptions\relax
\providecommand*{\@defaultcnfont}{pbk}
%    \end{macrocode}
%
%  If nobody said \textbf{nogrey}, we fetch the |color| package and
%  define our colour. If the color package is not included until now,
%  we define |\color| to do nothing but gobble up its argument.
%  An error is issued when \textbf{grey} is turned on and the color
%  package is nonexistent. When you read the documentation because of
%  this: \texttt{color.sty} is included in the graphics bundle to be
%  found at \textsc{ctan}.
%
%    \begin{macrocode}
\if@usecolor
  \IfFileExists{color.sty}{%
    \RequirePackage{color}
    \definecolor{chaptergrey}{rgb}{0.6,0.6,0.6}}{%
    \PackageError{quotchap}{%
      The color package is apparently unavailable.\MessageBreak
      Turn off the `grey' option and come back again}{%
      Since you did not say `nogrey', quotchap defined chapter
      numbers to appear\MessageBreak grey. You do not need a color
      printer, since most printing devices can cope\MessageBreak with
      grey scales, but you need the color package coming with the
      graphics\MessageBreak bundle available from CTAN.}}
\else
  \providecommand*{\color}[1]{}
\fi
%    \end{macrocode}
%
%  Now we are ready to give the final font declarations. The
%  commands |\sectfont| and
%  |\chapterhead|\{|start|\textbar|end|\}|vskip| are defined in the
%  \textsf{KOMA-Script} classes the chapter is based on,
%  they are provided in case |quotchap| is used with other, e.g.
%  the default classes. If we are building a report, there is no
%  |\frontmatter|, |\mainmatter| and |\backmatter| resp. everything is
%  |\mainmatter|, thus we have to provide the corresponding switch
%  used in the |\chapter| command.
%
%    \begin{macrocode}
\AtEndOfPackage{%
  \newcommand*{\chapnumfont}{%
    \usefont{\f@encoding}{\@defaultcnfont}{b}{n}\fontsize{100}{130}\selectfont%
    \color{chaptergrey}}
  \let\size@chapter\huge
  \providecommand*{\chapterheadstartvskip}{\vspace*{2.3\baselineskip}}
  \providecommand*{\chapterheadendvskip}{\vspace{1.7\baselineskip}}
  \providecommand*{\sectfont}{\relax}
  \providecommand*{\quotefont}{\slshape}
  \providecommand*{\qauthorfont}{\upshape}
  \@ifundefined{@mainmattertrue}{\newif\if@mainmatter\@mainmattertrue}{}}
%    \end{macrocode}
%
%  \subsection{User Level Commands}
%
%  \begin{macro}{savequote}
%    Here go the top level command declarations (and definitions, too).
%    We use the |lrbox| environment to save the contents of the whole
%    environment in a horizontal box. The quotes are effectively a
%    paragraph box typeset in footnote size and oblique style, to the
%    width given as a parameter, while any spacing at the beginning
%    and the end of the environment is ignored. Since
%    |\newenvironment| implies a group, we have to make the box
%    |\@quotebox| global explicitly.
%
%    Finally, we enable the box insertion command that is disabled
%    initially and after each chapter heading. (Possibly it is faster
%    to delete the save box contents and insert a nearly-empty vertical
%    box at each chapter---profilers to the front.)
%
%    \begin{macrocode}
\newenvironment{savequote}[1][10cm]{%
  \begin{lrbox}{\@quotebox}
    \begin{minipage}[t]{#1}\footnotesize\quotefont
      \ignorespaces}{%
      \unskip\end{minipage}\end{lrbox}
  \global\setbox\@quotebox\copy\@quotebox
  \global\let\@printcites\@iprintcites
  \ignorespacesafterend}
%    \end{macrocode}
%  \end{macro}
%
%  \begin{macro}{\qauthor}
%    The |\qauthor| command simply selects some font and
%    skip---lets the name be set in roman letters and flush right at
%    two ems distance from the margin.
%
%    \begin{macrocode}
\newcommand{\qauthor}[1]{%
  \par\smallskip
  {\raggedleft\qauthorfont #1\qquad\hbox{}\par}\bigskip}
%    \end{macrocode}
%  \end{macro}
%
%  \begin{macro}{\qsetcnfont}
%    The user can set any font for the chapter number by providing its family
%    name to this command.
%    \begin{macrocode}
\newcommand{\qsetcnfont}[1]{%
    \renewcommand*{\@defaultcnfont}{#1}}
%    \end{macrocode}
%  \end{macro}
%
%  \subsection{Making up the chapter heading}
%
%  Here are the modification to the chapter command definitions of
%  the \textsf{KOMA-Script} document classes. This package was
%  originally designed to
%  co-operate only with them; therefore we have to provide some
%  measurement defined only there. We insert the citations (if available)
%  by calling the insert box or do nothing wrapper.
%
%  The second modification is the formatting of the heading. If there
%  is a chapter number to be printed, our really huge font is selected
%  and the number is typeset to the right margin, followed by the
%  title, as usual.
%
%    \begin{macrocode}
\newsavebox{\@quotebox}
\let\@printcites\relax
\renewcommand\chapter{%
  \if@openright\cleardoublepage\else\clearpage\fi
  \thispagestyle{plain}%
  \global\@topnum\z@
  \@printcites
  \@afterindentfalse
  \secdef\@chapter\@schapter}
\renewcommand{\@makechapterhead}[1]{\chapterheadstartvskip%
  {\size@chapter{\sectfont\raggedleft
      {\chapnumfont
        \ifnum \c@secnumdepth >\m@ne%
        \if@mainmatter\thechapter%
        \fi\fi
        \par\nobreak}%
      {\raggedleft\advance\leftmargin10em\interlinepenalty\@M #1\par}}
    \nobreak\chapterheadendvskip}}
\renewcommand{\@makeschapterhead}[1]{%
  {\let\c@secnumdepth\m@ne\@makechapterhead{#1}}}
\newcommand*{\@iprintcites}{%
  \vbox to\z@{\copy\@quotebox\vss}
  \global\let\@printcites\relax}
%    \end{macrocode}
%
%  And this is it. Happy \TeX ing!
%
%\Finale
%
%% \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         \~}
%
%\endinput
%
% LocalWords:  QUOTCHAP quotchap sty docstrip cfg texmf EXMF tex misc dtx drv
% LocalWords:  multicol iNA tinnefeld irb cs uni dortmund de pt psnfss qauthor
% LocalWords:  savequote nogrey color chaptergrey xdvi BT palatino avantgarde
% LocalWords:  helvetica newcentury usecolor defaultcnfont bch ppl pag pbk pcr
% LocalWords:  phv pnc ptm ctan rgb vskip lrbox co em ing