Debian Codegraph @

texmf-dist/source/latex/colophon/colophon.dtx

raw
1 % \iffalse
2 % +AMDG This document was begun on E October 11EE, the
3 % feast of the Maternity of the Blessed Virgin Mary, and it
4 % is humbly dedicated to her and to her Immaculate Heart for
5 % her prayers, and to the Sacred Heart of Jesus for His
6 % mercy.
7 %
8 % This document is copyright 2015 by Donald P. Goodman, and is
9 % released publicly under the LaTeX Project Public License. The
10 % distribution and modification of this work is constrained by the
11 % conditions of that license. See
12 % http://www.latex-project.org/lppl.txt
13 % for the text of the license. This document is released
14 % under version 1.3c of that license, and this work may be distributed
15 % or modified under the terms of that license or, at your option, any
16 % later version.
17 %
18 % This work has the LPPL maintenance status 'maintained'.
19 %
20 % The Current Maintainer of this work is Donald P. Goodman
21 % ([email protected]).
22 %
23 % This work consists of colophon.dtx, colophon.ins, and
24 % derived files colophon.sty and colophon.pdf.
25 % \fi
26
27 % \iffalse
28 %<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
29 %<package>\ProvidesPackage{colophon}[2018/04/01 v1.1 Support for highly configurable colophons]
30 %<*driver>
31 \documentclass{ltxdoc}
32
33 \usepackage{doc}
34 \usepackage{array}
35 \usepackage{graphicx}
36 \usepackage{lettrine}
37 \setcounter{DefaultLines}{3}
38 \setlength{\DefaultFindent}{2pt}
39 \renewcommand{\LettrineFontHook}{\color{red}}
40 \usepackage{url}
41 \usepackage{spverbatim}
42 \usepackage[typeone]{dozenal}
43 \usepackage{lmodern}
44 \usepackage[]{colophon}
45 \usepackage[colorlinks]{hyperref}
46 \usepackage{makeidx}
47 \EnableCrossrefs
48 \PageIndex
49 \CodelineNumbered
50 \RecordChanges
51 \makeindex
52 \DoNotIndex{\?,\{,\},\|,\DeclareFontFamily,\DeclareFontShape,
53 \if,\else,\fi,\def,\divide,\clubpenalty,\widowpenalty,\ifdim,\fi,
54 \ifnum,\fi, \ifx, \fi, \Huge, \Large, \LARGE, \begin, \end,
55 \bfseries, \baselineskip, \begingroup,\endgroup,
56 \jobname, \l@poem,\leftskip, \linewidth, \index,
57 \@dottedtocline, \@firstoftwo, \@ifnextchar, \@starttoc,
58 \addcontentsline, \advance, \everypar, \expandafter,
59 \hangafter, \hangindent, \hbox, \hfil, \hsize, \hskip,
60 \multiply, \linewidth, \llap, \blap, \rlap, \tlap,
61 \makeindex, \newcommand, \newcount, \newcounter,
62 \newdimen, \newif, \newlength, \noindent, \par,
63 \parindent, \penalty, \ProvidesPackage, \relax,
64 \RequirePackage, \setcounter, \setlength, \settowidth,
65 \stepcounter, \textwidth, \the, \today, \value, \vbox,
66 \vskip, \vss, \@afterheading, \@afterindentfalse,
67 \bgroup, \egroup, \csname, \endcsname, \fontsize,
68 \ProcessOptionsX, \DeclareOptionsX, \parfillskip,
69 \rightskip, \vfil, \textheight, \thispagestyle, \scshape,
70 \selectfont,
71 }
72
73 \long\def\example#1#2{%
74 \bigskip%
75 \hrule%
76 \hbox to\linewidth{%
77 \hbox to0.5\linewidth{%
78 \vbox to2in{\vfil#1\vfil}%
79 }\hbox to0.5\linewidth{%
80 \vbox to2in{\vfil#2\vfil}%
81 }%
82 }%
83 \hrule%
84 \bigskip%
85 }
86
87 \tracingmacros=3
88 \begin{document}
89 \DocInput{colophon.dtx}
90 \end{document}
91 %</driver> \fi
92 %
93 % \title{The |colophon| Package, v1.1}
94 % \author{Donald P.\ Goodman III}
95 % \date{\today}
96 %
97 % \maketitle
98 %
99 % \begin{abstract}
100 % \noindent
101 % The \emph{colophon} is fascinating to anyone even slightly
102 % interested in typography and document design; and yet
103 % incredibly, the best document design system ever produced
104 % \emph{has no facilities for producing colophons}. Hence,
105 % the |colophon| package.
106 % \end{abstract}
107 %
108 % \tableofcontents
109 %
110 % \section{Introduction}
111 %
112 % Colophons date back to ancient times, where scribes would
113 % simply write in where they'd gotten the text that they'd
114 % copied, and what they'd changed in it. One might see a
115 % colophon that read, \textit{A M.\ Tullio Cicerone, e texto
116 % G.\ Juliani C\ae{}saris, cum tribus libris novis} (``By
117 % Marcus Tullius Cicero, from a text of Gaius Julius
118 % Caesar, with three new books.'' Though why Cicero is
119 % adding to a book of Julius Caesar, and using a ``j'' long
120 % before it became a letter, is a mystery.)
121 %
122 % When printing was invented, publishers would add a
123 % colophon, often at the end (rather than at the beginning,
124 % where it typically sits now), noting their identities and
125 % addresses. Over time, particularly with small publishers,
126 % colophons got bigger, and contained information about
127 % design, font types, and the like. Too often they're
128 % completely omitted now, but I think it's still worth
129 % putting them in. I know that I \emph{love} to see them in
130 % the books I read, at least.
131 %
132 % \section{Default Behavior}
133 %
134 % By default, |colophon| uses a very simple two-command
135 % structure that produces what I, personally, believe to be
136 % a well-formatted and attractive colophon. We begin with
137 % the \DescribeEnv{colophon}|colophon| environment, which
138 % can be realized by the usual |\begin{colophon}| and
139 % |\end{colophon}| pairs. The contents of the colophon
140 % itself will be put in between these two, and the spacing,
141 % page style, paragraph styling, and the like will all be
142 % taken care of in the way that I, personally, think looks
143 % best.
144 %
145 % If you don't like using environments, feel free to use
146 % \DescribeMacro{\colophon}|\colophon| to begin the colophon
147 % and \DescribeMacro{\endcolophon}|\endcolophon| to end it.
148 % That's how they were defined, and that's what the \LaTeX\
149 % environment creation macros produce anyway, so do as you
150 % will. Using one or the other system produces no
151 % difference in functionality.
152 %
153 % By default, this produces a full-page colophon, printed
154 % after a |\cleardoublepage| has been executed (in other
155 % words, on the next available recto (odd-numbered) page.
156 % It does this with a centered heading, which will be the
157 % word ``Colophon''. If you want it to have some other
158 % heading, tell the package so with
159 % \DescribeMacro{\colophontitle}|\colophontitle|. E.g., if
160 % you want the title to be ``Stuff About the Book,'' run:
161 %
162 % \begin{quote}
163 % |\colophontitle{Stuff About the Book}|
164 % \end{quote}
165 %
166 % Alternatively, you can set the title with the |title|
167 % package option:
168 %
169 % \begin{quote}
170 % |\usepackage[title={Stuff About the Book}]{colophon}|
171 % \end{quote}
172 %
173 % The title will also be printed in |\scshape|,
174 % once again because I like it that way. You can change
175 % that, too, with either the
176 % \DescribeMacro{\colophontitlestyle}|\colophontitlestyle|
177 % macro, or with the |titlestyle| package option. Remember
178 % that you should \emph{not} use the backslash with your
179 % style command in the package option. The following two
180 % lines are equivalent:
181 %
182 % \begin{quote}
183 % |\colophontitlestyle{\itshape}|\\
184 % |\usepackage[titlestyle=itshape]{colophon}|
185 % \end{quote}
186 %
187 % Give titlestyle no option if you just want normal roman
188 % type.
189 %
190 % There are similar options governing the size of the title,
191 % \DescribeMacro{\colophontitlesize}|\colophontitlesize| and
192 % the |titlesize| package option. It takes a point size as
193 % an argument and sets both font size \emph{and} leading to
194 % that amount. Since it seems unlikely the title will have
195 % more than one line, that seemed fine to me; if this breaks
196 % your use case, let me know, and I'll fix it. The
197 % following two lines are equivalent:
198 %
199 % \begin{quote}
200 % |\colophontitlesize{60pt}|\\
201 % |\usepackage[titlesize=60pt]{colophon}|
202 % \end{quote}
203 %
204 % The default size is |48pt|.
205 %
206 % There will also be some space between the title and the
207 % colophon text. This can be controlled with either the
208 % \DescribeMacro{\colophonmidspace}|\colophonmidspace|
209 % command, or the |aftertitle| package option. The
210 % following two are equivalent:
211 %
212 % \begin{quote}
213 % |\colophonmidspace{3em}|\\
214 % |\usepackage[aftertitle=3em]{colophon}|
215 % \end{quote}
216 %
217 % By default, the colophon page will have pagestyle |empty|.
218 % To change this, use
219 % \DescribeMacro{\colophonpagestyle}|\colophonpagestyle| or
220 % the package option |pagestyle|. The following two lines
221 % are equivalent:
222 %
223 % \begin{quote}
224 % |\colophonpagestyle{plain}|\\
225 % |\usepackage[pagestyle=plain]{colophon}|
226 % \end{quote}
227 %
228 % You can align the title centered, on the left, or on the
229 % right, by using
230 % \DescribeMacro{\colophontitlealign}|\colophontitlealign|,
231 % or the |titlealign| package option. The options are |c|
232 % for centered (the default), |l| for left-aligned, and |r|
233 % for right-aligned. The following two are
234 % equivalent:
235 %
236 % \begin{quote}
237 % |\colophontitlealign{c}|\\
238 % |\usepackage[titlealign=c]{colophon}|
239 % \end{quote}
240 %
241 % Finally, there are hooks before and after the title which
242 % should allow you to run whatever arbitrary code you'd like
243 % there. By default, these are empty; but you can fill them
244 % with, for example, font-changing commands. This spares
245 % the package the overhead of having to determine what font
246 % system you're using, and what engine, and lets you worry
247 % about all that. The hooks are
248 % \DescribeMacro{\colophonpretitlehook}|\colophonpretitlehook|
249 % and
250 % \DescribeMacro{\colophonposttitlehook}|\colophonposttitlehook|.
251 % By default, both are empty; redefine them to whatever you
252 % need them to be.
253 %
254 % The actual texts of the colophon are governed by much the
255 % same parameters. The macros simply have |par| rather than
256 % |title| in their names. There are two additional ones,
257 % however, worth noting. You can set:
258 %
259 % \begin{itemize}
260 % \item \DescribeMacro{\colophonparstyle}|\colophonparstyle|,
261 % which will govern the style of the text. By default,
262 % this is empty, yielding whatever your normal font style
263 % is. Its package option is |parstyle|; remember not to
264 % use the backslash when setting it in the package options,
265 % as with |titlestyle|.
266 % \item \DescribeMacro{\colophonparsize}|\colophonparsize|,
267 % which is the point size of the colophon text. Its
268 % package option is |parsize|. By default, |15pt|.
269 % \item \DescribeMacro{\colophonparlead}|\colophonparlead|,
270 % which is the size of the leading of the colophon text
271 % (that is, the distance from one baseline to the next
272 % baseline down. By default, |18pt|. Its package option
273 % is |parlead|.
274 % \item \DescribeMacro{\colophonnofirstindent}|\colophonnofirstindent|,
275 % turns off |colophon|'s default behavior of suppressing
276 % the first indent after the title line. Default is to
277 % suppress the indent. The package option is
278 % |nofirstindent|.
279 % \item \DescribeMacro{\colophonpreparhook}|\colophonpreparhook|
280 % and its brother,
281 % \DescribeMacro{\colophonpostparhook}|\colophonpostparhook|,
282 % allows arbitrary commands to be run before and after the
283 % colophon text. They do not have package option
284 % equivalents.
285 % \item Last but not least,
286 % \DescribeMacro{\colophonparalign}|\colophonparalign|.
287 % This takes more or less arbitrary commands, but it's
288 % designed to permit what I think is a great stylistic
289 % touch with colophons: a fully justified paragraph, with
290 % the final line containing equal space on either side. By
291 % default, it achieves this, and is set as follows:
292 % \begin{quote}
293 % |\leftskip=0pt plus.5fil%|\\
294 % |\rightskip=0pt plus-.5fil%|\\
295 % |\parfillskip=0pt plus1fil%|
296 % \end{quote}
297 % This does the trick. If you don't like this, or want to
298 % do something else with it, change it as you will. This
299 % also has no package option equivalent.
300 % \end{itemize}
301 %
302 % That gives the default settings. If for some reason you
303 % do not want a full-page colophon (maybe you like it tucked
304 % into the bottom of the last page, for example, as was
305 % common long ago), use the
306 % \DescribeMacro{\colophonnofullpage}|\colophonnofullpage|
307 % macro, or the |nofullpage| package option. Note, however,
308 % that this merely means the colophon won't take up a full
309 % page; it will still create a new page before it prints.
310 % To prevent it from clearing pages, use
311 % \DescribeMacro{\colophonnoclrdblpg}|\colophonnoclrdblpg|,
312 % or the package option |noclrdblpg|. Both options together
313 % will allow you to tuck your colophon on the bottom of your
314 % last page.
315 %
316 % If you want the colophon to clear one page, but not a double
317 % page, use \DescribeMacro{\colophonclrpg}|\colophonclrpg|,
318 % or the package option |clrpg|.
319 %
320 % Note that, if the colophon is not clearing any pages, it
321 % will \emph{not} set the colophon page style, so
322 % |\colophonpagestyle| and the |pagestyle| package option
323 % will do nothing.
324 %
325 % Note also that, when you're not using a full page, if
326 % doesn't mean you can't have the colophon alone on the
327 % page; it just means that the colophon won't be vertically
328 % centered on the that page. You can print your colophon,
329 % issue a |\newpage|, and have it on the page by itself but
330 % not vertically centered. So to set the spaces above and
331 % below the colophon, use
332 % \DescribeMacro{\colophontopspace}|\colophontopspace| and
333 % its obviously-named brother,
334 % \DescribeMacro{\colophonbotspace}|\colophonbotspace|.
335 % Their package option equivalents are |topspace| and
336 % |botspace|, respectively. These will insert the requested
337 % amount of space before and after the colophon, allowing
338 % you to format it however you like.
339 %
340 % \section{Examples}
341 %
342 % We've set up two examples, one of a full page and one of a
343 % partial page colophon, which will give a good idea of what
344 % the capabilities of the |colophon| package are.
345 %
346 % \begin{tabular}{>{\raggedright}m{0.5\textwidth}m{0.5\textwidth}}
347 % |\usepackage[%|
348 % |title={Design Information},|
349 % |titlestyle=scshape,|
350 % |titlesize=30pt,|
351 % |titlealign=c,|
352 % |parstyle=itshape,|
353 % |parsize=12pt,|
354 % |parlead=15pt|
355 % |]{colophon}| &
356 % \fbox{\includegraphics[scale=0.15]{fullpage_ex.pdf}} \\
357 % \end{tabular}
358 %
359 % Here, we've changed a lot of details, and unnecessarily
360 % specified |scshape| as our title style (that is the
361 % default, after all), but came up with the page shown
362 % above.
363 %
364 % \begin{tabular}{>{\raggedright}m{0.5\textwidth}m{0.5\textwidth}}
365 % |\usepackage[%|
366 % |title={Design Stuff},|
367 % |titlestyle=itshape,|
368 % |titlesize=24pt,|
369 % |titlealign=r,|
370 % |parstyle=upshape,|
371 % |parsize=10pt,|
372 % |parlead=11pt,|
373 % |noclrdblpg,|
374 % |nofullpage,|
375 % |topspace=2in|
376 % |]{colophon}| &
377 % \fbox{\includegraphics[scale=0.15]{partpage_ex.pdf}} \\
378 % \end{tabular}
379 %
380 % Here we've turned off the full page and clearing of a
381 % double page in order to tuck our colophon into the last
382 % part of the page. The folio is still there, therefore
383 % (|colophon| doesn't change page styles unless it has its
384 % own page), in accordance with the rest of the document.
385 % We've also right-aligned our title, and adjusted our top
386 % space to stick it closer to the bottom of the page.
387 %
388 % Happy \TeX{}ing!
389 %
390 % \section{Implementation}
391 %
392 % The first thing we do is load |xkeyval|, so we can
393 % implement all those great package-loading options.
394 % \begin{macrocode}
395 \RequirePackage{xkeyval}
396 % \end{macrocode}
397 % We'll declare the options and process them later, after
398 % we've declared a bunch of |\if|s and other defaults.
399 % Which we get to next: declaring all the new conditionals
400 % that we'll need, along with the functions that will enable
401 % us to alter them without mucking around with the
402 % |@|-containing internal commands.
403 % \begin{macrocode}
404 \newif\ifclpn@clrpg\clpn@clrpgfalse%
405 \def\colophonclrpg{\clpn@clrpgtrue}%
406 \newif\ifclpn@clrdblpg\clpn@clrdblpgtrue%
407 \def\colophonnoclrblpg{\clpn@clrdblpgfalse}%
408 \newif\ifclpn@fullpage\clpn@fullpagetrue%
409 \def\colophonnofullpage{\clpn@fullpagefalse}%
410 \newif\ifclpn@centertitle\clpn@centertitletrue%
411 \newif\ifclpn@lefttitle\clpn@lefttitlefalse%
412 \newif\ifclpn@righttitle\clpn@righttitlefalse%
413 % \end{macrocode}
414 % The code for |\colophontitlealign| is necessarily more
415 % complex than the others, since it has to adjust the
416 % settings for multiple conditions.
417 % \begin{macrocode}
418 \def\colophontitlealign#1{%
419 \ifx#1c%
420 \clpn@centertitletrue%
421 \clpn@lefttitlefalse%
422 \clpn@righttitlefalse%
423 \fi
424 \ifx#1l%
425 \clpn@centertitlefalse%
426 \clpn@lefttitletrue%
427 \clpn@righttitlefalse%
428 \fi
429 \ifx#1r%
430 \clpn@centertitlefalse%
431 \clpn@lefttitlefalse%
432 \clpn@righttitletrue%
433 \fi
434 }%
435 \newif\ifclpn@nofirstindent\clpn@nofirstindenttrue%
436 \def\colophonnofirstindent{\clpn@nofirstindentfalse}%
437 \def\clpn@overspace{0pt}%
438 \def\colophontopspace#1{\def\clpn@overspace{#1}}%
439 \def\clpn@underspace{0pt}%
440 \def\colophonbotspace#1{\def\clpn@underspace{#1}}%
441 \def\clpn@undertitle{2em}%
442 \def\colophonmidspace#1{\def\clpn@undertitle{#1}}%
443 \def\clpn@pagestyle{empty}%
444 \def\colophonpagestyle#1{\def\clpn@pagestyle{#1}}%
445 \def\clpn@titleword{Colophon}%
446 \def\colophontitle#1{\def\clpn@titleword{#1}}%
447 \def\clpn@titlesty{\scshape}%
448 \def\colophontitlestyle#1{\def\clpn@titlesty{#1}}%
449 \def\clpn@titlesize{48pt}%
450 \def\colophontitlesize#1{\def\clpn@titlesize{#1}}%
451 \def\clpn@pretitle{}%
452 \def\colophonpretitlehook#1{\def\clpn@pretitle{#1}}%
453 \def\clpn@posttitle{}
454 \def\colophonposttitlehook#1{\def\clpn@posttitle{#1}}%
455 \def\clpn@parsty{}%
456 \def\colophonparstyle#1{\def\clpn@parsty{#1}}%
457 \def\clpn@parsize{15pt}%
458 \def\colophonparsize#1{\def\clpn@parsize{#1}}%
459 \def\clpn@parlead{18pt}%
460 \def\colophonparlead#1{\def\clpn@parlead{#1}}%
461 \def\clpn@paralign{%
462 \leftskip=0pt plus.5fil%
463 \rightskip=0pt plus-.5fil%
464 \parfillskip=0pt plus1fil%
465 }%
466 \def\colophonparalign#1{\def\clpn@paralign{#1}}%
467 \def\clpn@prepar{}%
468 \def\colophonpreparhook#1{\def\clpn@prepar{#1}}%
469 \def\clpn@postpar{}
470 \def\colophonpostparhook#1{\def\clpn@postpar{#1}}%
471 % \end{macrocode}
472 % As promised, we're now at the option-declaring stage. We
473 % declare options for a everything that we can declare above
474 % (at least, reasonably), and finish by parsing them. We
475 % have to do some shenanigans to get the style options to
476 % work, in order to insert backslashes, but this is
477 % relatively minor.
478 % \begin{macrocode}
479 \DeclareOptionX{title}{\def\clpn@titleword{#1}}
480 \DeclareOptionX{titlestyle}{%
481 \def\clpn@titlesty{\csname#1\endcsname}%
482 }%
483 \DeclareOptionX{titlesize}{\def\clpn@titlesize{#1}}
484 \DeclareOptionX{aftertitle}{\def\clpn@undertitle{#1}}
485 \DeclareOptionX{titlealign}{\colophontitlealign{#1}}
486 \DeclareOptionX{parstyle}{%
487 \def\clpn@parsty{\csname#1\endcsname}%
488 }%
489 \DeclareOptionX{parsize}{\def\clpn@parsize{#1}}
490 \DeclareOptionX{parlead}{\def\clpn@parlead{#1}}
491 \DeclareOptionX{nofullpage}{\clpn@fullpagefalse}
492 \DeclareOptionX{noclrdblpg}{\clpn@clrdblpgfalse}
493 \DeclareOptionX{clrpg}{\clpn@clrpgtrue}
494 \DeclareOptionX{topspace}{\def\clpn@overspace{#1}}
495 \DeclareOptionX{botspace}{\def\clpn@underspace{#1}}
496 \DeclareOptionX{nofirstindent}{\clpn@nofirstindentfalse}
497 \ProcessOptionsX
498 % \end{macrocode}
499 % And now we define the colophon itself, putting all the
500 % options above to good use.
501 % \begin{macrocode}
502 \def\colophon{%
503 \ifclpn@clrdblpg%
504 \cleardoublepage%
505 \thispagestyle{\clpn@pagestyle}%
506 \fi%
507 \ifclpn@clrpg%
508 \clearpage%
509 \thispagestyle{\clpn@pagestyle}%
510 \fi%
511 \ifclpn@fullpage%
512 \vbox to\textheight\bgroup%
513 \vfil%
514 \fi%
515 \vskip\clpn@overspace%
516 \hbox to\linewidth{%
517 \ifclpn@centertitle\hfil\fi%
518 \ifclpn@righttitle\hfil\fi%
519 \fontsize{\clpn@titlesize}{\clpn@titlesize}\selectfont%
520 \clpn@titlesty%
521 \clpn@pretitle%
522 \clpn@titleword%
523 \clpn@posttitle%
524 \ifclpn@lefttitle\hfil\fi%
525 \ifclpn@centertitle\hfil\fi%
526 }%
527 \vskip\clpn@undertitle%
528 \bgroup%
529 \clpn@parsty%
530 \fontsize{\clpn@parsize}{\clpn@parlead}\selectfont%
531 \clpn@prepar\clpn@paralign%
532 \ifclpn@nofirstindent%
533 \@afterindentfalse\@afterheading%
534 \fi%
535 }%
536 % \end{macrocode}
537 % Then, finally, we end the colophon.
538 % \begin{macrocode}
539 \def\endcolophon{%
540 \clpn@postpar%
541 \par%
542 \egroup%
543 \vskip\clpn@underspace
544 \ifclpn@fullpage%
545 \vfil%
546 \egroup%
547 \fi
548 }%
549 % \end{macrocode}
550 % And there's the |colophon| package. I hope it proves
551 % useful to someone besides myself. Happy \TeX{}ing!
552 %
553 % \PrintIndex