summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/colophon/colophon.dtx
blob: 557b8c161e73c1ea417d24a01cd749f1430ed758 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
% \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