path: root/Master/texmf-dist/source/latex/colophon/colophon.dtx

% \iffalse
% +AMDG  This document was begun on E October 11EE, the
% feast of the Maternity of the Blessed Virgin Mary, and it
% is humbly dedicated to her and to her Immaculate Heart for
% her prayers, and to the Sacred Heart of Jesus for His
% mercy.
%
% This document is copyright 2015 by Donald P. Goodman, and is
% released publicly under the LaTeX Project Public License.  The
% distribution and modification of this work is constrained by the
% conditions of that license.  See
% 	http://www.latex-project.org/lppl.txt
% for the text of the license.  This document is released
% under version 1.3c of that license, and this work may be distributed
% or modified under the terms of that license or, at your option, any
% later version.
% 
% This work has the LPPL maintenance status 'maintained'.
% 
% The Current Maintainer of this work is Donald P. Goodman
% (dgoodmaniii@gmail.com).
% 
% This work consists of colophon.dtx, colophon.ins, and
% derived files colophon.sty and colophon.pdf.
% \fi

% \iffalse
%<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
%<package>\ProvidesPackage{colophon}[2018/04/01 v1.1 Support for highly configurable colophons]
%<*driver>
\documentclass{ltxdoc}

\usepackage{doc}
\usepackage{array}
\usepackage{graphicx}
\usepackage{lettrine}
	\setcounter{DefaultLines}{3}
	\setlength{\DefaultFindent}{2pt}
	\renewcommand{\LettrineFontHook}{\color{red}}
\usepackage{url}
\usepackage{spverbatim}
\usepackage[typeone]{dozenal}
\usepackage{lmodern}
\usepackage[]{colophon}
\usepackage[colorlinks]{hyperref}
\usepackage{makeidx}
\EnableCrossrefs
\PageIndex
\CodelineNumbered
\RecordChanges
\makeindex
\DoNotIndex{\?,\{,\},\|,\DeclareFontFamily,\DeclareFontShape,
	\if,\else,\fi,\def,\divide,\clubpenalty,\widowpenalty,\ifdim,\fi,
	\ifnum,\fi, \ifx, \fi, \Huge, \Large, \LARGE, \begin, \end,
	\bfseries, \baselineskip, \begingroup,\endgroup,
	\jobname, \l@poem,\leftskip, \linewidth, \index,
	\@dottedtocline, \@firstoftwo, \@ifnextchar, \@starttoc,
	\addcontentsline, \advance, \everypar, \expandafter,
	\hangafter, \hangindent, \hbox, \hfil, \hsize, \hskip,
	\multiply, \linewidth, \llap, \blap, \rlap, \tlap,
	\makeindex, \newcommand, \newcount, \newcounter,
	\newdimen, \newif, \newlength, \noindent, \par,
	\parindent, \penalty, \ProvidesPackage, \relax,
	\RequirePackage, \setcounter, \setlength, \settowidth,
	\stepcounter, \textwidth, \the, \today, \value, \vbox,
	\vskip, \vss, \@afterheading, \@afterindentfalse,
	\bgroup, \egroup, \csname, \endcsname, \fontsize,
	\ProcessOptionsX, \DeclareOptionsX, \parfillskip,
	\rightskip, \vfil, \textheight, \thispagestyle, \scshape,
	\selectfont,
}

\long\def\example#1#2{%
	\bigskip%
	\hrule%
	\hbox to\linewidth{%
		\hbox to0.5\linewidth{%
			\vbox to2in{\vfil#1\vfil}%
		}\hbox to0.5\linewidth{%
			\vbox to2in{\vfil#2\vfil}%
		}%
	}%
	\hrule%
	\bigskip%
}

\tracingmacros=3
\begin{document}
\DocInput{colophon.dtx}
\end{document}
%</driver> \fi
%
% \title{The |colophon| Package, v1.1}
% \author{Donald P.\ Goodman III}
% \date{\today}
%
% \maketitle
%
% \begin{abstract}
% \noindent
% The \emph{colophon} is fascinating to anyone even slightly
% interested in typography and document design; and yet
% incredibly, the best document design system ever produced
% \emph{has no facilities for producing colophons}.  Hence,
% the |colophon| package.  
% \end{abstract}
%
% \tableofcontents
%
% \section{Introduction}
%
% Colophons date back to ancient times, where scribes would
% simply write in where they'd gotten the text that they'd
% copied, and what they'd changed in it.  One might see a
% colophon that read, \textit{A M.\ Tullio Cicerone, e texto
% G.\ Juliani C\ae{}saris, cum tribus libris novis} (``By
% Marcus Tullius Cicero, from a text of Gaius Julius
% Caesar, with three new books.''  Though why Cicero is
% adding to a book of Julius Caesar, and using a ``j'' long
% before it became a letter, is a mystery.)
%
% When printing was invented, publishers would add a
% colophon, often at the end (rather than at the beginning,
% where it typically sits now), noting their identities and
% addresses.  Over time, particularly with small publishers,
% colophons got bigger, and contained information about
% design, font types, and the like.  Too often they're
% completely omitted now, but I think it's still worth
% putting them in.  I know that I \emph{love} to see them in
% the books I read, at least.
%
% \section{Default Behavior}
%
% By default, |colophon| uses a very simple two-command
% structure that produces what I, personally, believe to be
% a well-formatted and attractive colophon.  We begin with
% the \DescribeEnv{colophon}|colophon| environment, which
% can be realized by the usual |\begin{colophon}| and
% |\end{colophon}| pairs.  The contents of the colophon
% itself will be put in between these two, and the spacing,
% page style, paragraph styling, and the like will all be
% taken care of in the way that I, personally, think looks
% best.
%
% If you don't like using environments, feel free to use
% \DescribeMacro{\colophon}|\colophon| to begin the colophon
% and \DescribeMacro{\endcolophon}|\endcolophon| to end it.
% That's how they were defined, and that's what the \LaTeX\
% environment creation macros produce anyway, so do as you
% will.  Using one or the other system produces no
% difference in functionality.
%
% By default, this produces a full-page colophon, printed
% after a |\cleardoublepage| has been executed (in other
% words, on the next available recto (odd-numbered) page.
% It does this with a centered heading, which will be the
% word ``Colophon''.  If you want it to have some other
% heading, tell the package so with
% \DescribeMacro{\colophontitle}|\colophontitle|.  E.g., if
% you want the title to be ``Stuff About the Book,'' run:
%
% \begin{quote}
% |\colophontitle{Stuff About the Book}|
% \end{quote}
%
% Alternatively, you can set the title with the |title|
% package option:
%
% \begin{quote}
% |\usepackage[title={Stuff About the Book}]{colophon}|
% \end{quote}
%
% The title will also be printed in |\scshape|,
% once again because I like it that way.  You can change
% that, too, with either the
% \DescribeMacro{\colophontitlestyle}|\colophontitlestyle|
% macro, or with the |titlestyle| package option.  Remember
% that you should \emph{not} use the backslash with your
% style command in the package option.  The following two
% lines are equivalent:
%
% \begin{quote}
% |\colophontitlestyle{\itshape}|\\
% |\usepackage[titlestyle=itshape]{colophon}|
% \end{quote}
%
% Give titlestyle no option if you just want normal roman
% type.
%
% There are similar options governing the size of the title,
% \DescribeMacro{\colophontitlesize}|\colophontitlesize| and
% the |titlesize| package option.  It takes a point size as
% an argument and sets both font size \emph{and} leading to
% that amount.  Since it seems unlikely the title will have
% more than one line, that seemed fine to me; if this breaks
% your use case, let me know, and I'll fix it.  The
% following two lines are equivalent:
%
% \begin{quote}
% |\colophontitlesize{60pt}|\\
% |\usepackage[titlesize=60pt]{colophon}|
% \end{quote}
%
% The default size is |48pt|.
%
% There will also be some space between the title and the
% colophon text.  This can be controlled with either the
% \DescribeMacro{\colophonmidspace}|\colophonmidspace|
% command, or the |aftertitle| package option.  The
% following two are equivalent:
%
% \begin{quote}
% |\colophonmidspace{3em}|\\
% |\usepackage[aftertitle=3em]{colophon}|
% \end{quote}
%
% By default, the colophon page will have pagestyle |empty|.
% To change this, use
% \DescribeMacro{\colophonpagestyle}|\colophonpagestyle| or
% the package option |pagestyle|.  The following two lines
% are equivalent:
%
% \begin{quote}
% |\colophonpagestyle{plain}|\\
% |\usepackage[pagestyle=plain]{colophon}|
% \end{quote}
%
% You can align the title centered, on the left, or on the
% right, by using
% \DescribeMacro{\colophontitlealign}|\colophontitlealign|,
% or the |titlealign| package option.  The options are |c|
% for centered (the default), |l| for left-aligned, and |r|
% for right-aligned.  The following two are
% equivalent:
%
% \begin{quote}
% |\colophontitlealign{c}|\\
% |\usepackage[titlealign=c]{colophon}|
% \end{quote}
%
% Finally, there are hooks before and after the title which
% should allow you to run whatever arbitrary code you'd like
% there.  By default, these are empty; but you can fill them
% with, for example, font-changing commands.  This spares
% the package the overhead of having to determine what font
% system you're using, and what engine, and lets you worry
% about all that.  The hooks are
% \DescribeMacro{\colophonpretitlehook}|\colophonpretitlehook|
% and
% \DescribeMacro{\colophonposttitlehook}|\colophonposttitlehook|.
% By default, both are empty; redefine them to whatever you
% need them to be.
%
% The actual texts of the colophon are governed by much the
% same parameters.  The macros simply have |par| rather than
% |title| in their names.  There are two additional ones,
% however, worth noting.  You can set:
%
% \begin{itemize}
%	\item \DescribeMacro{\colophonparstyle}|\colophonparstyle|,
%	which will govern the style of the text.  By default,
%	this is empty, yielding whatever your normal font style
%	is.  Its package option is |parstyle|; remember not to
%	use the backslash when setting it in the package options,
%	as with |titlestyle|.
%	\item \DescribeMacro{\colophonparsize}|\colophonparsize|,
%	which is the point size of the colophon text.  Its
%	package option is |parsize|.  By default, |15pt|.
%	\item \DescribeMacro{\colophonparlead}|\colophonparlead|,
%	which is the size of the leading of the colophon text
%	(that is, the distance from one baseline to the next
%	baseline down.  By default, |18pt|.  Its package option
%	is |parlead|.
%  \item \DescribeMacro{\colophonnofirstindent}|\colophonnofirstindent|,
%	turns off |colophon|'s default behavior of suppressing
%	the first indent after the title line.  Default is to
%	suppress the indent.  The package option is
%	|nofirstindent|.
%	\item \DescribeMacro{\colophonpreparhook}|\colophonpreparhook|
%	and its brother, 
%	\DescribeMacro{\colophonpostparhook}|\colophonpostparhook|,
%	allows arbitrary commands to be run before and after the
%	colophon text.  They do not have package option
%	equivalents.
%  \item Last but not least,
%  \DescribeMacro{\colophonparalign}|\colophonparalign|.
%  This takes more or less arbitrary commands, but it's
%  designed to permit what I think is a great stylistic
%  touch with colophons:  a fully justified paragraph, with
%  the final line containing equal space on either side.  By
%  default, it achieves this, and is set as follows:
%  \begin{quote}
%	|\leftskip=0pt plus.5fil%|\\
%	|\rightskip=0pt plus-.5fil%|\\
%	|\parfillskip=0pt plus1fil%|
%  \end{quote}
%	This does the trick.  If you don't like this, or want to
%	do something else with it, change it as you will.  This
%	also has no package option equivalent.
% \end{itemize}
%
% That gives the default settings.  If for some reason you
% do not want a full-page colophon (maybe you like it tucked
% into the bottom of the last page, for example, as was
% common long ago), use the
% \DescribeMacro{\colophonnofullpage}|\colophonnofullpage|
% macro, or the |nofullpage| package option.  Note, however,
% that this merely means the colophon won't take up a full
% page; it will still create a new page before it prints.
% To prevent it from clearing pages, use
% \DescribeMacro{\colophonnoclrdblpg}|\colophonnoclrdblpg|,
% or the package option |noclrdblpg|.  Both options together
% will allow you to tuck your colophon on the bottom of your
% last page.
%
% If you want the colophon to clear one page, but not a double
% page, use \DescribeMacro{\colophonclrpg}|\colophonclrpg|,
% or the package option |clrpg|.
%
% Note that, if the colophon is not clearing any pages, it
% will \emph{not} set the colophon page style, so
% |\colophonpagestyle| and the |pagestyle| package option
% will do nothing.
%
% Note also that, when you're not using a full page, if
% doesn't mean you can't have the colophon alone on the
% page; it just means that the colophon won't be vertically
% centered on the that page.  You can print your colophon,
% issue a |\newpage|, and have it on the page by itself but
% not vertically centered.  So to set the spaces above and
% below the colophon, use
% \DescribeMacro{\colophontopspace}|\colophontopspace| and
% its obviously-named brother,
% \DescribeMacro{\colophonbotspace}|\colophonbotspace|.
% Their package option equivalents are |topspace| and
% |botspace|, respectively.  These will insert the requested
% amount of space before and after the colophon, allowing
% you to format it however you like.
%
% \section{Examples}
%
% We've set up two examples, one of a full page and one of a
% partial page colophon, which will give a good idea of what
% the capabilities of the |colophon| package are.
%
% \begin{tabular}{>{\raggedright}m{0.5\textwidth}m{0.5\textwidth}}
% |\usepackage[%|
% |title={Design Information},|
% |titlestyle=scshape,|
% |titlesize=30pt,|
% |titlealign=c,|
% |parstyle=itshape,|
% |parsize=12pt,|
% |parlead=15pt|
% |]{colophon}| &
% \fbox{\includegraphics[scale=0.15]{fullpage_ex.pdf}} \\
% \end{tabular}
%
% Here, we've changed a lot of details, and unnecessarily
% specified |scshape| as our title style (that is the
% default, after all), but came up with the page shown
% above.
%
% \begin{tabular}{>{\raggedright}m{0.5\textwidth}m{0.5\textwidth}}
% |\usepackage[%|
% |title={Design Stuff},|
% |titlestyle=itshape,|
% |titlesize=24pt,|
% |titlealign=r,|
% |parstyle=upshape,|
% |parsize=10pt,|
% |parlead=11pt,|
% |noclrdblpg,|
% |nofullpage,|
% |topspace=2in|
% |]{colophon}| &
% \fbox{\includegraphics[scale=0.15]{partpage_ex.pdf}} \\
% \end{tabular}
%
% Here we've turned off the full page and clearing of a
% double page in order to tuck our colophon into the last
% part of the page.  The folio is still there, therefore
% (|colophon| doesn't change page styles unless it has its
% own page), in accordance with the rest of the document.
% We've also right-aligned our title, and adjusted our top
% space to stick it closer to the bottom of the page.
%
% Happy \TeX{}ing!
%
% \section{Implementation}
%
% The first thing we do is load |xkeyval|, so we can
% implement all those great package-loading options.
%    \begin{macrocode}
\RequirePackage{xkeyval}
%    \end{macrocode}
% We'll declare the options and process them later, after
% we've declared a bunch of |\if|s and other defaults.
% Which we get to next:  declaring all the new conditionals
% that we'll need, along with the functions that will enable
% us to alter them without mucking around with the
% |@|-containing internal commands.
%    \begin{macrocode}
\newif\ifclpn@clrpg\clpn@clrpgfalse%
	\def\colophonclrpg{\clpn@clrpgtrue}%
\newif\ifclpn@clrdblpg\clpn@clrdblpgtrue%
	\def\colophonnoclrblpg{\clpn@clrdblpgfalse}%
\newif\ifclpn@fullpage\clpn@fullpagetrue%
	\def\colophonnofullpage{\clpn@fullpagefalse}%
\newif\ifclpn@centertitle\clpn@centertitletrue%
\newif\ifclpn@lefttitle\clpn@lefttitlefalse%
\newif\ifclpn@righttitle\clpn@righttitlefalse%
%    \end{macrocode}
% The code for |\colophontitlealign| is necessarily more
% complex than the others, since it has to adjust the
% settings for multiple conditions.
%    \begin{macrocode}
\def\colophontitlealign#1{%
	\ifx#1c%
		\clpn@centertitletrue%
		\clpn@lefttitlefalse%
		\clpn@righttitlefalse%
	\fi
	\ifx#1l%
		\clpn@centertitlefalse%
		\clpn@lefttitletrue%
		\clpn@righttitlefalse%
	\fi
	\ifx#1r%
		\clpn@centertitlefalse%
		\clpn@lefttitlefalse%
		\clpn@righttitletrue%
	\fi
}%
\newif\ifclpn@nofirstindent\clpn@nofirstindenttrue%
	\def\colophonnofirstindent{\clpn@nofirstindentfalse}%
\def\clpn@overspace{0pt}%
	\def\colophontopspace#1{\def\clpn@overspace{#1}}%
\def\clpn@underspace{0pt}%
	\def\colophonbotspace#1{\def\clpn@underspace{#1}}%
\def\clpn@undertitle{2em}%
	\def\colophonmidspace#1{\def\clpn@undertitle{#1}}%
\def\clpn@pagestyle{empty}%
	\def\colophonpagestyle#1{\def\clpn@pagestyle{#1}}%
\def\clpn@titleword{Colophon}%
	\def\colophontitle#1{\def\clpn@titleword{#1}}%
\def\clpn@titlesty{\scshape}%
	\def\colophontitlestyle#1{\def\clpn@titlesty{#1}}%
\def\clpn@titlesize{48pt}%
	\def\colophontitlesize#1{\def\clpn@titlesize{#1}}%
\def\clpn@pretitle{}%
	\def\colophonpretitlehook#1{\def\clpn@pretitle{#1}}%
\def\clpn@posttitle{}
	\def\colophonposttitlehook#1{\def\clpn@posttitle{#1}}%
\def\clpn@parsty{}%
	\def\colophonparstyle#1{\def\clpn@parsty{#1}}%
\def\clpn@parsize{15pt}%
	\def\colophonparsize#1{\def\clpn@parsize{#1}}%
\def\clpn@parlead{18pt}%
	\def\colophonparlead#1{\def\clpn@parlead{#1}}%
\def\clpn@paralign{%
	\leftskip=0pt plus.5fil%
	\rightskip=0pt plus-.5fil%
	\parfillskip=0pt plus1fil%
}%
	\def\colophonparalign#1{\def\clpn@paralign{#1}}%
\def\clpn@prepar{}%
	\def\colophonpreparhook#1{\def\clpn@prepar{#1}}%
\def\clpn@postpar{}
	\def\colophonpostparhook#1{\def\clpn@postpar{#1}}%
%    \end{macrocode}
% As promised, we're now at the option-declaring stage.  We
% declare options for a everything that we can declare above
% (at least, reasonably), and finish by parsing them.  We
% have to do some shenanigans to get the style options to
% work, in order to insert backslashes, but this is
% relatively minor.
%    \begin{macrocode}
\DeclareOptionX{title}{\def\clpn@titleword{#1}}
\DeclareOptionX{titlestyle}{%
	\def\clpn@titlesty{\csname#1\endcsname}%
}%
\DeclareOptionX{titlesize}{\def\clpn@titlesize{#1}}
\DeclareOptionX{aftertitle}{\def\clpn@undertitle{#1}}
\DeclareOptionX{titlealign}{\colophontitlealign{#1}}
\DeclareOptionX{parstyle}{%
	\def\clpn@parsty{\csname#1\endcsname}%
}%
\DeclareOptionX{parsize}{\def\clpn@parsize{#1}}
\DeclareOptionX{parlead}{\def\clpn@parlead{#1}}
\DeclareOptionX{nofullpage}{\clpn@fullpagefalse}
\DeclareOptionX{noclrdblpg}{\clpn@clrdblpgfalse}
\DeclareOptionX{clrpg}{\clpn@clrpgtrue}
\DeclareOptionX{topspace}{\def\clpn@overspace{#1}}
\DeclareOptionX{botspace}{\def\clpn@underspace{#1}}
\DeclareOptionX{nofirstindent}{\clpn@nofirstindentfalse}
\ProcessOptionsX
%    \end{macrocode}
% And now we define the colophon itself, putting all the
% options above to good use.
%    \begin{macrocode}
\def\colophon{%
	\ifclpn@clrdblpg%
		\cleardoublepage%
		\thispagestyle{\clpn@pagestyle}%
	\fi%
	\ifclpn@clrpg%
		\clearpage%
		\thispagestyle{\clpn@pagestyle}%
	\fi%
	\ifclpn@fullpage%
		\vbox to\textheight\bgroup%
			\vfil%
	\fi%
	\vskip\clpn@overspace%
	\hbox to\linewidth{%
		\ifclpn@centertitle\hfil\fi%
		\ifclpn@righttitle\hfil\fi%
		\fontsize{\clpn@titlesize}{\clpn@titlesize}\selectfont%
		\clpn@titlesty%
		\clpn@pretitle%
		\clpn@titleword%
		\clpn@posttitle%
		\ifclpn@lefttitle\hfil\fi%
		\ifclpn@centertitle\hfil\fi%
	}%
	\vskip\clpn@undertitle%
	\bgroup%
	\clpn@parsty%
	\fontsize{\clpn@parsize}{\clpn@parlead}\selectfont%
	\clpn@prepar\clpn@paralign%
	\ifclpn@nofirstindent%
		\@afterindentfalse\@afterheading%
	\fi%
}%
%    \end{macrocode}
% Then, finally, we end the colophon.
%    \begin{macrocode}
\def\endcolophon{%
	\clpn@postpar%
	\par%
	\egroup%
	\vskip\clpn@underspace
	\ifclpn@fullpage%
		\vfil%
		\egroup%
	\fi
}%
%    \end{macrocode}
% And there's the |colophon| package.  I hope it proves
% useful to someone besides myself.  Happy \TeX{}ing!
%
% \PrintIndex