Debian Codegraph @

texmf-dist/doc/latex/memoir/memman.tex

raw
1 %#% extstart input preamble.tex
2 %
3 % memman.tex Memoir class user manual (Part II only) last updated 2009/09/07
4 % Author: Peter Wilson
5 % Copyright 2001, 2002, 2003, 2004, 2008, 2009 Peter R. wilson
6 %
7 % This work has the LPPL maintenance status "maintained".
8 % Maintainer: Lars Madsen (daleif at math dot au dot dk)
9 %
10 %\listfiles
11 \documentclass[10pt,letterpaper,extrafontsizes]{memoir}
12 \usepackage{comment}
13
14 \hfuzz=5pt
15
16 %\setlength\overfullrule{5pt}
17
18
19 % For (non-printing) notes \PWnote{date}{text}
20 \newcommand{\PWnote}[2]{}
21 \PWnote{2009/04/29}{Added fonttable to the used packages}
22 \PWnote{2009/08/19}{Made Part I a separate doc (memdesign.tex).}
23
24 % same
25 \newcommand{\LMnote}[2]{}
26
27
28 \usepackage{memsty}
29 %%%%%%%%%%%%%%%%%%%%%%%%%%%%
30 \usepackage{titlepages} % code of the example titlepages
31 \usepackage{memlays} % extra layout diagrams
32 \usepackage{dpfloat} % floats on facing pages
33 \usepackage{fonttable}[2009/04/01] % font tables
34
35 % with 2024 updates to array.sty fonttable no longer works, it seems
36 % to be missing a \relax:
37 \makeatletter
38 \patchcmd{\f@tevenlinenonum}
39 {\ifnum\f@tn=\f@thigh\\\hline}
40 {\ifnum\f@tn=\f@thigh\relax\\\hline}
41 {}
42 {\typeout{Failed patching fonttable}}
43 \makeatother
44
45
46
47
48
49 %%%% \usepackage{xr-hyper} \externaldocument{memdesign} Doesn't work,
50 %%%% Idea won't work in general for memman/memdesign
51 %%%% as at display time, who knows where everything
52 %%%% will be located on the individual's computer.
53 %%%%%%%%%%%%%%%%%%%%%%%%%%%%
54
55 %%%% Change section heading styles
56 %%%\memmansecheads
57
58 %%%% Use the built-in division styling
59 \headstyles{memman}
60
61 %%% ToC down to subsections
62 \settocdepth{subsection}
63 %%% Numbering down to subsections as well
64 \setsecnumdepth{subsection}
65
66 %%%% extra index for first lines
67 \makeindex[lines]
68
69
70 % this 'if' is used to determine whether we are compiling the memoir
71 % master in the subversion repository, or the public memman.tex
72 \newif\ifMASTER
73 \MASTERfalse
74 %\MASTERtrue
75
76 \ifMASTER
77
78 % add patch to fink, such that \AtEndFile still work
79 \makeatletter
80 \AtEndFile{fink.sty}{
81 \typeout{patching fink}
82 \renewcommand{\InputIfFileExists}[2]{%
83 \IfFileExists{##1}%
84 {##2\@addtofilelist{##1}%
85 \m@matbeginf{##1}%
86 \fink@prepare{##1}%
87 %\@@input \@filef@und
88 \expandafter\fink@input%
89 \expandafter\fink@restore\expandafter{\finkpath}%
90 \m@matendf{##1}%
91 \killm@matf{##1}}%
92 }
93 }
94 \makeatother
95 % private package, not in circulation
96 % enables us to gather svn information on a single file basis
97 %\usepackage[filehooks]{svn-multi-private}
98 % use the current version
99 \usepackage[filehooks]{svn-multi}
100
101
102 % \svnidlong
103 % {}
104 % {$LastChangedDate: 2025-03-04 12:57:30 +0100 (Tue, 04 Mar 2025) $}
105 % {$LastChangedRevision: 831 $}
106 % {$LastChangedBy: [email protected] $}
107
108
109
110 \makeatletter
111 \newcommand\addRevisionData{%
112 \begin{picture}(0,0)%
113 \put(0,-20){%
114 \tiny%
115 \expandafter\@ifmtarg\expandafter{\svnfiledate}{}{%
116 \textit{\textcolor{darkgray}{Chapter last updated \svnfileyear/\svnfilemonth/\svnfileday
117 \enspace (revision \svnfilerev)}}
118 }%
119 }%
120 \end{picture}%
121 }
122 \makeatother
123
124 % we add this to the first page of each chapter
125
126 \makepagestyle{chapter}
127 \makeoddfoot{chapter}{\addRevisionData}{\thepage}{}
128 \makeevenfoot{chapter}{\addRevisionData}{\thepage}{}
129
130 \else
131 % disable svn info collecting
132 \newcommand\svnidlong[4]{}
133 \fi
134
135
136
137
138
139 %% end preamble
140 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
141 %#% extend
142
143
144 %\hfuzz=10pt
145
146 \usepackage[draft]{fixme}
147 \fxsetup{
148 multiuser,
149 marginface=\normalfont\tiny,
150 innerlayout=noinline,
151 layout=marginnote,
152 final,
153 }
154 \usepackage{tikz,ragged2e}
155 \makeatletter
156 % extra feature, vadj=length kan flytte på fxnotes hvis de overlapper
157 \@fxdefinekey{layout}{vadj}{\def\marginnotevadjust{#1}}
158
159 % endnu mere ekstra feature, kræver tikz og calc tikz lib
160
161 %\usepackage{morewrites}
162
163 \renewcommand*\FXLayoutMarginNote[3]{%
164 \tikz[overlay,remember picture]\coordinate (A) at (0,0);%
165 \marginnote[%
166 \RaggedLeft%
167 \rlap{\tikz[overlay,remember picture]\coordinate(C) at (0,0);}%
168 \@fxuseface{margin}%
169 \@fxtextstd{#1}{#2}{#3}%
170 {\tikz[overlay,remember picture,ultra thin,cyan]\draw(A) -| ++(0,-2pt) -|(C);}%
171 ]{%
172 \RaggedRight%
173 \tikz[overlay,remember picture]\coordinate(B) at (0,0);%
174 \@fxuseface{margin}%
175 \@fxtextstd{#1}{#2}{#3}%
176 \tikz[overlay,remember picture,ultra thin,cyan]\draw(A) -| ++(0,-2pt) -|(B);%
177 }%
178 }
179 \makeatother
180
181 %\AtEndDocument{
182 % \clearpage
183 % \listoffixmes
184 %}
185
186
187
188
189 \IfFileExists{trims-example.pdf}{}
190 {\ClassError{memoir}{For the manual we are missing "trims-example.pdf", please run pdflatex on "trims-example.tex" before proceeding}{}}
191
192
193 \begin{document}
194
195
196 %#% extstart input intro.tex
197
198
199
200
201
202 %\tightlists
203 \firmlists
204 \midsloppy
205 \raggedbottom
206 \chapterstyle{demo3}
207
208 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
209
210 \input{memnoidxnum}
211
212 \frontmatter
213 \pagestyle{empty}
214
215
216 % half-title page
217 \vspace*{\fill}
218 \begin{adjustwidth}{1in}{1in}
219 \begin{flushleft}
220 \HUGE\sffamily The
221 \end{flushleft}
222 \begin{center}
223 \HUGE\sffamily Memoir
224 \end{center}
225 \begin{flushright}
226 \HUGE\sffamily Class
227 \end{flushright}
228 %%\begin{center}
229 %%\sffamily (Draft Edition 7)
230 %%\end{center}
231 \end{adjustwidth}
232 \vspace*{\fill}
233 \cleardoublepage
234
235 % title page
236 \vspace*{\fill}
237 \begin{center}
238 \HUGE\textsf{The Memoir Class}\par
239 \end{center}
240 \begin{center}
241 \LARGE\textsf{for}\par
242 \end{center}
243 \begin{center}
244 \HUGE\textsf{Configurable Typesetting}\par
245 \end{center}
246
247 \begin{center}
248 \Huge\textsf{User Guide}\par
249 \end{center}
250 \begin{center}
251 \LARGE\textsf{Peter Wilson}\par
252 \bigskip
253 \normalsize\textsf{Maintained by Lars Madsen}\par
254 \medskip
255 \normalsize\textsf{Corresponding to \theclass\ version \memversion}\par
256 \end{center}
257 \vspace*{\fill}
258 \def\THP{T\kern-0.2em H\kern-0.4em P}% OK for CMR
259 \def\THP{T\kern-0.15em H\kern-0.3em P}% OK for Palatino
260 \newcommand*{\THPress}{The Herries Press}%
261 \begin{center}
262 \settowidth{\droptitle}{\textsf{\THPress}}%
263 \textrm{\normalsize \THP} \\
264 \textsf{\THPress} \\[0.2\baselineskip]
265 \includegraphics[width=\droptitle]{anvil2.mps}
266 \setlength{\droptitle}{0pt}%
267 \end{center}
268 \clearpage
269
270 \PWnote{2009/06/26}{Updated the copyright page for 9th impression}
271 % copyright page
272 \begingroup
273 \footnotesize
274 \setlength{\parindent}{0pt}
275 \setlength{\parskip}{\baselineskip}
276 %%\ttfamily
277 %\textcopyright{} 2001 --- 2010 Peter R. Wilson \\
278 %\textcopyright{} 2011 --- \phantom{2099} Lars Madsen \\
279
280 \begin{tabular}{@{} l l}
281 \textcopyright{} 2001\:---\:2010 &Peter R. Wilson \\
282 \textcopyright{} 2011\:---\:& Lars Madsen
283 \end{tabular}
284
285
286 All rights reserved
287
288 The Herries Press, Normandy Park, WA.
289
290 Printed in the World
291
292 The paper used in this publication may meet the minimum requirements
293 of the American National Standard for Information
294 Sciences --- Permanence of Paper for Printed Library Materials,
295 ANSI Z39.48--1984.
296
297 \PWnote{2009/07/08}{Changed manual date to 8 July 2009}
298 \begin{center}
299 10 09 08 07 06 05 04 03 02 01\hspace{2em}19 18 17 16 15 14 13
300 \end{center}
301 \begin{center}
302 \begin{tabular}{ll}
303 First edition: & 3 June 2001 \\
304 Second impression, with corrections: & 2 July 2001 \\
305 Second edition: & 14 July 2001 \\
306 Second impression, with corrections: & 3 August 2001 \\
307 Third impression, with minor additions: & 31 August 2001 \\
308 Third edition: & 17 November 2001 \\
309 Fourth edition: & 16 March 2002 \\
310 Fifth edition: & 10 August 2002 \\
311 Sixth edition: & 31 January 2004 \\
312 %%Draft Seventh edition: & 31 January 2008 \\
313 Seventh edition: & 10 May 2008 \\
314 Eighth impression, with very minor corrections: & 12 July 2008 \\
315 Ninth impression, with additions and corrections: & 8 July 2009 \\
316 Eighth edition: & August 2009 \\
317 Tenth impression, with additions and corrections: & 11 November 2015 \\
318 \end{tabular}
319 \end{center}
320 \ifMASTER
321 Manual last changed \svnyear/\svnmonth/\svnday
322 \fi
323
324 \endgroup
325
326 \clearpage
327 \vspace*{\fill}
328 \begin{quote}
329 \textbf{memoir,} \textit{n.} a written record set down as material
330 for a history or biography:
331 a biographical sketch:
332 a record of some study investigated by the writer:
333 (in \textit{pl.}) the transactions of a society.
334 [Fr. \textit{m\'{e}moire} --- L. \textit{memoria,} memory ---
335 \textit{memor}, mindful.] \\[0.5\baselineskip]
336 \hspace*{\fill}
337 \textit{Chambers Twentieth Century Dictionary, New Edition}, 1972.
338 \end{quote}
339
340 \vspace{2\baselineskip}
341
342 \begin{quote}
343 \textbf{memoir,} \textit{n.} [Fr. \textit{m\'{e}moire,} masc., a memorandum,
344 memoir, fem., memory $<$ L. \textit{memoria,} \textsc{memory}]
345 \hspace{1ex} \textbf{1.} a biography or biographical notice,
346 usually written by a relative or personal friend of the subject
347 \hspace{1ex} \textbf{2.} [\textit{pl.}] an autobiography,
348 usually a full or highly personal account
349 \hspace{1ex} \textbf{3.} [\textit{pl.}] a report or record of
350 important events based on the writer's personal observation,
351 special knowledge, etc.
352 \hspace{1ex} \textbf{4.} a report or record of a scholarly
353 investigation, scientific study, etc.
354 \hspace{1ex} \textbf{5.} [\textit{pl.}] the record of the proceedings
355 of a learned society \\[0.5\baselineskip]
356 \hspace*{\fill} \textit{Webster's New World Dictionary, Second College Edition}.
357 \end{quote}
358
359 \vspace{2\baselineskip}
360
361
362 \begin{quote}
363 \textbf{memoir,} \textit{n.} a fiction designed to flatter the subject
364 and to impress the reader. \\[0.5\baselineskip]
365 \hspace*{\fill} With apologies to Ambrose Bierce % and Reuben Thomas
366 \end{quote}
367
368 \vspace*{\fill}
369
370 \cleardoublepage
371
372 % ToC, etc
373 %%%\pagenumbering{roman}
374 \pagestyle{headings}
375 %%%%\pagestyle{Ruled}
376
377 \setupshorttoc
378 \tableofcontents
379 \clearforchapter
380 \setupparasubsecs
381 \setupmaintoc
382
383 \begingroup
384
385 % important point here: We need \endlineshar=-1 here for the inline
386 % list of subsections. Why? Beacause we have subsection subsubsection
387 % subsection, and under hyperref running the l@subsubsection for
388 % subsubsection, which typesets nothing, ruins our \ignorespaces in
389 % our redefinition of \l@subsection (it cannot see and ignore the space after the
390 % \contentsline line for subsubsection). Easiest solution: use
391 % change \endlinechar
392 %
393 % Special thanks to David Carlisle in the tex.stackexchange.com chat
394 % for suggesting it
395
396
397 \endlinechar=-1
398
399
400 \tableofcontents
401
402 \endgroup
403
404
405 \setlength{\unitlength}{1pt}
406 \clearpage
407 \listoffigures
408 \clearpage
409 \listoftables
410 \clearpage
411 \listofegresults
412
413 %#% extend
414
415
416 %#% extstart include maintainer-remarks.tex
417
418 \svnidlong
419 {$Ignore: $}
420 {$LastChangedDate: 2025-10-02 11:20:34 +0200 (Thu, 02 Oct 2025) $}
421 {$LastChangedRevision: 880 $}
422 {$LastChangedBy: [email protected] $}
423
424 \chapter{Remarks from the maintainer}
425 \label{cha:remarks-from-maint}
426
427
428 When Peter Wilson released the first version of \theclass{} (back in
429 2001), \LaTeX{} land was very different. Updating packages outside of
430 the yearly release (TeXLive) had to be done by hand. Manuals for
431 packages was \emph{not} even a requirement for CTAN. Thus it made
432 sense to embed the functionality from several packages and provide
433 usage information about them in this very manual. Peter even added a
434 lot of historical notes as well, that was later spun of as a separate
435 document of its own (see \cite{MEMDESIGN}). As time progressed
436 methods were set in place to make it easier to update packages during
437 a release cycle and later packages and classes were required to always
438 provide a suitable manual.
439
440 Over the past five years I have moved several packages out from being
441 embedded copies over to simply loading them as packages.\footnote{One
442 of the main reasons to do so was maintance, it is not feasible to
443 keep track of changes to an embedded package and then applying those
444 to \theclass.} As it is useful to have usage description in one
445 place, we have kept that in the manual, but users should always refer
446 back to the packages original manuals. Summer 2023, I moved
447 \Lpack{booktabs} from embedding to loading.
448
449 \fancybreak{}
450
451 As of Summer 2023 (begining with \theclass\ version 3.8) things are
452 changing a for \theclass. In the past 4 years (begining in 2019) the
453 \LaTeX\ Team have added lot of new functionality into the \LaTeX{}
454 format.\footnote{Most notably most of the \Lpack{xparse} package, plus
455 the entire \LaTeX3 programming layer.} They will continue to add
456 extra features to the kernel that are going to be very useful in the
457 future, both at the level of class and package writers, but also at
458 user level. As such we would like to begin using these new features
459 without having to also provide backwards compatibility for those (few)
460 users who manually update \theclass.\footnote{Overleaf users should be
461 aware that Overleaf does not update packages or kernels on their
462 \LaTeX\ images. So if we say the cut off is summer 2021, Overleaf
463 might not have the correct kernel update in their version of TeXLive
464 2021.}
465
466 Counting from version 3.8 we will therefore now require users to have
467 a modern \LaTeX{} kernel installed. For \theclass\ version 3.8 a user
468 who manually updates \theclass\ will need to have a \LaTeX\ format
469 released by 2021/06/01 or later. If the version is too old \theclass\
470 will halt the compilatiion to force users to react to the error and
471 not just ignore it.\footnote{Most \LaTeX\ editors incuding OverLeaf
472 use \texttt{-interaction=nonstopmode}, aka try do make a PDF even if
473 there are compilation errors. On old kernels, \theclass\ will end
474 even this! } In case we would like to use functionality that are in
475 a even newer formats, we will make sure that these macros are provided
476 by the class (eventhough they may do nothing unless you have the
477 proper kernel).
478
479 Going forward a main goal of the \LaTeX\ Team is the ability to tag
480 PDF files. The \theclass~class will also have to be adapted to become
481 compatible with this feature. For version~3.8 this required us to
482 rework how \cmd{\titleref} was implemented as we should no longer
483 redefine \cmd{\label}.\footnote{\cmd{\titleref} is now an alias for
484 \cmd{\nameref} (from the \Lpack{nameref} package), a package which
485 is maintained in close relation with \Lpack{hyperref}.}
486
487 \fancybreak{}
488
489 Additionally, going forward I will additionally be starting to look at
490 removing certain functionality from \theclass. This will be things
491 that does not really belong in \theclass. Things that users ought to
492 get from somewhere else (some additional package). Unless it is clear
493 that the macro has to go due to reimplemantation of a feature or that
494 the feature probably is not used by that many people, the removal will
495 be announced in advance (say 12--18 months), by adding a warning to
496 the macro (especially if we would like the user to use a different
497 macro). It will also be marked in the manual that the
498 macro/environment will be removed in a future release.
499 \begin{maintainersig}
500 Summer 2023
501 \end{maintainersig}
502
503 \fancybreak{}
504
505 In this over due update we fixed several things. Details are listed in
506 the README, which can be found in the \README. As listed below, some
507 macros are not marked for removal. For existing documents the
508 redefinition of \cs{cftchapterbreak}, might be of interest as it will
509 affect the look of documents that have changed this macro. See
510 pages~\pageref{cftbreak-start}--\pageref{cftbreak-end} for details,
511 where it is also listed the the most frequent reason to redefine
512 \cs{cftchapterbreak} (chanding the penalty) has now neen factored out
513 so the penalty can be changed directly. We have also started adding
514 warnings against packages that should not be used with memoir.
515 \begin{maintainersig}
516 March 2025
517 \end{maintainersig}
518
519
520 \fancybreak{}
521
522 This maintenance update that fixes several bugs and marks more macros
523 for deletion. Details are as usual listed in the \README. As for the
524 tagging project, we do not have anything concrete yet, but have been
525 doing some promising experiments. The required kernel version is now
526 set at 2023/06/01.
527 \begin{maintainersig}
528 Summer 2025
529 \end{maintainersig}
530
531
532
533 \begingroup
534 \renewcommand\descriptionlabel[1]{\hspace\labelsep\parbox[t]{\dimexpr\textwidth-5pt\relax}{#1}}
535
536 \section*{Macros marked to be removed in 2026}
537
538 Each will work, but their first use will issue a warning in the log.
539
540 \begin{description}
541 \item[\cmd{\addtodef}, \cmd{\addtodef*}, \cmd{\addtoiargdef}, \cmd{\addtoiargdef*}, \cmd{\patchcommand}]
542
543 Their effect can be achived using tools from \Lpack{etoolbox} and
544 \Lpack{xpatch} (both autoloaded by the class).
545 \item[\cmd{\newloglike}, \cmd{\provideloglike}] Users should really
546 use \cs{DeclareMathOperator} from \Lpack{amsopn} (autoloaded by
547 \Lpack{amsmath}). Note there is currently no equivalent for
548 \cs{provideloglike}.
549
550 \item[\cmd{\fref}, \cmd{\tref}, \cmd{\pref}, \cmd{\Aref}, \cmd{\Bref}, \cmd{\Pref}, \cmd{\Cref}, \cmd{\Sref}]
551
552 These are all convenience reference macros from when Peter W created
553 the class. With \Lpack{hyperref} and modern reference packages,
554 users should make their own macros, instead of having to redefine
555 these class macros.
556
557 The macros will give a deprecation warning at first use, unless the
558 macro is already defined in the preamble.
559
560 Users can just add the following to their preamble:
561 \begin{verbatim}
562 \newcommand*{\fref}[1]{\figurerefname~\ref{#1}}
563 \newcommand*{\tref}[1]{\tablerefname~\ref{#1}}
564 \newcommand*{\pref}[1]{\pagerefname~\pageref{#1}}
565 \newcommand*{\Aref}[1]{\appendixrefname~\ref{#1}}
566 \newcommand*{\Bref}[1]{\bookrefname~\ref{#1}}
567 \newcommand*{\Pref}[1]{\partrefname~\ref{#1}}
568 \newcommand*{\Cref}[1]{\chapterrefname~\ref{#1}}
569 \newcommand*{\Sref}[1]{\sectionrefname\ref{#1}}
570 \end{verbatim}
571 in order to get rid of the warning.
572
573 \item[\cmd{\settocpreprocessor}] It was added in order to fix the
574 problem of using, say, \cs{MakeUppercase} on toc
575 entried. \Lpack{hyperref} did not like that. This has now beed fixed
576 in the kernel/\Lpack{hyperref} so there is no need for it anymore.
577
578 \end{description}
579
580
581 \section*{Public interfaces removed/disabled in v3.8.4}
582
583 \begin{description}
584 \item[\cs{label}\parg{bookmark}\marg{labstr}] inside \cs{subcaption}
585 and friends. This ``\parg{bookmark}'' part is a non-standard syntax
586 and is too hard to keep working. The standard
587 \cs{label}\marg{labstr} continues to work of course.
588 \end{description}
589
590
591 \section*{Public interfaces removed/disabled in v3.8.2}
592 The following macros were discontinued due to the un-embedding of the \Lpack{verbatim package}
593 \begin{description}
594 \item[\cmd{\tabson}, \cmd{\tabsoff}] Used to be able to enable/disable
595 tab marking support in verbatim texts. \cs{tabson} issues a warning and does nothing.
596 \item[\cmd{\wrappingon}, \cmd{\wrappingoff}] Used to be able to enable
597 automatic line breaking at white space in verbatim
598 texts.\footnote{The implementation had bugs which were never
599 reported, thus probably not used that much.} \cs{wrappingon}
600 issues a warning and does nothing.
601 \item[\cmd{\verbatimbreakchar}] Left on a verbatim line broken at
602 white space.
603 \end{description}
604
605
606 \section*{Public interfaces removed/disabled in v3.8}
607
608 The four title macros was disabled due to the \cmd{\titleref} reimplementation.
609 \begin{description}
610 \item[\cmd{\currenttitle}] Would have given the title of the current
611 sectional devide. Too risky to rely on, use
612 \cmd{\label}+\cmd{\titleref} instead. Throws an error if used.
613 \item[\cmd{\namerefon}, \cmd{\namerefoff}]
614 These could turn sectional title referencing on/off. As we now load
615 \Lpack{nameref} by default, the value is always on. Both macros now
616 just give a warning.
617 \item[\cmd{\theTitleReference}]
618 Could control the look of \cmd{\titleref}. Does nothing but issue a warning.
619 \item[\texttt{noetex} (class option)] We only loaded \Lpack{etex} for
620 formats before 2015. The package loading and the class option have
621 been removed.
622 \end{description}
623
624
625
626 \endgroup
627
628
629
630
631
632 %#% extend
633 %#% extstart include preface.tex
634 %\chapter{Foreword}
635
636 \svnidlong
637 {$Ignore: $}
638 {$LastChangedDate: 2025-09-19 16:06:27 +0200 (Fri, 19 Sep 2025) $}
639 {$LastChangedRevision: 873 $}
640 {$LastChangedBy: [email protected] $}
641
642 \chapter{Preface}
643
644 From personal experience and also from lurking on the \url{comp.text.tex}
645 newsgroup the major problems with using \ltx\ are related to document
646 design. Some years ago most questions on \ctt\ were answered by
647 someone providing a piece of code that solved a particular problem, and
648 again and again. More recently these questions are answered along the
649 lines of `Use the ---------{} package', and again and again.
650
651 I have used many of the more common of these packages but my filing system
652 is not always well ordered and I tend to mislay the various user manuals,
653 even for the packages I have written. The \Pclass{memoir} class is an attempt
654 to integrate some of the more design-related packages with the LaTeX
655 \Pclass{book} class. I chose the \Pclass{book} class as the \Pclass{report} class
656 is virtually identical to \Pclass{book}, except that \Pclass{book} does
657 not have an \Ie{abstract} environment while \Pclass{report} does; however it is
658 easy to fake an \Ie{abstract} if it is needed. With a little bit of tweaking,
659 \Pclass{book} class documents can be made to look just like \Pclass{article}
660 class documents, and the \Pclass{memoir} class is designed with tweaking very
661 much in mind.
662
663 The \Pclass{memoir} class effectively incorporates the facilties that
664 are usually accessed by using external packages. In most cases the class
665 code is new code reimplementing package functionalities. The exceptions
666 tend to be where I have cut and pasted code from some of my packages.
667 I could not have written the \Pclass{memoir} class without the excellent
668 work presented by the implementors of \ltx\ and its many packages.
669
670 Apart from packages that I happen to have written I have gained many
671 ideas from the other packages listed in the \bibname. One way or another
672 their authors have all contributed, albeit unknowingly.
673 The participants in the
674 \url{comp.text.tex} newsgroup have also provided valuable input, partly
675 by questioning how to do something in \ltx, and partly by providing
676 answers. It is a friendly and educational forum.
677
678 {\raggedleft{\scshape Peter Wilson} \\ Seattle, WA \\ June 2001\par}
679
680 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
681 % \begin{comment}
682 % \chapter{Introduction to the first edition}
683
684 % This is not a guide to the general use of LaTeX but rather concentrates
685 % on where the \index{class}\Lclass{memoir} class differs from the standard LaTeX
686 % \Lclass{book} and \Lclass{report} classes. There are other sources that deal with LaTeX in
687 % general, some of which are listed in the \bibname. Lamport~\cite{LAMPORT94}
688 % is of course the original user manual for LaTeX, while the Companion
689 % series, for example~\cite{COMPANION}, go into further details and auxiliary
690 % programs. The Comprehensive TeX Archive Network (CTAN) is a valuable source
691 % of free information and the LaTeX system itself. For general questions see
692 % the FAQ~\cite{FAQ} which also has pointers to information sources. Among
693 % these are \btitle{The Not So Short Introduction to LaTeX2e}~\cite{LSHORT},
694 % Keith Reckdahl's \btitle{Using imported graphics in LaTeX2e}~\cite{EPSLATEX}
695 % and Piet van Oostrum's \btitle{Page layout in LaTeX}~\cite{FANCYHDR}.
696 % The question of how to use different fonts with LaTeX is left strictly alone;
697 % Alan Hoenig's book~\cite{HOENIG98} is the best guide to this that I know of
698 % although Philipp Lehman's \btitle{The Font Installation Guide}~\cite{FONTINST}
699 % has much information.
700
701
702 % The first part of the manual discusses briefly some aspects of book
703 % design and typography, independently of the means of typesetting. Among
704 % the several books on the subject listed in the \bibname{} I prefer
705 % Bringhurst's \btitle{The Elements of Typographic Style}~\cite{BRINGHURST99}.
706 % I have used the LaTeX \Lclass{book} design, which is the default
707 % \Lclass{memoir} class style, in typesetting Part~\ref{part:art}.
708
709 % The second part then goes into some detail on how the \Lclass{memoir}
710 % class can be used to implement a particular design.
711
712 % With two exceptions, the \Lclass{memoir} class has all the capabilities
713 % of the standard LaTeX \Lclass{book} class. These exceptions are:
714 % \begin{itemize}
715 % \item The old LaTeX v2.09 font commands ---
716 % \cmd{\rm} (roman),
717 % \cmd{\tt} (\texttt{typewriter}),
718 % \cmd{\sf} (\textsf{sans}),
719 % \cmd{\bf} (\textbf{bold}),
720 % \cmd{\sl} (\textsl{slanted}),
721 % \cmd{\it} (\textit{italic}),
722 % and \cmd{\sc} (\textsc{small caps}) ---
723 % are not supported and will give error messages if used.
724
725 % The \cmd{\em} (\emph{emphasis}) command is supported but gives
726 % a warning message if used.
727
728 % \item There are no commands for making titles. This is because title pages are
729 % usually designed individually for each book. The
730 % \index{package}\Lpack{titling}
731 % package~\cite{TITLING} can be used if you want the titling commands.
732 % The package
733 % provides extended titling facilities when compared to those in the
734 % standard LaTeX classes.
735
736 % \end{itemize}
737 % I hope that, apart from these, the class supports everything that the
738 % \Lclass{book} class provides.
739
740 % The major extra functions provided by the class include:
741 % \begin{itemize}
742 % \item Font sizes for the main text of 9, 10, 11, 12 and 14pt.
743 % \item A reasonably intuitive means of setting the page, text and margin sizes.
744 % \item Page trimming marks.
745 % \item If really required, typesetting as though in the olden typewriter days
746 % (double spaced, raggedright, no hyphenation, typewriter font).
747 % \item Configurable sectional headings, with several predefined styles for
748 % chapter headings and simple methods for defining new ones.
749 % \item `Anonymous' section breaks (e.g., a blank or decorated line or two).
750 % \item Configurable page headers and footers, with several predefined styles
751 % and simple methods for defining new ones.
752 % \item Configurable captions, with several predefined captioning styles and
753 % methods for defining new ones.
754 % \item Ability to define new `\listofx' and new floats with their accompanying
755 % captions and `\listofx'.
756 % \item Control over whether the `\listofx', bibliography, index, etc., appear
757 % in the Table of Contents.
758 % \item Support for epigraphs.
759 % \end{itemize}
760 % Also, along the way you will find other more minor but still useful things.
761
762 % As Part~\ref{part:practice} progresses I demonstrate some of the changes
763 % that the \Lclass{memoir} class lets you easily make to the normal LaTeX
764 % page and titling style.
765
766 % \section{Type conventions}
767
768 % The following conventions are used in the manual:
769 % \begin{itemize}
770 % \item \Pclass{The names of LaTeX classes\index{class} and
771 % packages\index{package} are typeset in this font,
772 % as are class and package options\index{option}.}
773 % \item \Ppstyle{The names of chapterstyles\index{chapterstyle} and
774 % pagestyles\index{pagestyle} are typeset in this font.}
775 % \item \texttt{LaTeX code is typeset in this font.}
776 % \end{itemize}
777
778 % \section{Caveats}
779
780 % At the moment both this manual and the class code are in a beta state.
781 % That is, they hopefully serve the purposes they are intended for, but
782 % it is probable that there are errors, poor explanations and missing
783 % elements. So, be warned that I'm sure that there will be further releases
784 % and these may not be entirely compatible with the current release.
785
786 % That said, I will be grateful for any constructive comments that
787 % anyone\footnote{I have received valuable comments from
788 % Javier Bezos,
789 % Sven Bovin,
790 % Scott Pakin,
791 % and
792 % Paul Stanley.}
793 % may have, especially regarding errors, mispeaking, and desireable
794 % enhancements. I can be reached by posting to \url{comp.text.tex}.
795
796 % TeX was designed principally for typesetting documents containing a
797 % lot of mathematics. In such works the mathematics breaks up the flow
798 % of the text on the page, and the vertical space required for displayed
799 % mathematics is arbitrary. Most non-technical books are typeset on a fixed
800 % grid as they do not have arbitrary insertions into the text.
801
802 % TeX is designed to handle arbitrary sized inserts in an elegant manner,
803 % and does this by allowing vertical spaces to stretch and shrink a little
804 % so that the actual height of the typeblock is constant. Therefore LaTeX, being
805 % built on top of TeX, does not typeset on a fixed grid, and it would be a
806 % very major task to try and make it do so; this has been tried but as far as
807 % I know nobody has been successful. Experimental work, though, is still ongoing.
808
809 % The manual includes many unbreakable names of LaTeX commands,
810 % some of which stick out into the margin. The way of getting rid of these
811 % is to rewrite the text so that they don't come at the end of a typeset
812 % line. This is tedious and I haven't done it because I expect the manual
813 % to be revised and that would throw off any hand tweaking done now.
814
815
816 % \chapter{Introduction to the second edition}
817
818 % Since the first edition of the manual was published the \Lclass{memoir}
819 % class has undergone some changes and extensions. The changes, to remove
820 % some unfortunate errors, are upwards compatible. The extensions, by
821 % their nature, are not upward compatible.
822
823 % The main extensions and changes include:
824 % \begin{itemize}
825 % \item A \index{option}\Lopt{subfigure} option to counteract an unfortunate
826 % interplay\footnote{Discovered by Ignasi Furi\'{o} Caldentey.}
827 % if the \Lpack{subfigure} package is used with the class.
828
829 % \item An \Lopt{article} option so that \Lclass{article} class typesetting
830 % may be \emph{simulated}.
831
832 % \item Incorporation of the essential code from the \Lpack{titling}
833 % package~\cite{TITLING} (to support the \Lopt{article} option).
834
835 % \item Incorporation of the essential code from the \Lpack{abstract}
836 % package~\cite{ABSTRACT} (to support the \Lopt{article} option).
837
838 % \end{itemize}
839
840 % The description of how to modify the \prtoc, \prlof{} and \prlot{} headings
841 % in the first edition was completely wrong, as was the corresponding
842 % description of the \cmd{\newlistof} macro. No noticeable
843 % changes have been made to the class code but the descriptions now
844 % reflect reality. I must have been a few bricks short of a full load when
845 % I wrote the original.
846
847 % There are other more minor changes and extensions\footnote{With thanks
848 % to, among others, Kevin Lin and
849 % Adriano Pascoletti.}
850 % which you may find if you recall the first edition.
851
852 % There was no mention of typesetting verse in the first edition,
853 % although the class does provide the normal LaTeX \Ie{verse}
854 % environment. A poem
855 % is usually individually typeset as the appearance often has an
856 % effect on the emotional response when reading it. The \Lpack{verse}
857 % package~\cite{VERSE} may be useful when typesetting poetry.
858
859 % \chapter{Introduction to the third edition}
860
861 % Since the second edition of the manual was published the \Lclass{memoir}
862 % class has been upgraded from beta code to a production release. Extensions
863 % have been made to both the class and this manual.
864
865 % The main extensions and changes include:
866 % \begin{itemize}
867 % \item An \Lopt{openleft} option to enable chapters to start
868 % on verso pages.
869
870 % \item Incorporation of the essential code from the \Lpack{verse}
871 % package~\cite{VERSE} for more flexibility when typesetting
872 % poetry.
873
874 % \item Replacement of the macro called \cmd{\makepshook} by
875 % \cmd{\makepsmarks}. Note that this is a non-upward compatible
876 % change.
877
878 % \item The first part of the manual has been reorganised and
879 % extended, principally
880 % by providing more typesetting examples.
881
882 % \item As usual, minor glitches have been removed from both the code
883 % and the manual; each revision, of course, eliminates the gap between
884 % advertisement and reality.
885
886 % \end{itemize}
887
888
889 % There are other more minor changes and extensions\footnote{With thanks
890 % to, among others, Ignasi Furi\'{o} Caldentey,
891 % Daniel Richard G. and
892 % Vladimir G. Ivanovi\'c.}
893 % which you may find if you recall the second edition.
894
895 % \chapter{Introduction to the fourth edition}
896
897 % Since the third edition of the manual was published the \Lclass{memoir}
898 % class has been upgraded from version~1.0 to version~1.1. Modifications
899 % have been made to both the class and this manual.
900
901 % The main extensions and changes include:
902 % \begin{itemize}
903 % \item The \Lopt{subfigure} option is no longer required.
904
905 % \item Subfloats have been added to the class. Steve Cochran kindly gave
906 % permission for me to use some of his \Lpack{subfigure} package
907 % code for this.
908
909 % \item Some packages still use the old, deprecated LaTeX version~2.09
910 % font commands. I have reluctantly introduced an option
911 % to enable the old, deprecated font commands to be used.
912
913 % \item The class now works harmoniously with the \Lpack{natbib}
914 % package~\cite{NATBIB}.
915
916 % \item As usual, minor glitches have been removed from both the code
917 % and the manual; each revision hopefully eliminates the gap between
918 % advertisement and reality.
919
920 % \end{itemize}
921
922
923 % There are other more minor changes and extensions\footnote{With thanks
924 % to, among others,
925 % William Adams
926 % Ignasi Furi\'{o} Caldentey,
927 % Steven Douglas Cochran,
928 % Henrik Holm,
929 % and Rolf Niepraschk.
930 % }
931 % which you may find if you have used earlier editions.
932
933 % \chapter{Introduction to the fifth edition}
934
935 % Since the fourth edition of the manual was published the \Lclass{memoir}
936 % class has been upgraded from version~1.1 to version~1.2. Modifications
937 % have been made to both the class and this manual.
938
939 % The main extensions and changes include:
940 % \begin{itemize}
941 % \item The size options have been extended\footnote{At the
942 % request of Vittorio De Martino whose children use LaTeX
943 % for their school projects.}
944 % to include a \Lopt{17pt} option.
945
946 % \item A few font sizes corresponding to the font size commands (e.g., \verb?\Large?)
947 % have been changed to give regular steps between sizes.
948
949 % \item Boxes that can break over pages and/or contain verbatim text.
950
951 % \item Several ways of dealing with verbatim text, including footnotes
952 % that can contain verbatim text.
953
954 % \item Some control over the typesetting of footnotes. Unfortunately
955 % this necessitated some changes in the methods for styling
956 % thanks notes.
957
958 % \item Comment environments.
959
960 % \item Convenient methods for file input and output.
961
962 % \item Additional \verb?\provide...? commands.
963
964 % \item The \Ie{description} environment has been modified to match
965 % the appearance of the standard environment. The original
966 % \Lclass{memoir} form is still available as the \Ie{blockdescription}
967 % environment.
968
969 % \item A new optional argument has been added to the \cmd{\chapter} and
970 % \cmd{\chapter*} commands for setting header texts.
971
972 % \end{itemize}
973
974 % As usual, minor glitches have been removed from both the code
975 % and the manual. Hopefully, new ones have not been introduced.
976
977 % \chapter{Introduction to the sixth edition}
978
979 % Since the fifth edition of the manual was published the \Lclass{memoir}
980 % class has been upgraded from version~1.2 to version~1.6.
981 % Many new functions have
982 % been added to the class and this manual has been updated to reflect all
983 % the additions.
984
985 % The main extensions and changes include:
986 % \begin{itemize}
987
988 % \item Major extensions for typesetting arrays and tabulars, including
989 % continuous tabulars and automatic tabulation.
990
991 % \item Major extensions to footnote styles and the ability to have
992 % multiple series of footnotes.
993
994 % \item Major extensions for indexing, including one column and multiple indexes.
995
996 % \item Major extensions to crop marks.
997
998 % \item \verb?\tableofcontents? and friends can be used multiple times.
999
1000 % \item Section titles (as well as numbers) can be referenced.
1001
1002 % \item Sheet numbers and access to the numbers of the last sheet and last page.
1003
1004 % \item Various methods for formatting numbers.
1005
1006 % \item Better cooperation with the \Lpack{chapterbib} and \Lpack{natbib} packages.
1007
1008 % \end{itemize}
1009
1010 % There are many more minor additions.
1011 % As usual, glitches have been removed from both the code
1012 % and the manual. Hopefully, new ones have not been introduced.
1013
1014
1015 % Many people have contributed to the \Lclass{memoir} class and this manual
1016 % in the forms of code, solutions to problems, suggestions for new functions,
1017 % bringing my attention to errors and infelicities in the code
1018 % and manual, and last but not least in simply being encouraging.
1019 % I am very grateful to the following for all they have done, whether they
1020 % knew it or not:
1021 % Paul Abrahams,
1022 % William Adams,
1023 % Donald Arseneau,
1024 % Jens Berger,
1025 % Karl Berry,
1026 % Javier Bezos,
1027 % Sven Bovin,
1028 % Alan Budden,
1029 % Ignasi Furi\'{o} Caldentey,
1030 % Ezequiel Mart\'{\i}n C\'{a}mara,
1031 % David Carlisle,
1032 % Steven Douglas Cochran,
1033 % Michael Downes,
1034 % Victor Eijkhout,
1035 % Danie Els,
1036 % Robin Fairbairns,
1037 % Simon Fear,
1038 % Kai von Fintel,
1039 % Daniel Richard G,
1040 % Romano Giannetti,
1041 % Kathryn Hargreaves,
1042 % Sven Hartrumpf,
1043 % Florence Henry,
1044 % Cartsten Heinz,
1045 % Peter Heslin,
1046 % Morton H\o{}gholm,
1047 % Henrik Holm,
1048 % Vladimir Ivanovich,
1049 % Stefan Kahrs,
1050 % J\o{}gen Larsen,
1051 % Kevin Lin,
1052 % Matthew Lovell,
1053 % Daniel Luecking,
1054 % Lars Madsen,
1055 % Vittorio De Martino,
1056 % Frank Mittelbach,
1057 % Rolf Niepraschk,
1058 % Patrik Nyman,
1059 % Heiko Oberdiek,
1060 % Scott Pakin,
1061 % Adriano Pascoletti,
1062 % Bernd Raichle,
1063 % Robert,
1064 % Chris Rowley,
1065 % Doug Schenck,
1066 % Rainer Sch\"{o}pf,
1067 % Paul Stanley,
1068 % Reuben Thomas,
1069 % Bastiaan Niels Veelo,
1070 % Emanuele Vicentini,
1071 % J\"{u}rgen Vollmer,
1072 % and others.
1073
1074 % If I have inadvertently left anyone off the list I apologise,
1075 % and please let me know so that I can correct the omisssion.
1076
1077 % Of course, none of this would have been possible without Donald Knuth's
1078 % TeX system and the subsequent development of LaTeX by Leslie Lamport.
1079
1080 % \end{comment}
1081 % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1082 % \begin{comment}
1083 % \chapter{Introduction to the seventh edition}
1084
1085 % The \Lclass{memoir} class and this manual have seen many changes since
1086 % they first saw the light of day. The major functions, and extensions to
1087 % them, were listed in the various
1088 % introductions to the previous editions of this manual and it would now be
1089 % tedious to read them.
1090
1091 % The \Mname\ class was first released in 2001 and since then has proven
1092 % to be reasonably popular. The class can be used as a replacement for
1093 % the \Lclass{book} and \Lclass{report} classes, by default generating
1094 % documents virtually indistinguisable from ones produced by those
1095 % classes. The class includes some options to produce documents with
1096 % other appearances; for example an \Lclass{article} class look or one
1097 % that looks as though the document was produced on a typewriter with a
1098 % single font, double spacing, no hyphenation, and so on. In the
1099 % following I use the term `standard class'\index{standard class} to
1100 % denote the \Lclass{book} and \Lclass{report} classes and, when
1101 % appropriate, the \Lclass{article} class as well.
1102
1103 % The \Mname\ class includes the functionality of many packages, for
1104 % instance the \Lpack{tocloft} package for controlling the table of contents or
1105 % methods similar to the \Lpack{fancyhdr} package for designing your own
1106 % headers. The built-in package functions are mainly related to document
1107 % design and layout; \Mname\ does not touch upon areas like those that are
1108 % covered by the \Lpack{babel} or \Lpack{hyperref} packages or any related to
1109 % typesetting mathematics. On the other hand it is easy to configure a work
1110 % produced with \Mname\
1111 % to meet a university's thesis layout requirements.
1112
1113 % \Mname\ has improved substantially since it was first released ---
1114 % over 50 \ltx ers have provided code or suggestions for improvements.
1115 % The class is included in the \TeXUG\ \tx\ distributions and the latest
1116 % version of the class and its supporting documentation is always
1117 % available from %
1118 % \ctan\ at \url{latex/contrib/memoir}.
1119
1120 % This is not a guide to the general use of \ltx\ but rather concentrates
1121 % on where the \index{class}\Lclass{memoir} class differs from the standard \ltx\
1122 % \Lclass{book} and \Lclass{report} classes. There are other sources that deal
1123 % with \ltx\ in general, some of which are noted later.
1124 % I assume that you have already used \ltx\ and therefore know how to prepare
1125 % a \ltx\ manuscript, how to run \ltx\ and print the resulting document,
1126 % and that you can also use auxiliary programs like \Lmakeindex\
1127 % and \Lbibtex.
1128
1129
1130 % \section{General considerations}
1131
1132 % The class is a large one consisting of about 10,000 lines of \ltx\ code
1133 % documented in a 400 page report; there is no need for most users to look at
1134 % this~\cite{MEMCODE}. However if you want to see exactly how some part,
1135 % or all of, \Mname\ is defined it is there for you to peruse.
1136 % The document you are now reading is the separate comprehensive
1137 % User Manual~\cite{MEMMAN} which runs to about 500 pages, and from time to
1138 % time an Addendum~\cite{MEMADD} is released noting extensions to the class.
1139 % Again, if you want to see how something was done in this Manual, which
1140 % of course was prepared using \Mname\ itself, the source
1141 % is available for you to read.
1142 % There is also the \Lpack{memexsupp} package by Lars Madsen~\cite{MEMEXSUPP}
1143 % which provides some extra facilities for the class.
1144
1145
1146 % The first part of this Manual discusses some aspects of book design
1147 % and typography in
1148 % general, something that I haven't come across in the usual \ltx\ books
1149 % and manuals. This is intended to provide a little background for when
1150 % you design your own printed documents.
1151
1152 % The second, and by far the longer part, describes the capabilities
1153 % of \Mname\ and how to use them. This manual is not a \ltx\ tutorial; I assume
1154 % that you already know the basics. If you don't then there are several
1155 % free tutorials available. In some instances I show you the internal code
1156 % for the class which may involve \ltx\ commands that you won't come
1157 % across in the tutorials and also sometimes basic \tx\ commands. Information
1158 % on these, if you want it, is obtained from reading the \ltx\ source itself
1159 % and the \txbook, and perhaps one of the free \tx\ manuals such as
1160 % \btitle{TeX for the Impatient}~\cite{IMPATIENT} or
1161 % \btitle{TeX by Topic}~\cite{TEXBYTOPIC}.
1162
1163 % \section{Class options}
1164
1165 % The standard classes provide point options of 10, 11, or 12 points for the
1166 % main body font. \Mname\ extends this by also providing a 9 point option, and
1167 % options ranging from 14 to 60 points.
1168 % The width of the text block is automatically adjusted according to
1169 % the selected point size to try and keep within generally accepted
1170 % typographical limits for line lengths; you can override this if you wish.
1171 % The class also provides easy methods for specifying the
1172 % page layout parameters such as the margins --- both the side margins and
1173 % those at
1174 % the top and bottom of the page; the methods are similar to those of the
1175 % \Lpack{geometry} package.
1176
1177 % The page layout facilities also include methods, like those provided
1178 % by the \Lpack{fancyhdr} package, for defining your own
1179 % header and footer styles, and you can have as many different ones as you wish.
1180 % In fact the class provides seven styles to choose from before having to
1181 % create your own if none of the built-in styles suit you.
1182
1183 % Sometimes it is useful, or even required, to place trimming marks on
1184 % each page showing the desired size of the final page with respect to the sheet
1185 % of paper that is used in the printer. This is provided by the \Lopt{showtrims}
1186 % option. A variety of trim marks are provided and you can define your own
1187 % if you need some other kind.
1188
1189 % \section{Sectioning styles}
1190
1191 % Handles are provided for designing and using your own styles for chapter
1192 % titles and such. The class comes with over 20 predefined chapter styles ranging
1193 % from the default look to a style that mimics that used in the
1194 % \emph{Companion} series of \ltx\ books. There are even a couple which use
1195 % words instead of numerals for chapter numbers.
1196 % % The Manual shows
1197 % %examples of these styles and about 30 are shown in Lars
1198 % %Madsen's collection~\cite{MEMCHAPS}.
1199
1200 % For those who like putting quotations near chapter titles the
1201 % \Ie{epigraph} environment can be used.
1202
1203 % The options for changing \cs{section} and lower level titles
1204 % are more constrained, but generally speaking document design, unless for
1205 % advertisements or other eye-catching ephemera, should be constrained.
1206 % The class does provide 9 integrated sets of sectional heading styles instead
1207 % of the usual single set.
1208
1209 % Sometimes, but particularly in novels, a sectional division is indicated
1210 % by just leaving a blank line or two between a pair of paragraphs, or there
1211 % might be some decorative item like three or four asterisks, or a fleuron
1212 % or two. (A \emph{fleuron}\index{fleuron} is a printers ornament looking
1213 % like a leaf, such as \ding{166} or \ding{167}.) Commands
1214 % are available for typesetting such anonymous divisions.
1215
1216 % In the standard classes the sectioning commands have an optional argument
1217 % which can be used to put a short version of the section title into the
1218 % table of contents and the page header. \Mname\ extends this with a second
1219 % optional argument so you can specify one short version for the contents and
1220 % an even shorter one for page headers where space is at a premium.
1221
1222 % \section{Captions}
1223
1224 % \Mname\ incorporates the code from my \Lpack{ccaption} package which
1225 % lets you easily modify the appearance of figure and table captions; bilingual
1226 % captions are available if required, as are captions placed at the side of
1227 % a figure or table or continuation captions from, say, one illustration to
1228 % another. Captioning can also be applied
1229 % to `non-floating' illustrations or as legends (i.e., unnumbered captions) to
1230 % the regular floats. The captioning system
1231 % also supports subfigures and subtables along the lines of the \Lpack{subfig}
1232 % package, plus letting you define your own new kinds of floats together
1233 % with the corresponding `\listofx'.
1234
1235 % \section{Tables}
1236
1237 % Code from the \Lpack{array}, \Lpack{dcolumn}, \Lpack{delarray} and
1238 % \Lpack{tabularx} packges is integrated within the class. To improve
1239 % the appearance of rules in tabular material the \Lpack{booktabs}
1240 % package is also included.
1241
1242 % Multipage tabulations are often set with the \Lpack{longtable} or
1243 % \Lpack{xtab} packages, which can of course be used with the class. For
1244 % simple tabulations that may continue from one page to the next, \Mname\
1245 % offers a `continuous tabular' environment. This doesn't have all the
1246 % flexibility provided by the packages but can often serve instead
1247 % of using them.
1248
1249 % More interestingly, but more limited, the class provides `automatic
1250 % tabulars'. For these you provide a list of simple entries, like a set of names,
1251 % and a number of
1252 % columns and the entries are automatically put into the appropriate column.
1253 % You choose whether the entries should be added row-by-row, like this with
1254 % the \cs{autorows} command:
1255
1256 % \begin{lcode}
1257 % \autorows{c}{5}{l}{one, two, three, four,
1258 % five, six, seven, eight, nine, ten,
1259 % eleven, twelve, thirteen }
1260 % \end{lcode}
1261
1262 % \showit{
1263 % {\centering
1264 % \begin{tabular}{lllll}
1265 % one & two & three & four & five \\
1266 % six & seven & eight & nine & ten \\
1267 % eleven & twelve & thirteen \\
1268 % \end{tabular}
1269 % \par}
1270 % }
1271
1272 % Or if you use the \cs{autocols} command the entries are listed
1273 % column-by-column, like this :
1274
1275 % \begin{lcode}
1276 % \autocols{c}{5}{l}{one, two, three, four,
1277 % five, six, seven, eight, nine, ten,
1278 % eleven, twelve, thirteen }
1279 % \end{lcode}
1280
1281 % \showit{
1282 % {\centering
1283 % \begin{tabular}{lllll}
1284 % one & four & seven & ten & thirteen \\
1285 % two & five & eight & eleven & \\
1286 % three & six & nine & twelve & \\
1287 % \end{tabular}
1288 % \par}
1289 % }
1290
1291 % \section{Verse}
1292
1293 % The standard classes provide a very simple \Ie{verse} environment for
1294 % typesetting poetry. This is greatly extended in \Mname. For example in the
1295 % standard classes the verse stanzas are at a fixed indentation from the
1296 % left margin whereas \Mname\ lets you control the amount of indentation so
1297 % that you can make a poem appear optically centered within the textwidth.
1298
1299 % Stanzas may be numbered, as can individual lines within a poem. There is
1300 % a special environment for stanzas where lines are alternately indented. Also
1301 % you can define an indentation pattern for stanzas when this is not regular
1302 % as, for example, in a limerick where the 3rd and 4th of the five lines are
1303 % indented with respect to the other three as shown below.
1304
1305 % \begin{lcode}
1306 % \indentpattern{00110}
1307 % \begin{verse}
1308 % \begin{patverse}
1309 % There was a young man of Quebec \\
1310 % Who was frozen in snow to his neck. \\
1311 % When asked: `Are you friz?' \\
1312 % He replied: `Yes, I is, \\
1313 % But we don't call this cold in Quebec.'
1314 % \end{patverse}
1315 % \end{verse}
1316 % \end{lcode}
1317
1318 % \showit{
1319 % \begin{verse}
1320 % There was a young man of Quebec \\
1321 % Who was frozen in snow to his neck. \\
1322 % \hspace*{2em}When asked: `Are you friz?' \\
1323 % \hspace*{2em}He replied: `Yes, I is, \\
1324 % But we don't call this cold in Quebec.'
1325 % \end{verse}
1326 % }
1327
1328 % It is not always possible to fit
1329 % a line into the available space and you can specify the particular indentation
1330 % to be used when a `logical' verse line spills over the available textwidth,
1331 % thus forming two or more typeset `physical' lines. On other occasions
1332 % where there are two half lines the poet might want the second half line
1333 % to start where the first one finished, like this:
1334
1335 % \begin{lcode}
1336 % \begin{verse}
1337 % Come away with me. \\
1338 % \vinphantom{Come away with me.} Impossible!
1339 % \end{verse}
1340 % \end{lcode}
1341
1342 % \showit{
1343 % \begin{verse}
1344 % Come away with me. \\
1345 % \leavevmode\phantom{Come away with me.} Impossible!
1346 % \end{verse}
1347 % }
1348
1349
1350 % \section{End matter}
1351
1352 % Normally appendices come after the main body of a book. The class provides
1353 % various methods for introducing appendices at the end, or you can place one or
1354 % more appendices at the end of selected chapters if that suits you better.
1355
1356 % \Mname\ also lets you have more than one index and an index can be set in
1357 % either the normal double column style or as a single column which would be more
1358 % appropriate, say, for an index of first lines in a book of poetry. The titles
1359 % of any bibliography or indexes are added to the table of contents, but you
1360 % can prevent this if you wish.
1361
1362 % The class provides a set of tools for making glossaries or lists of
1363 % symbols, the appearance of which can, of course, be easily altered. The
1364 % \Lmakeindex\ program is used to sort the entries.
1365 % %An example is
1366 % %shown in the current version of the Addendum. A recent addition
1367 % Also, the class provides configurable end notes which can be used as well as,
1368 % or instead of, footnotes.
1369
1370
1371 % \section{Miscellaneous}
1372
1373 % % As already noted, the Manual for \Mname\ runs to some 300 pages and it
1374 % %is impossible to cover everything in a short article.
1375 % %Suffice it to say that
1376 % Hooks and macros are provided for most aspects of document layout;
1377 % for instance,
1378 % footnotes can be as normal, typeset in two or three columns, or all run
1379 % into a single paragraph. There is a \cs{sidepar} macro which
1380 % is a non-floating \cs{marginpar} as well as the \cs{sidebar} macro for
1381 % typesetting sidebars in the margin, starting at the top of the text block.
1382 % You can create new verbatim-like environments, read
1383 % and write information in external files, design your own style of
1384 % \cs{maketitle}, convert numbers to words, reserve space at the bottom of a
1385 % page, and so on and so forth.
1386
1387
1388 % %% \appendix
1389 % \section{Packages}
1390
1391 % Most packages work with the \Mname\ class, the main exception being
1392 % the \Lpack{hyperref} package. This package modifies
1393 % many of the internals of the standard classes but does not cater for all of
1394 % the differences between \Mname\ and the standard ones. If you wish to use
1395 % \Lpack{hyperref} with \Mname\ then you must use the \Lpack{memhfixc}
1396 % package\footnote{\Lpack{memhfixc} is supplied as part of the \Mname\
1397 % distribution.} after using \Lpack{hyperref}. For example like:
1398 % \begin{lcode}
1399 % \documentclass[...]{memoir}
1400 % ...
1401 % \usepackage[...]{hyperref}
1402 % \usepackage{memhfixc}
1403 % ...
1404 % \begin{document}
1405 % \end{lcode}
1406 % However, if you have a version of \Lpack{hyperref} dated 2006/11/15 or after,
1407 % \Lpack{hyperref}
1408 % will automatically call in \Lpack{memhfixc} so that you don't have to do
1409 % anything.
1410
1411 % The \Mname\ class includes code either equivalent to, or extensions of, the
1412 % following packages; that is, the set of commands and environments is at least
1413 % the same as those in the packages:
1414 % %\begin{itemize}%\item
1415 % \begin{lineitems}
1416 % \Lpack{abstract}
1417 % \item \Lpack{appendix}
1418 % \item \Lpack{array}
1419 % \item \Lpack{booktabs}
1420 % \item \Lpack{ccaption}
1421 % \item \Lpack{chngcntr}
1422 % \item \Lpack{chngpage}
1423 % \item \Lpack{dcolumn}
1424 % \item \Lpack{delarray}
1425 % \item \Lpack{enumerate}
1426 % \item \Lpack{epigraph}
1427 % \item \Lpack{framed}
1428 % \item \Lpack{ifmtarg}
1429 % \item \Lpack{ifpdf}
1430 % \item \Lpack{index}
1431 % \item \Lpack{makeidx}
1432 % \item \Lpack{moreverb}
1433 % \item \Lpack{needspace}
1434 % \item \Lpack{newfile}
1435 % \item \Lpack{nextpage}
1436 % \item \Lpack{parskip}
1437 % \item \Lpack{patchcmd}
1438 % \item \Lpack{setspace}
1439 % \item \Lpack{shortvrb}
1440 % \item \Lpack{showidx}
1441 % \item \Lpack{tabularx}
1442 % \item \Lpack{titleref}
1443 % \item \Lpack{titling}
1444 % \item \Lpack{tocbibind}
1445 % \item \Lpack{tocloft}
1446 % \item \Lpack{verbatim}
1447 % \item \Lpack{verse}.
1448 % \end{lineitems}
1449 % %\end{itemize}
1450 % The class automatically ignores any
1451 % \verb?\usepackage? or \verb?\RequirePackage? related to these. However, if
1452 % you want to specifically use one of these packages rather than the integrated
1453 % version then you can do so. For arguments sake, assuming you really want
1454 % to use the \Lpack{titling} the package you can do this:
1455 % \begin{lcode}
1456 % \documentclass[...]{memoir}
1457 % \DisemulatePackage{titling}
1458 % \usepackage{titling}
1459 % \end{lcode}
1460
1461 % The \Mname\ class incorporates a version of the \Lpack{setspace} package,
1462 % albeit using different names for the macros. The package enables documents
1463 % to be set double spaced but leaves some document elements,
1464 % like captions for example, single spaced. To do this it has to make some
1465 % assumptions about how the document class works. I felt that this kind
1466 % of capability should be part of the class and not depend on assumptions.
1467 % In the particular case of the \Lpack{setspace} package, even with the
1468 % standard classes, there can be some unexpected spacing around displayed
1469 % material; this has not occured with \Mname's implementation.
1470
1471 % The class also provides functions similar to those provided by the following
1472 % packages, although the commands are different:
1473 % %\begin{itemize}%\item
1474 % \begin{lineitems}%\item
1475 % \Lpack{crop}
1476 % \item \Lpack{fancyhdr}
1477 % \item \Lpack{geometry}
1478 % \item \Lpack{sidecap}
1479 % \item \Lpack{subfigure}
1480 % \item \Lpack{titlesec}.
1481 % \end{lineitems}
1482 % %\end{itemize}
1483 % You can use these packages
1484 % if you wish, or just use the capabilities of the \Mname\ class.
1485
1486
1487 % \section{Resources} \label{sec:resources}
1488
1489
1490 % Scattered throughout
1491 % %, but mainly in Part~\ref{part:art},
1492 % are comments about aspects of book design and typography, in some cases
1493 % accompanied by examples of better and poorer practice. If you want more
1494 % authorative remarks there are several books on the subject listed in
1495 % the \bibname; I prefer
1496 % Bringhurst's \textit{The Elements of Typographic Style}~\cite{BRINGHURST99}.
1497
1498
1499 % \ltx\ is based on the \tx\ program which was designed principally
1500 % for typesetting documents containing a
1501 % lot of mathematics. In such works the mathematics breaks up the flow
1502 % of the text on the page, and the vertical space required for displayed
1503 % mathematics is highly dependent on the mathematical particularities.
1504 % Most non-technical books are typeset on a fixed
1505 % grid as they do not have arbitrary insertions into the text; it is these
1506 % kinds of publications that typographers are most comfortable talking about.
1507
1508 % There are other sources that deal with \ltx\ in
1509 % general, some of which are listed in the \bibname. Lamport~\cite{LAMPORT94}
1510 % is of course the original user manual for \ltx, while the Companion
1511 % series~\cite{COMPANION,GCOMPANION,WCOMPANION} go into further
1512 % details and auxiliary
1513 % programs. George Gr\"{a}tzer's \textit{Math into \ltx} is valuable if you
1514 % typeset a lot of mathematics with excellent coverage of the American
1515 % Mathematical Society's packages.
1516
1517 % The \cTeXan{} (\pixctan) is an invaluable source
1518 % of free information and of the \ltx\ system itself. For general questions see
1519 % the FAQ (Frequently Asked Questions, and answers) maintained by
1520 % Robin Fairbairns~\cite{FAQ}, which also has pointers to many information
1521 % sources. Among
1522 % these are \textit{The Not So Short Introduction to \ltxe}~\cite{LSHORT},
1523 % Keith Reckdahl's \textit{Using imported graphics in \ltxe}~\cite{EPSLATEX}
1524 % and Piet van Oostrum's \textit{Page layout in \ltx}~\cite{FANCYHDR}.
1525 % Peter Flynn's \textit{Formatting information}~\cite{FLYNN02} is unique
1526 % in that it describes how to install a \ltx\ system and editors for
1527 % writing your documents as well as how to use \ltx. There are a myriad
1528 % of packages and software tools freely available to enhance any \ltx\ system;
1529 % the great majority of these are listed in Graham Williams' magnificent
1530 % on line searchable catalogue~\cite{CATALOGUE}, which also links directly
1531 % to \pixctan. This is just one of the services offered by the \TeXUG{} (\pixtug)
1532 % and information on how to access it is available
1533 % at \url{http://www.tug.org}
1534 % which is the homepage for the \TeXUG.
1535
1536 % The most recent crops of messages on the \url{comp.text.tex}
1537 % newsgroup (\pixctt) show an increasing interest in using a wider range
1538 % of fonts with \ltx. This is a question that I have left alone.
1539 % Alan Hoenig's book~\cite{HOENIG98} is the best guide to this that I know of.
1540 % \pixctan\ hosts Philipp Lehman's font installation guide~\cite{FONTINST};
1541 % this is well worth looking at just as an example of fine typesetting.
1542
1543 % The source code for the \Lclass{memoir} class is, of course,
1544 % freely available from \pixctan\ if you wish to see exactly what it does
1545 % and how it does it.
1546
1547 % For a more interactive resource you can ask questions on the
1548 % \url{comp.text.tex} newsgroup. If you are a newcomer to \pixctt\
1549 % please read the FAQ~\cite{FAQ} before asking a question, and also read
1550 % a few day's worth of messages to check that your question hasn't just
1551 % been answered.
1552
1553 % \end{comment}
1554
1555 %#% extend
1556
1557 %#% extstart include intro-8.tex
1558
1559 \svnidlong
1560 {$Ignore: $}
1561 {$LastChangedDate: 2025-11-04 11:23:55 +0100 (Tue, 04 Nov 2025) $}
1562 {$LastChangedRevision: 887 $}
1563 {$LastChangedBy: [email protected] $}
1564
1565 \chapter{Introduction to the eighth edition}
1566
1567 The \Mname\ class and this manual have seen many changes since they
1568 first saw the light of day. The major functions, and extensions to
1569 them, were listed in the various introductions to the previous
1570 editions of this manual and it would now be tedious to read them.
1571
1572 The \Mname\ class was first released in 2001 and since then has proven
1573 to be reasonably popular. The class can be used as a replacement for
1574 the \Lclass{book} and \Lclass{report} classes, by default generating
1575 documents virtually indistinguisable from ones produced by those
1576 classes. The class includes some options to produce documents with
1577 other appearances; for example an \Lclass{article} class look or one
1578 that looks as though the document was produced on a typewriter with a
1579 single font, double spacing, no hyphenation, and so on. In the
1580 following I use the term `standard class'\index{standard class} to
1581 denote the \Lclass{book} and \Lclass{report} classes and, when
1582 appropriate, the \Lclass{article} class as well.
1583
1584 The \Mname\ class includes the functionality of many packages, for
1585 instance the \Lpack{tocloft} package for controlling the table of contents or
1586 methods similar to the \Lpack{fancyhdr} package for designing your own
1587 headers. The built-in package functions are mainly related to document
1588 design and layout; \Mname\ does not touch upon areas like those that are
1589 covered by the \Lpack{babel} or \Lpack{hyperref} packages or any related to
1590 typesetting mathematics. On the other hand it is easy to configure a work
1591 produced with \Mname\
1592 to meet a university's thesis layout requirements.
1593
1594 The \Mname\ class has improved substantially since it was first released ---
1595 over 50 \ltx ers have provided code or suggestions for improvements.
1596 The class is included in the \TeXUG\ \tx\ distributions and the latest
1597 version of the class and its supporting documentation is always
1598 available from %
1599 \ctan\ at \url{latex/contrib/memoir}.
1600
1601 This is not a guide to the general use of \ltx\ but rather concentrates
1602 on where the \index{class}\Lclass{memoir} class differs from the standard \ltx\
1603 \Lclass{book} and \Lclass{report} classes. There are other sources that deal
1604 with \ltx\ in general, some of which are noted later.
1605 I assume that you have already used \ltx\ and therefore know how to prepare
1606 a \ltx\ manuscript, how to run \ltx\ and print the resulting document,
1607 and that you can also use auxiliary programs like \Lmakeindex\
1608 and \Lbibtex.
1609
1610
1611 \section{General considerations}
1612
1613 The class is a large one consisting of about 10,000 lines of \ltx\
1614 code documented in a 400 page report; there is no need for most users
1615 to look at this~\cite{MEMCODE}. However if you want to see exactly how
1616 some part, or all of, \Mname\ is defined it is there for you to
1617 peruse. The document you are now reading is the separate
1618 comprehensive User Manual~\cite{MEMMAN} which runs to about 500 pages,
1619 and from time to time an Addendum %\cite{MEMADD}
1620 is released noting extensions to the class.\footnote{Currently not in
1621 use.} Again, if you want to see how something was done in this
1622 Manual, which of course was prepared using \Mname\ itself, the source
1623 is available for you to read.
1624 % There is also the \Lpack{memexsupp} package by Lars Madsen~\cite{MEMEXSUPP}
1625 % which provides some extra facilities for the class.
1626
1627 The previous editions of the Manual consisted of two parts. The first
1628 discussing some aspects of book design and typography in
1629 general, something that I hadn't come across in the usual \ltx\ books
1630 and manuals. That was intended to provide a little background for when
1631 you design your own printed documents. The second, and by far the longest
1632 part, described the capabilities of \Mname\ and how to use them.
1633
1634 The Manual kept growing until it was approaching 700 pages and I decided
1635 that it was better to put the original discussion on typography into a
1636 separate document~\cite{MEMDESIGN}, which is independent of \Mname, and in this
1637 edition concentrate on how to use \Mname. This has reduced the size of
1638 this document, but it is still large.
1639
1640 This manual is not a \ltx\ tutorial; I assume
1641 that you already know the basics. If you don't then there are several
1642 free tutorials available. In some instances I show you the internal code
1643 for the class which may involve \ltx\ commands that you won't come
1644 across in the tutorials and also sometimes basic \tx\ commands. Information
1645 on these, if you want it, is obtained from reading the \ltx\ source itself
1646 and the \txbook, and perhaps one of the free \tx\ manuals such as
1647 \btitle{TeX for the Impatient}~\cite{IMPATIENT} or
1648 \btitle{TeX by Topic}~\cite{TEXBYTOPIC}.
1649
1650 \section{Class options}
1651
1652 The standard classes provide point options of 10, 11, or 12 points for the
1653 main body font. \Mname\ extends this by also providing a 9 point option, and
1654 options ranging from 14 to 60 points.
1655 The width of the text block is automatically adjusted according to
1656 the selected point size to try and keep within generally accepted
1657 typographical limits for line lengths; you can override this if you wish.
1658 The class also provides easy methods for specifying the
1659 page layout parameters such as the margins --- both the side margins and
1660 those at
1661 the top and bottom of the page; the methods are similar to those of the
1662 \Lpack{geometry} package.
1663
1664 The page layout facilities also include methods, like those provided
1665 by the \Lpack{fancyhdr} package, for defining your own
1666 header and footer styles, and you can have as many different ones as you wish.
1667 In fact the class provides seven styles to choose from before having to
1668 create your own if none of the built-in styles suit you.
1669
1670 Sometimes it is useful, or even required, to place trimming marks on
1671 each page showing the desired size of the final page with respect to the sheet
1672 of paper that is used in the printer. This is provided by the \Lopt{showtrims}
1673 option. A variety of trim marks are provided and you can define your own
1674 if you need some other kind.
1675
1676 \section{Sectioning styles}
1677
1678 Handles are provided for designing and using your own styles for chapter
1679 titles and such. The class comes with over 20 predefined chapter styles ranging
1680 from the default look to a style that mimics that used in the
1681 \emph{Companion} series of \ltx\ books. There are even a couple which use
1682 words instead of numerals for chapter numbers.
1683 % The Manual shows
1684 %examples of these styles and about 30 are shown in Lars
1685 %Madsen's collection~\cite{MEMCHAPS}.
1686
1687 For those who like putting quotations near chapter titles the
1688 \Ie{epigraph} environment can be used.
1689
1690 The options for changing \cs{section} and lower level titles
1691 are more constrained, but generally speaking document design, unless for
1692 advertisements or other eye-catching ephemera, should be constrained.
1693 The class does provide 9 integrated sets of sectional heading styles instead
1694 of the usual single set.
1695
1696 Sometimes, but particularly in novels, a sectional division is indicated
1697 by just leaving a blank line or two between a pair of paragraphs, or there
1698 might be some decorative item like three or four asterisks, or a fleuron
1699 or two. (A \emph{fleuron}\index{fleuron} is a printers ornament looking
1700 like a leaf, such as \ding{166} or \ding{167}.) Commands
1701 are available for typesetting such anonymous divisions.
1702
1703 In the standard classes the sectioning commands have an optional argument
1704 which can be used to put a short version of the section title into the
1705 table of contents and the page header. \Mname\ extends this with a second
1706 optional argument so you can specify one short version for the contents and
1707 an even shorter one for page headers where space is at a premium.
1708
1709 \section{Captions}
1710
1711 \Mname\ incorporates the code from my \Lpack{ccaption} package which
1712 lets you easily modify the appearance of figure and table captions; bilingual
1713 captions are available if required, as are captions placed at the side of
1714 a figure or table or continuation captions from, say, one illustration to
1715 another. Captioning can also be applied
1716 to `non-floating' illustrations or as legends (i.e., unnumbered captions) to
1717 the regular floats. The captioning system
1718 also supports subfigures and subtables along the lines of the \Lpack{subfig}
1719 package, plus letting you define your own new kinds of floats together
1720 with the corresponding `\listofx'.
1721
1722 \section{Tables}
1723
1724 % Code from the \Lpack{array}, \Lpack{dcolumn}, \Lpack{delarray} and
1725 %\Lpack{tabularx} packges is integrated within the class. To improve
1726 %the appearance of rules in tabular material the \Lpack{booktabs}
1727 %package is also included.
1728
1729 The \Lpack{array}, \Lpack{dcolumn}, \Lpack{delarray}, \Lpack{tabularx}
1730 are automatically loaded by the class. In earlier days their code were
1731 embedded into the class, nowadays we just load the respective
1732 packages. To improve the appearance of rules in tabular material the
1733 \Lpack{booktabs} package is also included (as a code copy, this may
1734 change in the future).
1735
1736
1737
1738
1739 Multipage tabulations are often set with the \Lpack{longtable} or
1740 \Lpack{xtab} packages, which can of course be used with the class. For
1741 simple tabulations that may continue from one page to the next, \Mname\
1742 offers a `continuous tabular' environment. This doesn't have all the
1743 flexibility provided by the packages but can often serve instead
1744 of using them.
1745
1746 More interestingly, but more limited, the class provides `automatic
1747 tabulars'. For these you provide a list of simple entries, like a set of names,
1748 and a number of
1749 columns and the entries are automatically put into the appropriate column.
1750 You choose whether the entries should be added row-by-row, like this with
1751 the \cs{autorows} command:
1752
1753 \begin{lcode}
1754 \autorows{c}{5}{l}{one, two, three, four,
1755 five, six, seven, eight, nine, ten,
1756 eleven, twelve, thirteen }
1757 \end{lcode}
1758
1759 \showit{
1760 {\centering
1761 \begin{tabular}{lllll}
1762 one & two & three & four & five \\
1763 six & seven & eight & nine & ten \\
1764 eleven & twelve & thirteen \\
1765 \end{tabular}
1766 \par}
1767 }
1768
1769 Or if you use the \cs{autocols} command the entries are listed
1770 column-by-column, like this :
1771
1772 \begin{lcode}
1773 \autocols{c}{5}{l}{one, two, three, four,
1774 five, six, seven, eight, nine, ten,
1775 eleven, twelve, thirteen }
1776 \end{lcode}
1777
1778 \showit{
1779 {\centering
1780 \begin{tabular}{lllll}
1781 one & four & seven & ten & thirteen \\
1782 two & five & eight & eleven & \\
1783 three & six & nine & twelve & \\
1784 \end{tabular}
1785 \par}
1786 }
1787
1788 \section{Verse}
1789
1790 The standard classes provide a very simple \Ie{verse} environment for
1791 typesetting poetry. This is greatly extended in \Mname. For example in the
1792 standard classes the verse stanzas are at a fixed indentation from the
1793 left margin whereas \Mname\ lets you control the amount of indentation so
1794 that you can make a poem appear optically centered within the textwidth.
1795
1796 Stanzas may be numbered, as can individual lines within a poem. There is
1797 a special environment for stanzas where lines are alternately indented. Also
1798 you can define an indentation pattern for stanzas when this is not regular
1799 as, for example, in a limerick where the 3rd and 4th of the five lines are
1800 indented with respect to the other three as shown below.
1801
1802 \begin{lcode}
1803 \indentpattern{00110}
1804 \begin{verse}
1805 \begin{patverse}
1806 There was a young man of Quebec \\
1807 Who was frozen in snow to his neck. \\
1808 When asked: `Are you friz?' \\
1809 He replied: `Yes, I is, \\
1810 But we don't call this cold in Quebec.'
1811 \end{patverse}
1812 \end{verse}
1813 \end{lcode}
1814
1815 \showit{
1816 \begin{verse}
1817 There was a young man of Quebec \\
1818 Who was frozen in snow to his neck. \\
1819 \hspace*{2em}When asked: `Are you friz?' \\
1820 \hspace*{2em}He replied: `Yes, I is, \\
1821 But we don't call this cold in Quebec.'
1822 \end{verse}
1823 }
1824
1825 It is not always possible to fit
1826 a line into the available space and you can specify the particular indentation
1827 to be used when a `logical' verse line spills over the available textwidth,
1828 thus forming two or more typeset `physical' lines. On other occasions
1829 where there are two half lines the poet might want the second half line
1830 to start where the first one finished, like this:
1831
1832 \begin{lcode}
1833 \begin{verse}
1834 Come away with me. \\
1835 \vinphantom{Come away with me.} Impossible!
1836 \end{verse}
1837 \end{lcode}
1838
1839 \showit{
1840 \begin{verse}
1841 Come away with me. \\
1842 \leavevmode\phantom{Come away with me.} Impossible!
1843 \end{verse}
1844 }
1845
1846
1847 \section{End matter}
1848
1849 Normally appendices come after the main body of a book. The class provides
1850 various methods for introducing appendices at the end, or you can place one or
1851 more appendices at the end of selected chapters if that suits you better.
1852
1853 \Mname\ also lets you have more than one index and an index can be set in
1854 either the normal double column style or as a single column which would be more
1855 appropriate, say, for an index of first lines in a book of poetry. The titles
1856 of any bibliography or indexes are added to the table of contents, but you
1857 can prevent this if you wish.
1858
1859 The class provides a set of tools for making glossaries or lists of
1860 symbols, the appearance of which can, of course, be easily altered. The
1861 \Lmakeindex\ program is used to sort the entries.
1862 %An example is
1863 %shown in the current version of the Addendum. A recent addition
1864 Also, the class provides configurable end notes which can be used as well as,
1865 or instead of, footnotes.
1866
1867
1868 \section{Miscellaneous}
1869
1870 % As already noted, the Manual for \Mname\ runs to some 300 pages and it
1871 %is impossible to cover everything in a short article.
1872 %Suffice it to say that
1873 Hooks and macros are provided for most aspects of document layout;
1874 for instance,
1875 footnotes can be as normal, typeset in two or three columns, or all run
1876 into a single paragraph. There is a \cs{sidepar} macro which
1877 is a non-floating \cs{marginpar} as well as the \cs{sidebar} macro for
1878 typesetting sidebars in the margin, starting at the top of the text block.
1879 You can create new verbatim-like environments, read
1880 and write information in external files, design your own style of
1881 \cs{maketitle}, convert numbers to words, reserve space at the bottom of a
1882 page, and so on and so forth.
1883
1884
1885 %% \appendix
1886 \section{Packages}
1887
1888 Most packages work with the \Mname\ class, the main exception being
1889 the \Lpack{hyperref} package. This package modifies many of the
1890 internals of the standard classes but does not cater for all of the
1891 differences between \Mname\ and the standard ones.
1892
1893 If you use \Lpack{hyperref} with \Mname\ then the \Lpack{memhfixc}
1894 package\footnote{\Lpack{memhfixc} is supplied as part of the \Mname\
1895 distribution.} is automatically loaded by \Lpack{hyperref} to
1896 provide some class specific alterations.
1897 % For example like:
1898 % \begin{lcode}
1899 % \documentclass[...]{memoir}
1900 % ...
1901 % \usepackage[...]{hyperref}
1902 % \usepackage{memhfixc}
1903 % ...
1904 % \begin{document}
1905 % \end{lcode}
1906 % However, if you have a version of \Lpack{hyperref} dated 2006/11/15 or after,
1907 % \Lpack{hyperref}
1908 % will automatically call in \Lpack{memhfixc} so that you don't have to do
1909 % anything.
1910
1911 The \Mname\ class includes code either equivalent to, or extensions of, the
1912 following packages; that is, the set of commands and environments is at least
1913 the same as those in the packages:
1914 %\begin{itemize}%\item
1915 \begin{adjustwidth}{2em}{2em}
1916 \begin{center}
1917 \begin{lineitems}
1918 \Lpack{abstract}
1919 \item \Lpack{appendix}
1920 % \item \Lpack{array}
1921 \item \Lpack{booktabs}
1922 \item \Lpack{ccaption}
1923 \item \Lpack{chngcntr}
1924 \item \Lpack{chngpage}
1925 % \item \Lpack{dcolumn}
1926 % \item \Lpack{delarray}
1927 \item \Lpack{enumerate}
1928 \item \Lpack{epigraph}
1929 \item \Lpack{framed}
1930 \item \Lpack{ifmtarg}
1931 % \item \Lpack{ifpdf}
1932 \item \Lpack{index}
1933 \item \Lpack{makeidx}
1934 \item \Lpack{moreverb}
1935 \item \Lpack{needspace}
1936 \item \Lpack{newfile}
1937 \item \Lpack{nextpage}
1938 \item \Lpack{parskip}
1939 \item \Lpack{patchcmd}
1940 \item \Lpack{setspace}
1941 %\item \Lpack{shortvrb}
1942 \item \Lpack{showidx}
1943 % \item \Lpack{tabularx}
1944 \item \Lpack{titleref}
1945 \item \Lpack{titling}
1946 \item \Lpack{tocbibind}
1947 \item \Lpack{tocloft}
1948 \item \Lpack{verbatim}
1949 \item \Lpack{verse}.
1950 \end{lineitems}
1951 \end{center}
1952 \end{adjustwidth}
1953 % \end{itemize}
1954
1955 The class automatically ignores any
1956 \verb?\usepackage? or \verb?\RequirePackage? related to these. However, if
1957 you want to specifically use one of these packages rather than the integrated
1958 version then you can do so. For arguments sake, assuming you really want
1959 to use the \Lpack{titling} package you can do this:
1960 \begin{lcode}
1961 \documentclass[...]{memoir}
1962 \DisemulatePackage{titling}
1963 \usepackage{titling}
1964 \end{lcode}
1965
1966 The \Mname\ class incorporates a version of the \Lpack{setspace} package,
1967 albeit using different names for the macros. The package enables documents
1968 to be set double spaced but leaves some document elements,
1969 like captions for example, single spaced. To do this it has to make some
1970 assumptions about how the document class works. I felt that this kind
1971 of capability should be part of the class and not depend on assumptions.
1972 In the particular case of the \Lpack{setspace} package, even with the
1973 standard classes, there can be some unexpected spacing around displayed
1974 material; this has not occured with \Mname's implementation.
1975
1976 The class also provides functions similar to those provided by the following
1977 packages, although the commands are different:
1978 %\begin{itemize}%\item
1979 \begin{center}
1980 \begin{lineitems}%\item
1981 \Lpack{crop}
1982 \item \Lpack{fancyhdr}
1983 \item \Lpack{geometry}
1984 \item \Lpack{sidecap}
1985 \item \Lpack{subfigure}
1986 \item \Lpack{titlesec}.
1987 \end{lineitems}
1988 \end{center}
1989 %\end{itemize}
1990
1991 The class has built in support for the \Lpack{bidi} package for
1992 bidirectional typesetting~\cite{BIDI}.
1993
1994 The following packages are automatically loaded by the class:
1995 \begin{center}
1996 \begin{lineitems}
1997 \Lpack{array}
1998 \item \Lpack{dcolumn}
1999 \item \Lpack{delarray}
2000 % \item \Lpack{etex}
2001 % \item \Lpack{ifetex}
2002 % \item \Lpack{ifxetex}
2003 % \item \Lpack{ifpdf}
2004 % \item \Lpack{ifluatex}
2005 \item \Lpack{iftex}
2006 \item \Lpack{tabularx}
2007 \item \Lpack{textcase}~(with~\texttt{overload}~option)
2008 \item \Lpack{xpatch}~(it~autoloads~\Lpack{etoolbox})
2009 \item \Lpack{booktabs}
2010 \item \Lpack{nameref}
2011 \item \Lpack{mparhack}~(if~twocolumn)
2012 \item \Lpack{memhfixc}~(if~\Lpack{hyperref}~is~loaded)
2013 \item \Lpack{shortvrb}
2014 \end{lineitems}
2015 \end{center}
2016
2017 \section{Resources} \label{sec:resources}
2018
2019
2020 Scattered throughout
2021 %, but mainly in Part~\ref{part:art},
2022 are comments about aspects of book design and typography, in some cases
2023 accompanied by examples of better and poorer practice. If you want more
2024 comments and examples there are some notes on the topic~\cite{MEMDESIGN},
2025 and for
2026 authorative remarks there are several books on the subject listed in
2027 the \bibname; I prefer
2028 Bringhurst's \textit{The Elements of Typographic Style}~\cite{BRINGHURST99},
2029 while Derek Birdsall's \textit{notes on book design}~\cite{BIRDSALL04}
2030 is much more oriented to illustrated works, like museum
2031 catalogues and art books.
2032
2033
2034 \ltx\ is based on the \tx\ program which was designed principally
2035 for typesetting documents containing a
2036 lot of mathematics. In such works the mathematics breaks up the flow
2037 of the text on the page, and the vertical space required for displayed
2038 mathematics is highly dependent on the mathematical particularities.
2039 Most non-technical books are typeset on a fixed
2040 grid as they do not have arbitrary insertions into the text; it is these
2041 kinds of publications that typographers are most comfortable talking about.
2042
2043 There are other sources that deal with \ltx\ in
2044 general, some of which are listed in the \bibname. Lamport~\cite{LAMPORT94}
2045 is of course the original user manual for \ltx, while the Companion
2046 series~\cite{COMPANION,GCOMPANION,WCOMPANION,TLC3} go into further
2047 details and auxiliary
2048 programs. George Gr\"{a}tzer's \textit{Math into \ltx} is valuable if you
2049 typeset a lot of mathematics with excellent coverage of the American
2050 Mathematical Society's packages.
2051
2052 The \cTeXan{} (\pixctan) is an invaluable source
2053 of free information and of the \ltx\ system itself. For general questions see
2054 the FAQ (Frequently Asked Questions, and answers) maintained by
2055 Robin Fairbairns~\cite{FAQ}, which also has pointers to many information
2056 sources. Among
2057 these are \textit{The Not So Short Introduction to \ltxe}~\cite{LSHORT},
2058 Keith Reckdahl's \textit{Using imported graphics in \ltxe}~\cite{EPSLATEX}
2059 and Piet van Oostrum's \textit{Page layout in \ltx}~\cite{FANCYHDR}.
2060 Peter Flynn's \textit{Formatting information}~\cite{FLYNN02} is unique
2061 in that it describes how to install a \ltx\ system and editors for
2062 writing your documents as well as how to use \ltx. There are a myriad
2063 of packages and software tools freely available to enhance any \ltx\ system;
2064 the great majority of these are listed in Graham Williams' magnificent
2065 on line searchable catalogue~\cite{CATALOGUE}, which also links directly
2066 to \pixctan. This is just one of the services offered by the \TeXUG{} (\pixtug)
2067 and information on how to access it is available
2068 at \url{http://www.tug.org}
2069 which is the homepage for the \TeXUG.
2070
2071 The most recent crops of messages on the \url{comp.text.tex}
2072 newsgroup (\pixctt) show an increasing interest in using a wider range
2073 of fonts with \ltx. This is a question that I have left alone.
2074 Alan Hoenig's book~\cite{HOENIG98} is the best guide to this that I know of.
2075 \pixctan\ hosts Philipp Lehman's font installation guide~\cite{FONTINST};
2076 this is well worth looking at just as an example of fine typesetting.
2077
2078 The source code for the \Lclass{memoir} class is, of course,
2079 freely available from \pixctan\ if you wish to see exactly what it does
2080 and how it does it.
2081
2082 For a more interactive resource you can ask questions on
2083 \begin{center}
2084 \url{http://tex.stackexchange.com}.
2085 \end{center}
2086 -- if the question is \Mname\ related, please tag it so.
2087
2088
2089
2090 % For a more interactive resource you can ask questions on the
2091 % \url{comp.text.tex} newsgroup. If you are a newcomer to \pixctt\
2092 % please read the FAQ~\cite{FAQ} before asking a question, and also read
2093 % a few day's worth of messages to check that your question hasn't just
2094 % been answered.
2095
2096 \section{Type conventions}
2097
2098 The following conventions are used:
2099 \begin{itemize}
2100 \item \Pclass{The names of \ltx\ classes\index{class} and
2101 packages\index{package} are typeset in this font.}
2102 \item \Popt{Class options\index{option} are typeset in this font.}
2103 \item \Ppstyle{The names of chapterstyles\index{chapterstyle} and
2104 pagestyles\index{pagestyle} are typeset in this font.}
2105 \item \texttt{\ltx\ code is typeset in this font.}
2106 \item \Pprog{The names of programs are in this font.}
2107 \end{itemize}
2108 \begin{syntax}
2109 Macro command syntax is enclosed in a rectangular box.\\
2110 For referential purposes, arguments are denoted by \meta{arg} \\
2111 \end{syntax}
2112
2113
2114 \section{Acknowledgements}
2115
2116 Many people have contributed to the \Lclass{memoir} class and this manual
2117 in the forms of code, solutions to problems, suggestions for new functions,
2118 bringing my attention to errors and infelicities in the code
2119 and manual, and last but not least in simply being encouraging.
2120 I am very grateful to the following for all they have done, whether they
2121 knew it or not:
2122 Paul Abrahams, % code
2123 William Adams, % typography
2124 Tim Arnold, % among other things, \leavespergathering in general
2125 Donald Arseneau, % code
2126 Stephan von Bechtolsheim,
2127 Jens Berger,
2128 Karl Berry, % code
2129 Ingo Beyritz, % bug report (tabularx in subtable)
2130 Javier Bezos,
2131 Stefano Bianchi, % chaptersytyle
2132 Sven Bovin,
2133 Alan Budden,
2134 Ignasi Furi\'{o} Caldentey,
2135 Ezequiel Mart\'{\i}n C\'{a}mara,
2136 David Carlisle, % code
2137 Gustafo Cevolani,
2138 Jean-C{\^o}me Charpentier, % memmanadd typo fix
2139 Michael A. Cleverly, % code
2140 Steven Douglas Cochran, % code
2141 Frederic Connes, % code
2142 \v{Z}arko F. \v{C}u\v{c}ej, % bug report (contcaption & hyperref)
2143 Christopher Culver, % chapterstyle
2144 Iain Dalton, % typos
2145 Michael W. Daniels, % code
2146 Michael Downes, % code
2147 Christopher Dutchyn,
2148 Thomas Dye, % code, typos
2149 Victor Eijkhout, % code
2150 Roman Eisele, % fix of \parnopar (2008/09/13)
2151 Danie Els, % code
2152 Robin Fairbairns, % code
2153 Simon Fear, % code
2154 Ant\'{o}nio Ferreira, % many typos (2008/08/29)
2155 Kai von Fintel,
2156 Ivars Finvers, % bug report
2157 Ulrike Fischer, % general code ideas
2158 Matthew Ford,
2159 Musa Furber,
2160 Daniel Richard G,
2161 Ignacio Fern{\'a}ndez Galv{\'a}n,
2162 Gerardo Garcia, % chapterstyle
2163 Romano Giannetti, % code
2164 Kheng-Swee Goh, % manual typo `docotoral' should be `doctoral'
2165 Donald Goodman, % manual typo (1/2 title page should be in pagination)
2166 Gabriel Guernik, % bug report & suggested fix
2167 Matthias Haldiman, % bug report, fixed by Heiko
2168 Kathryn Hargreaves, % code
2169 Sven Hartrumpf,
2170 hazydirk, % code
2171 Carsten Heinz, % code
2172 Florence Henry,
2173 Peter Heslin,
2174 Timo Hoenig, % thank you letter
2175 Morten H{\o}gholm, % code
2176 Henrik Holm,
2177 Vladimir G. Ivanovi\'c,
2178 Martin J{\o}rgensen, % bug report
2179 Stefan Kahrs,
2180 Christian Keil, % typos
2181 Marcus Kohm, % algorithm
2182 Flavian Lambert, % float type bug
2183 J\o{}gen Larsen, % bug reports and fix
2184 Kevin Lin,
2185 Matthew Lovell,
2186 Daniel Luecking, % codef
2187 Anders Lyhne, % chapterstyle
2188 Lars Hendrik Gam Madsen, % extra space in Part title in ToC
2189 Lars~Madsen, % code
2190 Vittorio De Martino,
2191 Ben McKay, % errors in pagenote instructions
2192 Frank~Mittelbach, % code
2193 Wilhelm M\"{u}ller, % bugs & suggested extensions
2194 Vilar~Camara~Neto,
2195 Rolf Niepraschk,
2196 Patrik Nyman,
2197 Heiko~Oberdiek, % code
2198 Scott~Pakin,
2199 Adriano~Pascoletti,
2200 Paul, % bug report
2201 Ted Pavlic, % typo report
2202 Troels Pedersen, % chapterstyle
2203 Steve Peter,
2204 Fran\c{c}ois Poulain, % typo in Magellan's voyage title
2205 Erik Quaeghebeur, % bug report
2206 Bernd Raichle, % code
2207 Martin Reinders, % requested titleref extensions
2208 Aaron Rendahl, % bug report and fix
2209 Ren{\'e}, % correction (paper folding)
2210 Alan Ristow, % request for \leavespergathering
2211 Robert,
2212 Chris Rowley,
2213 Gary Ruben, % bug report
2214 Robert Schlicht, % code
2215 Doug Schenck,
2216 Dirk Schlimm,
2217 Arnaud Schmittbuhl,
2218 Rainer Sch\"{o}pf, % code
2219 Paul Stanley,
2220 Per Starb{\"a}ck, % boxedverbatim in narrow text bug, documentation
2221 James Szinger, % code
2222 Jens Taprogge,
2223 Ajit Thakkar, % reference to an appendix, typo
2224 Scott Thatcher, % chapterstyle
2225 Reuben Thomas,
2226 Bastiaan Niels Veelo, % code
2227 Guy Verville, % chapterstyle
2228 Emanuele Vicentini,
2229 J{\"o}rg Vogt, % suggestion re verse
2230 J\"{u}rgen Vollmer,
2231 M J Williams, % \input in tabular bug
2232 and
2233 David Wilson.
2234
2235
2236
2237
2238 If I have inadvertently left anyone off the list I apologise,
2239 and please let me know so that I can correct the
2240 omisssion.% \footnote{Peter is currently occasionably reachable via email
2241 % at \texttt{herries dot press (at) earthlink dot net}, otherwise write
2242 % the maintainer at \texttt{daleif at math dot au dot dk}}
2243 \footnote{Please write the maintainer at \texttt{daleif at math dot au
2244 dot dk}} Along those lines, if you have any questions you may
2245 %direct them to the \url{comp.text.tex} newsgroup or
2246 post them on
2247 \url{http://tex.stackexchange.com} as you are likely to get a
2248 satisfactory and timely response.
2249
2250 Of course, none of this would have been possible without Donald Knuth's
2251 \tx\ system and the subsequent development of \ltx\ by Leslie Lamport.
2252
2253 \PWnote{2009/07/26}{Added `Remarks to the user' chapter}
2254 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2255 \chapter{Remarks to the user}
2256 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2257
2258 The \Lclass{memoir} class gives you many ways to change the appearance of your
2259 document, and also provides some ready-made styles that might be
2260 appropriate for your purposes.
2261
2262 As you can see, this manual is not slim and attempts to describe in
2263 some detail how the various aspects of \Lclass{memoir} work and gives
2264 examples of how you can change these to better match your needs. However,
2265 there are a myriad of different things that users might wish to do and
2266 it is not possible either for the class to provide ready made simple,
2267 or even complex, methods to directly support these, or for this manual
2268 to give examples of how everything might be accomplished.
2269
2270 If many want a particular facility that is not available, then it
2271 may be possible to add that. If it is only one who wishes it then, unless
2272 the one is the author, it is unlikely to be provided. But don't let this stop
2273 you from asking, especially if you can provide the necessary code.
2274
2275 The complete documented code for the class is available in the file
2276 \file{memoir.dtx}. If you want to know how something is done then you
2277 can read the code for \emph{all} the details. If you want to do something
2278 different, then the code is there for you to look at and experiment with.
2279 You should, though, not change any of the code in the class. If you need
2280 to do so, then copy the code you wish to change into the document's preamble
2281 or a package of your own or a class of your own (with a different name)
2282 and make the changes there. Do not expect any help if you change the
2283 \Lclass{memoir} class code directly.
2284
2285 \fancybreak{}
2286
2287 As the years go by support for \Lclass{memoir} will devolve from one
2288 person to another.\footnote{Lars Madsen took over from Peter Wilson in
2289 2009.} Therefore it is
2290 probably safer to ask questions, complain, make suggestions, etc., on
2291 a Q\&A site like \url{http://tex.stackexchange.com}% or on the the
2292 % newsgroup \url{comp.text.tex}
2293 , which is archived and read by many,
2294 than correspond directly with the maintainer, who might well be away
2295 for some considerable time and perhaps not notice your email after
2296 having returned to base.
2297
2298 In either case please include the word \texttt{\theclass} in the
2299 subject, and if possible, please \emph{tag} the question with the
2300 \texttt{\theclass} tag. That will help the memoir maintainer keep
2301 track of memoir related matters.
2302
2303 \fancybreak{}
2304
2305 Most \Mname\ related questions should go to
2306 \url{http://tex.stackexchange.com}, please remember to tag them
2307 properly, that really helps locating the \Mname\ related questions. If
2308 no-one comes up with an answer, you can also write the maintainer
2309 directly via \texttt{daleif (at) math dot au dot dk}.
2310
2311 See also \emph{\titleref{cha:remarks-from-maint}} on
2312 \pref{cha:remarks-from-maint} for furher information from the
2313 maintainer.
2314
2315
2316 %#% extend
2317
2318
2319 %#% extstart include terminology.tex
2320
2321 \svnidlong
2322 {$Ignore: $}
2323 {$LastChangedDate: 2013-04-24 17:14:15 +0200 (Wed, 24 Apr 2013) $}
2324 {$LastChangedRevision: 442 $}
2325 {$LastChangedBy: daleif $}
2326
2327 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2328 \chapter{Terminology}
2329 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2330
2331 Like all professions and trades, typographers and printers have their
2332 specialised vocabulary.
2333
2334 First there is the question of pages, leaves and sheets.
2335 The trimmed sheets of paper\index{paper} that make up a book are called
2336 \emph{leaves}\index{leaf},
2337 and I will call the untrimmed sheets the \emph{stock}\index{stock} material.
2338 A leaf
2339 has two sides, and a \emph{page}\index{page} is one side of a leaf.
2340 If you think of a book
2341 being opened flat, then you can see two leaves. The front of the righthand
2342 leaf, is called the \emph{recto}\index{recto} page of that leaf,
2343 and the side of the
2344 lefthand leaf that you see is called the \emph{verso}\index{verso} page
2345 of that leaf.
2346 So, a leaf has a recto and a verso page. Recto pages are the odd-numbered
2347 pages and verso pages are even-numbered.
2348
2349 Then there is the question of folios. The typographical term for
2350 the number of a page is \emph{folio}\index{folio}.
2351 This is not to be confused with
2352 the same term as used in `Shakespeare's First Folio' where the reference is
2353 to the height and width of the book, nor to its use in the phrase
2354 `\emph{folio} signature'\index{signature} where the term refers to the
2355 number of times a printed sheet is folded.
2356 Not every page in a book has a printed
2357 folio, and there may be pages that do not have a folio at all. Pages with
2358 folios, whether printed or not, form the \emph{pagination}\index{pagination}
2359 of the book. Pages
2360 that are not counted in the pagination have no folios.
2361
2362 I have not been able to find what I think is a good
2363 definition for `type' as it seems to be used in different contexts with
2364 different meanings. It appears to be a kind of generic word; for instance
2365 there are type designers, type cutters, type setters, type foundries,...
2366 For my purposes I propose that \emph{type}\index{type|seealso{typeface}} is
2367 one or more printable characters (or variations or extensions to this idea).
2368 Printers use the term \emph{sort}\index{sort} to refer to one piece of lead
2369 type.
2370
2371 A \emph{typeface}\index{typeface} is a set of one or more fonts, in one
2372 or more sizes, designed as a stylistic whole.
2373
2374 A \emph{font}\index{font} is a set of characters. In the days of
2375 metal type and hot lead a font meant a complete alphabet and auxiliary
2376 characters in a given size. More recently it is taken to mean a complete
2377 set of characters regardless of size. A font of roman type normally
2378 consists of CAPITAL LETTERS, \textsc{small capitals}, lowercase letters,
2379 numbers, punctuation marks, ligatures (such as `fi' and `ffi'), and a
2380 few special symbols like \&.
2381
2382 A \emph{font family}\index{font!family} is a set of fonts designed to
2383 work harmoniously together, such as a pair of roman and italic fonts.
2384
2385 The size of a font\index{font} is expressed in points\index{point}
2386 (72.27 points equals 1 inch
2387 equals 25.4 millimeters). The size is a rough indication of the height
2388 of the tallest character, but different fonts with the same size may have
2389 very different actual heights. Traditionally font sizes were referred to
2390 by names (see \tref{tab:fontsizes}) but nowadays just the number of points
2391 is used.
2392
2393
2394 \begin{table}
2395 \centering
2396 \caption{Traditional font size designations} \label{tab:fontsizes}
2397 \begin{tabular}{cl@{\hspace{2em}}cl} \toprule
2398 Points & Name & Points & Name \\ \midrule
2399 %%3 & Excelsior \\
2400 \phantom{0}3 & Excelsior &
2401 11 & Small Pica \\
2402 \phantom{0}3\rlap{\slashfrac{1}{2}} & Brilliant &
2403 12 & Pica \\
2404 \phantom{0}4 & Diamond &
2405 14 & English \\
2406 \phantom{0}5 & Pearl &
2407 18 & Great Primer \\
2408 \phantom{0}5\rlap{\slashfrac{1}{2}} & Agate &
2409 24 & Double (or Two Line) Pica \\
2410 \phantom{0}6 & Nonpareil &
2411 28 & Double (or Two Line) English \\
2412 \phantom{0}6\rlap{\slashfrac{1}{2}} & Mignonette &
2413 36 & Double (or Two Line) Great Primer \\
2414 \phantom{0}7 & Minion &
2415 48 & French Canon (or Four Line Pica) \\
2416 \phantom{0}8 & Brevier &
2417 60 & Five Line Pica \\
2418 \phantom{0}9 & Bourgeois &
2419 72 & Six line Pica \\
2420 10 & Long Primer &
2421 %%16 & Columbian \\
2422 %%20 & Paragon \\
2423 %%22 & Double Small Pica \\
2424 %%32 & Four Line Brevier \\
2425 %%40 & Double Paragon \\
2426 %%44 & Meridian \\
2427 96 & Eight Line Pica \\ \bottomrule
2428 \end{tabular}
2429 \end{table}
2430
2431
2432
2433 The typographers' and printers' term for the vertical space between
2434 the lines of normal text is \emph{leading}\index{leading}, which is also
2435 usually expressed in points and is usually larger than the font size.
2436 A convention for describing the font and leading is to give the font size
2437 and leading separated by a slash; for instance $10/12$ for a
2438 10pt font set with a 12pt leading, or $12/14$ for a 12pt font set with a
2439 14pt leading.
2440
2441 The normal length of a line of text is often called the
2442 \emph{measure}\index{measure} and is normally specified in terms of
2443 picas\index{pica} where 1 pica equals 12 points (1pc = 12pt).
2444
2445 Documents may be described as being typeset with a particular font
2446 with a particular size and a particular leading on a particular measure;
2447 this is normally given in a shorthand form.
2448 A 10pt font with 11pt leading on a 20pc measure is described as
2449 \abyb{10/11}{20}, and \abyb{14/16}{22} describes a 14pt font
2450 with 16pt leading set on a a 22pc measure.
2451
2452 \section{Units of measurement}
2453
2454 Typographers and printers use a mixed system of units, some of which
2455 we met above. The fundamental unit is the point; \tref{tab:units} lists
2456 the most common units employed.
2457
2458 \begin{table}
2459 \centering
2460 \caption{Printers units} \label{tab:units}
2461 \begin{tabular}{ll} \toprule
2462 Name (abbreviation) & Value \\ \midrule
2463 point (pt)\index{point}\index{pt} & \\
2464 pica (pc)\index{pica}\index{pc} & 1pc = 12pt \\
2465 inch (in)\index{inch}\index{in} & 1in = 72.27pt \\
2466 centimetre (cm)\index{centimetre}\index{cm} & 2.54cm = 1in \\
2467 millimetre (mm)\index{millimetre}\index{mm} & 10mm = 1cm \\
2468 big point (bp)\index{big point}\index{bp} & 72bp = 72.27pt \\
2469 didot point (dd)\index{didot point}\index{dd} & 1157dd = 1238pt \\
2470 cicero (cc)\index{cicero}\index{cc} & 1cc = 12dd \\
2471 \bottomrule
2472 \end{tabular}
2473 \end{table}
2474
2475 Points\index{point} and picas\index{pica}
2476 are the traditional printers units used in English-speaking countries.
2477 The didot point\index{didot point} and cicero\index{cicero} are the
2478 corresponding units used in continental Europe. In Japan `kyus'\index{kyus}
2479 (a quarter of a millimetre) may be used as the unit of measurement.
2480 Inches\index{inch} and centimetres\index{centimetre} are the units that we
2481 are all, or should be, familiar with.
2482
2483 The point system was invented by Pierre Fournier le jeune in 1737 with
2484 a length of 0.349mm. Later in the same century Fran\c{c}ois-Ambroise Didot
2485 introduced his point system with a length of 0.3759mm. This is the value
2486 still used in Europe. Much later, in 1886, the American Type Founders
2487 Association settled on 0.013837in as the standard size for the point, and
2488 the British followed in 1898. Conveniently for those who are not entirely
2489 metric in their thinking this means that
2490 six picas are approximately equal to one inch.
2491
2492 The big point\index{big point}
2493 is somewhat of an anomaly in that it is a recent
2494 invention. It tends to be used
2495 in page markup languages, like \pscript\footnote{\pscript{} is a
2496 registered trademark of Adobe Systems Incorporated.\label{fn:ps}},
2497 in order to make calculations quicker and easier.
2498
2499 The above units are all constant in value. There are also some units
2500 whose value depends on the particular font\index{font} being used.
2501 The \textit{em}\index{em}
2502 is the nominal height of the current font; it is used as a width measure.
2503 An \textit{en}\index{en} is half an em.
2504 The \textit{ex}\index{ex} is
2505 nominally the height of the letter `x' in the current font. You may also
2506 come across the term \textit{quad}\index{quad}, often as in a phrase
2507 like `starts with a quad space'. It is a length defined in terms of
2508 an em, often a quad is 1em.
2509
2510
2511 %#% extend
2512
2513 \cleardoublepage
2514 \pagenumbering{arabic}
2515
2516 % body
2517 \mainmatter
2518
2519
2520 %%%%%%%%%%%%%%%%%%%%%%%%%%%%
2521 %%%%%\part{Practice} \label{part:practice}
2522 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2523
2524 %#% extstart include start-off.tex
2525
2526
2527 \svnidlong
2528 {$Ignore: $}
2529 {$LastChangedDate: 2024-02-15 12:01:51 +0100 (Thu, 15 Feb 2024) $}
2530 {$LastChangedRevision: 820 $}
2531 {$LastChangedBy: [email protected] $}
2532
2533 \chapter{Starting off} \label{chap:starting}
2534
2535
2536 As usual, the \Lclass{memoir} class is called by
2537 \cmd{\documentclass}\oarg{options}\texttt{\{memoir\}}. The \meta{options}\index{class options}
2538 include being able to select a paper\indextwo{paper}{size} size from among a range of sizes,
2539 selecting a type size, selecting the kind of manuscript, and some related
2540 specifically to the typesetting of mathematics.
2541
2542 \section{Stock paper size options}
2543
2544 The stock\indextwo{stock}{size} size is the size of a single sheet of the
2545 paper\index{paper} you expect to put through the printer. There is a range of
2546 stock\indextwo{stock}{size} paper sizes from which to make a selection.
2547 These are listed in\index{class options!stock size} \tref{tab:sizeoptsmetric}
2548 through \tref{tab:sizeoptsbrit}. Also
2549 included in the tables are commands that will set the stock size or paper size to
2550 the same dimensions.
2551
2552 \begin{note}
2553 Note that the \cs{stock...} macros set \cs{stockheight} and
2554 \cs{stochwidth} if executed. Similarily \cs{page...} commands sets
2555 \cs{pageheight} and \cs{pagewidth}.
2556 \end{note}
2557
2558
2559
2560 \begin{table}
2561 \centering
2562 \caption{Class stock metric paper size options, and commands}\label{tab:sizeoptsmetric}
2563 \begin{tabular}{llll} \toprule
2564 Option & Size & stock size command & page size command \\ \midrule
2565 \Lopt{a7paper}\index{paper!size!A7}\index{stock!size!A7}
2566 & \abybm{105}{74}{mm} & \cmd{\stockavii} & \cmd{\pageavii} \\
2567 \Lopt{a6paper}\index{paper!size!A6}\index{stock!size!A6}
2568 & \abybm{148}{105}{mm} & \cmd{\stockavi} & \cmd{\pageavi} \\
2569 \Lopt{a5paper}\index{paper!size!A5}\index{stock!size!A5}
2570 & \abybm{210}{148}{mm} & \cmd{\stockav} & \cmd{\pageav} \\
2571 \Lopt{a4paper}\index{paper!size!A4}\index{stock!size!A4}
2572 & \abybm{297}{210}{mm} & \cmd{\stockaiv} & \cmd{\pageaiv} \\
2573 \Lopt{a3paper}\index{paper!size!A3}\index{stock!size!A3}
2574 & \abybm{420}{297}{mm} & \cmd{\stockaiii} & \cmd{\pageaiii} \\
2575 \Lopt{b7paper}\index{paper!size!B7}\index{stock!size!B7}
2576 & \abybm{125}{88}{mm} & \cmd{\stockbvii} & \cmd{\pagebvii} \\
2577 \Lopt{b6paper}\index{paper!size!B6}\index{stock!size!B6}
2578 & \abybm{176}{125}{mm} & \cmd{\stockbvi} & \cmd{\pagebvi} \\
2579 \Lopt{b5paper}\index{paper!size!B5}\index{stock!size!B5}
2580 & \abybm{250}{176}{mm} & \cmd{\stockbv} & \cmd{\pagebv} \\
2581 \Lopt{b4paper}\index{paper!size!B4}\index{stock!size!B4}
2582 & \abybm{353}{250}{mm} & \cmd{\stockbiv} & \cmd{\pagebiv} \\
2583 \Lopt{b3paper}\index{paper!size!B3}\index{stock!size!B3}
2584 & \abybm{500}{353}{mm} & \cmd{\stockbiii} & \cmd{\pagebiii} \\
2585 \Lopt{mcrownvopaper}\index{paper!size!metric crown octavo}\index{stock!size!metric crown octavo}
2586 & \abybm{186}{123}{mm} & \cmd{\stockmetriccrownvo} & \cmd{\pagemetriccrownvo} \\
2587 \Lopt{mlargecrownvopaper}\index{paper!size!metric large crown octavo}\index{stock!size!metric large crown octavo}
2588 & \abybm{198}{129}{mm} & \cmd{\stockmlargecrownvo} & \cmd{\pagemlargecrownvo} \\
2589 \Lopt{mdemyvopaper}\index{paper!size!metric demy octavo}\index{stock!size!metric demy octavo}
2590 & \abybm{216}{138}{mm} & \cmd{\stockmdemyvo} & \cmd{\pagemdemyvo} \\
2591 \Lopt{msmallroyalvopaper}\index{paper!size!metric small royal octavo}\index{stock!size!metric small royal octavo}
2592 & \abybm{234}{156}{mm} & \cmd{\stockmsmallroyalvo} & \cmd{\pagemsmallroyalvo} \\
2593 \bottomrule
2594 \end{tabular}
2595 \glossary(a6paperco)%
2596 {\Popt{a6paper}}%
2597 {Class option for A6 stock paper size.}%
2598 \glossary(a5paperco)%
2599 {\Popt{a5paper}}%
2600 {Class option for A5 stock paper size.}%
2601 \glossary(a4paperco)%
2602 {\Popt{a4paper}}%
2603 {Class option for A4 stock paper size.}%
2604 \glossary(a3paperco)%
2605 {\Popt{a3paper}}%
2606 {Class option for A3 stock paper size.}%
2607 \glossary(b6paperco)%
2608 {\Popt{b6paper}}%
2609 {Class option for B6 stock paper size.}%
2610 \glossary(b5paperco)%
2611 {\Popt{b5paper}}%
2612 {Class option for B5 stock paper size.}%
2613 \glossary(b4paperco)%
2614 {\Popt{b4paper}}%
2615 {Class option for B4 stock paper size.}%
2616 \glossary(b3paperco)%
2617 {\Popt{b3paper}}%
2618 {Class option for B3 stock paper size.}%
2619 \glossary(mcrownvopaperco)%
2620 {\Popt{mcrownvopaper}}%
2621 {Class option for metric crown octavo stock paper size.}%
2622 \glossary(mlargecrownvopaperco)%
2623 {\Popt{mlargecrownvopaper}}%
2624 {Class option for metric large crown octavo stock paper size.}%
2625 \glossary(mdemyvopaperco)%
2626 {\Popt{mdemyvopaper}}%
2627 {Class option for metric demy octavo stock paper size.}%
2628 \glossary(msmallroyalvopaperco)%
2629 {\Popt{msmallroyalvopaper}}%
2630 {Class option for metric small royal octavo stock paper size.}%
2631 \end{table}
2632
2633
2634
2635
2636
2637 \begin{table}
2638 \centering
2639 \caption{Class stock US paper size options, and commands}\label{tab:sizeoptsus}
2640 \begin{tabular}{llll} \toprule
2641 Option & Size & stock size command & page size command \\ \midrule
2642 \Lopt{dbillpaper}\index{paper!size!dollar bill}\index{stock!size!dollar bill}
2643 & \abybm{7}{3}{in} & \cmd{\stockdbill} & \cmd{\pagedbill} \\
2644 \Lopt{statementpaper}\index{paper!size!statement}\index{stock!size!statement}
2645 & \abybm{8.5}{5.5}{in} & \cmd{\stockstatement} & \cmd{\pagestatement} \\
2646 \Lopt{executivepaper}\index{paper!size!executive}\index{stock!size!executive}
2647 & \abybm{10.5}{7.25}{in} & \cmd{\stockexecutive} & \cmd{\pageexecutive} \\
2648 \Lopt{letterpaper}\index{paper!size!letterpaper}\index{stock!size!letterpaper}
2649 & \abybm{11}{8.5}{in} & \cmd{\stockletter} & \cmd{\pageletter} \\
2650 \Lopt{oldpaper}\index{paper!size!old}\index{stock!size!old}
2651 & \abybm{12}{9}{in} & \cmd{\stockold} & \cmd{\pageold} \\
2652 \Lopt{legalpaper}\index{paper!size!legal}\index{stock!size!legal}
2653 & \abybm{14}{8.5}{in} & \cmd{\stocklegal} & \cmd{\pagelegal} \\
2654 \Lopt{ledgerpaper}\index{paper!size!ledger}\index{stock!size!ledger}
2655 & \abybm{17}{11}{in} & \cmd{\stockledger} & \cmd{\pageledger} \\
2656 \Lopt{broadsheetpaper}\index{paper!size!broadsheet}\index{stock!size!broadsheet}
2657 & \abybm{22}{17}{in} & \cmd{\stockbroadsheet} & \cmd{\pagebroadsheet} \\
2658 \bottomrule
2659 \end{tabular}
2660 \glossary(dbillpaperco)%
2661 {\Popt{dbillpaper}}%
2662 {Class option for dollar bill stock paper size.}%
2663 \glossary(statementpaperco)%
2664 {\Popt{statementpaper}}%
2665 {Class option for statement stock paper size.}%
2666 \glossary(executivepaperco)%
2667 {\Popt{executivepaper}}%
2668 {Class option for executive-paper stock paper size.}%
2669 \glossary(letterpaperco)%
2670 {\Popt{letterpaper}}%
2671 {Class option for letterpaper stock paper size.}%
2672 \glossary(oldpaperco)%
2673 {\Popt{oldpaper}}%
2674 {Class option for old stock paper size.}%
2675 \glossary(legalpaperco)%
2676 {\Popt{legalpaper}}%
2677 {Class option for legal-paper stock paper size.}%
2678 \glossary(ledgerpaperco)%
2679 {\Popt{ledgerpaper}}%
2680 {Class option for ledger stock paper size.}%
2681 \glossary(broadsheetpaperco)%
2682 {\Popt{broadsheetpaper}}%
2683 {Class option for broadsheet stock paper size.}%
2684 \end{table}
2685
2686
2687 \begin{table}
2688 \centering
2689 \caption{Class stock British paper size options, and commands}\label{tab:sizeoptsbrit}
2690 \begin{tabular}{llll} \toprule
2691 Option & Size & stock size command & page size command \\ \midrule
2692 \Lopt{pottvopaper}\index{paper!size!pott octavo}\index{stock!size!pott octavo}
2693 & \abybm{6.25}{4}{in} & \cmd{\stockpottvo} & \cmd{\pagepottvo} \\
2694 \Lopt{foolscapvopaper}\index{paper!size!foolscap octavo}\index{stock!size!foolscap octavo}
2695 & \abybm{6.75}{4.25}{in} & \cmd{\stockfoolscapvo} & \cmd{\pagefoolscapvo} \\
2696 \Lopt{crownvopaper}\index{paper!size!crown octavo}\index{stock!size!crown octavo}
2697 & \abybm{7.5}{5}{in} & \cmd{\stockcrownvo} & \cmd{\pagecrownvo} \\
2698 \Lopt{postvopaper}\index{paper!size!post octavo}\index{stock!size!post octavo}
2699 & \abybm{8}{5}{in} & \cmd{\stockpostvo} & \cmd{\pagepostvo} \\
2700 \Lopt{largecrownvopaper}\index{paper!size!large crown octavo}\index{stock!size!large crown octavo}
2701 & \abybm{8}{5.25}{in} & \cmd{\stocklargecrownvo} & \cmd{\pagelargecrown
2702 vo} \\
2703 \Lopt{largepostvopaper}\index{paper!size!large post octavo}\index{stock!size!large post octavo}
2704 & \abybm{8.25}{5.25}{in} & \cmd{\stocklargepostvo} & \cmd{\pagelargepostvo} \\
2705 \Lopt{smalldemyvopaper}\index{paper!size!small demy octavo}\index{stock!size!small demy octavo}
2706 & \abybm{8.5}{5.675}{in} & \cmd{\stocksmalldemyvo} & \cmd{\pagesmalldemyvo} \\
2707 \Lopt{demyvopaper}\index{paper!size!demy octavo}\index{stock!size!demy octavo}
2708 & \abybm{8.75}{5.675}{in} & \cmd{\stockdemyvo} & \cmd{\pagedemyvo} \\
2709 \Lopt{mediumvopaper}\index{paper!size!medium octavo}\index{stock!size!medium octavo}
2710 & \abybm{9}{5.75}{in} & \cmd{\stockmediumvo} & \cmd{\pagemediumvo} \\
2711 \Lopt{smallroyalvopaper}\index{paper!size!small royal octavo}\index{stock!size!small royal octavo}
2712 & \abybm{9.25}{6.175}{in} & \cmd{\stocksmallroyalvo} & \cmd{\pagesmallroyalvo} \\
2713 \Lopt{royalvopaper}\index{paper!size!royal octavo}\index{stock!size!royal octavo}
2714 & \abybm{10}{6.25}{in} & \cmd{\stockroyalvo} & \cmd{\pageroyalvo} \\
2715 \Lopt{superroyalvopaper}\index{paper!size!super royal octavo}\index{stock!size!super royal octavo}
2716 & \abybm{10.25}{6.75}{in} & \cmd{\stocksuperroyalvo} & \cmd{\pagesuperroyalvo} \\
2717 \Lopt{imperialvopaper}\index{paper!size!imperial octavo}\index{stock!size!imperial octavo}
2718 & \abybm{11}{7.5}{in} & \cmd{\stockimperialvo} & \cmd{\pageimperialvo} \\
2719 \bottomrule
2720 \end{tabular}
2721 \glossary(pottvopaperco)%
2722 {\Popt{pottvopaper}}%
2723 {Class option for pott octavo stock paper size.}%
2724 \glossary(foolscapvopaperco)%
2725 {\Popt{foolscapvopaper}}%
2726 {Class option for foolscap octavo stock paper size.}%
2727 \glossary(crownvopaperco)%
2728 {\Popt{crownvopaper}}%
2729 {Class option for crown octavo stock paper size.}%
2730 \glossary(postvopaperco)%
2731 {\Popt{postvopaper}}%
2732 {Class option for post octavo stock paper size.}%
2733 \glossary(largecrownvopaperco)%
2734 {\Popt{largecrownvopaper}}%
2735 {Class option for large crown octavo stock paper size.}%
2736 \glossary(largepostvopaperco)%
2737 {\Popt{largepostvopaper}}%
2738 {Class option for large post octavo stock paper size.}%
2739 \glossary(smalldemyvopaperco)%
2740 {\Popt{smalldemyvopaper}}%
2741 {Class option for small demy octavo stock paper size.}%
2742 \glossary(demyvopaperco)%
2743 {\Popt{demyvopaper}}%
2744 {Class option for demy octavo stock paper size.}%
2745 \glossary(mediumvopaperco)%
2746 {\Popt{mediumvopaper}}%
2747 {Class option for medium octavo stock paper size.}%
2748 \glossary(smallroyalvopaperco)%
2749 {\Popt{smallroyalvopaper}}%
2750 {Class option for small royal octavo stock paper size.}%
2751 \glossary(royalvopaperco)%
2752 {\Popt{royalvopaper}}%
2753 {Class option for royal octavo stock paper size.}%
2754 \glossary(superroyalvopaperco)%
2755 {\Popt{superroyalvopaper}}%
2756 {Class option for super royal octavo stock paper size.}%
2757 \glossary(imperialvopaperco)%
2758 {\Popt{imperialvopaper}}%
2759 {Class option for imperial octavo stock paper size.}%
2760 \end{table}
2761
2762 \FloatBlock
2763
2764
2765 There are two options that don't really fit into the tables.
2766
2767 \begin{itemize}
2768 \item[\Lopt{ebook}]\index{stock!size!ebook}
2769 for a stock size of \abybm{6}{9}{inches}, principally
2770 for `electronic books' intended to be displayed
2771 on a computer monitor
2772 \glossary(ebookco)%
2773 {\Popt{ebook}}%
2774 {Class option for elecronic book stock size.}
2775 \item[\Lopt{landscape}] to interchange the height and width of the stock.
2776 \glossary(landscapeco)%
2777 {\Popt{landscape}}%
2778 {Class option to interchange height and width of stock paper size.}
2779 \end{itemize}
2780
2781 All the options, except for \Lopt{landscape}, are mutually exclusive.
2782 The default stock\indextwo{stock}{default} paper\indextwo{paper}{size} size is
2783 \Lopt{letterpaper}\index{paper!size!letterpaper}\index{stock!size!letterpaper}.
2784
2785 If you want to use a stock size that is not listed there are methods for doing this,
2786 which will be described later.
2787
2788 \section{Type size options}
2789
2790 The type size option sets the default font size throughout the document. The class
2791 offers a wider range of type sizes\index{type size} than usual. These are:\index{class options!type size}
2792 \begin{itemize}
2793 \item[\Lopt{9pt}] for 9pt as the normal type size
2794 \glossary(9ptco)%
2795 {\Popt{9pt}}%
2796 {Class option for a 9pt body font.}
2797 \item[\Lopt{10pt}] for 10pt as the normal type size
2798 \glossary(10ptco)%
2799 {\Popt{10pt}}%
2800 {Class option for a 10pt body font.}
2801 \item[\Lopt{11pt}] for 11pt as the normal type size
2802 \glossary(11ptco)%
2803 {\Popt{11pt}}%
2804 {Class option for a 11pt body font.}
2805 \item[\Lopt{12pt}] for 12pt as the normal type size
2806 \glossary(12ptco)%
2807 {\Popt{12pt}}%
2808 {Class option for a 12pt body font.}
2809 \item[\Lopt{14pt}] for 14pt as the normal type size\footnote{Note that
2810 for \Lopt{14pt}, \cs{huge}, \cs{Huge} and \cs{HUGE} will be the
2811 same as \cs{LARGE}, unless the \Lopt{extrafontsizes} option is
2812 also is activated.} \glossary(14ptco)%
2813 {\Popt{14pt}}%
2814 {Class option for a 14pt body font.}
2815 \item[\Lopt{17pt}] for 17pt as the normal type size
2816 \glossary(17ptco)%
2817 {\Popt{17pt}}%
2818 {Class option for a 17pt body font.}
2819 \item[\Lopt{20pt}] for 20pt as the normal type size
2820 \glossary(20ptco)%
2821 {\Popt{20pt}}%
2822 {Class option for a 20pt body font.}
2823 \item[\Lopt{25pt}] for 25pt as the normal type size
2824 \glossary(25ptco)%
2825 {\Popt{25pt}}%
2826 {Class option for a 25pt body font.}
2827 \item[\Lopt{30pt}] for 30pt as the normal type size
2828 \glossary(30ptco)%
2829 {\Popt{30pt}}%
2830 {Class option for a 30pt body font.}
2831 \item[\Lopt{36pt}] for 36pt as the normal type size
2832 \glossary(36ptco)%
2833 {\Popt{36pt}}%
2834 {Class option for a 36pt body font.}
2835 \item[\Lopt{48pt}] for 48pt as the normal type size
2836 \glossary(48ptco)%
2837 {\Popt{48pt}}%
2838 {Class option for a 48pt body font.}
2839 \item[\Lopt{60pt}] for 60pt as the normal type size
2840 \glossary(60ptco)%
2841 {\Popt{60pt}}%
2842 {Class option for a 60pt body font.}
2843 \item[\Lopt{*pt}] for an author-defined size as the normal type size
2844 \glossary(*ptco)%
2845 {\Popt{*pt}}%
2846 {Class option for an author-defined size for the body font.}
2847 \item[\Lopt{extrafontsizes}] Using scalable fonts that can exceed
2848 25pt.
2849
2850 \emph{Note that this includes \cs{huge}, \cs{Huge} and \cs{HUGE}
2851 under \Lopt{14pt}. For \Lopt{17pt} and up, an error is thrown if
2852 used without \Lopt{extrafontsizes}, no error is given for
2853 \Lopt{14pt}, there sizes above \cs{LARGE} will just be unavailable
2854 unless \Lopt{extrafontsizes} is used.}
2855 \glossary(extrafontsizes)%
2856 {\Popt{extrafontsizes}}%
2857 {Class option for using scalable fonts that can exceed 25pt.}
2858 \end{itemize}
2859
2860 These options, except for \Lopt{extrafontsizes}, are mutually exclusive.
2861 The default type size\indextwo{default}{type size} is \Lopt{10pt}.
2862
2863 Options greater than \Lopt{17pt} or \Lopt{20pt} are of little use unless
2864 you are using scalable fonts --- the regular Computer
2865 Modern\facesubseeidx{Computer Modern} bitmap fonts only go up
2866 to 25pt. The option \Lopt{extrafontsizes} indicates that you will be using
2867 scalable fonts that can exceed 25pt. By default this option makes
2868 Latin Modern in the \texttt{T1} encoding as the default font (normally
2869 Computer Modern in the \texttt{OT1} encoding is the default).
2870
2871 \subsection{Extended font sizes}
2872
2873 By default, if you use the \Lopt{extrafontsizes} option the default
2874 font for the document is Latin Modern\facesubseeidx{Latin Modern}
2875 in the \texttt{T1} font encoding.
2876 This is like putting
2877 \begin{lcode}
2878 \usepackage{lmodern}\usepackage[T1]{fontenc}
2879 \end{lcode}
2880 in the documents's preamble (but with the \Lopt{extrafontsizes} option
2881 you need not do this).
2882
2883 \begin{syntax}
2884 \verb?\newcommand*{\memfontfamily}?\marg{fontfamily} \\
2885 \verb?\newcommand*{\memfontenc}?\marg{fontencoding} \\
2886 \verb?\newcommand*{\memfontpack}?\marg{package} \\
2887 \end{syntax}
2888 \glossary(memfontfamily)%
2889 {\cs{memfontfamily}}%
2890 {Font family for the \Popt{extrafontsizes} class option (default \texttt{lmr})}
2891 \glossary(memfontenc)%
2892 {\cs{memfontenc}}%
2893 {Font encoding for the \Popt{extrafontsizes} class option (default \texttt{T1})}
2894 \glossary(memfontpack)%
2895 {\cs{memfontpack}}%
2896 {Font package for the \Popt{extrafontsizes} class option (default \texttt{lmodern})}
2897 Internally the class uses \cmd{\memfontfamily} and \cmd{\memfontenc} as
2898 specifying
2899 the new font and encoding, and uses \cmd{\memfontpack} as the name of the
2900 package to be used to implement the font. The internal definitions are:
2901 \begin{lcode}
2902 \providecommand*{\memfontfamily}{lmr}
2903 \providecommand*{\memfontenc}{T1}
2904 \providecommand*{\memfontpack}{lmodern}
2905 \end{lcode}
2906 which result in the \texttt{lmr} font
2907 (Latin Modern)\facesubseeidx{Latin Modern} in the \texttt{T1}
2908 encoding as the default font, which is implemented by the \Lpack{lmodern}
2909 package. If you want a different default, say
2910 New Century Schoolbook\facesubseeidx{New Century Schoolbook}
2911 (which comes in the \texttt{T1} encoding), then
2912 \begin{lcode}
2913 \newcommand*{\memfontfamily}{pnc}
2914 \newcommand*{\memfontpack}{newcent}
2915 \documentclass[...]{memoir}
2916 \end{lcode}
2917 will do the trick, where the \cs{newcommand*}s are put \emph{before} the
2918 \cs{documentclass} declaration (they will then override the \cs{provide...}
2919 definitions within the class code).
2920
2921 If you use the \Lopt{*pt} option then you have to supply a \file{clo}
2922 file containing all the size and space specifications for your chosen font
2923 size, and also tell \Mname\ the name of the file. \emph{Before} the
2924 \cmd{\documentclass} command define two macros, \cmd{\anyptfilebase} and
2925 \cmd{\anyptsize} like:
2926 \begin{syntax}
2927 \verb|\newcommand*{\anyptfilebase}|\marg{chars}\\
2928 \verb|\newcommand*{\anyptsize}|\marg{num}
2929 \end{syntax}
2930 \glossary(anyptsize)%
2931 {\cs{anyptsize}}%
2932 {Second part (the pointsize) of the name the \texttt{clo} file for the
2933 \Popt{*pt} class option (default \texttt{10}).}
2934 \glossary(anyptfilebase)%
2935 {\cs{anyptfilebase}}%
2936 {First part of the name of the \texttt{clo} file for the
2937 \Popt{*pt} class option (default \texttt{mem}).}
2938
2939 When it comes time to get the font size and spacing information \Mname\
2940 will try and input a file called \verb?\anyptfilebase\anyptsize.clo? which
2941 you should have made available; the \cmd{\anyptsize} \meta{num} must be an
2942 integer.\footnote{If it is not an integer then \tx\ could get confused
2943 as to the name of the file --- it normally expects there to be only one
2944 period (.) in the name of a file.} Internally, the class specifies
2945 \begin{lcode}
2946 \providecommand*{\anyptfilebase}{mem}
2947 \providecommand*{\anyptsize}{10}
2948 \end{lcode}
2949 which names the default as \file{mem10.clo}, which is for a 10pt font.
2950 If, for example, you have an 18pt font you want to use, then
2951 \begin{lcode}
2952 \newcommand*{\anyptfilebase}{myfont}
2953 \newcommand*{\anyptsize}{18}
2954 \documentclass[...*pt...]{memoir}
2955 \end{lcode}
2956 will cause \ltx\ to try and input the \texttt{myfont18.clo} file that
2957 you should have provided. Use one
2958 of the supplied \file{clo} files, such as \file{mem10.clo} or \file{mem60.clo}
2959 as an example of what must be specified in your \file{clo} file.
2960
2961 \section{Printing options}
2962
2963 This group of options\index{class options!printing} includes:
2964
2965 \begin{itemize}
2966 \item[\Lopt{twoside}] for when the document will be published with printing
2967 on both sides of the paper.
2968 \glossary(twosideco)%
2969 {\Popt{twoside}}%
2970 {Class option for text on both sides of the paper.}
2971 \item[\Lopt{oneside}] for when the document will be published with only
2972 one side of each sheet being printed on.
2973 \glossary(onesideco)%
2974 {\Popt{oneside}}%
2975 {Class option for text on only one side of the paper.}
2976
2977 The \Lopt{twoside} and \Lopt{oneside} options
2978 are mutually exclusive.
2979
2980 \item[\Lopt{onecolumn}] only one column\index{column!single} of text on a page.
2981 \glossary(onecolumnco)%
2982 {\Popt{onecolumn}}%
2983 {Class option for a single column.}
2984 \item[\Lopt{twocolumn}] two equal width columns\index{column!double} of text on a page.
2985 \glossary(twocolumnco)%
2986 {\Popt{twocolumn}}%
2987 {Class option for two columns.}
2988
2989 The \Lopt{onecolumn} and \Lopt{twocolumn} options
2990 are mutually exclusive.
2991
2992 \item[\Lopt{openright}] each chapter\index{chapter} will start on a recto page.
2993 \glossary(openrightco)%
2994 {\Popt{openright}}%
2995 {Class option for chapters to start on recto pages.}
2996 \item[\Lopt{openleft}] each chapter\index{chapter} will start on a verso page.
2997 \glossary(openleftco)%
2998 {\Popt{openleft}}%
2999 {Class option for chapters to start on verso pages.}
3000 \item[\Lopt{openany}] a chapter\index{chapter} may start on either a recto or verso page.
3001 \glossary(openanyco)%
3002 {\Popt{openany}}%
3003 {Class option for chapters to start on a recto or a verso page.}
3004
3005 The \Lopt{openright}, \Lopt{openleft} and
3006 \Lopt{openany} options
3007 are mutually exclusive.
3008
3009 \item[\Lopt{final}] for camera-ready copy of your labours.
3010 \glossary(finalco)%
3011 {\Popt{final}}%
3012 {Class option for final document.}
3013 \item[\Lopt{draft}] this marks overfull lines with black bars and enables
3014 some change marking to be shown. There may be other
3015 effects as well, particularly if some packages are used.
3016 \glossary(draftco)%
3017 {\Popt{draft}}%
3018 {Class option for draft document.}
3019 \item[\Lopt{ms}] this tries to make the document look as though it was
3020 prepared on a typewriter. Some publishers prefer to receive
3021 poor looking submissions.
3022 \glossary(msco)%
3023 {\Popt{ms}}%
3024 {Class option for `typewritten manuscript'.}
3025
3026 The \Lopt{final}, \Lopt{draft} and \Lopt{ms} options
3027 are mutually exclusive.
3028
3029 \item[\Lopt{showtrims}] this option prints marks at the corners of the
3030 sheet so that you can see where the stock\index{stock}
3031 must be trimmed to produce the final page size.
3032 \glossary(showtrimsco)%
3033 {\Popt{showtrims}}%
3034 {Class option for printing trimming marks.}
3035
3036 \end{itemize}
3037 %
3038 The defaults among the printing options\index{default!printing options}
3039 are \Lopt{twoside}, \Lopt{onecolumn}, \Lopt{openright}, and \Lopt{final}.
3040
3041 \section{Other options}
3042
3043 The remaining options are:
3044 \begin{itemize}
3045
3046 \item[\Lopt{leqno}]\index{class options!math}
3047 equations will be numbered at the left (the default is
3048 to number them at the right).
3049 \glossary(leqnoco)%
3050 {\Popt{leqno}}%
3051 {Class option for numbering equations at the left.}
3052
3053 \item[\Lopt{fleqn}]\index{class options!math}
3054 displayed math environments will be indented an amount
3055 \cmd{\mathindent} from the left margin\index{margin} (the default is to
3056 center the environments).
3057 \glossary(fleqnco)%
3058 {\Popt{fleqn}}%
3059 {Class option for fixed indentation of displayed math.}
3060
3061 \item[\Lopt{openbib}]\index{class options!bibliography}
3062 each part of a bibliography\index{bibliography} entry will start on a
3063 new line, with second and succeding lines indented
3064 by \cmd{\bibindent} (the default is for an entry
3065 to run continuously with no indentations).
3066 \glossary(openbibco)%
3067 {\Popt{openbib}}%
3068 {Class option for indenting continuation lines in a bibliography.}
3069
3070 \item[\Lopt{article}]\index{class options!article}
3071 typesetting \emph{simulates} the \Lclass{article} class,
3072 but the \cmd{\chapter} command is not disabled, basically
3073 \cmd{\chapter} will behave as if it was \cmd{\section}.
3074 Chapters\index{chapter} do not start a new page and chapter
3075 headings\index{heading!chapter} are typeset
3076 like a section heading\index{heading!sections}. The numbering of
3077 figures\index{figure}, etc., is continuous
3078 and not per chapter. However, a \cmd{\part} command still puts
3079 its heading\index{heading!part} on a page by itself.
3080 \glossary(articleco)%
3081 {\Popt{article}}%
3082 {Class option for simulating the \Pclass{article} class.}
3083
3084 \item[\Lopt{oldfontcommands}]\index{class options!fonts}
3085 makes the old, deprecated LaTeX version~2.09
3086 font commands available. Warning messages will be produced whenever
3087 an old font command is encountered.
3088 \glossary(oldfontcommandsco)%
3089 {\Popt{oldfontcommands}}%
3090 {Class option for permitting obsolete, deprecated font commands.}
3091
3092
3093 \item[\Lopt{fullptlayout}]\index{class options!layout truncation}
3094 disable point trunction of certain layout lengths, for example
3095 \cmd{\textwidth}. The default is to round these of to a whole number
3096 of points, this option disables this feature.
3097 \glossary(fullptlayout)%
3098 {\Popt{fullptlayout}}%
3099 {Class option to disable point truncation of certain layout lengths.}
3100 \end{itemize}
3101 %
3102 None of these options are defaulted.
3103
3104 \section{Remarks}
3105
3106 Calling the class with no options is equivalent to:
3107 \begin{lcode}
3108 \documentclass[letterpaper,10pt,twoside,onecolumn,openright,final]{memoir}
3109 \end{lcode}
3110 The source file for this manual starts
3111 \begin{lcode}
3112 \documentclass[letterpaper,10pt,extrafontsizes]{memoir}
3113 \end{lcode}
3114 which is overkill as both \Lopt{letterpaper} and \Lopt{10pt} are among
3115 the default options.
3116
3117 Actual typesetting only occurs within the \Ie{document} environment. The
3118 region of the file between the \cmd{\documentclass} command and the start
3119 of the \Ie{document} environment is called the
3120 \emph{preamble}\index{preamble}. This is where you ask for external packages
3121 and define your own macros if you feel so inclined.
3122
3123 \begin{syntax}
3124 \cmd{\flushbottom} \cmd{\raggedbottom} \\
3125 \end{syntax}
3126 \glossary(flushbottom)%
3127 {\cs{flushbottom}}%
3128 {Declaration for last line on a page to be at a constant height.}
3129 \glossary(raggedbottom)%
3130 {\cs{raggedbottom}}%
3131 {Declaration allowing the last line on a page to be at a variable height.}
3132 When the \Lopt{twoside} or \Lopt{twocolumn} option is selected then
3133 typesetting is done with \cmd{\flushbottom}, otherwise it is done
3134 with \cmd{\raggedbottom}.
3135
3136 When \cmd{\raggedbottom} is in effect LaTeX makes little attempt to
3137 keep a constant height for the typeblock\index{typeblock}; pages may run short.
3138
3139 When \cmd{\flushbottom} is in effect LaTeX ensures that the typeblock\index{typeblock}
3140 on each page is a constant height, except when a page break is deliberately
3141 introduced when the page might run short. In order to maintain a constant
3142 height it may stretch or shrink some vertical spaces
3143 (e.g., between paragraphs\index{paragraph}, around headings\index{heading} or
3144 around floats\index{float} or other inserts like displayed maths).
3145 This may have a deleterious effect on the color\index{page color}
3146 of some pages.
3147 % Serendipitously this has happened on \pref{chap:lpage} where
3148 % there is additional space between the paragraphs\index{paragraph} (caused by the next sectional
3149 % division having to be put at the top of the next page). You may wish to
3150 % compare that page with the following one to see the difference in the
3151 % colors.
3152
3153 % I could have made the page run short by inserting \cmd{\raggedbottom}
3154 % at an appropriate place, followed later by a \cmd{\flushbottom}.
3155
3156 If you get too many strung out pages with \cmd{\flushbottom} you may
3157 want to put \cmd{\raggedbottom} in the preamble\index{preamble}.
3158
3159 If you use the \Lopt{ebook} option you may well also want to use the
3160 \Lopt{12pt} and \Lopt{oneside} options.
3161
3162 %#% extend
3163
3164 \clearpage
3165 \pagestyle{ruled}
3166
3167 %#% extstart include laying-out-page.tex
3168
3169 \svnidlong
3170 {$Ignore: $}
3171 {$LastChangedDate: 2025-08-07 16:33:42 +0200 (Thu, 07 Aug 2025) $}
3172 {$LastChangedRevision: 858 $}
3173 {$LastChangedBy: [email protected] $}
3174
3175 \chapter{Laying out the page} \label{chap:layingpage}
3176
3177
3178 Up until this chapter the \pstyle{headings} pagestyle\index{pagestyle}
3179 has been used; pagestyles are described in \Sref{sec:pagestyles}.
3180 This, and later chapters, are typeset with the \pstyle{ruled} pagestyle.
3181
3182 \section{Introduction}
3183
3184 The class provides a default page
3185 layout\index{page layout}\indextwo{page layout}{default},
3186 in which the page size is the
3187 same as the stock\index{stock} size and the typeblock\index{typeblock} is
3188 roughly in the middle of the page.
3189 This chapter describes the commands provided by the class to help you
3190 produce your own page layout if the default is inappropriate.
3191
3192 If you are happy with the default layout you may skip the rest of this
3193 chapter.
3194
3195 \fancybreak{}
3196
3197 The pages of a book carry the text which is intended to educate, entertain
3198 and/or amuse the reader. The page must be designed to serve the purposes of
3199 the author and to ease the reader's task in assimilating the author's ideas.
3200 A good page design is one which the general reader does not notice. If the
3201 reader is constantly noticing the page layout, even unconsciously, it distracts
3202 from the purpose of the book. It is not the job of the designer to
3203 shout, or even to murmur, `look at my work'.
3204
3205 There are three main parts to a page: the page itself, the
3206 typeblock\index{typeblock}, and
3207 the margins\index{margin} separating the typeblock\index{typeblock} from
3208 the edges of the page. Of slightly lesser importance are the running
3209 headers\index{header} and footers\index{footer},
3210 and possibly marginal\index{marginalia} notes.
3211 The art of page design is obtaining a harmonious balance or rhythm between
3212 all these.
3213
3214 Although the form is different, the facilities described in this chapter
3215 are similar to those provided by the \Lpack{geometry}
3216 package~\cite{GEOMETRY}.
3217
3218 \fancybreak{}
3219
3220 \begin{adjustwidth}{3em}{3em}
3221 \itshape Note, if your paper choice matches one of the class paper
3222 options, then you can skip forward to \Sref{sec:typeblock2} --
3223 \emph{\titleref{sec:typeblock2}}, as you have already chosen your
3224 stock size and does not need trimming.
3225 \end{adjustwidth}
3226
3227 \fancybreak{}
3228
3229 On the other hand, if, say, you are designing a document, that is to
3230 be printed on one type of paper (the stock), and then trimmed to
3231 another, please read on.
3232
3233 % Before we start let use summarize what laying out the page
3234 % involves\fxnote{where did the spacings around enumerate go? Had to add
3235 % a blank line}
3236
3237 % \begin{enumerate}[(a)]
3238 % \item Figure out the stock size of your document and whether or not
3239 % you need to trim the stock to get the desired paper size.
3240
3241 % Most people just specify the stick and paper size via a class option
3242 % like \Lopt{a4paper}. Thus you can proceed to
3243 % section~\ref{sec:typeblock2}.
3244 % \item Specify the text block, basically the margins.
3245
3246 % The class provide two interfaces for this: (1) Set the margins
3247 % around the text block, thereby defining the text block, and (2),
3248 % specify the size of the text block directly and then place it on the
3249 % page.
3250 % \item Specify auxiliary layout, like placement of headers, footers and
3251 % margin notes.
3252 % \item At the end (\emph{very important}) we ask the class to put
3253 % everything together and check that they make sense.
3254 % \end{enumerate}
3255
3256
3257
3258
3259
3260
3261 \section{Stock material}
3262 \label{sec:stock-material}
3263
3264 Printing is the act of laying symbols onto a piece of
3265 stock\index{stock} material. Some print on T-shirts by a process
3266 called silk screening, where the shapes of the symbols are made in a
3267 screen and then fluid is squeezed through the screen onto the stock
3268 material --- in this case the fabric of the T shirt. Whether or not
3269 this is of general interest it is not the sort of printing or stock
3270 material that is normally used in book production. Books, except for
3271 the very particular, are printed on paper\index{paper}.
3272
3273 In the desktop publishing world the stock\indextwo{stock}{paper}
3274 paper\indextwo{stock}{size} is usually one from a range of standard sizes.
3275 In the USA it is typically
3276 letterpaper\index{letterpaper}\index{stock!size!letterpaper}
3277 (11 by 8.5 inches) and in the
3278 rest of the world A4\index{A4 paper}\index{stock!size!A4} paper
3279 (297 by 210 mm), with one page per piece of stock\index{stock}. In commercial
3280 printing the stock\index{stock!commercial printing} material is
3281 much larger with several
3282 pages being printed on each stock\index{stock} piece;
3283 the stock\index{stock} is then folded, cut and trimmed to form
3284 the final pages for binding. The class assumes that desktop publishing is
3285 the norm.
3286
3287
3288 \section{The page}
3289 \label{sec:page}
3290
3291 The class assumes that there will be only a single page on a side of
3292 each piece of stock\index{stock}; two sides means that there can be two
3293 pages, one on the front and the other on the back.
3294
3295 \begin{figure}
3296 \centering
3297 \drawpage
3298 \caption{\ltx\ page layout parameters for a recto page} \label{fig:anoddpage}
3299 \end{figure}
3300
3301 The parameters\index{page layout!LaTeX parameters?\ltx\ parameters}
3302 used by \ltx\ itself to define the page layout are
3303 illustrated in \fref{fig:anoddpage}. \ltx\ does not actually care about the
3304 physical size of a page --- it assumes that, with respect to the top lefthand
3305 corner, the sheet of paper\index{sheet} to be printed is infinitely wide
3306 and infinitely long. If you happen to have a typeblock\index{typeblock}
3307 that is too wide or too long for the sheet, \ltx\ will merrily position
3308 text outside the physical boundaries.
3309
3310 The \ltx\ parameters are often not particularly convenient if, say,
3311 the top of the text must be a certain distance below the top of the page
3312 and the \foredge{} margin\index{margin!foredge?\foredge} must be twice
3313 the spine margin\index{margin!spine}. It is obviously possible
3314 to calculate the necessary values for the parameters, but it is
3315 not a pleasurable task.
3316
3317 The class provides various means of specifying the page layout, which
3318 are hopefully more convenient to use than the standard ones. Various
3319 adjustable parameters\index{page layout!class parameters} are used
3320 that define the stock\indextwo{stock}{size} size,
3321 page\indextwo{page}{size} size, and so on. These differ in some
3322 respects from the parameters in the standard classes, although the
3323 parameters for marginal notes are the same in both cases.
3324 \fref{fig:oddstock} shows the main class layout parameters for a recto
3325 page. These may be changed individually by \cmd{\setlength} or by
3326 using the commands described below. \fref{fig:evenstock}
3327 illustrates the same parameters on a verso page.
3328
3329
3330 \begin{figure}
3331 \centering
3332 \oddpagelayoutfalse
3333 \drawstock
3334 \caption{The \textsf{memoir} class page layout parameters for a verso
3335 (left hand) page} \label{fig:evenstock}
3336 \end{figure}
3337
3338 \begin{figure}
3339 \centering
3340 %%%\drawmarginparsfalse
3341 \drawstock
3342 \caption{The \textsf{memoir} class page layout parameters for a recto
3343 (right hand) page} \label{fig:oddstock}
3344 \end{figure}
3345
3346
3347 \fancybreak{}
3348
3349
3350 The first step in designing the page layout\index{page layout!design}
3351 is to decide on the page size\indextwo{page}{size} and then pick an
3352 appropriate stock\indextwo{stock}{size} size. Selecting a standard
3353 stock\indextwo{stock}{size} size will
3354 be cheaper than having to order specially sized stock\index{stock} material.
3355
3356 \begin{syntax}
3357 \cmd{\setstocksize}\marg{height}\marg{width} \\
3358 \end{syntax}
3359 \glossary(setstocksize)%
3360 {\cs{setstocksize}\marg{height}\marg{width}}%
3361 {Set the stock paper size to be \meta{height} by \meta{width}.}
3362 \glossary(stockheight)%
3363 {\ls{stockheight}}%
3364 {Height of the stock paper.}
3365 \glossary(stockwidth)%
3366 {\ls{stockwidth}}%
3367 {Width of the stock paper.}
3368 The class options\index{stock paper size option}
3369 provide for some common stock\indextwo{stock}{size} sizes.
3370 So if you have specified the class option \texttt{a4paper} and intend
3371 to print on A4, then you have no need for \cmd{\setstocksize}, proceed
3372 directly to \Sref{sec:typeblock2}. Alternatively, the class
3373 provide settings for many other standard stock sizes, see
3374 \tref{tab:sizeoptsmetric} through \tref{tab:sizeoptsbrit}.
3375
3376
3377 If you have some other size that you want to use, the
3378 command \cmd{\setstocksize} can be used to
3379 specify that the stock\index{stock!specifying size} size is
3380 \meta{height} \index{stock!height} by \meta{width}\index{stock!width}.
3381 For example the following specifies a stock\index{stock!size} of 9 by 4 inches:
3382 \begin{lcode}
3383 \setstocksize{9in}{4in}
3384 \end{lcode}
3385
3386 The size of the page\indextwo{page}{size} must be no larger than the
3387 stock\indextwo{stock}{size} but
3388 may be smaller which means that after printing
3389 the stock\index{stock!trimmed} must be trimmed down to the size of the page.
3390 The page may
3391 be positioned anywhere within the bounds of the stock\index{stock}.
3392
3393 Page layout should be conceived in terms of a double spread\index{spread};
3394 when you open a book in the middle what you see is a double spread ---
3395 a verso page on the left and a recto page on the right with the spine
3396 between them. Most books when closed are taller\index{proportion!book}
3397 than they are wide; this makes them easier to hold when open
3398 for reading. A squarish page when opened out into a wide spread
3399 makes for discomfort unless the book is supported on a table.
3400
3401 \begin{syntax}
3402 \cmd{\settrimmedsize}\marg{height}\marg{width}\marg{ratio} \\
3403 \end{syntax}
3404 \glossary(settrimmedsize)%
3405 {\cs{settrimmedsize}\marg{height}\marg{width}\marg{ratio}}%
3406 {Sets the size of the trimmed stock paper.}
3407 \glossary(paperheight)%
3408 {\ls{paperheight}}%
3409 {The height of the trimmed stock paper.}
3410 \glossary(paperwidth)%
3411 {\ls{paperwidth}}%
3412 {The width of the trimmed stock paper.}
3413 Initially the page size\indextwo{page}{size} is made the same as the
3414 stock\indextwo{stock}{size} size, as set by the
3415 paper\index{stock paper size option} size option.
3416 The command \cmd{\settrimmedsize}\index{page!specifying size}
3417 can be used to specify the height\index{page!height} and width\index{page!width}
3418 of the page (after any trimming). The \meta{ratio} argument is
3419 the amount by which the \meta{height} or the \meta{width} must be multiplied
3420 by to give the
3421 width or the height. Only two out of the three possible arguments must be
3422 given values with the other (unvalued) argument given as \verb?*?
3423 (an asterisk). The lengths \lnc{\paperheight} and \lnc{\paperwidth} are
3424 calculated according to the given arguments. That is, the command enables
3425 the \lnc{\paperheight}
3426 and \lnc{\paperwidth} to be specified directly or as one being in a given
3427 ratio to the other. The potential combinations of arguments and the
3428 corresponding results are listed in \tref{tab:rectsize}.
3429
3430
3431 \begin{table}
3432 \centering
3433 \caption{Arguments and results for \cs{settrimmedsize} and \cs{settypeblocksize} } \label{tab:rectsize}
3434 %\begin{tabular}{ccc|l} \hline
3435 \begin{tabular}{cccl} \toprule
3436 \meta{height} & \meta{width} & \meta{ratio} & Result \\ \midrule
3437 H & W & r & ambiguous \\
3438 H & W & {*} & $H$, $W$ \\
3439 H & {*} & r & $W = rH$ \\
3440 H & {*} & {*} & ambiguous \\
3441 {*} & W & r & $H = rW$ \\
3442 {*} & W & {*} & ambiguous \\
3443 {*} & {*} & r & ambiguous \\
3444 {*} & {*} & {*} & ambiguous \\
3445 \bottomrule
3446 \end{tabular}
3447 \end{table}
3448
3449 If you have used \cmd{\setstocksize} to redefine the stock\index{stock},
3450 then to get the same page size, do:
3451 \begin{lcode}
3452 \settrimmedsize{\stockheight}{\stockwidth}{*}
3453 \end{lcode}
3454 or for the page dimensions to be 90\% of the stock\index{stock} dimensions:
3455 \begin{lcode}
3456 \settrimmedsize{0.9\stockheight}{0.9\stockwidth}{*}
3457 \end{lcode}
3458
3459 The following are three different ways of defining an 8 by 5 inch page.
3460 \begin{lcode}
3461 \settrimmedsize{8in}{5in}{*}
3462 \settrimmedsize{8in}{*}{0.625} % 5 = 0.625 times 8
3463 \settrimmedsize{*}{5in}{1.6} % 8 = 1.6 times 5
3464 \end{lcode}
3465
3466 If you look at a well bound hardback book you
3467 can see that the sheets are folded so that they are continuous at the spine,
3468 where they are sewn together into the binding. The top of the pages should be
3469 smooth so that when the book is upright on a bookshelf dust has a harder
3470 job seeping between the pages than if the top was all raggedy. Thus, if
3471 the stock\index{stock!trimmed} is trimmed it will be trimmed at the top.
3472 It will also have been
3473 cut at the \foredge s of the pages and at the bottom, otherwise the book
3474 would be unopenable and unreadable.
3475
3476 \begin{syntax}
3477 \cmd{\settrims}\marg{top}\marg{foredge} \\
3478 \end{syntax}
3479 \glossary(settrims)%
3480 {\cs{settrims}\marg{top}\marg{foredge}}%
3481 {Sets the amount to be trimmed from the top and \foredge{} of the stock paper.}
3482 \glossary(trimtop)%
3483 {\ls{trimtop}}%
3484 {Amount to be trimmed from the top of the stock paper.}
3485 \glossary(trimedge)%
3486 {\ls{trimedge}}%
3487 {Amount to be trimmed from the \foredge{} of the stock paper.}
3488 The command \cmd{\settrims} can be used to specify
3489 the amount intended to be removed from the top
3490 (\meta{top}) and \foredge{} (\meta{foredge}) of the
3491 stock\index{stock!specifying trimming}
3492 material to produce the top and \foredge{} of a recto page.
3493 Note that the combination of \cmd{\settrims} and \cmd{\settrimmedsize}
3494 locate the page\index{page} with respect to the stock\index{stock}.
3495 By default the top and edge trims are zero, which means that if any trimming
3496 is required it will be at the spine and bottom edges of the stock
3497 unless \cmd{\settrims} is used to alter this.
3498
3499 You can either do any trim calculation for youself or let \ltx\ do it for
3500 you. For example, with an 8in by 5in page on 10in by 7in stock
3501 \begin{lcode}
3502 \settrims{2in}{2in}
3503 \end{lcode}
3504 specifies trimming 2in from the top and \foredge{} of the stock
3505 giving the desired page size. Taking a design where, say, the page
3506 is 90\% of the stock size it's easy to get \ltx\ to do the calculation:
3507 \begin{lcode}
3508 \setlength{\trimtop}{\stockheight} % \trimtop = \stockheight
3509 \addtolength{\trimtop}{-\paperheight} % - \paperheight
3510 \setlength{\trimedge}{\stockwidth} % \trimedge = \stockwidth
3511 \addtolength{\trimedge}{-\paperwidth} % - \paperwidth
3512 \end{lcode}
3513 which will set all the trimming to be at the top and \foredge.
3514 If you wanted, say, equal trims at the top and bottom you could go
3515 on and specify
3516 \begin{lcode}
3517 \settrims{0.5\trimtop}{\trimedge}
3518 \end{lcode}
3519
3520 \fancybreak{}
3521
3522 See also \Sref{sec:place-trimmed-page} --
3523 \emph{\titleref{sec:place-trimmed-page}}, where we present some extra
3524 commands. For example \cmd{\setpagecc} for placing a trimmed page
3525 centered on the stock.
3526
3527 After trimming the various methods to specify the typeblock, now
3528 refers to the \emph{trimmed} page, not the stock material.
3529
3530
3531 \section{The typeblock} \label{sec:typeblock2}
3532
3533 Like the page, the typeblock\index{proportion!typeblock} is normally
3534 rectangular with the height greater than the width.
3535 % Consider a typeblock that includes no illustrations\index{illustration}
3536 %or tables\index{table}.
3537 The lines of text must be laid out so that they are easy to read.
3538 Common practice, and more recently psychological testing, has shown that
3539 long lines of text are difficult to read. Thus, there is a physiological
3540 upper limit to the width of the typeblock. From a practical viewpoint,
3541 a line should not be too short because then there is difficulty in justifying
3542 the text.
3543
3544 \subsection{A note on the width of the typeblock}
3545
3546
3547 Experiments have shown that the number of characters in a line of
3548 single column\index{column} text on a page should be
3549 in the range 60 to 70 for ease of reading. The range may be as much
3550 as 45 to 75 characters but 66 characters is often
3551 considered to be the ideal number. Much shorter and the eye is dashing
3552 back and forth between each line. Much longer and it is hard to pick up the
3553 start of the next line if the eye has to jump back too far --- the same line
3554 may be read twice or the following line may be inadvertently jumped over.
3555 For double column\index{column!double} text the ideal number of characters
3556 is around 45, give or take 5 or so.
3557
3558 Bringhurst\index{Bringhurst, Robert}~\cite{BRINGHURST99} gives a
3559 method for determining the number
3560 of characters in a line for any font\index{font!measuring}:
3561 measure the length of the lowercase alphabet and use a
3562 copyfitting\index{copyfitting}
3563 table that shows for a given alphabet
3564 length and line length, the average number of characters in that line.
3565 \tref{tab:copyfitting} is an
3566 abridged version of Bringhurt's copyfitting table.
3567 For example, it suggests that a font with a length of 130pt should be
3568 set on a measure of about 26pc for a single column\index{column!single}
3569 or in an 18pc wide column if there are multiple\index{column!multiple}
3570 columns.
3571
3572
3573 \begin{table}
3574 %%%\DeleteShortVerb{\|}
3575 \centering
3576 \caption{Average characters per line} \label{tab:copyfitting}
3577 \begin{tabular}{r !\quad rrrrrrrr} %|
3578 \toprule
3579 Pts. & \multicolumn{8}{c}{Line length in picas} \\
3580 \cmidrule{2-9}
3581 & 10 & 14 & 18 & 22 & 26 & 30 & 35 & 40 \\
3582 \midrule
3583 80 & \textit{40} & \textbf{56} & \textbf{72} & 88 & 104 & & & \\
3584 85 & \textit{38} & \textit{53} & \textbf{68} & 83 & 98 & 113 & & \\
3585 90 & \textit{36} & \textit{50} & \textbf{64} & 79 & 86 & 107 & & \\
3586 95 & 34 & \textit{48} & \textbf{62} & 75 & 89 & 103 & & \\
3587 100 & 33 & \textit{46} & \textbf{59} & \textbf{73} & 86 & 99 & 116 & \\
3588 105 & 32 & \textit{44} & 57 & \textbf{70} & 82 & 95 & 111 & \\
3589 110 & 30 & \textit{43} & 55 & \textbf{67} & 79 & 92 & 107 & \\
3590 115 & 29 & \textit{41} & 53 & \textbf{64} & 76 & 88 & 103 & \\
3591 120 & 28 & \textit{39} & \textit{50} & \textbf{62} & 73 & 84 & 98 & 112 \\
3592 125 & 27 & 38 & \textit{48} & \textbf{59} & \textbf{70} & 81 & 94 & 108 \\
3593 130 & 26 & 36 & \textit{47} & 57 & \textbf{67} & 78 & 91 & 104 \\
3594 135 & 25 & 35 & \textit{45} & 55 & \textbf{65} & 75 & 88 & 100 \\
3595 140 & 24 & 34 & \textit{44} & 53 & \textbf{63} & 73 & 85 & 97 \\
3596 145 & 23 & 33 & \textit{42} & 51 & \textbf{61} & \textbf{70} & 82 & 94 \\
3597 150 & 23 & 32 & \textit{41} & \textit{51} & \textbf{60} & \textbf{69} & 81 & 92 \\
3598 155 & 22 & 31 & \textit{39} & \textit{49} & 58 & \textbf{67} & 79 & 90 \\
3599 160 & 22 & 30 & 39 & \textit{48} & 56 & \textbf{65} & 76 & 87 \\
3600 165 & 21 & 30 & 38 & \textit{46} & 55 & \textbf{63} & 74 & 84 \\
3601 170 & 21 & 29 & 37 & \textit{45} & 53 & \textbf{62} & 72 & 82 \\
3602 175 & 20 & 28 & 36 & \textit{44} & 52 & \textbf{60} & \textbf{70} & 80 \\
3603 180 & 20 & 27 & 35 & \textit{43} & 51 & 59 & \textbf{68} & 78 \\
3604 185 & 19 & 27 & 34 & \textit{42} & \textit{49} & 57 & \textbf{67} & 76 \\
3605 190 & 19 & 26 & 33 & 41 & \textit{48} & 56 & \textbf{65} & 74 \\
3606 195 & 18 & 25 & 32 & 40 & \textit{47} & 54 & \textbf{63} & 72 \\
3607 200 & 18 & 25 & 32 & 39 & \textit{46} & 53 & \textbf{62} & \textbf{70} \\
3608 220 & 16 & 22 & 29 & 35 & \textit{41} & \textit{48} & 56 & \textbf{64} \\
3609 240 & 15 & 20 & 26 & 32 & 38 & \textit{44} & 51 & 58 \\
3610 260 & 14 & 19 & 24 & 30 & 35 & 41 & \textit{48} & 54 \\
3611 280 & 13 & 18 & 23 & 28 & 33 & 38 & \textit{44} & 50 \\
3612 300 & 12 & 17 & 21 & 26 & 31 & 35 & 41 & \textit{47} \\
3613 320 & 11 & 16 & 20 & 25 & 29 & 34 & 39 & \textit{45} \\
3614 340 & 10 & 15 & 19 & 23 & 27 & 32 & 37 & 42 \\
3615 \bottomrule
3616 \end{tabular}
3617 %%%\MakeShortVerb{\|}
3618 \end{table}
3619
3620 Morten H{\o}gholm\index{H{\o}gholm, Morten} has done some curve fitting
3621 to the data. He determined that the expressions
3622 \begin{equation}
3623 L_{65} = 2.042\alpha + 33.41 \label{eq:L65}
3624 \end{equation}
3625 and
3626 \begin{equation}
3627 L_{45} = 1.415\alpha + 23.03 \label{eq:L45}
3628 \end{equation}
3629 fitted aspects of the data, where $\alpha$ is the length of the alphabet
3630 in points, and $L_{i}$ is the suggested width in points, for a line with
3631 $i$ characters (remember that 1pc = 12pt).
3632
3633
3634
3635 \tref{tab:cmrlengths} gives the lowercase alphabet\index{alphabet
3636 length} lengths for some typefaces over a range of font sizes; this
3637 may be used in conjunction with \tref{tab:copyfitting} on
3638 \pref{tab:copyfitting} when deciding on an appropriate
3639 textwidth\index{textwidth}. I have grouped the listed typefaces into
3640 roman, sans-serif, and monospaced, and they are all available in a
3641 standard \ltx\ system. The Computer Modern
3642 Roman\facesubseeidx{Computer Modern}, Concrete
3643 Roman\facesubseeidx{Concrete Roman}, Computer
3644 Sans\facesubseeidx{Computer Sans}, and
3645 Typewriter\facesubseeidx{Computer Typewriter}
3646 typefaces\index{typeface} were all designed by Donald Knuth
3647 using\index{font!Metafont} \metafont, specifically for use with
3648 \tx. The other font families are \pscript{} outline fonts and can be
3649 used in many document publishing systems. These particular fonts are
3650 available for use in \ltx\ via the packages in the
3651 \Ppack{psnfss}\index{psnfss?\Ppack{psnfss}} bundle. Be aware that the
3652 Knuthian\index{font!Knuthian} fonts were designed to form a font
3653 family --- that is, they were designed to work together and complement
3654 each other --- while the listed \pscript{}
3655 fonts\index{font!PostScript} were designed by different people at
3656 different times and for different
3657 purposes. Bringhurst~\cite[p. 96]{BRINGHURST99} memorably says
3658 `Baskerville\facesubseeidx{Baskerville},
3659 Helvetica\facesubseeidx{Helvetica}, Palatino\facesubseeidx{Palatino}
3660 and Times Roman\facesubseeidx{Times Roman}, for example --- which are
3661 four of the most widely available typefaces --- are four faces with
3662 nothing to offer one another except public disagreement'.
3663
3664
3665 The monospaced\index{font!monospaced}\index{monospaced font} fonts,
3666 Courier\facesubseeidx{Courier} and Typewriter\facesubseeidx{Typewriter}
3667 have no place in high quality typesetting except when typesetting computer
3668 code or the like, or when trying to fake text written on a real typewriter.
3669 Ignoring these, a quick glance at the \tablerefname{} shows that
3670 Bookman\facesubseeidx{Bookman} is a broad font while
3671 Times\facesubseeidx{Times Roman} is narrow as befits its original
3672 design intent for typesetting narrow columns in newspapers.
3673 Computer Modern\facesubseeidx{Computer Modern}
3674 tends towards the narrow end of the range.
3675
3676
3677 \begin{syntax}
3678 \lnc{\xlvchars} \lnc{\lxvchars} \\
3679 \end{syntax}
3680 \glossary(xlvchars)%
3681 {\ls{xlvchars}}%
3682 {Approximate length of 45 characters.}
3683 \glossary(lxvchars)%
3684 {\ls{lxvchars}}%
3685 {Approximate length of 65 characters.}
3686 Based on \tref{tab:cmrlengths}, the two lengths
3687 \lnc{\xlvchars} and
3688 \lnc{\lxvchars} are initially set to approximately the lengths of a
3689 line of text with
3690 45\index{measure!45 characters} or
3691 65\index{measure!65 characters} characters, respectively, for
3692 Computer Modern Roman in the type size selected for the document.
3693
3694 If you are using a different font or size you can use something like the
3695 following to calculate and print out the length for you.
3696 \begin{lcode}
3697 \newlength{\mylen} % a length
3698 \newcommand{\alphabet}{abc...xyz} % the lowercase alphabet
3699 \begingroup % keep font change local
3700 % font specification e.g., \Large\sffamily
3701 \settowidth{\mylen}{\alphabet}
3702 The length of this alphabet is \the\mylen. % print in document
3703 \typeout{The length of the Large sans alphabet
3704 is \the\mylen} % put in log file
3705 \endgroup % end the grouping
3706 \end{lcode}
3707 The \cmd{\typeout} macro prints its argument to the terminal and the
3708 log file. There is, however, an easier method.
3709
3710 \begin{syntax}
3711 \cmd{\setxlvchars}\oarg{fontspec} \\
3712 \cmd{\setlxvchars}\oarg{fontspec} \\
3713 \end{syntax}
3714 \glossary(setxlvchars)%
3715 {\cs{setxlvchars}\oarg{fontspec}}%
3716 {Sets \cs{xlvchars} to the length of 45 characters in the \meta{fontspec}
3717 font (default \cs{normalfont}).}
3718 \glossary(setlxvchars)%
3719 {\cs{setlxvchars}\oarg{fontspec}}%
3720 {Sets cs{lxvchars} to the length of 65 characters in the \meta{fontspec}
3721 font (default \cs{normalfont}).}
3722 The macros \cmd{\setxlvchars} and \cmd{\setlxvchars}, which were suggested
3723 by Morten H{\o}gholm\index{H{\o}gholm, Morten},
3724 set the lengths \lnc{\xlvchars} and \lnc{\lxvchars}
3725 respecively for the font \meta{fontspec}. The default for \meta{fontspec}
3726 is \cmd{\normalfont}. For example, the values of \lnc{\lxvchars} and
3727 \lnc{\xlvchars} after calling:
3728 \begin{lcode}
3729 \setlxvchars \setxlvchars[\small\sffamily]
3730 \end{lcode}
3731 \begingroup
3732 are: \setlxvchars\setxlvchars[\small\sffamily]
3733 \lnc{\lxvchars} = \the\lxvchars, and \lnc{\xlvchars} = \the\xlvchars.
3734 \endgroup
3735
3736 Morten H{\o}gholm\footnote{Private communication} also commented:
3737 \begin{quotation}
3738 \ldots I was defining some environments that had to have \lnc{\parindent}
3739 as their indentation. For some reason I just wrote \verb?1.5em? instead
3740 of \lnc{\parindent} because I `knew' that was the value. What I had
3741 overlooked was that I had loaded the \Lpack{mathpazo} package~\cite{MATHPAZO},
3742 thus, among other things, altering \lnc{\parindent}. Conclusion: the
3743 environment would use 1.5em = 18.0pt, whereas the \lnc{\parindent}
3744 was only 17.607pt.
3745
3746 This, and other related situations can be avoided if one places
3747 \begin{center}
3748 \cmd{\RequirePackage}\marg{font-package}\cmd{\normalfont}
3749 \end{center}
3750 \emph{before} \cmd{\documentclass}.
3751 \end{quotation}
3752 Note that, in general, it is inadviseable to put any
3753 commands\index{packages before class} before
3754 \cmd{\documentclass}.
3755
3756
3757
3758
3759 \PWnote{2009/04/01}{Fixed errors in lowercase alphabet lengths for Utopia (2) and Avantgarde (1)}
3760 \PWnote{2009/04/28}{Corrected font names of Avant Garde Gothic, Times Roman,
3761 New Century Schoolbook}
3762 \begin{table}
3763 \centering
3764 \caption{Lowercase alphabet lengths, in points, for various fonts}\label{tab:cmrlengths}
3765 \begin{tabular}{lrrrrrrrr} \toprule
3766 & 8pt & 9pt & 10pt & 11pt & 12pt & 14pt & 17pt & 20pt \\ \midrule
3767 \fontfamily{pbk}\selectfont Bookman & 113 & 127 & 142 & 155 & 170 & 204 & 245 & 294 \\
3768 \fontfamily{bch}\selectfont Charter & 102 & 115 & 127 & 139 & 152 & 184 & 221 & 264 \\
3769 \fontfamily{cmr}\selectfont Computer Modern & 108 & 118 & 127 & 139 & 149 & 180 & 202 & 242 \\
3770 \fontfamily{ccr}\selectfont Concrete Roman & 109 & 119 & 128 & 140 & 154 & 185 & 222 & 266 \\
3771 \fontfamily{pnc}\selectfont New Century Schoolbook & 108 & 122 & 136 & 149 & 162 & 194 & 234 & 281 \\
3772 \fontfamily{ppl}\selectfont Palatino & 107 & 120 & 133 & 146 & 160 & 192 & 230 & 276 \\
3773 \fontfamily{ptm}\selectfont Times Roman & 96 & 108 & 120 & 131 & 143 & 172 & 206 & 247 \\
3774 \fontfamily{put}\selectfont Utopia & 107 & 120 & 134 & 146 & 161 & 193 & 232 & 277 \\
3775 \fontfamily{pag}\selectfont Avant Garde Gothic & 113 & 127 & 142 & 155 & 169 & 203 & 243 & 293 \\
3776 \fontfamily{cmss}\selectfont Computer Sans & 102 & 110 & 120 & 131 & 140 & 168 & 193 & 233 \\
3777 \fontfamily{phv}\selectfont Helvetica & 102 & 114 & 127 & 139 & 152 & 184 & 220 & 264 \\
3778 \fontfamily{pcr}\selectfont Courier & 125 & 140 & 156 & 170 & 187 & 224 & 270 & 324 \\
3779 \fontfamily{cmtt}\selectfont Typewriter & 110 & 122 & 137 & 149 & 161 & 192 & 232 & 277 \\
3780 \bottomrule
3781 \facesubseeidx{Bookman}\facesubseeidx{Charter}\facesubseeidx{Computer Modern}%
3782 \facesubseeidx{Concrete Roman}\facesubseeidx{New Century Schoolbook}
3783 \facesubseeidx{Palatino}\facesubseeidx{Times Roman}\facesubseeidx{Utopia}%
3784 \facesubseeidx{Avant Garde Gothic}\facesubseeidx{Computer Sans}
3785 \facesubseeidx{Helvetica}\facesubseeidx{Courier}%
3786 \facesubseeidx{Computer Typewriter}%
3787 \end{tabular}
3788 \end{table}
3789
3790
3791
3792 \subsection{Specifying the typeblock size}
3793 \label{sec:spec-typebl-size}
3794
3795
3796
3797
3798 The height of the typeblock\index{typeblock!height} should be
3799 equivalent to an integral number of lines. The class provides two
3800 different methods to specify the typeblock. \cmd{\settypeblocksize}
3801 (below) will set the size of the typeblock, other commands will then
3802 be used to place it on the paper. Alternatively the typeblock size can
3803 be determined by setting the margins around it. We present this later
3804 on in this section (see \cmd{\setlrmarginsandblock} and
3805 \cmd{\setulmarginsandblock}).
3806
3807 \begin{syntax}
3808 \cmd{\settypeblocksize}\marg{height}\marg{width}\marg{ratio} \\
3809 \end{syntax}
3810 \glossary(settypeblocksize)%
3811 {\cs{settypeblocksize}\marg{height}\marg{width}\marg{ratio}}%
3812 {Sets the size of the typeblock.}
3813 \glossary(textheight)%
3814 {\ls{textheight}}%
3815 {The height of the typeblock.}
3816 \glossary(textwidth)%
3817 {\ls{textwidth}}%
3818 {The width of the typeblock.}
3819 The command \cmd{\settypeblocksize}\index{typeblock!specifying size}
3820 is similar to
3821 \cmd{\settrimmedsize} except that it sets the \lnc{\textheight} and
3822 \lnc{\textwidth} for the typeblock\index{typeblock!height}\index{typeblock!width}.
3823 The potential combinations of arguments and the
3824 corresponding results are listed in \tref{tab:rectsize} on \pref{tab:rectsize}.
3825 For instance, here are three ways of specifying
3826 a 6in by 3in typeblock\index{typeblock}:
3827 \begin{lcode}
3828 \settypeblocksize{6in}{3in}{*}
3829 \settypeblocksize{6in}{*}{0.5}
3830 \settypeblocksize{*}{3in}{2}
3831 \end{lcode}
3832
3833 The typeblock\index{typeblock} has to be located on the page. There is
3834 a relationship between the page, typeblock\index{typeblock} and
3835 margins\index{margin}. The sum of the spine, or inner,
3836 margin\index{margin!spine}\index{margin!inner},
3837 the \foredge, or outer, margin\index{margin!foredge?\foredge}\index{margin!outer}
3838 and the width of the
3839 typeblock\index{typeblock!width} must equal the width\index{page!width}
3840 of the page.
3841 Similarly the sum of the upper margin\index{margin!upper},
3842 the lower margin\index{margin!lower} and the height of the
3843 typeblock\index{typeblock!height}
3844 must equal the height\index{page!height} of the page.
3845 The process of locating the
3846 typeblock\index{typeblock} with respect to the page can be viewed
3847 either as positioning the typeblock\index{typeblock} with respect to the edges
3848 of the page or as setting the margins\index{margin} between the page and the
3849 typeblock\index{typeblock}.
3850
3851 Remembering that the page layout should be defined in terms of the
3852 appearance as a spread\index{spread}, the spine margin\index{margin!spine}
3853 is normally half the \foredge{} margin\index{margin!foredge?\foredge},
3854 so that the white space is equally distributed around the sides of the text.
3855
3856 \begin{note}
3857 One will often find that using \cmd{\settypeblocksize} without
3858 subsequent use of \cmd{\setlrmargins} and \cmd{\setulmargins} will
3859 result in errors as the relationships mentioned above are not met
3860 (the \lnc{\textwidth} has changed, but not the margins).
3861
3862 We may add auto adjustments to a future version of \theclass.
3863 \end{note}
3864
3865
3866 There is more latitude in choosing the
3867 proportions\index{proportion!margin}
3868 of the upper and lower margins, though usually the upper
3869 margin\index{margin!upper} is less than the lower margin\index{margin!lower}
3870 so the typeblock\index{typeblock!location} is not vertically centered.
3871
3872 Two methods are provided for setting the horizontal dimensions on a page.
3873 One is where the width of the typeblock\index{typeblock!width}
3874 is fixed and the margins\index{margin} are adjustable.
3875 The other method is where the size of the margins\index{margin} determines
3876 the width of the typeblock\index{typeblock!width}.
3877
3878 \begin{syntax}
3879 \cmd{\setlrmargins}\marg{spine}\marg{edge}\marg{ratio} \\
3880 \end{syntax}
3881 \glossary(setlrmargins)%
3882 {\cs{setlrmargins}\marg{spine}\marg{edge}\marg{ratio}}%
3883 {Sets the spine and \foredge{} margins for the current typeblock width.}
3884 The command \cmd{\setlrmargins}\index{margin!specify width} can be used to specify
3885 the side margins\footnote{Only the spine margin is noted in
3886 \fref{fig:oddstock} and~\ref{fig:evenstock};
3887 the \foredge\ margin\index{margin!foredge?\foredge} is at the
3888 opposite side of the typeblock.}
3889 with the width of the page and the typeblock being fixed.
3890
3891 Not more than one one argument value is required, with any
3892 unvalued arguments being denoted by an asterisk. There are several cases to
3893 consider and these are tabulated in \tref{tab:lrmargins}.
3894
3895 In the \tablerefname, $S$ is the calculated spine
3896 margin\index{margin!spine},
3897 $E$ is the calculated \foredge{} margin\index{margin!foredge?\foredge},
3898 and $P_{w}$ and $B_{w}$ are respectively the page\index{page!width} and
3899 typeblock\index{typeblock!width}
3900 widths. The \cmd{\setlrmargins}\index{margin!specifying size} command maintains the relationship
3901 \begin{displaymath}
3902 S + E = K_{w} = \textrm{constant} \mbox{\space} (= P_{w} - B_{w}).
3903 \end{displaymath}
3904
3905
3906 \begin{table}
3907 \centering
3908 \caption{Arguments and results for \cs{setlrmargins} } \label{tab:lrmargins}
3909 %\begin{tabular}{ccc|l} \hline
3910 \begin{tabular}{cccl} \toprule
3911 \meta{spine} & \meta{edge} & \meta{ratio} & Result \\ \midrule
3912 S & E & r & ambiguous \\
3913 S & E & * & ambiguous \\
3914 S & * & r & ambiguous \\
3915 S & * & * & $E = K_{w} - S$ \\
3916 {*} & E & r & ambiguous \\
3917 {*} & E & * & $S = K_{w} - E$ \\
3918 {*} & * & r & $E + S = K_{w}$, $E = rS$ \\
3919 {*} & * & * & $E + S = K_{w}$, $E = S$ \\
3920 \bottomrule
3921 \end{tabular}
3922 \end{table}
3923
3924 The cases marked ambiguous in the \tablerefname{} are where the particular combination
3925 of argument values may make it impossible to guarantee the relationship.
3926
3927 Assuming that we have a 3in wide typeblock\index{typeblock!width} on a 5in
3928 wide page and we want the spine margin\index{margin!spine} to be 0.8in and
3929 the \foredge{} margin\index{margin!foredge?\foredge} to be 1.2in
3930 (i.e., the \foredge{} margin is half as big again as the spine margin)
3931 this can be accomplished in three ways (with the \cmd{\paperwidth} and
3932 \lnc{\textwidth} being previously specified and fixed):
3933 \begin{lcode}
3934 % specify spine margin
3935 \setlrmargins{0.8in}{*}{*}
3936 % specify fore-edge margin
3937 \setlrmargins{*}{1.2in}{*}
3938 % specify fore-edge/spine ratio
3939 \setlrmargins{*}{*}{1.5}
3940 \end{lcode}
3941
3942 \begin{syntax}
3943 \cmd{\setlrmarginsandblock}\marg{spine}\marg{edge}\marg{ratio}\\
3944 \end{syntax}
3945 \glossary(setlrmarginsandblock)%
3946 {\cs{setlrmarginsandblock}\marg{spine}\marg{edge}\marg{ratio}}%
3947 {Sets the spine and \foredge{} margins, modifying the typeblock width to match.}
3948 The command \cmd{\setlrmarginsandblock}\index{margin!specifying size}
3949 can be used to specify the spine\index{margin!spine} and
3950 \foredge\ margins\index{margin!foredge?\foredge},
3951 where the page width\index{page!width} is fixed and the width of the
3952 typeblock\index{typeblock!width}
3953 depends on the margins\index{margin}. Results
3954 for this command are given in \tref{tab:lrblock}. The same notation is used,
3955 but in this case \cmd{\setlrmarginsandblock} maintains the relationship
3956 \begin{displaymath}
3957 S + B_{w} + E = \textrm{constant} \mbox{\space} (= P_{w}).
3958 \end{displaymath}
3959 The width of the typeblock\index{typeblock} is calculated
3960 from $B_{w} = P_{w} - S - E$.
3961
3962 \begin{table}
3963 \centering
3964 \caption{Arguments and results for \cs{setlrmarginsandblock} } \label{tab:lrblock}
3965 %\begin{tabular}{ccc|l} \hline
3966 \begin{tabular}{cccl} \toprule
3967 \meta{spine} & \meta{edge} & \meta{ratio} & Result \\ \midrule
3968 S & E & r & $S$, $E$ \\
3969 S & E & * & $S$, $E$ \\
3970 S & * & r & $E = rS$ \\
3971 S & * & * & $E = S$ \\
3972 {*} & E & r & $S = rE$ \\
3973 {*} & E & * & $S = E$ \\
3974 {*} & * & r & ambiguous \\
3975 {*} & * & * & ambiguous \\
3976 \bottomrule
3977 \end{tabular}
3978 \end{table}
3979
3980 Assuming that we want a 3in wide typeblock\index{typeblock!width} on a
3981 5in wide page\index{page!width} and we want the spine
3982 margin\index{margin!spine} to be 0.8in and the \foredge{}
3983 margin\index{margin!foredge?\foredge} to be 1.2in
3984 (i.e., the \foredge\ margin is half as big again as the spine margin)
3985 this can be accomplished in the following ways (with the \lnc{\textwidth}
3986 being calculated from the previously specified \cmd{\paperwidth} and the
3987 specified margins):
3988 \begin{lcode}
3989 % specify both margins
3990 \setlrmarginsandblock{0.8in}{1.2in}{*}
3991 % specify spine & fore-edge/spine ratio
3992 \setlrmarginsandblock{0.8in}{*}{1.5}
3993 % specify fore-edge & spine/fore-edge ratio
3994 \setlrmarginsandblock{*}{1.2in}{0.667}
3995 \end{lcode}
3996 If we wanted the margins\index{margin!specifying size} to be both 1in
3997 instead then any of the following
3998 will do it:
3999 \begin{lcode}
4000 % specify both margins
4001 \setlrmarginsandblock{1in}{1in}{*}
4002 % specify spine & fore-edge/spine ratio
4003 \setlrmarginsandblock{1in}{*}{1}
4004 % specify spine (fore-edge = spine)
4005 \setlrmarginsandblock{1in}{*}{*}
4006 % specify fore-edge & spine/fore-edge ratio
4007 \setlrmarginsandblock{*}{1in}{1}
4008 % specify fore-edge (spine = fore-edge)
4009 \setlrmarginsandblock{*}{1in}{*}
4010 \end{lcode}
4011
4012 \begin{syntax}
4013 \cmd{\setbinding}\marg{length} \\
4014 \end{syntax}
4015 \glossary(setbinding)%
4016 {\cs{setbinding}\marg{length}}%
4017 {Adds a binding allowance to the spine margin.}
4018 In some cases, for example when doing a Japanese stab binding, it may be
4019 desireable to add a small allowance\index{binding allowance}
4020 to the spine margin for the binding.
4021 You can use the command \cmd{\setbinding} for this purpose. It decreases the
4022 effective page width by \meta{length} and later this length will be added
4023 on to the spine margin, thus restoring the page width to its original value.
4024 If you use \cmd{\setbinding} than it must be \emph{after} setting the page
4025 width and \emph{before} setting the spine and fore-edge margins.
4026
4027 That completes the methods for specifying the horizontal spacings. There
4028 are similar commands for setting the vertical spacings which are
4029 described below.
4030
4031 \begin{syntax}
4032 \cmd{\setulmargins}\marg{upper}\marg{lower}\marg{ratio} \\
4033 \end{syntax}
4034 \glossary(setulmargins)%
4035 {\cs{setulmargins}\marg{upper}\marg{lower}\marg{ratio}}%
4036 {Sets the upper and lower margins with the current typeblock height.}
4037 The command \cmd{\setulmargins} can be used to
4038 specify\index{margin!specifying size}
4039 the upper and lower margins\footnote{Only the upper margin is noted in
4040 \fref{fig:oddstock} and~\ref{fig:evenstock};
4041 the lower margin\index{margin!lower} is the distance between the bottom
4042 of the typeblock\index{typeblock} and the bottom of the page.}
4043 where the heights of the page\index{page!height} and the
4044 typeblock\index{typeblock!height} are
4045 fixed. This is similar to \cmd{\setlrmargins}. Using a slightly
4046 different notation this time, with $U$ being the upper
4047 margin\index{margin!upper}, $L$ being the lower margin\index{margin!lower},
4048 and $P_{h}$ and $B_{h}$ being the
4049 \emph{height} of the page\index{page!height} and
4050 typeblock\index{typeblock!height}, respectively,
4051 the results are shown in \tref{tab:ulmargins}.
4052 The \cmd{\setulmargins} command maintains the relationship
4053 \begin{displaymath}
4054 U + L = K_{h} = \textrm{constant} \mbox{\space} (= P_{h} - B_{h}).
4055 \end{displaymath}
4056
4057 Note that in terms of the traditional \ltx\ parameters memoir's
4058 \lnc{\uppermargin} is (\lnc{\topmargin} + \lnc{\headheight} + \lnc{\headsep}).
4059
4060 \begin{table}
4061 \centering
4062 \caption{Arguments and results for \cs{setulmargins} } \label{tab:ulmargins}
4063 %\begin{tabular}{ccc|l} \hline
4064 \begin{tabular}{cccl} \toprule
4065 \meta{upper} & \meta{lower} & \meta{ratio} & Result \\ \midrule
4066 U & L & r & ambiguous \\
4067 U & L & * & ambiguous \\
4068 U & * & r & ambiguous \\
4069 U & * & * & $L = K_{h} - U$ \\
4070 {*} & L & r & ambiguous \\
4071 {*} & L & * & $U = K_{h} - L$ \\
4072 {*} & * & r & $L + U = K_{h}$, $L = rU$ \\
4073 {*} & * & * & $L + U = K_{h}$, $L = U$ \\
4074 \bottomrule
4075 \end{tabular}
4076 \end{table}
4077
4078 \begin{syntax}
4079 \cmd{\setulmarginsandblock}\marg{upper}\marg{lower}\marg{ratio} \\
4080 \end{syntax}
4081 \glossary(setulmarginsandblock)%
4082 {\cs{setulmarginsandblock}\marg{upper}\marg{lower}\marg{ratio}}%
4083 {Sets the upper and lower margins, modifying the typeblock height to match.}
4084 The command \cmd{\setulmarginsandblock}
4085 can be used to specify\index{margin!specifying size}
4086 the upper\index{margin!upper} and lower margins\index{margin!lower},
4087 where the page height\index{page!height}
4088 is fixed and the height of the typeblock\index{typeblock!height}
4089 depends on the margins. Results
4090 for this command are given in \tref{tab:ulblock}. The same notation is used,
4091 but in this case \cmd{\setulmarginsandblock} maintains the
4092 relationship
4093 \begin{displaymath}
4094 U + B_{h} + L = \textrm{constant} \mbox{\space} (P_{h}).
4095 \end{displaymath}
4096 The height of the typeblock\index{typeblock!specifying size}
4097 is calculated from $B_{h} = P_{h} - U - L$.
4098
4099 \begin{table}
4100 \centering
4101 \caption{Arguments and results for \cs{setulmarginsandblock} } \label{tab:ulblock}
4102 %\begin{tabular}{ccc|l} \hline
4103 \begin{tabular}{cccl} \toprule
4104 \meta{upper} & \meta{lower} & \meta{ratio} & Result \\ \midrule
4105 U & L & r & $U$, $L$ \\
4106 U & L & * & $U$, $L$ \\
4107 U & * & r & $L = rU$ \\
4108 U & * & * & $L = U$ \\
4109 {*} & L & r & $U = rL$ \\
4110 {*} & L & * & $U = L$ \\
4111 {*} & * & r & ambiguous \\
4112 {*} & * & * & ambiguous \\
4113 \bottomrule
4114 \end{tabular}
4115 \end{table}
4116
4117 \begin{note}
4118 Readers may find several folio designs in \cite{MEMDESIGN}.
4119 \end{note}
4120
4121 See also \Sref{sec:predefined-layouts}
4122 (\emph{\titleref{sec:predefined-layouts}}) for some predefined layouts.
4123
4124
4125
4126
4127 This completes the methods for specifying the layout of the
4128 main elements of the page --- the page\index{page!specifying size}
4129 size, the size of the typeblock\index{typeblock!specifying size} and the
4130 margins\index{margin!specifying size}
4131 surrounding the typeblock\index{typeblock!location}.
4132
4133 \section{Headers, footers and marginal notes}
4134 \label{sec:head-foot-marg}
4135 \index{header|(}\index{footer|(}
4136
4137 A page may have two additional items, and usually has at least one of
4138 these. They are the running header and running footer. If the page has a
4139 folio\index{folio} then it is located either in the header or in the footer.
4140 The word `in' is used rather lightly here as the folio\index{folio}
4141 may not be actually \emph{in} the header or footer but is always located
4142 at some constant relative position. A common position for the
4143 folio\index{folio} is towards the \foredge\index{foredge?\foredge}\index{margin!outer} of the
4144 page, either in the header or the footer. This makes it easy to spot when
4145 thumbing through the book. It may be placed at the center of the footer,
4146 but unless you want to really annoy the reader do not place it near
4147 the spine.
4148
4149 Often a page header contains the current chapter title, with perhaps a
4150 section title on the opposite header, as aids to the reader in navigating
4151 around the book. Some books put the book title into one of the headers,
4152 usually the verso one, but I see
4153 little point in that as presumably the reader knows which particular book he
4154 is reading, and the space would be better used providing more useful signposts.
4155
4156 \index{header!specifying size|(}
4157
4158 \begin{syntax}
4159 \cmd{\setheadfoot}\marg{headheight}\marg{footskip} \\
4160 \end{syntax}
4161 \glossary(setheadfoot)%
4162 {\cs{setheadfoot}\marg{headheight}\marg{footskip}}%
4163 {Sets the headheight and footskip.}
4164 \glossary(headheight)%
4165 {\ls{headheight}}%
4166 {Height available for a header.}
4167 \glossary(footskip)%
4168 {\ls{footskip}}%
4169 {Distance between the bottom of the typeblock and the bottom of a footer.}
4170 The \cmd{\setheadfoot} macro sets the
4171 \lnc{\headheight} parameter to the value \meta{headheight} and the
4172 \lnc{\footskip} parameter to \meta{footskip}. It is usual to set the
4173 \lnc{\headheight} to at least the value of the \lnc{\baselineskip} of
4174 the normal body font.
4175
4176
4177 \begin{syntax}
4178 \cmd{\setheaderspaces}\marg{headdrop}\marg{headsep}\marg{ratio} \\
4179 \end{syntax}
4180 \glossary(setheaderspaces)%
4181 {\cs{setheaderspaces}\marg{headdrop}\marg{headsep}\marg{ratio}}%
4182 {Sets the spacing above and below a header.}
4183 \glossary(headsep)%
4184 {\ls{headsep}}%
4185 {Distance between the bottom of a header and the top of the typeblock.}
4186 \glossary(headdrop)%
4187 {\ls{headdrop}}%
4188 {Distance between the top of the trimmed page and the top of a header.}
4189 The command \cmd{\setheaderspaces} is similar to \cmd{\setulmargins}.
4190 Using the notation $U$ for the upper margin\index{margin!upper} (as before), $H_{h}$ for the
4191 \lnc{\headheight}, $H_{s}$ for the \lnc{\headsep} and $D$ for the
4192 \lnc{\headdrop}, where the \lnc{\headdrop} is the distance between the top
4193 of the trimmed page and the top of the header\footnote{The head drop is not
4194 shown in \fref{fig:oddstock} or~\ref{fig:evenstock}.},
4195 then the macro \cmd{\setheaderspaces} maintains the relationship
4196 \begin{displaymath}
4197 D + H_{s} = C_{h} = \textrm{constant} \mbox{\space} (= U - H_{h}).
4198 \end{displaymath}
4199
4200 \begin{table}
4201 \centering
4202 \caption{Arguments and results for \cs{setheaderspaces} } \label{tab:headspaces}
4203 %\begin{tabular}{ccc|l} \hline
4204 \begin{tabular}{cccl} \toprule
4205 \meta{headdrop} & \meta{headsep} & \meta{ratio} & Result \\ \midrule
4206 D & $H_{s}$ & r & ambiguous \\
4207 D & $H_{s}$ & * & ambiguous \\
4208 D & * & r & ambiguous \\
4209 D & * & * & $H_{s} = C_{h} - D$ \\
4210 {*} & $H_{s}$ & r & ambiguous \\
4211 {*} & $H_{s}$ & * & $D = C_{h} - H_{s}$ \\
4212 {*} & * & r & $H_{s} + D = C_{h}$, $H_{s} = rD$ \\
4213 {*} & * & * & $H_{s} + D = C_{h}$, $H_{s} = D$ \\
4214 \bottomrule
4215 \end{tabular}
4216 \end{table}
4217
4218 The macro \cmd{\setheaderspaces} is for specifying the spacing above and below
4219 the page header.
4220 The possible arguments and results are shown in \tref{tab:headspaces}. Typically,
4221 the \lnc{\headsep} is of more interest than the \lnc{\headdrop}.
4222
4223 \index{header!specifying size|)}
4224 \index{footer|)}\index{header|)}
4225
4226 \index{marginalia|(}
4227 Finally, some works have marginal notes. These really come last in the
4228 design scheme, providing the margins have been made big enough to accomodate
4229 them. \fref{fig:evenstock} shows the marginal note parameters on a verso
4230 page, and also illustrates that some parameters control different
4231 positions on the stock\index{stock}.
4232
4233
4234
4235 \begin{syntax}
4236 \cmd{\setmarginnotes}\marg{separation}\marg{width}\marg{push} \\
4237 \end{syntax}
4238 \glossary(setmarginnotes)%
4239 {\cs{setmarginnotes}\marg{separation}\marg{width}\marg{push}}%
4240 {Sets the length parameters for marginal notes.}
4241 \glossary(marginparsep)%
4242 {\ls{marginparsep}}%
4243 {Horizontal distance between the edge of the typeblock and a marginal note.}
4244 \glossary(marginparwidth)%
4245 {\ls{marginparwidth}}%
4246 {Maximum width of marginal note.}
4247 \glossary(marginparpush)%
4248 {\ls{marginparpush}}%
4249 {Minimum vertical distance between marginal notes.}
4250
4251 The command \cmd{\setmarginnotes}
4252 sets the parameters for marginal notes. The distance \lnc{\marginparsep}
4253 between the typeblock\index{typeblock} and any note is set
4254 to \meta{separation}, the
4255 maximum width for a note, \lnc{\marginparwidth}, is set to \meta{width}
4256 and the minimum vertical distance between notes, \lnc{\marginparpush},
4257 is set to \meta{push}.
4258
4259 \begin{note}
4260 As of \theclass\ v3.6k, we have added an auto adjustment feature for
4261 \lnc{\marginparwidth}, such that unless \cmd{\setmarginnotes} have
4262 been used to make a specific choice, the \lnc{\marginparwidth} is
4263 chosen according to the algorithm described in
4264 \Sref{sec:auto-csmarg}. The algorithm relies on
4265 \cmd{\marginparmargin} (if used) being set \emph{before}
4266 \cmd{\checkandfixthelayout}.
4267
4268 We may add other auto adjusting features to future \theclass\ releases.
4269 \end{note}
4270
4271 \index{marginalia|)} %|
4272
4273
4274 \section{Other}
4275 \label{sec:other}
4276
4277 \begin{syntax}
4278 \cmd{\setcolsepandrule}\marg{colsep}\marg{thickness} \\
4279 \end{syntax}
4280 \glossary(setcolsepandrule)%
4281 {\cs{setcolsepandrule}\marg{colsep}\marg{thickness}}%
4282 {Sets the width of the gutter and the thickness of the rule in the gutter.}
4283 \glossary(columnsep)%
4284 {\ls{columnsep}}%
4285 {Width of the gutter between columns.}
4286 \glossary(columnseprule)%
4287 {\ls{columnseprule}}%
4288 {Thickness of the rule in the gutter.}
4289 For twocolumn\index{column!double} text the width of
4290 the gutter\index{gutter}
4291 between the columns must be specified. \ltx\ also lets you draw a
4292 vertical rule in the middle of the
4293 gutter. The macro \cmd{\setcolsepandrule}
4294 sets the gutter width\index{gutter!width}, \lnc{\columnsep}, to \meta{colsep}
4295 and the thickness of the rule, \lnc{\columnseprule},
4296 to \meta{thickness}. A \meta{thickness} of 0pt means that the rule will be
4297 invisible. Visible rules usually have a thickness\index{rule!thickness}
4298 of about 0.4pt. The total width of the twocolumns\index{column!double}
4299 of text and the gutter equals the width of the typeblock\index{typeblock}.
4300
4301
4302 \fancybreak{}
4303
4304
4305 \begin{syntax}
4306 \cmd{\setfootins}\marg{length for normal}\marg{length for minipage} \\
4307 \end{syntax}
4308 % \glossary(setfootins)%
4309 % {\cs{setfootins}\marg{length for normal}\marg{length for minipage}}%
4310 % {Sets \cs{skip}\cs{footins} and its minipage counterpart.}
4311
4312 \noindent
4313 When footnotes are added to the text block they are added
4314 \cs{skip}\cs{footins} below the text. Since this is a skip it usually
4315 needs special syntax to change it. Instead we have provided an
4316 interface to set it.\footnote{This interface also sets the equivalent
4317 lengths used when \cs{twocolumnfootnotes} and friends are being
4318 used.} The default sizes are \cs{bigskipamount}.
4319
4320
4321
4322
4323 \section{Putting it together}
4324
4325 The page layout parameters\index{page layout!class parameters}
4326 just discussed are not always the same
4327 as those that are expected by \ltx, or by \ltx\ packages. The parameters
4328 that \ltx\ expects are shown in \fref{fig:anoddpage}. You can either use
4329 the class commands for changing the page layout or change the \ltx\
4330 parameters\index{page layout!LaTeX parameters?\ltx\ parameters}
4331 directly using either \cmd{\setlength} or \cmd{\addtolength} applied to the
4332 parameter(s) to be modified. If you choose the latter route, those class
4333 parameters which differ from the standard \ltx\ parameters will \emph{not} be
4334 modified.
4335
4336 The general process of setting up your own page layout\index{page layout}
4337 is along these lines:
4338 \begin{itemize}
4339 \item Decide on the required finished page\indextwo{page}{size} size,
4340 and pick a stock\indextwo{stock}{size} size that is at least as
4341 large as the page.
4342 \item If needed, use \cmd{\setstocksize}\index{stock!specifying size}
4343 to set the values of \lnc{\stockheight} and \lnc{\stockwidth},
4344 followed by \cmd{\settrimmedsize} to specify the values\ of
4345 \lnc{\paperheight} and \lnc{\paperwidth}.
4346
4347 If you use and print on, say, A4, the \texttt{a4paper} class option
4348 is enough, no \cmd{\setstocksize} needed.
4349 \item Decide on the location of the page\index{page!location} with
4350 respect to the stock\index{stock}. If the page and
4351 stock\index{stock} sizes are the same, then call
4352 \verb?\settrims{0pt}{0pt}?. If they are not the same size then
4353 decide on the appropriate values for \lnc{\trimtop} and
4354 \lnc{\trimedge} to position the page on the stock\index{stock}, and
4355 then set\index{trim!specifying} these through \cmd{\settrims}.
4356 \item Decide on the size of the typeblock\indextwo{typeblock}{size}
4357 and use \cmd{\settypeblocksize}\index{typeblock!specifying size} to
4358 specify the values of \lnc{\textheight} and \lnc{\textwidth}.
4359 \item If you need a binding\index{binding allowance} allowance, now is
4360 the time for \cmd{\setbinding}.
4361 \item Pick the value for the spine margin\index{margin!spine}, and use
4362 \cmd{\setlrmargins}\index{margin!specifying size} to set the values
4363 for the \lnc{\spinemargin} and \lnc{\foremargin}.
4364
4365 An alternative sequence is to use \cmd{\setlrmarginsandblock} to set
4366 the \lnc{\textwidth} for a particular choice of side
4367 margins\index{margin}.
4368
4369 \item Pick the value for the upper margin\index{margin!upper} and use
4370 \cmd{\setulmargins} to set the values\index{margin!specifying size}
4371 for the \lnc{\uppermargin} and \cmd{\lowermargin}.
4372
4373 An alternative sequence is to use \cmd{\setulmarginsandblock} to set
4374 the \lnc{\textheight} for a particular choice of upper and lower
4375 margins\index{margin}.
4376
4377 The typeblock is now located\index{typeblock!location} on the page.
4378
4379 \item Pick the values for the \lnc{\headheight} and \lnc{\footskip}
4380 and use \cmd{\setheadfoot}\index{header!specifying size} to specify
4381 these.
4382
4383 \item Pick your value for \cmd{\headskip} and use
4384 \cmd{\setheaderspaces} to set this and \lnc{\headmargin}.
4385
4386 \item If you are going to have any marginal\index{marginalia} notes,
4387 use \cmd{\setmarginnotes} to specify the values for
4388 \lnc{\marginparsep}, \lnc{\marginparwidth} and \lnc{\marginparpush}.
4389
4390 \end{itemize}
4391
4392 You can plan and specify your layout in any order that is
4393 convenient to you. Each of the page layout commands is independent of the
4394 others; also if
4395 a value is set at one point, say the \lnc{\textwidth}, and is then
4396 later changed in some way, only the last of the settings is used as the actual
4397 value.
4398
4399
4400 Comparing \figurerefname s~\ref{fig:oddstock} and~\ref{fig:anoddpage}
4401 you can see the different layout\index{page layout!parameters} parameters
4402 provided by the class and used by standard
4403 \ltx. For convenience, and because the figures do not show all
4404 the parameters, the two sets of parameters are listed in \tref{tab:stockpage}.
4405
4406 \begin{table}
4407 \centering
4408 \caption{The class and \ltx\ page layout parameters}\label{tab:stockpage}
4409 %\begin{tabular}{ll} \hline
4410 \begin{tabular}{ll} \toprule
4411 Class & \ltx\ \\ \midrule
4412 \lnc{\stockheight} & \\
4413 \lnc{\trimtop} & \\
4414 \lnc{\trimedge} & \\
4415 \lnc{\stockwidth} & \\
4416 \lnc{\paperheight} & \lnc{\paperheight} \\
4417 \lnc{\paperwidth} & \lnc{\paperwidth} \\
4418 \lnc{\textheight} & \lnc{\textheight} \\
4419 \lnc{\textwidth} & \lnc{\textwidth} \\
4420 \lnc{\columnsep} & \lnc{\columnsep} \\
4421 \lnc{\columnseprule} & \lnc{\columnseprule} \\
4422 \lnc{\spinemargin} & \\
4423 \lnc{\foremargin} & \\
4424 & \lnc{\oddsidemargin} \\
4425 & \lnc{\evensidemargin} \\
4426 \lnc{\uppermargin} & \\
4427 \lnc{\headmargin} & \\
4428 & \lnc{\topmargin} \\
4429 \lnc{\headheight} & \lnc{\headheight} \\
4430 \lnc{\headsep} & \lnc{\headsep} \\
4431 \lnc{\footskip} & \lnc{\footskip} \\
4432 \lnc{\marginparsep} & \lnc{\marginparsep} \\
4433 \lnc{\marginparwidth} & \lnc{\marginparwidth} \\
4434 \lnc{\marginparpush} & \lnc{\marginparpush} \\
4435 \bottomrule
4436 \end{tabular}
4437 \end{table}
4438
4439 Unless you are satisfied with the default page layout, after specifying
4440 the layout that you want you have to call the \cmd{\checkandfixthelayout}
4441 command to finally implement your specification.
4442
4443 \begin{syntax}
4444 \cmd{\checkandfixthelayout}\oarg{algorithm} \\
4445 \cmd{\checkthelayout}\oarg{algorithm} \\
4446 \cmd{\fixthelayout} \\
4447 \lnc{\baselineskip} \lnc{\topskip} \\
4448 \end{syntax}
4449 \glossary(checkandfixthelayout)%
4450 {\cs{checkandfixthelayout}\oarg{algorithm}}%
4451 {Command to check and implement the page layout specifications, adjusting
4452 the \cs{textheight} using \meta{algorithm}
4453 (classic, fixed, lines, or nearest, the default being classic)
4454 for the calculation.}%
4455 \glossary(checkthelayout)%
4456 {\cs{checkthelayout}\oarg{algorithm}}%
4457 {Command to check the page layout specifications, adjusting
4458 the \cs{textheight} using \meta{algorithm}
4459 (classic, fixed, lines, or nearest, the default being classic)
4460 for the calculation.}%
4461 \glossary(topskip)%
4462 {\ls{topskip}}%
4463 {The height of the first line of text on a page. This is usually
4464 less than the \cs{baselineskip}.}
4465 \glossary(baselineskip)%
4466 {\ls{baselineskip}}%
4467 {The normal vertical distance between the baselines of adjacent lines
4468 of text (depends on the size of the font).}
4469
4470 The \cmd{\checkandfixthelayout} macro uses
4471 \cmd{\checkthelayout} to
4472 check the page layout specification you have given, and then calls
4473 \cmd{\fixthelayout} to finally implement it.
4474
4475 The \cmd{\checkthelayout} macro checks the class layout
4476 parameters\index{page layout!check parameters} to see whether
4477 they have `sensible' values (e.g., the \lnc{\textwidth} is not negative)
4478 and, depending on the \meta{algorithm} argument, it may modify the
4479 \lnc{\textheight}. It does not actually implement the layout.
4480
4481 When using \cmd{\flushbottom} \ltx\ expects that the \lnc{\textheight}
4482 is such that an integral number of text lines in the body font will fit
4483 exactly into the height. If not, then it issues `underfull vbox' messages.
4484 More precisely, if $b$ is the \lnc{\baselineskip} and $t$ is the
4485 \lnc{\topskip}, $N$ is an integer (the number of lines in the typeblock),
4486 and $T$ is the
4487 \lnc{\textheight} then to avoid underfull vboxes the following relationship
4488 must hold
4489 \begin{equation}
4490 T = (N-1)b + t \label{eq:heightlines}
4491 \end{equation}
4492 By default \cmd{\checkthelayout} ensures that the final \lnc{\textheight}
4493 meets this criterion. The optional \meta{algorithm} argument lets you control
4494 just how it does this. In the following $H$ is your requested value for
4495 the \lnc{\textheight} and the other symbols are as before, with $T$ as
4496 the adjusted value, and using integer arithmetic.\footnote{In this context
4497 `integer arithmetic' means that the result of a division will be rounded down.
4498 For example $99/10$ in `real arithmetic' results in $9.9$, whereas with
4499 integer arithmetic the result is 9, not 10.}
4500 The permissible values for \meta{algorithm} are:
4501 \begin{itemize}
4502 \item[\texttt{fixed}] The \lnc{\textheight} is not altered.
4503 \begin{equation} T = H \end{equation}
4504 If you use this option you may find that underfull vboxes are reported
4505 for \cmd{\flushbottom} pages.
4506 \item[\texttt{classic}] This is the default and is the one used by the standard
4507 classes.
4508 \begin{equation} T = b \lfloor H/b \rfloor + t \end{equation}
4509 The relationship (\ref{eq:heightlines}) is maintained. This algorithm
4510 gets as close to $H$ as possible from below.
4511 \item[\texttt{lines}] This is similar to \texttt{classic}, but results in a
4512 smaller final value.
4513 \begin{equation} T = b \lfloor (H-b)/b \rfloor + t \end{equation}
4514 The relationship (\ref{eq:heightlines}) is maintained.
4515 \item[\texttt{nearest}] The calculated value is the nearest to the given value
4516 while still maintaining the relationship (\ref{eq:heightlines}).
4517 \begin{equation}
4518 T = b \lfloor (H - t + b/2)/b \rfloor + t
4519 \end{equation}
4520 In contrast to \texttt{classic}, \texttt{nearest}
4521 will get as close to $H$ as possible even if this means that $T$ ends
4522 up being slightly larger than $H$.
4523 \end{itemize}
4524
4525 \begin{table}
4526 \centering
4527 \caption{Results from sample \cs{textheight} adjustments} \label{tab:textht}
4528 \begin{tabular}{ccccc} \toprule
4529 & \multicolumn{4}{c}{Algorithm} \\ \cmidrule{2-5}
4530 & fixed & classic & lines & nearest \\ \cmidrule{2-5}
4531 Requested height & \multicolumn{4}{c}{adjusted height in pts, (lines) } \\
4532 \midrule
4533 10.0\cs{baselineskip} & 120.0pt, (10) & 130pt, (11) & 118pt, (10) & 118pt, (10) \\
4534 10.2\cs{baselineskip} & 122.4pt, (10) & 130pt, (11) & 118pt, (10) & 118pt, (10) \\
4535 10.4\cs{baselineskip} & 124.8pt, (10) & 130pt, (11) & 118pt, (10) & 130pt, (11) \\
4536 10.6\cs{baselineskip} & 127.2pt, (10) & 130pt, (11) & 118pt, (10) & 130pt, (11) \\
4537 10.8\cs{baselineskip} & 129.6pt, (10) & 130pt, (11) & 118pt, (10) & 130pt, (11) \\
4538 11.0\cs{baselineskip} & 132.0pt, (11) & 142pt, (12) & 130pt, (11) & 130pt, (11) \\
4539 \bottomrule
4540 \end{tabular}
4541 \end{table}
4542
4543 \tref{tab:textht} shows the results from the various \lnc{\textheight}
4544 adjustment calculations\footnote{For comparison the optimum heights from
4545 equation \ref{eq:heightlines} for 10, 11 and 12 lines are respectively
4546 118pt, 130pt and 142pt.} where the \lnc{\baselineskip} is 12pt and
4547 the \lnc{\topskip} is 10pt, which are the normal values for a Computer
4548 Modern 10pt font.
4549 In all cases the \texttt{fixed} algorithm resulted in
4550 underfull vboxes. If you know the number of lines that you want, say 42,
4551 then requesting
4552 \begin{lcode}
4553 %% setting equivalent to \setlength{\textheight}{42\baselineskip}
4554 \checkandfixthelayout[lines]
4555 \end{lcode}
4556 will result in the most appropriate \lnc{\textheight}.
4557
4558 If you use the \Lpack{calc} package you can use constructs like
4559 the following in a page layout specification:
4560 \begin{lcode}
4561 \setlength{\textheight}{41\baselineskip + \topskip}
4562 \settypeblocksize{41\baselineskip + \topskip}{33pc}{*}
4563 \end{lcode}
4564
4565 The \cmd{\fixthelayout} macro finally implements the layout,
4566 making due adjustement for any binding\index{binding allowance} allowance,
4567 and calculates the values for all the standard \ltx\ layout
4568 parameters\index{page layout!LaTeX parameters?\ltx\ parameters} (such
4569 that packages can use these expected values).
4570 If you have used the class macros to change
4571 the layout in any way, you must call \cmd{\checkandfixthelayout} after you have
4572 made all the necessary changes. As an aid, the final layout parameter values
4573 are displayed on the terminal and written out to the log file.
4574
4575 At the beginning of the document we will automatically add the
4576 page/stock sizes etc to the output such that viewers etc reacts
4577 accordingly. In incase you need to manually have the class rewrite
4578 these sizes to the document, you can use
4579
4580 \begin{syntax}
4581 \cmd{\refixpagelayout}\\
4582 \end{syntax}
4583 \glossary(refixpagelayout)%
4584 {\cs{refixpagelayout}}%
4585 {Command to reemit the document size to the output.}%
4586 Please note that this macro (and its name), may change in the
4587 future.\footnote{In a comming version, we will hopefully be able to
4588 support changing the stock and layout mid document, like what is
4589 provided by the \Lpack{geometry}. But it is currently not being
4590 prioritised.}
4591
4592
4593 \LMnote{2010/09/17}{added \cs{\settypeoutlayoutunit}}
4594 \begin{syntax}
4595 \cmd{\typeoutlayout} \\
4596 \cmd{\typeoutstandardlayout} \\
4597 \cmd{\settypeoutlayoutunit}\marg{unit} \\
4598 \end{syntax}
4599 \glossary(settypeoutlayoutunit)%
4600 {\cs{settypeoutlayoutunit}}%
4601 {Allows the user to set the unit in which to typeset the layout
4602 listing. Supported units: \texttt{pt}, \texttt{mm}, \texttt{cm},
4603 \texttt{in}, \texttt{bp}, \texttt{dd} and \texttt{cc}.}
4604 \glossary(typeoutlayout)%
4605 {\cs{typeoutlayout}}%
4606 {Outputs the current values of the class layout parameters to the
4607 terminal and log file.}
4608 \glossary(typeoutstandardlayout)%
4609 {\cs{typeoutstandardlayout}}%
4610 {Outputs the current values of the standard \ltx\ layout parameters
4611 to the terminal and log file.}
4612 \cmd{\typeoutlayout} writes the current class layout
4613 parameter\index{page layout!class parameters} values to the terminal
4614 and the log file. It is called by \cmd{\checkandfixthelayout} but you can
4615 use it yourself at any time.
4616 The macro \cmd{\typeoutstandardlayout} writes the
4617 standard layout parameter\index{page layout!LaTeX parameters?\ltx\ parameters}
4618 values to the terminal and log file so that you can
4619 compare the two sets of parameter values.
4620
4621 By using the macro \cmd{\settypeoutlayoutunit}, the user can change
4622 the unit in which the layout list is shown. Very handy when designing
4623 in, say, centimeters. Supported units are \texttt{pt}, \texttt{pc},
4624 \texttt{mm}, \texttt{cm}, \texttt{in}, \texttt{bp}, \texttt{dd} and
4625 \texttt{cc}, default being \texttt{pt}, see \tref{tab:units} for more
4626 information about the units.
4627
4628 \section{Side margins}
4629
4630 In \Lopt{twoside} printing the spine margin is normally the same on
4631 both recto and verso pages and, unless the spine and \foredge{} margins are the
4632 same, the typeblock is shifted side to side when printing the recto and
4633 verso pages. Additionally you can have different headers and footers for the
4634 recto and verso pages. However, in \Lopt{oneside} printing the typeblock
4635 is not moved and the headers and footers are the same for both odd and
4636 even pages.
4637
4638 Some documents are designed to have, say, a very wide righthand margin
4639 in which to put illustrations; this leads to needing the spine margin on
4640 verso pages to be much larger than the spine margin on recto pages. This
4641 can be done with the \Lopt{oneside} option. However, different headers
4642 and footers are required for the recto and verso pages, which can only be
4643 done with the \Lopt{twoside} option. The way to get the desired effects
4644 is like this (\Lopt{twoside} is the default class option):
4645 \begin{lcode}
4646 \documentclass{memoir}
4647 %%% set up the recto page layout
4648 \checkandfixthelayout% or perhaps \checkandfixthelayout[lines]
4649 \setlength{\evensidemargin}{\oddsidemargin}% after \checkandfix...
4650 ...
4651 \end{lcode}
4652
4653 %\section{Printing and viewing}
4654
4655 \section{Emitting the page size}
4656 \label{sec:emitting-page-size}
4657
4658 At the start of the document the class will automatically emit the
4659 chosen stocksize to the output format (DVI or PDF).\footnote{In
4660 earlier versions we had macros \cs{fixpdflayout} and
4661 \cs{fixdvipslayout} that held some of the code needed to emit this
4662 data. With the newer engines like LuaLaTeX, this became unfeasible
4663 thus they we discontinued (their use now emit a warning).}
4664
4665
4666 % When \pdfltx\ is used to generate a \pixpdf\ version of a \Pclass{memoir}
4667 % document some special setup must be done.
4668 % \begin{syntax}
4669 % \cmd{\fixpdflayout} \\
4670 % \end{syntax}
4671 % \glossary(fixpdflayout)%
4672 % {\cs{fixpdflayout}}%
4673 % {Sets up page size information for \pdfltx.}
4674 % The macro \cmd{\fixpdflayout}\index{page layout!PDF} is
4675 % \emph{automatically}\footnote{That is you do not need to.} called after the preamble when
4676 % \pdfltx{} is used to generate \pixpdf. The default definition is effectively:
4677 % \begin{lcode}
4678 % \newcommand*{\fixpdflayout}{
4679 % \pdfpageheight=\the\stockheight
4680 % \pdfpagewidth=\the\stockwidth
4681 % \ifxetex\else
4682 % \ifdim\pdforigin=0pt\pdforigin=1in\fi
4683 % \ifdim\pdfhorigin=0pt\pdfhorigin=1in\fi
4684 % \fi}
4685 % \end{lcode}
4686 % The first settings (\verb?\pdfpage...?) ensure that \pdfltx{} knows
4687 % the size of the physical sheet\indextwo{stock}{size} for printing.
4688 % The \verb?\...origin? settings
4689 % set the \pdf{} origin per the \tx\ origin, provided that their values are
4690 % 0pt. If you have set the origin values yourself, either in a \pdfltx{}
4691 % configuration\index{configuration file} file or earlier in the preamble,
4692 % the \cmd{\fixpdflayout}
4693 % macro will not alter them (if you need an origin value to be 0 then
4694 % set it to 1sp, which is visually indistinguishable from 0pt).
4695
4696 % \begin{syntax}
4697 % \cmd{\fixdvipslayout} \\
4698 % \end{syntax}
4699 % \glossary(fixdvipslayout)%
4700 % {\cs{fixdvipslayout}}%
4701 % {Sets up page size information for dvi processors.}
4702
4703 % The macro \cmd{\fixdvipslayout}\index{page layout!dvips} is automatically
4704 % called after the preamble
4705 % when \pixpdf{} output is not being produced. It provides the \Lprog{dvips}
4706 % processor
4707 % with information about the stock\indextwo{stock}{size} size,
4708 % which a viewer or printer may use.
4709
4710 % The macros \cmd{\fixpdflayout} and \cmd{\fixdvipslayout} are
4711 % automatically executed at the start of the document, in combinations
4712 % that make the most sense (i.e., \cmd{\fixpdflayout} when using XeLaTeX
4713 % or \pdfltx{} and \cmd{fixdvipslayout} for the rest.
4714
4715
4716 % \LMnote{2015/02/23}{Next lines outcommented as I do not feel that this
4717 % kind of examples belong in a manual like this}
4718
4719 % With a \Lopt{landscape} document and using the processing route
4720 % \verb?latex -> dvips? the resulting \file{ps} \pscript{} file may appear
4721 % upside-down when viewed with, say, \Lprog{ghostview}
4722 % (also known as \Lprog{gsview32}). If this happens
4723 % try putting the following in your preamble:
4724 % \begin{lcode}
4725 % \addtodef{\fixdvipslayout}{}{%
4726 % \special{!TeXDict begin /landplus90{true}store end }}
4727 % \end{lcode}
4728 % If required, additional code can be added to \cmd{\fixdvipslayout} by repeated
4729 % applications of \cmd{\addtodef}. Some other potential specials for \pscript{}
4730 % printing may be\footnote{At least for an HP 5SiMx LaserJet duplex printer.}
4731 % \begin{lcode}
4732 % % specify duplex printing
4733 % \special{!TeXDict begin <</Duplex true>> setpagedevice end}
4734 % % specify short side binding
4735 % \special{!TeXDict begin <</Tumble true>> setpagedevice end}
4736 % \end{lcode}
4737 % %<< because of emacs ...
4738
4739 \section{Example} \label{sec:pexamp}
4740
4741 Suppose you want a page that will fit on both A4\index{paper!size!A4}
4742 and US letterpaper\index{paper!size!letterpaper} stock\index{stock},
4743 wanting to do the least amount of trimming. The layout requirements
4744 are as follows.
4745 \begin{itemize}\tightlist
4746 \item The width of the typeblock\index{typeblock} should be such that
4747 there are the optimum number of characters per line.
4748 \item The ratio of the height to the width of the
4749 typeblock\index{typeblock} should equal the golden section.
4750 \item The text has to start 50pt below the top of the page. We will
4751 use the default \lnc{\headheight} and \lnc{\footskip}.
4752 \item The ratio of the outer margin\index{margin!outer} to the inner
4753 margin\index{margin!inner} should equal the golden
4754 section\index{golden section}, as should the space above and below
4755 the header\index{header}.
4756 \item There is no interest at all in
4757 marginal\index{marginalia} notes, so we can ignore any settings for
4758 these.
4759 \end{itemize}
4760 We can either do the maths ourselves or get \ltx\ to do it for us. Let's
4761 use \ltx. First we will work out the size of the largest sheet that can be
4762 cut from A4\index{paper!size!A4} and
4763 letterpaper\index{paper!size!letterpaper},
4764 whose sizes are \abybm{297}{210}{mm} and
4765 \abybm{11}{8.5}{in}; A4 is taller and narrower than letterpaper.
4766 \begin{lcode}
4767 \settrimmedsize{11in}{210mm}{*}
4768 \end{lcode}
4769 The stocksize is defined by the class option, which could be either
4770 \Lopt{letterpaper} or \Lopt{a4paper}, but we have to work out the
4771 trims to reduce the stock\index{stock} to the page. To make life easier,
4772 we will only trim
4773 the \foredge{} and the bottom of the stock\index{stock}, so the
4774 \lnc{\trimtop} is zero.
4775 The \lnc{\trimtop} and \lnc{\trimedge} are easily specified by
4776 \begin{lcode}
4777 \setlength{\trimtop}{0pt}
4778 \setlength{\trimedge}{\stockwidth}
4779 \addtolength{\trimedge}{-\paperwidth}
4780 \end{lcode}
4781 Or if you are using the \Lpack{calc} package, perhaps:
4782 \begin{lcode}
4783 \settrims{0pt}{\stockwidth - \paperwidth}
4784 \end{lcode}
4785 Specification of the size of the typeblock\index{typeblock} is also easy
4786 \begin{lcode}
4787 \settypeblocksize{*}{\lxvchars}{1.618}
4788 \end{lcode}
4789 and now the upper and lower margins\index{margin!upper}\index{margin!lower}
4790 are specified by
4791 \begin{lcode}
4792 \setulmargins{50pt}{*}{*}
4793 \end{lcode}
4794 The spine and \foredge\ margins\index{margin!spine}\index{margin!foredge?\foredge}
4795 are specified just by the value of the golden section\index{golden section},
4796 via
4797 \begin{lcode}
4798 \setlrmargins{*}{*}{1.618}
4799 \end{lcode}
4800 The only remaining calculation to be done is the \lnc{\headmargin} and
4801 \lnc{\headsep}. Again this just involves using a ratio
4802 \begin{lcode}
4803 \setheaderspaces{*}{*}{1.618}
4804 \end{lcode}
4805 To finish off we have to make sure that the layout is changed
4806 \begin{lcode}
4807 \checkandfixthelayout
4808 \end{lcode}
4809
4810
4811 \subsection{The page layout of this manual}
4812
4813 \begin{figure}
4814 \setlayoutscale{0.49}
4815 \currentstock
4816 \oddpagelayouttrue
4817 \twocolumnlayoutfalse
4818 \drawmarginparstrue
4819 \drawparametersfalse
4820 \drawstock
4821 \caption{The recto page layout for this manual}\label{fig:thispagelay}
4822 \end{figure}
4823
4824
4825
4826 The page layout for this manual is defined in the preamble\index{preamble} as:
4827 \begin{lcode}
4828 \settrimmedsize{11in}{210mm}{*}
4829 \setlength{\trimtop}{0pt}
4830 \setlength{\trimedge}{\stockwidth}
4831 \addtolength{\trimedge}{-\paperwidth}
4832 \settypeblocksize{7.75in}{33pc}{*}
4833 \setulmargins{4cm}{*}{*}
4834 \setlrmargins{1.25in}{*}{*}
4835 \setmarginnotes{17pt}{51pt}{\onelineskip}
4836 \setheadfoot{\onelineskip}{2\onelineskip}
4837 \setheaderspaces{*}{2\onelineskip}{*}
4838 \checkandfixthelayout
4839 \end{lcode}
4840
4841 An illustration of the layout is shown in \fref{fig:thispagelay} which also
4842 lists the parameter values resulting from the code above, to the nearest point.
4843
4844 I initially used the layout defined in \Sref{sec:pexamp}, which I thought
4845 looked reasonable, but then I decided to use the one above in order
4846 to save paper\index{paper} when anyone printed out the manual. The wider
4847 typeblock\index{typeblock} also makes it easier for TeX when dealing with
4848 lines that include unhyphenatable text, like the LaTeX code.
4849
4850 Andreas Mathias, via Rolf Niepraschk,\footnote{Email
4851 from \url{[email protected]} on 2002/02/05.}
4852 has suggested that the following might be better for typesetting the manual
4853 on A4 paper.
4854 \begin{lcode}
4855 \documentclass[a4paper]{memoir}
4856 ...
4857 \settrimmedsize{297mm}{210mm}{*}
4858 \setlength{\trimtop}{0pt}
4859 \setlength{\trimedge}{\stockwidth}
4860 \addtolength{\trimedge}{-\paperwidth}
4861 \settypeblocksize{634pt}{448.13pt}{*}
4862 \setulmargins{4cm}{*}{*}
4863 \setlrmargins{*}{*}{1.5}
4864 \setmarginnotes{17pt}{51pt}{\onelineskip}
4865 \setheadfoot{\onelineskip}{2\onelineskip}
4866 \setheaderspaces{*}{2\onelineskip}{*}
4867 \checkandfixthelayout
4868 \end{lcode}
4869
4870 However, the layout that I have provided will print on both letterpaper
4871 and A4 sized stock even if it might look better if it was designed for always
4872 being printed on one or the other.
4873
4874 \section{Predefined layouts}
4875 \label{sec:predefined-layouts}
4876
4877
4878 The class, like the standard classes, will automatically produce
4879 working layouts for \Lopt{letterpaper}
4880 and \Lopt{a4paper} size options. They might be a bit problematic, though,
4881 when the page is much smaller, particularly with respect to the space
4882 alloted for marginal notes. You perhaps will find the \Lpack{layouts}
4883 package~\cite{LAYOUTS} useful for checking the page layout.
4884
4885 Some non-default layouts are provided via the commands \cmd{\medievalpage},
4886 \cmd{\isopage} and \cmd{\semiisopage}; these set the size and position of the
4887 typeblock with respect to the page. After using any of these commands you
4888 \emph{must} call \cmd{\checkandfixthelayout} (and after having made any other
4889 changes to match the new layout).
4890
4891 \begin{figure}[p]
4892 \begin{leftfullpage}
4893 \centering
4894 \begin{minipage}[b]{\pwlayi}
4895 \drawaspread{\pwlayii}{1.3}{1.62}{0.18}{1.13}{1.5}{0}
4896 \end{minipage}
4897 \caption{Default layout for letterpaper}
4898 \label{fig:pagefirstlay}
4899
4900 \begin{minipage}[b]{\pwlayi}
4901 \drawaspread{\pwlayii}{1.3}{1.19}{0.11}{1.5}{2}{0}
4902 \end{minipage}
4903 \hfill
4904 \begin{minipage}[b]{\pwlayi}
4905 \drawaspread{\pwlayii}{1.3}{1.25}{0.08}{1.5}{2}{0}
4906 \end{minipage}
4907 \caption{Letterpaper layout: Left \cs{medievalpage}, Right \cs{medievalpage}\texttt{[12]}}
4908
4909 \begin{minipage}[b]{\pwlayi}
4910 \drawaspread{\pwlayii}{1.3}{1.315}{0.11}{1.29}{2}{0}
4911 \end{minipage}
4912 \hfill
4913 \begin{minipage}[b]{\pwlayi}
4914 \drawaspread{\pwlayii}{1.3}{1.3}{0.08}{1.4}{2}{0}
4915 \end{minipage}
4916 \caption{Letterpaper layout: Left \cs{isopage}, Right \cs{isopage}\texttt{[12]}}
4917
4918 \begin{minipage}[b]{\pwlayi}
4919 \drawaspread{\pwlayii}{1.3}{1.46}{0.11}{1}{2}{0}
4920 \end{minipage}
4921 \hfill
4922 \begin{minipage}[b]{\pwlayi}
4923 \drawaspread{\pwlayii}{1.3}{1.4}{0.08}{1}{2}{0}
4924 \end{minipage}
4925 \caption{Letterpaper layout: Left \cs{semiisopage}, Right \cs{semiisopage}\texttt{[12]}}
4926 \end{leftfullpage}
4927 \end{figure}
4928 \begin{figure}[p]
4929 \begin{fullpage}
4930 \centering
4931 \begin{minipage}[b]{\pwlayi}
4932 \drawaspread{\pwlayii}{1.41}{1.75}{0.17}{1.22}{1.5}{0}
4933 \end{minipage}
4934 \caption{Default layout for a4paper}
4935
4936 \begin{minipage}[b]{\pwlayi}
4937 \drawaspread{\pwlayii}{1.41}{1.38}{0.11}{1.5}{2}{0}
4938 \end{minipage}
4939 \hfill
4940 \begin{minipage}[b]{\pwlayi}
4941 \drawaspread{\pwlayii}{1.41}{1.39}{0.08}{1.5}{2}{0}
4942 \end{minipage}
4943 \caption{A4paper layout: Left \cs{medievalpage}, Right \cs{medievalpage}\texttt{[12]}}
4944
4945 \begin{minipage}[b]{\pwlayi}
4946 \drawaspread{\pwlayii}{1.41}{1.41}{0.11}{1.42}{2}{0}
4947 \end{minipage}
4948 \hfill
4949 \begin{minipage}[b]{\pwlayi}
4950 \drawaspread{\pwlayii}{1.41}{1.41}{0.08}{1.4}{2}{0}
4951 \end{minipage}
4952 \caption{A4paper layout: Left \cs{isopage}, Right \cs{isopage}\texttt{[12]}}
4953
4954 \begin{minipage}[b]{\pwlayi}
4955 \drawaspread{\pwlayii}{1.41}{1.62}{0.11}{1}{2}{0}
4956 \end{minipage}
4957 \hfill
4958 \begin{minipage}[b]{\pwlayi}
4959 \drawaspread{\pwlayii}{1.41}{1.55}{0.08}{1}{2}{0}
4960 \end{minipage}
4961 \caption{A4paper layout: Left \cs{semiisopage}, Right \cs{semiisopage}\texttt{[12]}} \label{fig:pagelastlay}
4962 \end{fullpage}
4963 \end{figure}
4964
4965
4966
4967
4968
4969 \begin{syntax}
4970 \cmd{\medievalpage}\oarg{spine} \\
4971 \end{syntax}
4972 \glossary(medievalpage)%
4973 {\cs{medievalpage}\oarg{spine}}%
4974 {Generates a page layout according to the principles of early printers.}
4975 The \cmd{\medievalpage} command generates the position and size of the
4976 typeblock according to the principles of medieval scribes and the early
4977 printers, as discovered and described by Jan Tschichold~\cite{TSCHICHOLD91}.
4978 %%%some details about this were given earlier in \Sref{sec:gutenbergpage}.
4979 The basic principle is that the
4980 spine, top, \foredge\ and bottom margins
4981 around the typeblock are in the ratio 2:3:4:6. Typically the spine margin
4982 was 1/9 the width of the page, which is what \cmd{\medievalpage} assumes
4983 by default. This can be changed with the optional \meta{spine} argument. For
4984 example, to get narrower margins with the spine being 1/12 the page width:
4985 \begin{lcode}
4986 \medievalpage[12]
4987 \end{lcode}
4988 Note that \meta{spine} must be an integer. See
4989 figures~\ref{fig:pagefirstlay}--\ref{fig:pagelastlay}.
4990
4991 \begin{syntax}
4992 \cmd{\isopage}\oarg{spine} \\
4993 \cmd{\semiisopage}\oarg{spine} \\
4994 \end{syntax}
4995 \glossary(isopage)%
4996 {\cs{isopage}\oarg{spine}}%
4997 {Generates a page layout especially suited to ISO proportioned paper.}
4998 \glossary(semiisopage)%
4999 {\cs{semiisopage}\oarg{spine}}%
5000 {Generates a page layout especially suited to ISO proportioned paper but with
5001 smaller margins than \cs{isopage}.}
5002 Robert Bringhurst~\cite{BRINGHURST99} presented a page layout that was
5003 especially suitable for ISO proportioned paper, although it can be applied to
5004 any page proportion. The \cmd{\isopage} command implements this design. The
5005 spine margin is normally 1/9 the page width and the top margin is 1/9 the
5006 page height, and the \foredge\ and bottom margins are respectively twice the
5007 spine and top margins.
5008
5009 The \cmd{\semiisopage} layout is similar where the spine margin by default
5010 is 1/9 the page width, but the top margin is the same as the spine margin.
5011 Again the \foredge\ and bottom margins are respectively twice the
5012 spine and top margins.
5013
5014 The size of the spine (and top) margins can be changed by using the optional
5015 \meta{spine} argument, which must be an integer. To set the spine margin to
5016 be, for example, 1/8 of the page width:
5017 \begin{lcode}
5018 \semiisopage[8]% or \isopage[8]
5019 \end{lcode}
5020 The same factor applies to both the spine and top margins in the case
5021 of \cmd{\isopage}.
5022
5023 Spreads showing a variety of these layouts are in \fref{fig:pagefirstlay}
5024 through \ref{fig:pagelastlay}. These were produced with the aid of the
5025 \Lpack{layouts} package.
5026
5027
5028 \section{Place trimmed page on the stock}
5029 \label{sec:place-trimmed-page}
5030
5031 As mentined earlier, when the resulting paper size is smaller than the
5032 stock that it is printed on, you'll need to specify the trimmed size
5033 (the resulting paper size) using \cmd{\settrimmedsize} and you'll want
5034 to position that in relation to the stock using \cmd{\settrims}.
5035
5036 There are nine common layouts, so we made nine easy tro use
5037 macros. The take the same arguments as \cmd{\settrimmedsize} and then
5038 automatically add an appropriate \cmd{\settrims}.
5039
5040
5041 \begin{syntax}
5042 \cmd{\setpagetl}\marg{height}\marg{width}\marg{ratio} (top-left) \\
5043 \cmd{\setpagetm}\marg{height}\marg{width}\marg{ratio} (top-middle)\\
5044 \cmd{\setpagetr}\marg{height}\marg{width}\marg{ratio} (top-right)\\
5045 \cmd{\setpagebl}\marg{height}\marg{width}\marg{ratio} (bottom-left)\\
5046 \cmd{\setpagebm}\marg{height}\marg{width}\marg{ratio} (bottom-middle)\\
5047 \cmd{\setpagebr}\marg{height}\marg{width}\marg{ratio} (bottom-right) \\
5048 \cmd{\setpageml}\marg{height}\marg{width}\marg{ratio} (middle-left) \\
5049 \cmd{\setpagecc}\marg{height}\marg{width}\marg{ratio} (center, alias \cmd{\setpagemm}) \\
5050 \cmd{\setpagemr}\marg{height}\marg{width}\marg{ratio} (middle-right)\\
5051 \end{syntax}
5052 \glossary(setpagebl)%
5053 {\cs{setpagebl}\marg{height}\marg{width}\marg{ratio}}%
5054 {Specifies a page of the given dimensions positioned at the bottom left
5055 of the stock; see \cs{settrimmedsize}.}
5056 \glossary(setpagebl)%
5057 {\cs{setpageml}\marg{height}\marg{width}\marg{ratio}}%
5058 {Specifies a page of the given dimensions positioned at the middle left
5059 of the stock; see \cs{settrimmedsize}.}
5060 \glossary(setpagebl)%
5061 {\cs{setpagetl}\marg{height}\marg{width}\marg{ratio}}%
5062 {Specifies a page of the given dimensions positioned at the top left
5063 of the stock; see \cs{settrimmedsize}.}
5064 \glossary(setpagetm)%
5065 {\cs{setpagetm}\marg{height}\marg{width}\marg{ratio}}%
5066 {Specifies a page of the given dimensions positioned at the top middle
5067 of the stock; see \cs{settrimmedsize}.}
5068 \glossary(setpagetr)%
5069 {\cs{setpagetr}\marg{height}\marg{width}\marg{ratio}}%
5070 {Specifies a page of the given dimensions positioned at the top right
5071 of the stock; see \cs{settrimmedsize}.}
5072 \glossary(setpagemr)%
5073 {\cs{setpagemr}\marg{height}\marg{width}\marg{ratio}}%
5074 {Specifies a page of the given dimensions positioned at the middle right
5075 of the stock; see \cs{settrimmedsize}.}
5076 \glossary(setpagebr)%
5077 {\cs{setpagebr}\marg{height}\marg{width}\marg{ratio}}%
5078 {Specifies a page of the given dimensions positioned at the bottom right
5079 of the stock; see \cs{settrimmedsize}.}
5080 \glossary(setpagebm)%
5081 {\cs{setpagebm}\marg{height}\marg{width}\marg{ratio}}%
5082 {Specifies a page of the given dimensions positioned at the bottom middle
5083 of the stock; see \cs{settrimmedsize}.}
5084 \glossary(setpagecc)%
5085 {\cs{setpagecc}\marg{height}\marg{width}\marg{ratio}}%
5086 {Specifies a page of the given dimensions positioned at the center
5087 of the stock; see \cs{settrimmedsize}.}
5088
5089 \noindent
5090 Note: Always remember to combine this with \cmd{\checkandfixthelayout}!
5091
5092
5093 % When your page is smaller than the stock it has to be positioned on
5094 % the stock by specifying the trims to give the desired size and location.
5095 % The macro \cmd{\setpagebl}, which takes the same arguments as
5096 % \cmd{\settrimmedsize} (see \tref{tab:rectsize} on \pref{tab:rectsize}),
5097 % calculates the trims so that the page is located at the bottom left of
5098 % the stock. Similarly \cmd{\setpageml} and \cmd{\setpagetl} will locate
5099 % the page at the middle left and the top left, respectively, of the
5100 % stock.
5101
5102 \goodbreak
5103
5104 \noindent
5105 For instance, if you are using letterpaper stock but want the final trimmed
5106 page size to be~A5, then this will put page area at the bottom left of the
5107 stock.
5108 \begin{lcode}
5109 % letterpaper stock added via class option
5110 \pagebv % sets \paperheight and \paperwidth for A5 paper
5111 \setpagebl{\paperheight}{\paperwidth}{*}
5112 ...
5113 \checkandfixthelayout
5114 \end{lcode}
5115 The above macros position the page at the left of the stock because usually
5116 trimming of the stock is limited to the top, right, and bottom, the left
5117 being the spine when the pages are finally assembled.
5118
5119
5120 % To reposition the page to
5121 % the center of the stock the following will halve the top and edge
5122 % trims.
5123 % \begin{lcode}
5124 % \settrims{0.5\trimtop}{0.5\trimedge}
5125 % ...
5126 % \checkandfixthelayout
5127 % \end{lcode}
5128
5129 % \begin{syntax}
5130 % \end{syntax}
5131
5132 % The commands \cmd{\setpagetm}, \cmd{\setpagetr}, \cmd{\setpagemr},
5133 % \cmd{\setpagebr}, \cmd{\setpagebm}, \cmd{\setpagecc} are analagous to the
5134 % earlier ones and they set a page at the top middle, top right, middle right,
5135 % bottom right, bottom middle and centered with respect to the stock.
5136
5137
5138 % Remember that after you have finished defining the layout you want you
5139 % have to call \cmd{\checkandfixthelayout} for all the changes to take
5140 % effect.
5141
5142 % \fancybreak{}
5143
5144 In \fref{fig:setpage} we show the effect of the nine
5145 \cmd{\setpageXX}. The code used for the examples is similar to the
5146 code below, and then the result was scaled down.
5147
5148 \begin{lcode}
5149 \documentclass[showtrims]{memoir}
5150 \trimLmarks
5151 \setstocksize{18cm}{15cm}
5152 \setpagebl{16cm}{12cm}{*}
5153 \setlrmarginsandblock{15mm}{15mm}{*}
5154 \setulmarginsandblock{15mm}{15mm}{*}
5155 \setheadfoot{5mm}{5mm}
5156 \checkandfixthelayout[fixed]
5157 \pagestyle{empty}
5158 \AtBeginDocument{\LARGE}
5159 \begin{document}
5160 \begin{vplace}
5161 \centering
5162 \cs{setpagebl}\marg{height}\marg{width}\marg{ratio}
5163 \end{vplace}
5164 \end{document}
5165 \end{lcode}
5166
5167
5168
5169
5170 \begin{figure}[htbp]
5171 \centering
5172 \fboxsep=0pt
5173 \fbox{\includegraphics[page=1,scale=0.3]{setpage-example.pdf}}
5174 \hfill
5175 \fbox{\includegraphics[page=2,scale=0.3]{setpage-example.pdf}}
5176 \hfill
5177 \fbox{\includegraphics[page=3,scale=0.3]{setpage-example.pdf}}
5178
5179 \medskip
5180
5181 \fbox{\includegraphics[page=4,scale=0.3]{setpage-example.pdf}}
5182 \hfill
5183 \fbox{\includegraphics[page=5,scale=0.3]{setpage-example.pdf}}
5184 \hfill
5185 \fbox{\includegraphics[page=6,scale=0.3]{setpage-example.pdf}}
5186
5187 \medskip
5188
5189
5190 \fbox{\includegraphics[page=7,scale=0.3]{setpage-example.pdf}}
5191 \hfill
5192 \fbox{\includegraphics[page=8,scale=0.3]{setpage-example.pdf}}
5193 \hfill
5194 \fbox{\includegraphics[page=9,scale=0.3]{setpage-example.pdf}}
5195
5196 \caption{Example of the nine \cs{setpageXX} macros for placing
5197 a trimmed page on the stock. These are all odd pages, under
5198 \Lopt{twoside}, even pages will have the left/right trims
5199 reversed. The outer frames indicate the stock size. Inside the trim
5200 marks hint at where the page is positioned on the stock.}
5201 \label{fig:setpage}
5202 \end{figure}
5203
5204
5205
5206
5207
5208 %#% extend
5209 %#% extstart include text-and-fonts.tex
5210
5211 \svnidlong
5212 {$Ignore: $}
5213 {$LastChangedDate: 2025-08-08 14:39:37 +0200 (Fri, 08 Aug 2025) $}
5214 {$LastChangedRevision: 859 $}
5215 {$LastChangedBy: [email protected] $}
5216
5217
5218 \chapter{Text and fonts}
5219
5220 Presumably you will be creating a document that contains at least some
5221 text. In this chapter I talk a little about the kinds of fonts that you might
5222 use and how text appears on a page.
5223
5224
5225 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
5226
5227
5228 \section{Fonts} \label{sec:fonts}
5229
5230 \alltx{} comes with a standard set of fonts, designed by Donald Knuth,
5231 and known as the Computer Modern\index{font!Computer Modern} font family.
5232 The Knuthian
5233 fonts\index{font!metafont?\metafont} were created via the \metafont{}
5234 program~\cite{METAFONT,CM}\index{metafont?\metafont}
5235 and are in the form of bitmaps\index{bitmap}
5236 (i.e., each character is represented as a bunch of tiny dots). Fonts of
5237 this kind are called \emph{bitmap fonts}\indextwo{bitmap}{font}.
5238 There is also a wide range of \metafont{} fonts available, created by
5239 many others, in addition to the standard set. More modern
5240 digital fonts, such as \pscript\indexsupsubmain{font}{PostScript} or
5241 TrueType\indexsupsubmain{font}{TrueType} fonts are represented in terms
5242 of the curves outlining the character, and it is the job of the printing
5243 machine to fill in the outlines (with a bunch of tiny dots). Fonts of
5244 this type are called \emph{outline fonts}\indextwo{outline}{font}.
5245
5246 \metafont\ fonts
5247 are designed for a particular display resolution and cannot reasonably
5248 be scaled to match an arbitrary display device, whereas outline fonts can be
5249 scaled before they are physically displayed.
5250
5251 \PWnote{2009/04/27}{Extended the font use/installation references}
5252 There is an excessive number of \pscript\indexsupsubmain{font}{PostScript}
5253 and TrueType\indexsupsubmain{font}{TrueType}
5254 fonts available
5255 and these can all, with some amount of effort, be used with \ltx. How to do
5256 that is outside the scope of this work; Alan Hoenig has written an excellent
5257 book on the subject~\cite{HOENIG98} and there is the invaluable
5258 \btitle{The \ltx\ Companion} \cite[Chapter 7 Fonts and Encodings]{COMPANION}.
5259 The original \btitle{The \ltx\ Graphics Companion} had chapters on PostScript
5260 fonts and tools but these were dropped in the second edition to keep it below
5261 an overwhelming size. This material has been updated and is available
5262 free from \url{http://xml.cern.ch/lgc2}; you can also get a
5263 `work in progress'\pagenote[`work in progress']{\pixxetx\ enables you to
5264 use Opentype fonts with \ltx, and supports both left-to-right and
5265 right-to-left typesetting. It has become very popular with those involved
5266 in linguistics and non-Latin scripts.}
5267 about \pixxetx, Unicode\index{Unicode}, and
5268 Opentype\indexsupsubmain{font}{Opentype}
5269 fonts from the same source.
5270 There is less detailed, but also free,
5271 information available via \pixctan, for example Philipp Lehman's
5272 \textit{Font Installation Guide}~\cite{FONTINST}; even if you are not
5273 interested in
5274 installing \pscript\ fonts this is well worth looking at just as an
5275 example of the kind of elegant document that can be achieved with \ltx.
5276 If you choose one of the popular
5277 \pscript\indexsupsubmain{font}{PostScript} fonts, such as those built
5278 into \ixpscript\ printers, you may
5279 well find that the work has been done for you and it's just a question
5280 of using the appropriate
5281 package.%
5282 \pagenote[using the appropriate package]{I have found Christopher
5283 League's\index{League, Christopher} \textit{\tx\ support for the FontSite
5284 500 CD}, obtainable from \url{http:contrapunctus.net/fs500tex},
5285 extremely useful in providing packages for a wide range of
5286 \pscript\indexsupsubmain{font}{PostScript} fonts for me to use. You do have
5287 to buy a CD containing the sources of the fonts from FontSite
5288 (\url{http://www.fontsite.com}); it cost me
5289 a total of \$37.12, including taxes and shipping, in 2002 for 512
5290 \pscript\ and TrueType\indexsupsubmain{font}{TrueType} professional
5291 quality fonts that are legal and very reasonably priced.
5292
5293 Many of the fonts fall into the Decorative/Display category but the book
5294 fonts include:
5295 \begin{description}
5296
5297 \item[Blackletter]\typesubidx{Blackletter}
5298 Alte Schwabacher\facesubseeidx{Alte Schwabacher},
5299 Engravers Old English\facesubseeidx{Engravers Old English},
5300 Fette Fraktur\facesubseeidx{Fette Fraktur},
5301 Fette Gotisch\facesubseeidx{Fette Gotisch}, and
5302 Olde English\facesubseeidx{Olde English}.
5303
5304 \item[Uncial/Mediaeval]\typesubidx{Uncial}\typesubidx{Mediaeval}
5305 American UncialXX{American Uncial},
5306 Linden\facesubseeidx{Linden}, and
5307 Rosslaire\facesubseeidx{Rosslaire}.
5308
5309 \item[Geralde/Venetian]\typesubidx{Geralde}\typesubidx{Venetian}
5310 Bergamo\facesubseeidx{Bergamo} (also known as Bembo\facesubseeidx{Bembo}),
5311 Caslon\facesubseeidx{Caslon},
5312 Garamond\facesubseeidx{Garamond},
5313 Goudy Old Style\facesubseeidx{Goudy Old Style},
5314 Jenson Recut\facesubseeidx{Jenson Recut} (also known as Centaur\facesubseeidx{Centaur}),
5315 URW Palladio\facesubseeidx{URW Palladio} (also known as Palatino\facesubseeidx{Palatino}),
5316 Savoy\facesubseeidx{Savoy} (also known as Sabon\facesubseeidx{Sabon}),
5317 Schnittger\facesubseeidx{Schnittger},
5318 University Old Style\facesubseeidx{University Old Style}, and
5319 Vendome\facesubseeidx{Vendome}.
5320
5321 \item[Transitional]\typesubidx{Transitional}
5322 URW Antiqua\facesubseeidx{URW Antiqua},
5323 Baskerville\facesubseeidx{Baskerville},
5324 Century Old Style\facesubseeidx{Century Old Style},
5325 ATF Clearface\facesubseeidx{ATF Clearface},
5326 English Serif\facesubseeidx{English Serif},
5327 Jessica\facesubseeidx{Jessica} (also known as Joanna\facesubseeidx{Joanna}),
5328 Lanston Bell\facesubseeidx{Lanston Bell},
5329 New Baskerville\facesubseeidx{New Baskerville}, and
5330 Nicholas Cochin\facesubseeidx{Nicholas Cochin}.
5331
5332 \item[Modern/Didone]\typesubidx{Modern}\typesubidx{Didone}
5333 Basel\facesubseeidx{Basel} (also known as Basilia\facesubseeidx{Basilia}),
5334 Bodoni\facesubseeidx{Bodoni},
5335 Modern\facesubseeidx{Modern}, and
5336 Walbaum\facesubseeidx{Walbaum}.
5337
5338 \item[Free Form]\typesubidx{Free Form}
5339 Barbedour\facesubseeidx{Barbedour},
5340 Bernhard Modern\facesubseeidx{Bernhard Modern},
5341 Della Robbia\facesubseeidx{Della Robbia},
5342 Engravers Litho\facesubseeidx{Engravers Litho},
5343 Flanders\facesubseeidx{Flanders}, and
5344 Lydian\facesubseeidx{Lydian}.
5345
5346 \item[Sans Serif]\typesubidx{Sans Serif}
5347 There are over 20 in this category but some of the ones I am most familiar
5348 with are:
5349 Chantilly\facesubseeidx{Chantilly} (also known as Gill Sans\facesubseeidx{Gill Sans}),
5350 Franklin Gothic\facesubseeidx{Franklin Gothic},
5351 Function\facesubseeidx{Function} (also known as Futura\facesubseeidx{Futura}),
5352 Lanston Koch\facesubseeidx{Lanston Koch},
5353 News Gothic\facesubseeidx{News Gothic},
5354 Opus\facesubseeidx{Opus} (also known as Optima\facesubseeidx{Optima}),
5355 Struktor\facesubseeidx{Struktor} (also known as Syntax\facesubseeidx{Syntax}), and
5356 Unitus\facesubseeidx{Unitus} (also known as Univers\facesubseeidx{Univers}).
5357
5358 \item[Slab Serif]\typesubidx{Slab Serif}
5359 Cheltenham\facesubseeidx{Cheltenham},
5360 Clarendon\facesubseeidx{Clarendon},
5361 Egyptian\facesubseeidx{Egyptian},
5362 Glytus\facesubseeidx{Glytus} (also known as Glypha\facesubseeidx{Glypha}),
5363 URW Latino\facesubseeidx{URW Latino} (also known as Melior\facesubseeidx{Melior}),
5364 Litho Antique\facesubseeidx{Litho Antique},
5365 Serific\facesubseeidx{Serific} (also known as Serifa\facesubseeidx{Serifa}).
5366
5367 \item[Script]\typesubidx{Script}
5368 There are some sixteen Script fonts.
5369
5370 \item[Decorative]\typesubidx{Decorative}
5371 There are over fifty Decorative fonts.
5372
5373 \item[Symbol]\typesubidx{Symbol}
5374 There are a dozen miscellaneous symbol fonts which include, among others,
5375 arrows, borders, fleurons\index{fleuron} and various icons.
5376 \end{description}
5377 } % end pagenote
5378
5379 A standard \ltx\ distribution includes some
5380 \pscript\indexsupsubmain{font}{PostScript} fonts and the packages to support
5381 them are in the \Ppack{psnfss}\index{psnfss?\Ppack{psnfss}}
5382 bundle. Most of the fonts are for normal text work but two supply
5383 symbols rather than characters. \tref{tab:palatinoglyphs}, although it
5384 is specifically for Palatino\facesubseeidx{Palatino}, shows the glyphs
5385 typically available. \tref{tab:symbolglyphs} and~\ref{tab:dingglyphs}
5386 show the glyphs in the two symbol fonts.
5387
5388 \begin{table}
5389 \centering
5390 \caption{Glyphs in the \ltx\ supplied Palatino roman font}\label{tab:palatinoglyphs}
5391 \nohexoct
5392 \fonttable{pplr}
5393 \end{table}
5394
5395 \begin{table}
5396 \centering
5397 \caption{Glyphs in the \ltx\ distributed Symbol font}\label{tab:symbolglyphs}
5398 \nohexoct
5399 \fonttable{psyr}
5400 \end{table}
5401
5402 \begin{table}
5403 \centering
5404 \caption{Glyphs in the \ltx\ distributed Zapf Dingbat font}\label{tab:dingglyphs}
5405 \nohexoct
5406 \fonttable{pzdr}
5407 \end{table}
5408
5409
5410 These supplied \pscript\ fonts, their respective \ltx\ fontfamily\index{fontfamily} names,
5411 and running text examples of each, are:
5412 \begin{description}
5413 \item[ITC Avant Garde Gothic\facesubseeidx{Avant Garde Gothic}] {\LXfont{pag}
5414 is a geometric sans type designed
5415 by Herb Lubalin\index{Lubalin, Herb} and Tom Carnase\index{Carnase, Tom} and
5416 based on the logo of the \textit{Avant Garde} magazine.
5417 The fontfamily name is \pfontfam{pag}.
5418
5419 \vspace{0.5\onelineskip}
5420 \fox\par\Kafka\par\namesAZ
5421 \vspace{0.5\onelineskip}
5422 }
5423
5424 \item[ITC Bookman\facesubseeidx{Bookman}] {\LXfont{pbk} was originally
5425 sold in 1860 by the Miller \& Richard\index{Miller \& Richard} foundry
5426 in Scotland; it was designed by
5427 Alexander Phemister\index{Phemister, Alexander}. The ITC revival is by
5428 Ed Benguiat\index{Benguiat, Ed}.
5429 The fontfamily name is \pfontfam{pbk}.
5430
5431
5432 \vspace{0.5\onelineskip}
5433 \fox\par\Kafka\par\namesAZ
5434 \vspace{0.5\onelineskip}
5435 }
5436
5437 \item[Bitstream Charter\facesubseeidx{Charter}] {\LXfont{bch} was designed
5438 by Matthew Carter\index{Carter, Matthew} for display on low resolution
5439 devices, and is useful for many applications, including bookwork.
5440 The fontfamily name is \pfontfam{bch}.
5441
5442 \vspace{0.5\onelineskip}
5443 \fox\par\Kafka\par\namesAZ
5444 \vspace{0.5\onelineskip}
5445 }
5446
5447 \item[Courier\facesubseeidx{Courier}] {\LXfont{pcr} is a monospaced font
5448 that was originally
5449 designed by Howard Kettler\index{Kettler, Howard} at IBM and then later
5450 redrawn by Adrian Frutiger\index{Frutiger, Adrian}.
5451 The fontfamily name is \pfontfam{pcr}.
5452
5453 \vspace{0.5\onelineskip}
5454 \fox\par\Kafka\par\namesAZ
5455 \vspace{0.5\onelineskip}
5456 }
5457
5458 \item[Helvetica\facesubseeidx{Helvetica}] {\LXfont{phv} was originally
5459 designed for the Haas
5460 foundry in Switzerland by Max Miedinger\index{Miedinger, Max}; it was later
5461 extended by the Stempel foundry and further refined by
5462 Linotype\index{Linotype}.
5463 The fontfamily name is \pfontfam{phv}.
5464
5465 \vspace{0.5\onelineskip}
5466 \fox\par\Kafka\par\namesAZ
5467 \vspace{0.5\onelineskip}
5468 }
5469
5470 \item[New Century Schoolbook\facesubseeidx{New Century Schoolbook}]
5471 {\LXfont{pnc}
5472 was designed by Morris Benton\index{Benton, Morris} for ATF (American
5473 Type Founders) in the early 20th century. As its name implies it was designed
5474 for maximum legibility in schoolbooks.
5475 The fontfamily name is \pfontfam{pnc}.
5476
5477 \vspace{0.5\onelineskip}
5478 \fox\par\Kafka\par\namesAZ
5479 \vspace{0.5\onelineskip}
5480 }
5481
5482 \item[Palatino\facesubseeidx{Palatino}]
5483 {\LXfont{ppl} was designed by Hermann
5484 Zapf\index{Zapf, Hermann} and is one of the most popular typefaces today.
5485 The fontfamily name is \pfontfam{ppl}.
5486
5487 \vspace{0.5\onelineskip}
5488 \fox\par\Kafka\par\namesAZ
5489 \vspace{0.5\onelineskip}
5490 }
5491
5492 \item[Times Roman\facesubseeidx{Times Roman}]
5493 {\LXfont{ptm} is Linotype's version
5494 of the Times New Roman\facesubseeidx{Times New Roman} face designed by
5495 Stanley Morison\index{Morison, Stanley} for the
5496 Monotype Corporation for printing \emph{The Times} newspaper.
5497 The fontfamily name is \pfontfam{ptm}.
5498
5499 \vspace{0.5\onelineskip}
5500 \fox\par\Kafka\par\namesAZ
5501 \vspace{0.5\onelineskip}
5502 }
5503
5504 \item[Utopia\facesubseeidx{Utopia}]
5505 {\LXfont{put} was designed by Robert
5506 Slimbach\index{Slimbach, Robert} and combines
5507 Transitional\indextwo{type}{Transitional} features and contemporary details.
5508 The fontfamily name is \pfontfam{put}.
5509
5510 \vspace{0.5\onelineskip}
5511 \fox\par\Kafka\par\namesAZ
5512 \vspace{0.5\onelineskip}
5513 }
5514
5515 \item[ITC Zapf Chancery\facesubseeidx{Zapf Chancery}]
5516 {\LXfont{pzc} is a
5517 Script\indextwo{type}{Script} type fashioned after the chancery
5518 handwriting styles of the Italian Renaissance. It was created by
5519 Hermann Zapf\index{Zapf, Hermann}.
5520 The fontfamily name is \pfontfam{pzc}.
5521
5522 \vspace{0.5\onelineskip}
5523 \fox\par\Kafka\par\namesAZ
5524 \vspace{0.5\onelineskip}
5525 }
5526
5527 \item[Symbol\facesubseeidx{Symbol}]
5528 {\LXfont{psy} contains various symbols and Greek letters for
5529 mathematical work; these are most easily accessible via
5530 the \Lpack{pifont} package.
5531 The fontfamily name is \pfontfam{psy}.
5532
5533 The available glyphs are shown in \tref{tab:symbolglyphs}.
5534 }
5535
5536 \item[Zapf Dingbats]\facesubseeidx{Zapf Dingbats}
5537 {\LXfont{pzd} contains a variety of dingbats which, like the Symbol
5538 characters, are most easily
5539 accessible via the \Lpack{pifont} package.
5540 The fontfamily name is \pfontfam{pzd}.
5541
5542 The available glyphs are shown in \tref{tab:dingglyphs}.
5543 }
5544
5545
5546 \end{description}
5547
5548 In \ltx\ there are three characteristics that apply to a font. These
5549 are: (a)~the shape\index{font characteristic!shape}, (b)~the
5550 series\index{font characteristic!series} (or
5551 weight), %\index{font characteristic!weight|see{series}},
5552 and (c)~the family\index{font characteristic!family}.
5553 \tref{tab:fontcat} illustrates these and lists the relevant
5554 commands\index{font commands} to access the different font categories.
5555
5556 \begin{table}
5557 \centering
5558 \caption{Font categorisation and commands} \label{tab:fontcat}
5559 \begin{tabular}{ll} \toprule
5560 \multicolumn{2}{c}{Shape}\index{font characteristic!shape} \\ \addlinespace
5561 \textup{Upright shape} & \cmd{\textup}\verb?{Upright shape}? \\
5562 \textit{Italic shape} & \cmd{\textit}\verb?{Italic shape}? \\
5563 \textsl{Slanted shape} & \cmd{\textsl}\verb?{Slanted shape}? \\
5564 \textsc{Small Caps shape} & \cmd{\textsc}\verb?{Small Caps shape}? \\ \addlinespace
5565 \multicolumn{2}{c}{Series or weight}\index{font characteristic!series} \\ \addlinespace
5566 \textmd{Medium series} & \cmd{\textmd}\verb?{Medium series}? \\
5567 \textbf{Bold series} & \cmd{\textbf}\verb?{Bold series}? \\ \addlinespace
5568 \multicolumn{2}{c}{Family}\index{font characteristic!family} \\ \addlinespace
5569 \textrm{Roman family} & \cmd{\textrm}\verb?{Roman family}? \\
5570 \textsf{Sans serif family} & \cmd{\textsf}\verb?{Sans serif family}? \\
5571 \texttt{Typewriter family} & \cmd{\texttt}\verb?{Typewriter family}? \\
5572 \bottomrule
5573 \end{tabular}
5574 \glossary(textup)%
5575 {\cs{textup}\marg{text}}%
5576 {Typeset \meta{text} with an upright font.}
5577 \glossary(textit)%
5578 {\cs{textit}\marg{text}}%
5579 {Typeset \meta{text} with an italic font.}
5580 \glossary(textsl)%
5581 {\cs{textsl}\marg{text}}%
5582 {Typeset \meta{text} with a slanted (oblique) font.}
5583 \glossary(textsc)%
5584 {\cs{textsc}\marg{text}}%
5585 {Typeset \meta{text} with a small caps font.}
5586 \glossary(textmd)%
5587 {\cs{textmd}\marg{text}}%
5588 {Typeset \meta{text} with a medium font.}
5589 \glossary(textbf)%
5590 {\cs{textbf}\marg{text}}%
5591 {Typeset \meta{text} with a bold font.}
5592 \glossary(textrm)%
5593 {\cs{textrm}\marg{text}}%
5594 {Typeset \meta{text} with a Roman font.}
5595 \glossary(textsf)%
5596 {\cs{textsf}\marg{text}}%
5597 {Typeset \meta{text} with a Sans serif font.}
5598 \glossary(texttt)%
5599 {\cs{texttt}\marg{text}}%
5600 {Typeset \meta{text} with a Typewriter (monospaced) font.}
5601 \end{table}
5602
5603 The normal body font\index{body font} --- the font used for the bulk
5604 of the text ---
5605 is an upright, medium, roman font of a size specified by the font size
5606 option for the \cmd{\documentclass}.
5607 \begin{syntax}
5608 \cmd{\normalfont} \\
5609 \end{syntax}
5610 \glossary(normalfont)%
5611 {\cs{normalfont}}%
5612 {Declaration setting the font to the normal body font (upright, Roman,
5613 and medium weight).}
5614 The declaration \cmd{\normalfont} sets the font to be the normal body font.
5615
5616 There is a set of font declarations\index{font declarations}, as shown in \tref{tab:fontdecl},
5617 that correspond to the commands listed in \tref{tab:fontcat}. The commands
5618 are most useful when changing the font for a word or two, while the
5619 declarations are more convenient when you want to typeset longer passages
5620 in a different font.
5621
5622 \begin{table}
5623 \centering
5624 \caption{Font declarations} \label{tab:fontdecl}
5625 \begin{tabular}{ll} \toprule
5626 \multicolumn{2}{c}{Shape}\index{font characteristic!shape} \\ \addlinespace
5627 \textup{Upright shape} & \verb?{?\cmd{\upshape} \verb?Upright shape}? \\
5628 \textit{Italic shape} & \verb?{?\cmd{\itshape} \verb?Italic shape}? \\
5629 \textsl{Slanted shape} & \verb?{?\cmd{\slshape} \verb?Slanted shape}? \\
5630 \textsc{Small Caps shape} & \verb?{?\cmd{\scshape} \verb?Small Caps shape}? \\ \addlinespace
5631 \multicolumn{2}{c}{Series or weight}\index{font characteristic!series} \\ \addlinespace
5632 \textmd{Medium series} & \verb?{?\cmd{\mdseries} \verb?Medium series}? \\
5633 \textbf{Bold series} & \verb?{?\cmd{\bfseries} \verb?Bold series}? \\ \addlinespace
5634 \multicolumn{2}{c}{Family}\index{font characteristic!family} \\ \addlinespace
5635 \textrm{Roman family} & \verb?{?\cmd{\rmfamily} \verb?Roman family}? \\
5636 \textsf{Sans serif family} & \verb?{?\cmd{\sffamily} \verb?Sans serif family}? \\
5637 \texttt{Typewriter family} & \verb?{?\cmd{\ttfamily} \verb?Typewriter family}? \\
5638 \bottomrule
5639 \end{tabular}
5640 \glossary(upshape)%
5641 {\cs{upshape}}%
5642 {Declaration for using an upright font.}
5643 \glossary(itshape)%
5644 {\cs{itshape}}%
5645 {Declaration for using an italic font.}
5646 \glossary(slshape)%
5647 {\cs{slshape}}%
5648 {Declaration for using a slanted font.}
5649 \glossary(scshape)%
5650 {\cs{scshape}}%
5651 {Declaration for using a small caps font.}
5652 \glossary(mdseries)%
5653 {\cs{mdseries}}%
5654 {Declaration for using a medium font.}
5655 \glossary(bfseries)%
5656 {\cs{bfseries}}%
5657 {Declaration for using a bold font.}
5658 \glossary(rmfamily)%
5659 {\cs{rmfamily}}%
5660 {Declaration for using a Roman font.}
5661 \glossary(sffamily)%
5662 {\cs{sffamily}}%
5663 {Declaration for using a Sans serif font.}
5664 \glossary(ttfamily)%
5665 {\cs{ttfamily}}%
5666 {Declaration for using a Typewriter (monospaced) font.}
5667 \end{table}
5668
5669 Do not go wild seeing how many different kinds of fonts you can cram into
5670 your work as in \eref{egbadmf}.
5671
5672 \begin{egsource}{egbadmf}
5673 Mixing \textbf{different series, \textsf{families}} and
5674 \textsl{\texttt{shapes,}} \textsc{especially in one sentence,}
5675 is usually \emph{highly inadvisable!}
5676 \end{egsource}
5677 \index{mixing fonts}
5678 \begin{egresult}[Badly mixed fonts]{egbadmf}
5679 Mixing \textbf{different series, \textsf{families}} and
5680 \textsl{\texttt{shapes,}} \textsc{especially in one sentence,}
5681 is usually \emph{highly inadvisable!}
5682 \end{egresult}
5683
5684 On the other hand there are occasions when several fonts may be used
5685 for a reasonable effect, as in \eref{eg16}.
5686 \begin{egsource}{eg16}
5687 \begin{center}
5688 \textsc{Des Dames du Temps Jadis}
5689 \end{center}%
5690 \settowidth{\versewidth}{Or yet in a year where they are}
5691 \begin{verse}[\versewidth] \begin{itshape}
5692 Prince, n'enquerez de sepmaine \\*
5693 Ou elles sont, ne de cest an, \\*
5694 Qu'a ce reffrain ne vous remaine: \\*
5695 Mais ou sont les neiges d'antan?
5696 \end{itshape}
5697
5698 Prince, do not ask in a week \\*
5699 Or yet in a year where they are, \\*
5700 I could only give you this refrain: \\*
5701 But where are the snows of yesteryear?
5702 \end{verse}
5703 \begin{flushright}
5704 {\bfseries Fran\c{c}ois Villon} [1431--1463?]
5705 \end{flushright}
5706 \end{egsource}
5707
5708 \begin{egresult}[Sometimes mixed fonts work]{eg16}
5709 \begin{center}
5710 \textsc{Des Dames du Temps Jadis}
5711 \end{center}%
5712 \settowidth{\versewidth}{Or yet in a year where they are}
5713 \begin{verse}[\versewidth] \begin{itshape}
5714 Prince, n'enquerez de sepmaine \\* \index[lines]{Prince, n'enquerez de sepmaine}
5715 Ou elles sont, ne de cest an, \\*
5716 Qu'a ce reffrain ne vous remaine: \\*
5717 Mais ou sont les neiges d'antan?
5718 \end{itshape}
5719
5720 Prince, do not ask in a week \\* \index[lines]{Prince, do not ask in a week}
5721 Or yet in a year where they are, \\*
5722 I could only give you this refrain: \\*
5723 But where are the snows of yesteryear?
5724 \end{verse}
5725 \begin{flushright}
5726 {\bfseries Fran\c{c}ois Villon} [1431--1463?]
5727 \end{flushright}
5728 \end{egresult}
5729
5730 \begin{syntax}
5731 \cmd{\emph}\marg{text} \\
5732 \end{syntax}
5733 \glossary(emph)%
5734 {\cs{emph}\marg{text}}%
5735 {Use a change in font to emphasise \meta{text}.}
5736 The \cmd{\emph}\index{emphasis} command is a font changing command that
5737 does not fit
5738 into the above scheme of things. What it does is to typeset its \meta{text}
5739 argument using a different font than the surrounding text. By default,
5740 \cmd{\emph} switches between an upright shape and an italic shape. The
5741 commands can be nested to produce effects like those in the next example.
5742
5743 \begin{egsource}{eg:emph}
5744 The \verb?\emph? command is used to produce some text that
5745 should be \emph{emphasised for some reason and can be
5746 \emph{infrequently interspersed} with some further emphasis}
5747 just like in this sentence.
5748 \end{egsource}
5749
5750 \begin{egresult}[Emphasis upon emphasis]{eg:emph}
5751 The \cmd{\emph} command is used to produce some text that
5752 should be \emph{emphasised for some reason and can be
5753 \emph{infrequently interspersed} with some further emphasis}
5754 just like in this sentence.
5755 \end{egresult}
5756
5757
5758 \begin{syntax}
5759 \cmd{\eminnershape}\marg{shape} \\
5760 \end{syntax}
5761 \glossary(eminnershape)%
5762 {\cs{eminnershape}\marg{shape}}%
5763 {Font shape for emphasized text within emphasized text.}%
5764 If the \cmd{\emph} command is used within italic text then the
5765 newly emphasized text will be typeset using the
5766 \cmd{\eminnershape} font shape. The default definition is:
5767 \begin{lcode}
5768 \newcommand*{\eminnershape}{\upshape}
5769 \end{lcode}
5770 which you can change if you wish.\footnote{The maintainer often sets
5771 it to \cs{bfseries}\cs{itshape} as just setting it as \cs{upshape}
5772 might not give enough emphasis.}
5773
5774
5775
5776 \section{Font sizes}
5777
5778 The Computer Modern \metafont{} fonts come in a fixed number of
5779 sizes\index{font size}, with
5780 each size being subtly different in shape so that they blend harmoniously.
5781 Traditionally, characters were designed for each size to be cut, and
5782 Computer Modern follows the traditional type design. For example, the smaller
5783 the size the more likely that the characters will have a relatively larger
5784 width.
5785 Outline fonts\indextwo{outline}{font} can be scaled to any size,
5786 but as the scaling is typically
5787 linear, different sizes do not visually match quite as well.
5788
5789 Computer Modern fonts come in twelve sizes which, rounded to a point,
5790 are: 5, 6, 7, 8, 9, 10, 11, 12, 14, 17, 20 and 25pt.
5791 In \ltx\ the size for a particular font is specifed by a macro name like
5792 \cs{scriptsize} and not by points; for example \cs{scriptsize}, not
5793 7pt.\footnote{It is possible to use points but that is outside the scope
5794 of this manual.}
5795 The actual size of, say, \cs{scriptsize} characters, is not fixed but depends
5796 on the type size option given for the document.
5797
5798 \begin{table}
5799 \centering
5800 \caption{Standard font size declarations} \label{tab:fontsize}
5801 \begin{tabular}{llcll} \toprule
5802 \cmd{\tiny} & {\tiny tiny} & & \cmd{\scriptsize} & {\scriptsize scriptsize} \\[5pt]
5803 \cmd{\footnotesize} & {\footnotesize footnotesize} & & \cmd{\small} & {\small small} \\[5pt]
5804 \cmd{\normalsize} & {\normalsize normalsize} & & \cmd{\large} & {\large large} \\[5pt]
5805 \cmd{\Large} & {\Large Large} & & \cmd{\LARGE} & {\LARGE LARGE} \\[5pt]
5806 \cmd{\huge} & {\huge huge} & & \cmd{\Huge} & {\Huge Huge} \\[5pt]
5807 \bottomrule
5808 \end{tabular}
5809 \end{table}
5810
5811 Standard
5812 \ltx\ provides ten
5813 declarations, illustrated in \tref{tab:fontsize}, for setting the type size,
5814 which means that two of the sizes are
5815 not easily accessible. Which two depend on the class and the
5816 selected point size option. However, for normal typesetting four different
5817 sizes should cover the majority of needs, so there is plenty of scope with
5818 a mere ten to choose from.
5819
5820 \begin{table}
5821 \centering
5822 \caption{Standard font sizes} \label{tab:standardclassfontsize}
5823 \begin{tabular}{lrrr} \toprule
5824 Class option & 10pt & 11pt & 12pt \\ \midrule
5825 \cmd{\tiny} & 5pt & 6pt & 6pt \\
5826 \cmd{\scriptsize} & 7pt & 8pt & 8pt \\
5827 \cmd{\footnotesize} & 8pt & 9pt & 10pt \\
5828 \cmd{\small} & 9pt & 10pt & 11pt \\
5829 \cmd{\normalsize} & 10pt & 11pt & 12pt \\
5830 \cmd{\large} & 12pt & 12pt & 14pt \\
5831 \cmd{\Large} & 14pt & 14pt & 17pt \\
5832 \cmd{\LARGE} & 17pt & 17pt & 20pt \\
5833 \cmd{\huge} & 20pt & 20pt & 25pt \\
5834 \cmd{\Huge} & 25pt & 25pt & 25pt \\
5835 \bottomrule
5836 \end{tabular}
5837 \end{table}
5838
5839 The \cmd{\normalsize} is the size that is set as the class
5840 option\index{class option} and is the size used for the body\index{body font}
5841 text. The \cmd{\footnotesize} is the size normally
5842 used for typesetting footnotes\index{footnote}. The standard classes
5843 use the other sizes, usually the larger ones, for typesetting certain
5844 aspects of a document, for example sectional headings.
5845
5846 With respect to the standard classes, the \Mname\ class
5847 provides a wider range of the document class type size options and
5848 adds two extra font size declarations, namely \cmd{\miniscule}
5849 and \cmd{\HUGE}, one at each end of the range.
5850
5851 The \Mname\ class font size declarations names are given in
5852 \tref{tab:fsizenames} together with the name set in the specified size
5853 relative to the manual's \cs{normalsize} font.
5854 font. The corresponding actual sizes are given in \tref{tab:fsizepoints}.
5855
5856 \begin{table}
5857 \centering
5858 \caption{The \Mname\ class font size declarations} \label{tab:fsizenames}
5859 \begin{tabular}{llll} \toprule
5860 \cmd{\miniscule} & {\miniscule miniscule} & \cmd{\tiny} & {\tiny tiny} \\
5861 \cmd{\scriptsize} & {\scriptsize scriptsize} & \cmd{\footnotesize} & {\footnotesize footnotesize} \\
5862 \cmd{\small} & {\small small} & \cmd{\normalsize} & {\normalsize normalsize} \\
5863 \cmd{\large} & {\large large} & \cmd{\Large} & {\Large\strut Large} \\
5864 \cmd{\LARGE} & {\LARGE LARGE} & \cmd{\huge} & {\huge\strut huge} \\
5865 \cmd{\Huge} & {\Huge Huge} & \cmd{\HUGE} & {\HUGE\strut HUGE} \\ \bottomrule
5866 \end{tabular}
5867 \end{table}
5868
5869 \begin{table}
5870 \begin{adjustwidth}{-1in}{-1in}
5871 \centering
5872 \caption{The \Mname\ class font sizes} \label{tab:fsizepoints}
5873 \begin{tabular}{lrrrrrrrrrrrr}\toprule
5874 Class option & \Lopt{9pt} & \Lopt{10pt} & \Lopt{11pt} & \Lopt{12pt} & \Lopt{14pt} & \Lopt{17pt} & \Lopt{20pt} & \Lopt{25pt} & \Lopt{30pt} & \Lopt{36pt} & \Lopt{48pt} & \Lopt{60pt} \\ \midrule
5875 \cmd{\miniscule} & 4pt & 5pt & 6pt & 7pt & 8pt & 9pt &
5876 10pt & 11pt & 12pt & 14pt & 17pt & 20pt \\
5877 \cmd{\tiny} & 5pt & 6pt & 7pt & 8pt & 9pt & 10pt &
5878 11pt & 12pt & 14pt & 17pt & 20pt & 25pt \\
5879 \cmd{\scriptsize} & 6pt & 7pt & 8pt & 9pt & 10pt & 11pt &
5880 12pt & 14pt & 17pt & 20pt & 25pt & 30pt \\
5881 \cmd{\footnotesize} & 7pt & 8pt & 9pt & 10pt & 11pt & 12pt &
5882 14pt & 17pt & 20pt & 25pt & 30pt & 36pt \\
5883 \cmd{\small} & 8pt & 9pt & 10pt & 11pt & 12pt & 14pt &
5884 17pt & 20pt & 25pt & 30pt & 36pt & 48pt \\
5885 \cmd{\normalsize} & 9pt & 10pt & 11pt & 12pt & 14pt & 17pt &
5886 20pt & 25pt & 30pt & 36pt & 48pt & 60pt \\
5887 \cmd{\large} & 10pt & 11pt & 12pt & 14pt & 17pt & 20pt &
5888 25pt & 30pt & 36pt & 48pt & 60pt & 72pt \\
5889 \cmd{\Large} & 11pt & 12pt & 14pt & 17pt & 20pt & 25pt &
5890 30pt & 36pt & 48pt & 60pt & 72pt & 84pt \\
5891 \cmd{\LARGE} & 12pt & 14pt & 17pt & 20pt & 25pt & 30pt &
5892 36pt & 48pt & 60pt & 72pt & 84pt & 96pt \\
5893 \cmd{\huge} & 14pt & 17pt & 20pt & 25pt & 30pt & 36pt &
5894 48pt & 60pt & 72pt & 84pt & 96pt & 108pt \\
5895 \cmd{\Huge} & 17pt & 20pt & 25pt & 30pt & 36pt & 48pt &
5896 60pt & 72pt & 84pt & 96pt & 108pt & 120pt \\
5897 \cmd{\HUGE} & 20pt & 25pt & 30pt & 36pt & 48pt & 60pt &
5898 72pt & 84pt & 96pt & 108pt & 120pt & 132pt \\ \bottomrule
5899 \end{tabular}
5900 \end{adjustwidth}
5901 \end{table}
5902
5903 Whereas the standard font sizes range from 5pt to 25pt, \Mname\
5904 provides for fonts ranging from 4pt to 132pt. That is: \par
5905 {\fontsize{4}{5}\selectfont from the 4pt size (the 9pt \cs{miniscule} size)} \par
5906 {\fontsize{9}{10}\selectfont through the 9pt normal size\raggedright\par}% \par
5907 {\fontsize{60}{72}\selectfont through the 60pt normal size\raggedright\par}% \par
5908 {\fontsize{132}{160}\selectfont \raggedright to the 132pt size (the 60pt
5909 \cs{HUGE} size).\raggedright\par}
5910
5911
5912 This extended range, though,
5913 is only accessible if you are using outline\indextwo{outline}{font} fonts
5914 and the \Lopt{extrafontsizes} class option.
5915 If you are using bitmap fonts\indextwo{bitmap}{font} then, for example,
5916 the \cmd{\HUGE} font will be automatically limited to 25pt, and the minimum
5917 size of a \cmd{\miniscule} font is 5pt.
5918
5919
5920 \section{Spaces}
5921
5922 \subsection{Paragraphs}
5923
5924 In traditional typography the first line of a paragraph, unless it comes
5925 immediately after a chapter or section heading, is indented. Also, there
5926 is no extra space between paragraphs. Font designers go to great pains
5927 to ensure that they look good when set with the normal leading. Sometimes,
5928 such as when trying to meet a University's requirements for the layout
5929 of your thesis, you may be forced to ignore the experience of centuries.
5930
5931 \index{space!inter-paragraph|(}
5932 If you like the idea of eliminating paragraph indentation and using extra
5933 inter-paragraph space to indicate where paragraphs start and end, consider how
5934 confused your reader will be if the last paragraph on the page ends with a full
5935 line; how will the reader know that a new paragraph starts at the top of
5936 the following page?
5937
5938 \begin{syntax}
5939 \cs{par} \\
5940 \lnc{\parskip} \\
5941 \cmd{\abnormalparskip}\marg{length} \\
5942 \cmd{\nonzeroparskip} \\
5943 \cmd{\traditionalparskip} \\
5944 \end{syntax}
5945 \glossary(par)%
5946 {\cs{par}}%
5947 {Ends a paragraph.}
5948 \glossary(parksip)%
5949 {\cs{parskip}}%
5950 {Space between paragraphs.}
5951 \glossary(abnormalparskip)%
5952 {\cs{abnormalparskip}\marg{length}}%
5953 {Sets the inter-paragraph spacing to \meta{length}.}
5954 \glossary(nonzeroparskip)%
5955 {\cs{nonzeroparskip}}%
5956 {Sets the inter-paragraph spacing to a `perhaps not too unreasonable' non-zero value.}
5957 \glossary(traditionalparskip)%
5958 {\cs{traditionalparskip}}%
5959 {Sets the interparagraph spacing to its traditional value.}
5960 In the input text the end of a paragraph is indicated either by leaving
5961 a blank line, or by the \cs{par} command.
5962 The length \lnc{\parskip} is the inter-paragraph spacing, and is normally 0pt.
5963 You can change this by saying, for example:
5964 \begin{lcode}
5965 \setlength{\parskip}{2\baselineskip}
5966 \end{lcode}
5967 but you are likely to find that many things have changed that you
5968 did not expect, because \ltx\ uses the \cs{par} command in many
5969 places that are not obvious.
5970
5971 If, in any event, you wish to do a disservice to your readers you can use
5972 \cmd{\abnormalparskip} to set the inter-paragraph spacing to
5973 a value of your own choosing. Using the \cmd{\nonzeroparskip} will set
5974 the spacing to what might be a reasonable non-zero value.\footnote{Except
5975 that all values except zero are unreasonable.}
5976 Both these macros try and eliminate the worst of the side effects that occur
5977 if you just simply change \lnc{\parskip} directly.
5978
5979 Following the \cmd{\traditionalparskip} declaration all will be returned
5980 to their traditional values.
5981
5982 I based the code for these functions upon the NTG classes~\cite{NTG}
5983 which indicated some of the pitfalls in increasing the spacing. The difficulty
5984 is that \cs{par}, and hence \lnc{\parskip}, occurs in many places, some
5985 unexpected and others deeply buried in the overall code.
5986
5987 \index{space!inter-paragraph|)}
5988
5989 \index{space!at start of paragraph|see{paragraph indentation}}
5990
5991 \begin{syntax}
5992 \lnc{\parindent} \\
5993 \end{syntax}
5994 \glossary(parindent)%
5995 {\cs{parindent}}
5996 {Indentation at the start of the first line of a paragraph.}
5997 \index{paragraph indentation}
5998 The length \lnc{\parindent} is the indentation at the start of a paragraph's
5999 first line. This is usually of the order of 1 to 1\slashfrac{1}{2} em.
6000 To make the first line of a paragraph flushleft set this to zero:
6001 \begin{lcode}
6002 \setlength{\parindent}{0pt}
6003 \end{lcode}
6004 Though, this is generally \emph{not} recommended, as it can make it
6005 difficult for the reader to see when new paragraph starts, thuse use
6006 with care.
6007
6008
6009 \subsection{Double spacing}
6010
6011 \index{double spacing|(}
6012
6013 Some of those that have control over the visual appearance of academic
6014 theses like them to be `double spaced'. This, of course, will make the thesis
6015 harder to read\footnote{I certainly found them so when I was having to read
6016 them before examining the candidates for their degrees. The writers of the
6017 regulations, which were invariably single spaced, seemed immune to any
6018 suggestions.} but perhaps that is the purpose, or maybe they have stock
6019 (shares) in papermills and lumber companies, as the theses were usually
6020 required to be printed single sided as well.
6021
6022 \begin{syntax}
6023 \lnc{\baselineskip} \lnc{\onelineskip} \\
6024 \end{syntax}
6025 The length \lnc{\baselineskip} is the space, or
6026 leading\index{leading}, between the baselines of adjacent text lines,
6027 and is constant
6028 throughout a paragraph. The value may change
6029 depending on the size of the current font. More precisely, the
6030 \cmd{\baselineskip} depends on the font being used at the \emph{end} of
6031 the paragraph. The class also provides the length \lnc{\onelineskip}
6032 which is the default leading for the normal body font.\footnote{That
6033 is \cmd{\onelineskip} is set in the \text{memX.clo} file
6034 corresponding to the font size class option. For \texttt{10pt}, the
6035 size is set via \texttt{mem10.clo}.} As far as the class
6036 is concerned this is a constant value; that is, unlike \lnc{\baselineskip},
6037 it never alters \lnc{\onelineskip}. You can use (fractions) of
6038 \lnc{\onelineskip} to specify vertical spaces in terms of normal text
6039 lines.
6040
6041 The following is heavily based on the \Lpack{setspace}
6042 package~\cite{SETSPACE}, but
6043 the names have been changed to avoid any clashes. Like the nonzero
6044 \lnc{\parskip}, the \lnc{\baselineskip} rears its head in many places, and
6045 it is hard for a package to get at the internals of the overlying class
6046 and kernel code. This is not to say that all is well with trying to deal
6047 with it at the class level.
6048
6049 \LMnote{2010/09/19}{Added description about the starred macros}
6050 \begin{syntax}
6051 \cmd{\OnehalfSpacing} \cmd{\OnehalfSpacing*} \\
6052 \cmd{\DoubleSpacing} \cmd{\DoubleSpacing*}\\
6053 \end{syntax}
6054 \glossary(OnehalfSpacing)%
6055 {\cs{OnehalfSpacing}}%
6056 {Declaration increasing the baseline to create the illusion of double spacing.}
6057 \glossary(OnehalfSpacing*)%
6058 {\cs{OnehalfSpacing*}}%
6059 {Same as \cs{OnehalfSpacing} but also effects page note and floats.}
6060 \glossary(DoubleSpacing)%
6061 {\cs{DoubleSpacing}}%
6062 {Declaration doubling the baselineskip.}
6063 \glossary(DoubleSpacing*)%
6064 {\cs{DoubleSpacing*}}%
6065 {Same as \cs{DoubleSpacing} but also effects page notes and floats.}
6066
6067 The declaration \cmd{\OnehalfSpacing} increases the spacing between
6068 lines so that they appear to be double spaced (especially to the
6069 thesis layout arbiters), while the declaration \cmd{\DoubleSpacing}
6070 really doubles the spacing between lines which really looks bad; but
6071 if you have to use it, it is there. The spacing in footnotes and
6072 floats (e.g., captions) is unaltered, which is usually required once
6073 the controllers see what a blanket double spacing brings. Sometimes
6074 it is also required to make page notes and floats (including
6075 captions) in `double' spacing. The starred version of the two macros
6076 above takes care of this. Alternatively the spacing in page notes
6077 (i.e. footnotes and friends) or floats an be set explicitly using
6078 \begin{syntax}
6079 \cmd{\setPagenoteSpacing}\marg{factor}\\
6080 \cmd{\setFloatSpacing}\marg{factor}
6081 \end{syntax}
6082 \glossary(setFloatSpacing)%
6083 {\cs{setFloatSpacing}}%
6084 {Explicitly set the spacing used inside floats.}
6085 \glossary(setPagenoteSpacing)%
6086 {\cs{setPagenoteSpacing}}%
6087 {Explicitly set the spacing used inside page notes such including footnotes.}
6088 \cs{setFloatSpacing} should go after say \cs{OnehalfSpacing*} if used.
6089
6090
6091
6092 \PWnote{2009/06/24}{Corrected \cs{SetSingleSpace} to \cs{setSingleSpace}}
6093 \begin{syntax}
6094 \cmd{\SingleSpacing}\\
6095 \cmd{\SingleSpacing*}\\
6096 \cmd{\setSingleSpace}\marg{factor} \\
6097 \end{syntax}
6098 \glossary(SingleSpacing)%
6099 {\cs{SingleSpacing}}%
6100 {Declaration restoring normal single spacing (or that set by
6101 \cs{setSingleSpace}). Note, this added a skip at the end.}
6102 \glossary(SingleSpacing*)%
6103 {\cs{SingleSpacing*}}%
6104 {Same as \cs{SingleSpacing}, but does not add a skip at the end.}
6105 \glossary(setSingleSpace)%
6106 {\cs{setSingleSpace}\marg{factor}}%
6107 {Change the baselineskip by \meta{factor}.}
6108 The \cmd{\setSingleSpace} command is meant to be used to
6109 adjust \emph{slightly} the normal spacing betwen lines, perhaps because
6110 the font being used looks too crampled or loose. The effect is that the
6111 normal \lnc{\baselineskip} spacing will be multiplied by \meta{factor}, which
6112 should be close to 1.0. Using \cmd{\setSingleSpace} will also reset
6113 the float and page note spacings.
6114
6115 The declaration \cmd{\SingleSpacing} returns everthing to normal, or at
6116 least the setting from \cmd{\setSingleSpace} if it has been used. It
6117 will also reset float and page note spacings to the same value.
6118
6119 \begin{note}
6120 \sloppy
6121 \cmd{\SingleSpacing} will also issue a
6122 \cmd{\vskip}\cmd{\baselineskip} at the end (which is ignored if
6123 \cmd{\SingleSpacing} is used in the preamble). This skip makes sure
6124 that comming from \cmd{\DoubleSpacing} to \cmd{\SingleSpacing} still
6125 looks ok.
6126
6127 But in certain cases, this skip is unwanted. Therefore as of 2018 we
6128 added a \cmd{\SingleSpacing*} that is equal to \cmd{\SingleSpacing}
6129 but \emph{does not} add this skip.
6130 \end{note}
6131
6132
6133 \begin{syntax}
6134 \senv{SingleSpace} ...\eenv{SingleSpace} \\
6135 \senv{Spacing}\marg{factor} ... \eenv{Spacing} \\
6136 \senv{OnehalfSpace} ... \eenv{OnehalfSpace} \\
6137 \senv{OnehalfSpace*} ... \eenv{OnehalfSpace*} \\
6138 \senv{DoubleSpace} ... \eenv{DoubleSpace} \\
6139 \senv{DoubleSpace*} ... \eenv{DoubleSpace*} \\
6140 \end{syntax}
6141 \glossary(SingleSpace)%
6142 {\senv{SingleSpace}}%
6143 {Environment form of \cs{SingleSpacing}}
6144 \glossary(Spacing)%
6145 {\senv{SingleSpace}\marg{factor}}%
6146 {Environment form of \cs{setSingleSpace}}
6147 \glossary(OnehalfSpace)%
6148 {\senv{OnehalfSpace}}%
6149 {Environment form of \cs{OnehalfSpacing}}
6150 \glossary(OnehalfSpace*)%
6151 {\senv{OnehalfSpace*}}%
6152 {Environment form of \cs{OnehalfSpacing*}}
6153 \glossary(DoubleSpace)%
6154 {\senv{DoubleSpace}}%
6155 {Environment form of \cs{DoubleSpacing}}
6156 \glossary(DoubleSpace*)%
6157 {\senv{DoubleSpace*}}%
6158 {Environment form of \cs{DoubleSpacing*}}
6159
6160 These are the environments corresponding to the declarations presented
6161 earlier, for when you want to change the spacing locally.
6162
6163 \begin{syntax}
6164 \cmd{\setDisplayskipStretch}\marg{fraction} \\
6165 \cmd{\memdskipstretch} \\
6166 \cmd{\noDisplayskipStretch} \\
6167 \cmd{\memdskips} \\
6168 \end{syntax}
6169 \glossary(setDisplayskipStretch)%
6170 {\cs{setDisplayskipStretch}\marg{factor}}%
6171 {Increase the display skips by gmeta{factor}.}%
6172 \glossary(noDisplayskipStretch)%
6173 {\cs{noDisplayskipStretch}}%
6174 {No increased display skips.}%
6175 \glossary(memdskipstretch)%
6176 {\cs{memdskipstretch}}%
6177 {The current factor for increasing display skips.}%
6178 \glossary(memdskips)%
6179 {\cs{memdskips}}%
6180 {Adjusts the display skips according to \cs{memdskipstretch}.}%
6181
6182
6183 If you have increased the interlinear space in the text you may wish, or be
6184 required, to increase it around displays (of maths).
6185 The declaration \cmd{\setDisplayskipStretch} will increase the before
6186 and after displayskips by \meta{fraction}, which must be at least 0.0.
6187 More precisely, it defines \cmd{\memdskipstretch} to be \meta{fraction}.
6188 The \cmd{\noDisplayskipStretch} declaration
6189 sets the skips back to their normal values. It is equivalent to
6190 \begin{lcode}
6191 \setDisplayskipStretch{0.0}
6192 \end{lcode}
6193 The skips are changed within the macro \cmd{\memdskips} which, in turn, is
6194 called by \cmd{\everydisplay}. If you find odd spacing around displays then
6195 redefine \cmd{\memdskips} to do nothing. Its orginal specification is:
6196 \begin{lcode}
6197 \newcommand*{\memdskips}{%
6198 \advance\abovedisplayskip \memdskipstretch\abovedisplayskip
6199 \advance\belowdisplayskip \memdskipstretch\belowdisplayskip
6200 \advance\abovedisplayshortskip \memdskipstretch\abovedisplayshortskip
6201 \advance\belowdisplayshortskip \memdskipstretch\belowdisplayshortskip}
6202 \end{lcode}
6203
6204 If you need to use a \Ie{minipage} as a stand-alone item in a widely
6205 spaced text then you
6206 may need to use the \Ie{vminipage} environment instead to get the before and
6207 after spacing correct.
6208
6209 \index{double spacing|)}
6210
6211
6212
6213 \section{Overfull lines}
6214
6215 \index{overfull lines|(}
6216 \index{space!interword|(}
6217
6218
6219 \tx\ tries very hard to keep text lines justified while keeping the
6220 interword spacing as constant as possible, but sometimes fails and complains
6221 about an overfull hbox.
6222
6223 \begin{syntax}
6224 \cmd{\fussy} \cmd{\sloppy} \\
6225 \senv{sloppypar} ... \eenv{sloppypar} \\
6226 \cmd{\midsloppy} \\
6227 \senv{midsloppypar} ... \eenv{midsloppypar} \\
6228 \end{syntax}
6229 \glossary(fussy)%
6230 {\cs{fussy}}%
6231 {Declaration for \tx\ to minimise interword space variations in justified text lines.}
6232 \glossary(sloppy)%
6233 {\cs{sloppy}}%
6234 {Declaration for \tx\ to allow large interword space variations in justified
6235 text lines.}%
6236 \glossary(sloppypar)%
6237 {\senv{sloppypar}}%
6238 {Typeset contents of the enclosed paragraph(s) using \cs{sloppy}.}%
6239 \glossary(midsloppy)%
6240 {\cs{midsloppy}}%
6241 {Declaration for \tx\ to allow moderate interword space variations in justified
6242 text lines.}%
6243 \glossary(midsloppypar)%
6244 {\senv{midsloppypar}}%
6245 {Typeset contents of the enclosed paragraph(s) using \cs{midsloppy}.}%
6246
6247 The default mode for \ltx\ typesetting is \cmd{\fussy} where
6248 the (variation of) interword spacing in justified text is kept to a
6249 minimum. Following the \cmd{\sloppy}
6250 declaration there may be a much looser setting of justified text.
6251 The \Ie{sloppypar} environment is equivalent to:
6252 \begin{lcode}
6253 {\par \sloppy ... \par}
6254 \end{lcode}
6255
6256 Additionally the class provides the \cmd{\midsloppy} declaration (and the
6257 \Ie{midsloppypar} environment) which allows a setting somewhere between
6258 \cmd{\fussy} and \cmd{\sloppy}. Using \cmd{\midsloppy} you will get fewer
6259 overfull lines compared with \cmd{\fussy} and fewer obvious large
6260 interword spaces than with \cmd{\sloppy}.
6261 I have used \cmd{\midsloppy} for this manual; it hasn't prevented
6262 overfull lines or noticeably different interword spaces, but has markedly
6263 reduced them compared with \cmd{\fussy} and \cmd{\sloppy} respectively.
6264
6265 \index{overfull lines|)}
6266 \index{space!interword|)}
6267
6268 \section{Sloppybottom}
6269
6270 \indextwo{widow}{line}\indextwo{orphan}{line}
6271 \tx\ does its best to avoid widow and orphan lines --- a widow is where
6272 the last line of a paragraph ends up at the top of a page, and an
6273 orphan\footnote{Knuth uses the term `club' instead of the normal typographers'
6274 terminology.}
6275 is when the first line of a paragraph is at the bottom of a page.
6276
6277 The following is the generally suggested method of eliminating widows
6278 and orphans, but it may well result in some odd looking pages, especially
6279 if \cmd{\raggedbottom} is not used.
6280 \begin{lcode}
6281 \clubpenalty=10000
6282 \widowpenalty=10000
6283 \raggedbottom
6284 \end{lcode}
6285
6286 \begin{syntax}
6287 \cmd{\enlargethispage}\marg{length} \\
6288 \end{syntax}
6289 \glossary(enlargethispage)%
6290 {\cs{enlargethispage}\marg{length}}%
6291 {Increase (or decrease) the text height of the current page by \meta{length}.}
6292 You can use \cmd{\enlargethispage} to add or subtract to the text height
6293 on a particular page to move a line forwards or backwards between two pages.
6294
6295
6296 Here is one person's view on the matter:
6297 \begin{quote}
6298 \ldots in experimenting with raggedbottom, widowpenalty, and clubpenalty,
6299 I think that I have not found a solution that strikes me as particularly
6300 desirable. I think what I would really like is that widows (i.e., left-over
6301 single lines that begin on the following page) are resolved not by pushing
6302 one extra line from the same paragraph also onto the next page, but by
6303 stretching the textheight to allow this one extra at the bottom of the
6304 same page. \\
6305 \hfill /iaw (from \ctt, \textit{widow handling?}, May 2006)
6306 \end{quote}
6307
6308 As so often happens, Donald Arseneau\index{Arseneau, Donald}
6309 came up with a solution.
6310
6311 \begin{syntax}
6312 \cmd{\sloppybottom} \\
6313 \end{syntax}
6314 \glossary(sloppybottom)%
6315 {\cs{sloppybottom}}%
6316 {Declaration for \tx\ to allow an extra line at the bottom of a page.
6317 The \cs{topskip} must have been increased beforehand.}%
6318 The declaration \cmd{\sloppybottom} lets \tx\ put an extra line at
6319 the bottom of a page to avoid a widow on the following page.
6320
6321 The \lnc{\topskip} must have been increased beforehand for this to
6322 work (a 60\% increase is reasonable) and this will push the text
6323 lower on the page. Run \cmd{\checkandfixthelayout} after the change (which
6324 may reduce the number of lines per page). For example, in the preamble:
6325 \begin{lcode}
6326 \setlength{\topskip}{1.6\topskip}
6327 \checkandfixthelayout
6328 \sloppybottom
6329 \end{lcode}
6330
6331 \indextwo{widow}{line}\indextwo{orphan}{line}
6332 The late Michael Downes\index{Downes, Michael} provided the following
6333 (from \ctt\ \textit{widow/orphan control package (for 2e)?}, 1998/08/31):
6334 \begin{quote}
6335 For what it's worth here are the penalty values that I use when I don't
6336 [want] to \emph{absolutely} prohibit widow/orphan break, but come
6337 about as close as \tx\ permits otherwise. This is copied straight out
6338 of some code that I had lying around. I guess I could wrap it into
6339 package form and post it to CTAN. \\
6340 \hfill Michael Downes
6341 \end{quote}
6342
6343 \begin{lcode}
6344 % set \clubpenalty, etc. to distinctive values for use
6345 % in tracing page breaks. These values are chosen so that
6346 % no single penalty will absolutely prohibit a page break, but
6347 % certain combinations of two or more will.
6348 \clubpenalt=9996
6349 \widowpenalty=9999
6350 \brokenpenalty=4991
6351 % Reiterate the default value of \redisplaypenalty, for
6352 % completeness.
6353 % Set postdisplaypenalty to a fairly high value to discourage a
6354 % page break between a display and a widow line at the end of a
6355 % paragraph.
6356 \predisplaypenalty=10000
6357 \postdisplaypenalty=1549
6358 % And then \displaywidowpenalty should be at least as high as
6359 % \postdisplaypenalty, otherwise in a situation where two displays
6360 % are separated by two lines, TeX will prefer to break between the
6361 % two lines, rather than before the first line.
6362 \displaywidowpenalty=1602
6363 \end{lcode}
6364
6365 \indextwo{widow}{line}\indextwo{orphan}{line}
6366 As you can see, perfect automatic widow/orphan control is problematic
6367 though typographers are typically more concerned about widows than orphans ---
6368 a single line of a paragraph somehow looks worse at the top of a page than
6369 at the bottom. If all else fails, the solution is either to live with the
6370 odd line or to reword the text.
6371
6372 \section{Text case}
6373 \label{sec:text-case}
6374
6375 The standard kernel \cmd{\MakeUppercase}\marg{text} and
6376 \cmd{\MakeLowercase}\marg{text} basically upper or lower case
6377 everything it can get its hands on. In later years these macros have
6378 been extended greatly, and can now ignore math, \cs{label}, \cs{ref},
6379 \cs{cite}, \cs{begin} and \cs{end}. Earlier one would need a package
6380 like \Lpack{textcase} for this.
6381
6382 \begin{Changed}[August 2025]
6383 Earlier the class autoloaded \Lpack{textcase} and used
6384 \cs{MakeTextUppercase} and \cs{MakeTextLowercase}. From Summer 2025
6385 we provide the macros as aliases for the kernel macros (unless the
6386 user ahs manually loaded \Lpack{textcase}.
6387 \end{Changed}
6388
6389 \begin{syntax}
6390 \cmd{\MakeUppercase}\marg{text}\\
6391 \cmd{\MakeLowercase}\marg{text}
6392 \end{syntax}
6393 \glossary(MakeUppercase)
6394 {\cs{MakeUppercase}\marg{text}}
6395 {Upper case \meta{text} by leave math, references, citations and
6396 \cs{NoCaseChange}\marg{text} alone.}
6397 \glossary(MakeLowercase)
6398 {\cs{MakeTextLowercase}\marg{text}}
6399 {Lower case \meta{text} by leave math, references, citations and
6400 \cs{NoCaseChange}\marg{text} alone.}
6401 Thus
6402 \begin{verbatim}
6403 \MakeUppercase{abc\ae\ \( a = b \) and $\alpha \neq a$
6404 or even \ensuremath{x=y} and $\ensuremath{x=y}$}
6405 \end{verbatim}
6406 Should produce (the upper is \cs{MakeUppercase} the latter line is manually typed):
6407 \begin{quotation}
6408 \MakeUppercase{abc\ae\ \( a = b \) and $\alpha \neq a$
6409 or even \ensuremath{x=y} and $\ensuremath{x=y}$}
6410
6411 ABC\AE\ \( a = b \) AND $\alpha \neq a$
6412 OR EVEN \ensuremath{x=y} AND $\ensuremath{x=y}$
6413 \end{quotation}
6414
6415 In case you have some text should should \emph{not} be altered, use
6416 \begin{syntax}
6417 \cmd{\NoCaseChange}\marg{text}
6418 \end{syntax}
6419 \glossary(NoCaseChange)
6420 {\cs{NoCaseChange}\marg{text}}
6421 {The argument of this macro is not touched by \cs{MakeTextUppercase}
6422 or \cs{MakeTextLowercase}.}
6423 Example
6424 \begin{verbatim}
6425 \MakeTextUppercase{%
6426 The new \NoCaseChange{iPhone} yet more text}
6427 \end{verbatim}
6428 which produces
6429 \begin{quotation}
6430 \MakeTextUppercase{%
6431 The new \NoCaseChange{iPhone} yet more text}
6432 \end{quotation}
6433
6434 The kernel maintains a list of macros the casing should ignore, one
6435 can add to it via
6436 \cs{AddToNoCaseChangeList}\verb?{\macro}?. Additionally the kernel now
6437 also provide
6438 \begin{syntax}
6439 \cmd{\MakeTitlecase}\marg{text}
6440 \end{syntax}
6441 \glossary(MakeTitlecase)
6442 {\cs{MakeTitlecase}\marg{text}}
6443 {Kernel amcro to title case a text.}
6444 See \cite[\sectionrefname 7]{USRGUIDE} for more.
6445
6446
6447
6448
6449
6450 % \subsection{Nested text}
6451 % The commands defined here only skip math sections and \cmd{\ref} arguments
6452 % if they are not `hidden' inside a \verb|{ }| brace group. All text inside
6453 % such a group will be made uppercase just as with the standard
6454 % \cmd{\MakeUppercase}.
6455 % \begin{verbatim}
6456 % \MakeTextUppercase{a b {c $d$} $e$}
6457 % \end{verbatim}
6458 % produces
6459 % \begin{quotation}
6460 % \MakeTextUppercase{a b {c $d$} $e$}
6461 % \end{quotation}
6462 % Of course, this restriction does not apply to the arguments of the
6463 % supported commands \verb|\ensuremath|, \verb|\label|, \verb|\ref|, and
6464 % \verb|\cite|.
6465
6466 % If you cannot arrange for your mathematics to be at the outer level of
6467 % brace grouping, you should use the following basic technique (which
6468 % works even with the standard \cmd{\MakeUppercase} command). Define a
6469 % new command that expands to your math expression, and then use that
6470 % command, with \cmd{\protect}, in the text to be uppercased. Note that
6471 % if the text being uppercased is in a section title or other moving
6472 % argument you may need to make the definition in the document preamble,
6473 % rather than just before the section command, so that the command is
6474 % defined when the table of contents file is read.
6475 % \begin{verbatim}
6476 % \MakeTextUppercase{%
6477 % Text \fbox{$a=b$ and $x=y$}}%
6478
6479 % \newcommand{\mathexprone}{$a=b$}
6480 % \newcommand{\mathexprtwo}{$x=y$}
6481 % \MakeTextUppercase{%
6482 % Text \fbox{\protect\mathexprone\ and \protect\mathexprtwo}}%
6483 % \end{verbatim}
6484 % which produces
6485 % \begin{quotation}
6486 % \MakeTextUppercase{%
6487 % Text \fbox{$a=b$ and $x=y$}}%
6488
6489 % \newcommand{\mathexprone}{$a=b$}
6490 % \newcommand{\mathexprtwo}{$x=y$}
6491 % \MakeTextUppercase{%
6492 % Text \fbox{\protect\mathexprone\ and \protect\mathexprtwo}}%
6493 % \end{quotation}
6494
6495
6496 % \fancybreak{}
6497
6498 % See also \cite{textcase} for some information about upper casing
6499 % citations using a non-nummeric style.
6500
6501
6502 % \subsubsection{Citations}
6503 % As documented above, \cmd{\cite} and \cmd{\ref} commands are not
6504 % uppercased by \cmd{\MakeTextUppercase}. If you are using a non-numeric
6505 % citation scheme you may want the replacement text for \cmd{\cite} to
6506 % be uppercased.
6507
6508 % It is difficult to arrange that \cmd{\MakeTextUppercase} uppercases
6509 % such text, not least because this would lead to interaction with the
6510 % many bibliography packages which redefine \cmd{\cite} one way or
6511 % another. One possibility to achieve this is to use Donald Arseneau's
6512 % cite package and to locally redefine \cmd{\citeform} to add
6513 % \cmd{\MakeUppercase} around the final text string produced by \cmd{\cite}.
6514 % \begin{verbatim}
6515 % \MakeTextUppercase{%
6516 % Text \cite{bbb} and \cite{ccc}}
6517
6518 % {\renewcommand\citeform{\MakeUppercase}\MakeTextUppercase{%
6519 % Text \cite{bbb} and \cite{ccc}}}
6520 % \end{verbatim}
6521 % which produces\footnote{This is faked, so this document does not
6522 % rely on \texttt{cite.sty} being installed}
6523 % \begin{quotation}
6524 % TEXT [1] AND [David Carlisle 1997]
6525
6526 % TEXT [1] AND [DAVID CARLISLE 1997]
6527 % \end{quotation}
6528
6529
6530
6531
6532 %#% extend
6533 %#% extstart include titles.tex
6534
6535 \svnidlong
6536 {$Ignore: $}
6537 {$LastChangedDate: 2025-09-19 16:06:27 +0200 (Fri, 19 Sep 2025) $}
6538 {$LastChangedRevision: 873 $}
6539 {$LastChangedBy: [email protected] $}
6540
6541
6542 \chapter{Titles}
6543
6544 The standard classes provide little in the way of help in setting
6545 the title page(s) for your work, as the \cmd{\maketitle} command
6546 is principally aimed at generating a title for an article in a technical
6547 journal; it provides little for titles for works like theses, reports or
6548 books. For these I recommend that you design your own title page
6549 layout\footnote{If you are producing a thesis you are probably told
6550 just how it must look.}
6551 using the regular \ltx\ commands to lay it out, and ignore \cmd{\maketitle}.
6552
6553 Quoting from Ruari McLean~\cite[p. 148]{MCLEAN80} in reference to the
6554 title page he says:
6555 \begin{quotation}
6556 The title-page states, in words, the actual title (and sub-title, if
6557 there is one) of the book and the name of the author and publisher, and
6558 sometimes also the number of illustrations, but it should do more than that.
6559 From the designer's point of view, it is the most important page in the
6560 book: it sets the style. It is the page which opens communication with the
6561 reader\ldots
6562
6563 If illustrations play a large part in the book, the title-page opening
6564 should, or may, express this visually. If any form of decoration is used
6565 inside the book, e.g., for chapter openings, one would expect this to be
6566 repeated or echoed on the title-page.
6567
6568 Whatever the style of the book, the title-page should give a foretaste
6569 of it. If the book consists of plain text, the title-page should at least
6570 be in harmony with it. The title itself should not exceed the width of the
6571 type area, and will normally be narrower\ldots
6572 \end{quotation}
6573
6574 A pastiche of McLean's title page is shown in \fref{figure:titleTH}.
6575
6576 \begin{figure}
6577 \centering
6578 \begin{showtitle}
6579 \titleTH
6580 \end{showtitle}
6581 \caption{Layout of a title page for a book on typography}\label{figure:titleTH}
6582 \end{figure}
6583
6584
6585 % \begin{comment}
6586 % Figures~\ref{fig:titleTH} and~\ref{fig:titleDB}, for example,
6587 % show title pages created using normal \ltx, without bothering
6588 % with \cmd{\maketitle}.
6589 % \end{comment}
6590
6591 The typeset format of the \cmd{\maketitle} command is virtually fixed
6592 within the \ltx\ standard classes. This class
6593 provides a set of formatting commands that can be used to modify
6594 the appearance of the title\index{title} information; that is, the contents of
6595 the \cmd{\title}, \cmd{\author} and \cmd{\date} commands.
6596 It also keeps the values
6597 of these commands so that they may be printed again later in the
6598 document.
6599 The class also inhibits the normal automatic cancellation of titling
6600 commands after \cmd{\maketitle}. This means that you can have multiple
6601 instances of the same, or perhaps different, titles in one document;
6602 for example on a half title page\index{half-title page} and the
6603 full title page\index{title page}.
6604 Hooks are provided so that additional titling elements can be defined
6605 and printed by \cmd{\maketitle}.
6606 The \cmd{\thanks} command is enhanced to provide various configurations
6607 for both the marker symbol and the layout of the thanks\index{thanks} notes.
6608
6609 \begin{figure}
6610 \centering
6611 \begin{showtitle}
6612 \titleDS
6613 \end{showtitle}
6614 \caption{Example of a mandated title page style for a doctoral thesis}\label{figure:titleDS}
6615 \end{figure}
6616
6617 \begin{figure}%\setlength{\unitlength}{1pt}
6618 \centering
6619 %\begin{showtitle}
6620 {\titleRB}
6621 %\end{showtitle}
6622 \caption{Example of a Victorian title page}\label{figure:titleRB}
6623 \end{figure}
6624
6625 \begin{figure}
6626 \centering
6627 \begin{showtitle}
6628 \titleDB
6629 \end{showtitle}
6630 \caption{Layout of a title page for a book on book design}\label{figure:titleDB}
6631 \end{figure}
6632
6633 \begin{figure}
6634 \centering
6635 \begin{showtitle}
6636 \titleGM
6637 \end{showtitle}
6638 \caption{Layout of a title page for a book about books}\label{figure:titleGM}
6639 \end{figure}
6640
6641 Generally speaking, if you want anything other than minor variations
6642 on the \cmd{\maketitle} layout then it is better to ignore \cmd{\maketitle}
6643 and take the whole layout into your own hands so you can place everthing
6644 just where you want it on the page.
6645
6646 \section{Styling the titling}
6647
6648
6649 \index{title!styling|(}
6650
6651 The facilities provided for typesetting titles are limited, essentially
6652 catering for the kind of titles of articles published in technical journals.
6653 They can also be used as a quick and dirty method for typesetting titles
6654 on reports, but for serious work, such as a title page for a book or thesis,
6655 each title page\index{title page} should be handcrafted.
6656 For instance, a student of mine, Donald Sanderson\index{Sanderson, Donald}
6657 used \ltx\ to typeset his doctoral thesis, and \fref{figure:titleDS} shows
6658 the title page style mandated by Rensselear Polytechnic Institute as of 1994.
6659 Many other examples of title pages, together with the code to create them,
6660 are in~\cite{TITLEPAGES}.
6661
6662 Another handcrafted title page\index{title page} from~\cite{TITLEPAGES} is
6663 shown in \fref{figure:titleRB}. This one is based on an old booklet I found
6664 that was
6665 published towards the end of the 19th century and exhibits the love of
6666 Victorian printers in displaying a variety of types; the rules are
6667 an integral part of the title page. For the purposes of this manual I
6668 have used New Century\index{New Century Schoolbook} Schoolbook, which
6669 is part of the regular
6670 \ltx\ distribution, rather than my original choice of
6671 Century Old Style\index{Century Old Style}
6672 which is one of the commercial FontSite\index{FontSite} fonts licensed from
6673 the
6674 SoftMaker/ATF library, supported for \ltx\ through
6675 Christopher\index{League, Christopher}
6676 League's estimable work~\cite{TEXFONTSITE}.
6677
6678 The title page in \fref{figure:titleDB} follows the style of
6679 of \textit{The Design of Books}~\cite{ADRIANWILSON93}
6680 and a page similar to Nicholas Basbanes \textit{A Gentle Madness: Bibliophiles,
6681 Bibliomanes, and the Eternal Passion for Books} is illustrated in
6682 \fref{figure:titleGM}. These are all from~\cite{TITLEPAGES} and handcrafted.
6683
6684 In contrast the following code produces the standard \cmd{\maketitle} layout.
6685
6686 \begin{egsource}{eg:maketitle}
6687 \title{MEANDERINGS}
6688 \author{T. H. E. River \and
6689 A. Wanderer\thanks{Supported by a grant from the
6690 R. Ambler's Fund}\\
6691 Dun Roamin Institute, NY}
6692 \date{1 April 1993\thanks{First drafted on 29 February 1992}}
6693 ...
6694 \maketitle
6695 \end{egsource}
6696
6697 \begin{egresult}[Example \cs{maketitle} title]{eg:maketitle}
6698 %\begin{figure}
6699 %\centering
6700 %\caption{Example \cs{maketitle} title} \label{fig:maketitle}
6701 %\rule{\textwidth}{0.4pt}
6702 %
6703 %\vspace*{2ex}
6704 \begin{center}
6705 \vspace{0.5\onelineskip}
6706 \begin{minipage}{0.75\textwidth}
6707 \begin{center}
6708 {\Large MEANDERINGS} \\
6709 \vspace*{2ex}
6710 T. H. E. River and A. Wanderer\textsuperscript{*} \\
6711 Dun Roamin Institute, NY \\
6712 \vspace*{2ex}
6713 1 April 1993\textsuperscript{\dag}
6714 \begin{displaymath}
6715 \vdots
6716 \end{displaymath}
6717 \end{center}
6718 \begin{footnotesize}
6719 \rule{0.3\textwidth}{0.4pt} \\
6720 \noindent
6721 \textsuperscript{*} Supported by a grant from the R. Ambler's Fund \\
6722 \textsuperscript{\dag} First drafted on 29 February 1992
6723 \end{footnotesize}
6724 \end{minipage}
6725 \vspace{0.75\onelineskip}
6726 \end{center}
6727
6728 %\rule{\textwidth}{0.4pt}
6729 %\end{figure}
6730 \end{egresult}
6731
6732 This part of the class is a reimplementation of the \Lpack{titling}
6733 package~\cite{TITLING}.
6734
6735 The class provides a configurable \cmd{\maketitle} command.
6736 The \cmd{\maketitle} command as defined by the class
6737 is essentially
6738 \begin{lcode}
6739 \newcommand{\maketitle}{%
6740 \vspace*{\droptitle}
6741 \maketitlehooka
6742 {\pretitle \title \posttitle}
6743 \maketitlehookb
6744 {\preauthor \author \postauthor}
6745 \maketitlehookc
6746 {\predate \date \postdate}
6747 \maketitlehookd
6748 \thispagestyle{title}
6749 }
6750 \end{lcode}
6751 where the \pstyle{title} pagestyle is initially the same as the
6752 \pstyle{plain} pagestyle.
6753 The various macros used within \cmd{\maketitle} are described below.
6754
6755
6756 \begin{syntax}
6757 \cmd{\pretitle}\marg{text} \cmd{\posttitle}\marg{text} \\
6758 \cmd{\preauthor}\marg{text} \cmd{\postauthor}\marg{text} \\
6759 \cmd{\predate}\marg{text} \cmd{\postdate}\marg{text} \\
6760 \end{syntax}
6761 \glossary(pretitle)%
6762 {\cs{pretitle}\marg{text}}%
6763 {Command processed before the \cs{title} in \cs{maketitle}.}
6764 \glossary(posttitle)%
6765 {\cs{postitle}\marg{text}}%
6766 {Command processed after the \cs{title} in \cs{maketitle}.}
6767 \glossary(preauthor)%
6768 {\cs{preauthor}\marg{text}}%
6769 {Command processed before the \cs{author} in \cs{maketitle}.}
6770 \glossary(postauthor)%
6771 {\cs{postauthor}\marg{text}}%
6772 {Command processed after the \cs{author} in \cs{maketitle}.}
6773 \glossary(predate)%
6774 {\cs{predate}\marg{text}}%
6775 {Command processed before the \cs{date} in \cs{maketitle}.}
6776 \glossary(postate)%
6777 {\cs{postdate}\marg{text}}%
6778 {Command processed after the \cs{date} in \cs{maketitle}.}
6779 These six commands each have a single argument, \meta{text},
6780 which controls the typesetting of the
6781 standard elements of the document's \cmd{\maketitle}
6782 command. The \cmd{\title} is effectively processed between the
6783 \cmd{\pretitle} and \cmd{\posttitle} commands; that is, like:
6784 \begin{lcode}
6785 {\pretitle \title \posttitle}
6786 \end{lcode}
6787 and similarly for the \cmd{\author} and \cmd{\date} commands. The
6788 commands are initialised to mimic the normal result of \cmd{\maketitle}
6789 typesetting in the \Lclass{report} class.
6790 That is, the default definitions of the commands are:
6791 \begin{lcode}
6792 \pretitle{\begin{center}\LARGE}
6793 \posttitle{\par\end{center}\vskip 0.5em}
6794 \preauthor{\begin{center}
6795 \large \lineskip 0.5em%
6796 \begin{tabular}[t]{c}}
6797 \postauthor{\end{tabular}\par\end{center}}
6798 \predate{\begin{center}\large}
6799 \postdate{\par\end{center}}
6800 \end{lcode}
6801
6802 They can be changed to obtain different effects. For example to get
6803 a right justified sans-serif title and a left justifed small caps
6804 date:
6805 \begin{lcode}
6806 \pretitle{\begin{flushright}\LARGE\sffamily}
6807 \posttitle{\par\end{flushright}\vskip 0.5em}
6808 \predate{\begin{flushleft}\large\scshape}
6809 \postdate{\par\end{flushleft}}
6810 \end{lcode}
6811
6812 \begin{syntax}
6813 \lnc{\droptitle} \\
6814 \end{syntax}
6815 \glossary(droptitle)%
6816 {\cs{droptitle}}%
6817 {Length controlling the position of \cs{maketitle} on the page (default 0pt).}
6818 The \cmd{\maketitle} command puts the title at a particular height on the
6819 page.
6820 You can change the vertical position of the title via the length
6821 \lnc{\droptitle}. Giving this a positive value will lower the title and a
6822 negative value will raise it. The default definition is:
6823 \begin{lcode}
6824 \setlength{\droptitle}{0pt}
6825 \end{lcode}
6826
6827 \begin{syntax}
6828 \cmd{\maketitlehooka} \cmd{\maketitlehookb} \\
6829 \cmd{\maketitlehookc} \cmd{\maketitlehookd} \\
6830 \end{syntax}
6831 \glossary(maketitlehooka)%
6832 {\cs{maketitlehooka}}%
6833 {Hook into \cs{maketitle} applied before the \cs{title}.}
6834 \glossary(maketitlehookb)%
6835 {\cs{maketitlehookb}}%
6836 {Hook into \cs{maketitle} applied between the \cs{title} and \cs{author}.}
6837 \glossary(maketitlehookc)%
6838 {\cs{maketitlehookc}}%
6839 {Hook into \cs{maketitle} applied between the \cs{author} and \cs{date}.}
6840 \glossary(maketitlehookd)%
6841 {\cs{maketitlehookd}}%
6842 {Hook into \cs{maketitle} applied after the \cs{date}.}
6843 These four hook commands are provided so that additional elements may
6844 be added to \cmd{\maketitle}. These are initially defined to do nothing
6845 but can be renewed. For example, some publications
6846 want a statement about where an article is published immediately
6847 before the actual titling text. The following defines a command
6848 \cmd{\published} that can be used to hold the publishing information
6849 which will then be automatically printed by \cmd{\maketitle}.
6850 \begin{lcode}
6851 \newcommand{\published}[1]{%
6852 \gdef\puB{#1}}
6853 \newcommand{\puB}{}
6854 \renewcommand{\maketitlehooka}{%
6855 \par\noindent \puB}
6856 \end{lcode}
6857 You can then say:
6858 \begin{lcode}
6859 \published{Originally published in
6860 \textit{The Journal of ...}\thanks{Reprinted with permission}}
6861 ...
6862 \maketitle
6863 \end{lcode}
6864 to print both the published and the normal titling information. Note
6865 that nothing extra had to be done in order to use the \cmd{\thanks} command
6866 in the argument to the new \cmd{\published} command.
6867
6868 \index{title page|(}
6869
6870 \begin{syntax}
6871 \senv{titlingpage} text \eenv{titlingpage} \\
6872 \senv{titlingpage*} text \eenv{titlingpage*}\\
6873 \cmd{\titlingpageend}\marg{twoside code}\marg{oneside code}\\
6874 \cmd{\settitlingpagenumbering}\marg{macro to be given a counter name}
6875 \end{syntax}
6876 \glossary(titlingpage)%
6877 {\senv{titlingpage}}%
6878 {Environment for a title page, resets the page counter to 1 after it}
6879 \glossary(titlingpage*)%
6880 {\senv{titlingpage*}}%
6881 {Like \senv{titlingpage}, but does not reset the page counter.}%
6882 \glossary(titlingpageend)%
6883 {\cs{titlingpageend}}%
6884 {Can be used to set what kind of page clearing is issued at the end
6885 of a titling page. The default for the two args are
6886 \cs{cleardoublepage} and \cs{clearpage}.}
6887 When one of the standard classes is used with the \Lopt{titlepage}
6888 option, \cmd{\maketitle} puts the title elements on an unnumbered page
6889 and then starts a new page numbered page 1.
6890 The standard classes also provide
6891 a \Ie{titlepage} environment which starts a new unnumbered page and at the
6892 end starts a new page numbered 1. You are entirely responsible
6893 for specifying exactly what and where is to go on this title page.
6894 If \cmd{\maketitle} is used within the \Ie{titlepage} environment it
6895 will start yet another page.
6896
6897 This class provides neither a \Lopt{titlepage} option nor
6898 a \Ie{titlepage} environment; instead it provides the \Ie{titlingpage}
6899 environment which falls between the \Lopt{titlepage}
6900 option and the \Ie{titlepage} environment. Within the \Ie{titlingpage}
6901 environment you can use the \cmd{\maketitle} command, and any others
6902 you wish. The \pstyle{titlingpage} pagestyle is used, and
6903 at the end it starts another ordinary page numbered one
6904 (\senv{titlingpage*} does note reset the page number).
6905 The \pstyle{titlingpage} pagestyle is initially defined to be the same
6906 as the \pstyle{empty} pagestyle.
6907
6908 At the end of a \Ie{titlingpage} clearing code is issued, which can
6909 send you to the next page or the next right handed page. Using
6910 \cmd{\titlingpageend}\marg{twoside code}\marg{oneside code}, you can
6911 specify what this clearing code should be. The default is
6912 \cs{cleardoublepage} and \cs{clearpage} respectively.\footnote{Thus
6913 this refactorization will not change existing documents, LM, 2018/03/06.} However a
6914 better choice might be to just let it follow \cs{clearforchapter}:
6915 \begin{lcode}
6916 \titlingpageend{\clearforchapter}{\clearforchapter}
6917 \end{lcode}
6918 -- using this value, \Ie{titlingpage} will work as expected with \Lopt{openany}.
6919
6920
6921 For example, to put both the title and an abstract\index{abstract}
6922 on a title page,
6923 with a \pstyle{plain} pagestyle:
6924 \begin{lcode}
6925 \begin{document}
6926 \begin{titlingpage}
6927 \aliaspagestyle{titlingpage}{plain}
6928 \setlength{\droptitle}{30pt} lower the title
6929 \maketitle
6930 \begin{abstract}...\end{abstract}
6931 \end{titlingpage}
6932 \end{lcode}
6933
6934 However, it is not required to use \senv{titlingpage} to create a
6935 title page, you can use regular \ltx\ typesetting without any special
6936 environment. That is like:
6937 \begin{lcode}
6938 \pagestyle{empty}
6939 %%% Title, author, publisher, etc., here
6940 \cleardoublepage
6941 ...
6942 \end{lcode}
6943
6944 By default, titling information is centered with respect to the width
6945 of the typeblock\index{typeblock}. Occasionally someone asks to
6946 center the titling information on a title page with respect to the
6947 width of the physical page. If the typeblock\index{typeblock} is
6948 centered with respect to the physical page, then the default centering
6949 suffices. If the typeblock\index{typeblock} is not physically
6950 centered, then the titling information either has to be shifted
6951 horizontally or \cmd{\maketitle} has to be made to think that the
6952 typeblock\index{typeblock} has been shifted horizontally. The simplest
6953 solution is to use the \cmd{\calccentering} and \Ie{adjustwidth*}
6954 command and environment. For example:
6955 \begin{lcode}
6956 \begin{titlingpage}
6957 \calccentering{\unitlength}
6958 \begin{adjustwidth*}{\unitlength}{-\unitlength}
6959 \maketitle
6960 \end{adjustwidth*}
6961 \end{titlingpage}
6962 \end{lcode}
6963
6964 The macro \cmd{\settitlingpagenumbering} can be used to control how
6965 \cmd{\thepage} is configured \emph{inside} a \Ie{titlingpage}. By
6966 default we cannot see any page numbers, but \Lpack{hyperref} can, and
6967 we often see this warning:
6968 \begin{lcode}
6969 pdfTeX warning (ext4): destination with the same identifier (name{page.1}) has
6970 been already used, duplicate ignored
6971 \end{lcode}
6972 This is because \Lpack{hyperref} does make targets on each page and it
6973 uses the current value of \cmd{\thepage}. So the first page of the
6974 title page and the first page of the document now have the same
6975 identifier. You can get rid of this using say
6976 \begin{lcode}
6977 \settitlingpagenumbering{\Alph}
6978 \end{lcode}
6979 The default is \cs{arabic}. It just needs to be a macro that takes one
6980 argument, which will be given the name of a counter, here
6981 \texttt{page}.
6982
6983 \index{title page|)}
6984
6985 \fancybreak{}
6986
6987
6988 \begin{syntax}
6989 \cmd{\title}\marg{text} \cmd{\thetitle} \\
6990 \cmd{\author}\marg{text} \cmd{\theauthor} \\
6991 \cmd{\date}\marg{text} \cmd{\thedate} \\
6992 \end{syntax}
6993 \glossary(title)
6994 {\cs{title}\marg{text}}%
6995 {Used by \cs{maketitle} to typeset \meta{text} as the document title.}
6996 \glossary(thetitle)
6997 {\cs{thetitle}}%
6998 {Copy of \meta{text} from \cs{title}.}
6999 \glossary(author)
7000 {\cs{author}\marg{text}}%
7001 {Used by \cs{maketitle} to typeset \meta{text} as the document author.}
7002 \glossary(theauthor)
7003 {\cs{theauthor}}%
7004 {Copy of \meta{text} from \cs{author}.}
7005 \glossary(date)
7006 {\cs{date}\marg{text}}%
7007 {Used by \cs{maketitle} to typeset \meta{text} as the document date.}
7008 \glossary(thedate)
7009 {\cs{thedate}}%
7010 {Copy of \meta{text} from \cs{date}.}
7011
7012 In the usual document classes, the contents (\meta{text}) of
7013 the \cmd{\title}, \cmd{\author} and \cmd{\date}
7014 macros used for \cmd{\maketitle} are unavailable once \cmd{\maketitle}
7015 has been
7016 issued. The class provides the \cmd{\thetitle},
7017 \cmd{\theauthor} and \cmd{\thedate} commands that can be used for printing
7018 these elements of the title later in the document,
7019 if desired.
7020
7021 \begin{syntax}
7022 \cmd{\and} \cmd{\andnext} \\
7023 \end{syntax}
7024 \glossary(and)%
7025 {\cs{and}}%
7026 {Use within the argument to \cs{author} to separate author's names.}
7027 \glossary(andnext)%
7028 {\cs{andnext}}%
7029 {Use within the argument to \cs{author} to insert a newline..}
7030 The macro \cmd{\and} is used within the argument to the
7031 \cmd{\author} command to add some extra space between the author's names.
7032 The class \cmd{\andnext} macro inserts a newline instead of a space.
7033 Within the \cmd{\theauthor} macro both \cmd{\and} and \cmd{\andnext}
7034 are replaced by a comma.
7035
7036 The class does not follow the standard classes' habit
7037 of automatically killing the titling
7038 commands after \cmd{\maketitle} has been issued. You can have multiple
7039 \cmd{\title}, \cmd{\author}, \cmd{\date} and \cmd{\maketitle}
7040 commands in your
7041 document if you wish. For example, some reports are issued with
7042 a title page, followed by an executive summary, and then they
7043 have another, possibly modified, title at the start of
7044 the main body of the report. This can be accomplished like this:
7045 \begin{lcode}
7046 \title{Cover title}
7047 ...
7048 \begin{titlingpage}
7049 \maketitle
7050 \end{titlingpage}
7051 ...
7052 \title{Body title}
7053 \maketitle
7054 ...
7055 \end{lcode}
7056
7057 \begin{syntax}
7058 \cmd{\killtitle} \cmd{\keepthetitle} \\
7059 \cmd{\emptythanks} \\
7060 \end{syntax}
7061 \glossary(killtitle)%
7062 {\cs{killtitle}}%
7063 {Makes all aspects of \cs{maketitle} unavailable.}
7064 \glossary(keepthetitle)%
7065 {\cs{keepthetitle}}%
7066 {Makes most aspects of \cs{maketitle} unavailable but keeps \cs{thetitle},
7067 \cs{theauthor} and \cs{thedate}.}
7068 \glossary(emptythanks)%
7069 {\cs{emptythanks}}%
7070 {Discards any text from previous uses of \cs{thanks}.}
7071 The \cmd{\killtitle} macro makes all aspects of titling, including
7072 \cmd{\thetitle} etc.,
7073 unavailable from the point that it is issued (using this command will save
7074 some macro space if the \cmd{\thetitle}, etc., commands are not required).
7075 Using this command is the class's manual version
7076 of the automatic killing performed by the standard classes.
7077 The \cmd{\keepthetitle} command performs a similar function, except that
7078 it keeps the \cmd{\thetitle}, \cmd{\theauthor} and \cmd{\thedate} commands,
7079 while killing everything else.
7080
7081 The \cmd{\emptythanks} command discards any text from prior use of
7082 \cmd{\thanks}.
7083 This command is useful when \cmd{\maketitle} is used multiple times ---
7084 the \cmd{\thanks} commands in each use just stack up the texts for output
7085 at each use, so each subsequent use of \cmd{\maketitle} will output all
7086 previous \cmd{\thanks} texts together with any new ones. To avoid this,
7087 put \cmd{\emptythanks} before each \cmd{\maketitle} after the first.
7088
7089 \index{title!styling|)}
7090
7091
7092 \section{Styling the thanks} \label{sec:thanks}
7093
7094 \index{thanks}
7095 \index{thanks!styling|(}
7096
7097 The class provides a configurable \cmd{\thanks} command.
7098
7099 \begin{syntax}
7100 \cmd{\thanksmarkseries}\marg{format} \\
7101 \cmd{\symbolthanksmark} \\
7102 \end{syntax}
7103 \glossary(thanksmarkseries)%
7104 {\cs{thanksmarkseries}\marg{format}}%
7105 {Thanks marks will be printed using \meta{format} series of symbols.}
7106 \glossary(symbolthanksmark)%
7107 {\cs{symbolthanksmark}}
7108 {Set the thanks marks to be printed using the footnote series of symbols.}
7109 Any \cmd{\thanks} are marked with symbols in the
7110 titling and footnotes\index{footnote}.
7111 The command \cmd{\thanksmarkseries}
7112 can be used to change the marking style. The \meta{format} argument
7113 is the name of one of the formats for printing a counter. The name
7114 is the same as that of a counter format but without the backslash.
7115 To have the \cmd{\thanks} marks as lowercase letters instead of symbols
7116 do:
7117 \begin{lcode}
7118 \thanksmarkseries{alph}
7119 \end{lcode}
7120 Just for convenience the \cmd{\symbolthanksmark} command sets the series
7121 to be footnote\index{footnote} symbols.
7122 Using this class the potential names for \meta{format} are:
7123 \texttt{arabic}, \texttt{roman}, \texttt{Roman}, \texttt{alph},
7124 \texttt{Alph}, and \texttt{fnsymbol}.
7125
7126 \begin{syntax}
7127 \cmd{\continuousmarks} \\
7128 \end{syntax}
7129 \glossary(continuousmarks)%
7130 {\cs{continuousmarks}}%
7131 {Specifies that the thanks/footnote marker is not zeroed after titling.}
7132 The \cmd{\thanks} command uses the \Icn{footnote} counter,
7133 and normally the counter
7134 is zeroed after the titling so that the footnote marks\index{footnote!mark} start from 1.
7135 If the counter should not be zeroed, then just specify
7136 \cmd{\continuousmarks}.
7137 This might be required if numerals are used as the thanks markers.
7138
7139 \begin{syntax}
7140 \cmd{\thanksheadextra}\marg{pre}\marg{post} \\
7141 \end{syntax}
7142 \glossary(thanksheadextra)%
7143 {\cs{thanksheadextra}\marg{pre}\marg{post}}%
7144 {Inserts \meta{pre} and \meta{post} before and after thanks markers
7145 in the titling code.}
7146 The \cmd{\thanksheadextra} command will insert
7147 \meta{pre} and \meta{post} before and after the thanks markers in the
7148 titling block. By default \meta{pre} and \meta{post} are empty.
7149 For example, to put parentheses round the titling markers do:
7150 \begin{lcode}
7151 \thanksheadextra{(}{)}
7152 \end{lcode}
7153
7154
7155 \begin{syntax}
7156 \cmd{\thanksmark}\marg{n} \\
7157 \end{syntax}
7158 \glossary(thanksmark)%
7159 {\cs{thanksmark}\marg{n}}%
7160 {Prints a thanks mark identical to the n'th (previously) printed mark.}
7161 It is sometimes desireable to have the same thanks text be applied to,
7162 say, four out of six authors, these being the first 3 and the last one.
7163 The command \cmd{\thanksmark}\marg{n} is similar to
7164 \cmd{\footnotemark}\oarg{n} in that it prints a thanks mark identical
7165 to that of the \meta{n}'th \cmd{\thanks} command. No changes are made
7166 to any thanks in the footnotes\index{footnote}. For instance, in the following
7167 the authors Alpha and Omega will have the same mark:
7168 \begin{lcode}
7169 \title{The work\thanks{Draft}}
7170 \author{Alpha\thanks{ABC},
7171 Beta\thanks{XYZ} and
7172 Omega\thanksmark{2}}
7173 \maketitle
7174 \end{lcode}
7175
7176 %\begin{syntax}
7177 %\cmd{\thanksgap}\marg{length} \\
7178 %\end{syntax}
7179 %The marks in the titling block printed by the
7180 %\cmd{\thanks} and \cmd{\thanksmark}
7181 %commands take zero space. This is acceptable if they come at the end of
7182 %a line, but not in the middle of a line. Use the
7183 %\cmd{\thanksgap} command immediately after a mid-line
7184 %\cmd{\thanks} or \cmd{\thanksmark} command to add \meta{length} amount of
7185 %space before the next word. For example, if there are three authors
7186 %from two different institutions:
7187 %\begin{lcode}
7188 %\author{Alpha\thanks{ABC},
7189 % Omega\thanks{XYZ}\thanksgap{1ex} and
7190 % Beta\thanksmark{1}}
7191 %\end{lcode}
7192
7193 \begin{syntax}
7194 \cmd{\thanksmarkstyle}\marg{defn} \\
7195 \end{syntax}
7196 \glossary(thanksmarkstyle)%
7197 {\cs{thanksmarkstyle}\marg{defn}}%
7198 {Sets the style for the thanks marks at the foot.}
7199 By default the thanks mark at the foot is typeset as a superscript. In
7200 the class this is specifed via
7201 \begin{lcode}
7202 \thanksmarkstyle{\textsuperscript{#1}}
7203 \end{lcode}
7204 where \verb?#1? will be replaced by the thanks mark symbol. You can change
7205 the mark styling
7206 if you wish. For example, to put parentheses round the
7207 mark and typeset it at normal size on the baseline:
7208 \begin{lcode}
7209 \thanksmarkstyle{(#1)}
7210 \end{lcode}
7211
7212
7213 \begin{syntax}
7214 \lnc{\thanksmarkwidth} \\
7215 \end{syntax}
7216 \glossary(thanksmarkwidth)%
7217 {\cs{thanksmarkwidth}}%
7218 {Width of box for the thanks marks at the foot.}
7219 The thanks mark in the footnote\index{footnote} is typeset right justified in a box
7220 of width \lnc{\thanksmarkwidth}. The first line of the thanks text starts
7221 after this box. The initialisation is
7222 \begin{lcode}
7223 \setlength{\thanksmarkwidth}{1.8em}
7224 \end{lcode}
7225 giving the default position.
7226
7227 \begin{syntax}
7228 \lnc{\thanksmarksep} \\
7229 \end{syntax}
7230 \glossary(thanksmarksep)%
7231 {\cs{thanksmarksep}}%
7232 {Indentation of second and subsequent thanks text lines at the foot.}
7233 The value of the length
7234 \lnc{\thanksmarksep} controls the indentation the
7235 second and subsequent lines of the thanks text, with respect to
7236 the end of the mark box. As examples:
7237 \begin{lcode}
7238 \setlength{\thanksmarksep}{0em}
7239 \end{lcode}
7240 will align the left hand ends of of a multiline thanks text, while:
7241 \begin{lcode}
7242 \setlength{\thanksmarksep}{-\thanksmarkwidth}
7243 \end{lcode}
7244 will left justify any second and subsequent lines of the thanks text.
7245 This last
7246 setting is the initialised value, giving the default appearance.
7247
7248 \begin{syntax}
7249 \cmd{\thanksfootmark} \\
7250 \end{syntax}
7251 \glossary(thanksfootmark)%
7252 {\cs{thanksfootmark}}%
7253 {Typesets a thanks mark at the foot.}
7254 A thanks mark in the footnote\index{footnote} region is typeset by \cmd{\thanksfootmark}.
7255 The code for this is roughly:
7256 \LMnote{2012/07/02}{Text changed to reflect the actual code}
7257 \begin{lcode}
7258 \newcommand{\thanksfootmark}{%
7259 \hbox to\thanksmarkwidth{\hfil\normalfont%
7260 \thanksscript{\thefootnote}}}
7261 \end{lcode}
7262 You should not need to change the definition
7263 of \cmd{\thanksfootmark}
7264 but you may want to change the default definitions of one or more
7265 of the macros it uses.
7266
7267 \begin{syntax}
7268 \cmd{\thanksscript}\marg{text} \\
7269 \end{syntax}
7270 \glossary(thanksfootmark)%
7271 {\cs{thanksfootmark}}%
7272 {Handle the inner part of the thanks mark at the foot.}
7273 This is initially defined as:
7274 \begin{lcode}
7275 \newcommand{\thanksscript}[1]{\textsuperscript{#1}}
7276 \end{lcode}
7277 so that \cmd{\thanksscript} typesets its argument as a superscript, which
7278 is the default for thanks notes.
7279
7280
7281
7282 % \begin{comment}
7283
7284 % \begin{syntax}
7285 % \cmd{\thanksscript}\marg{text} \\
7286 % \end{syntax}
7287 % Note that the thanks mark, together with the \verb?\...pre? and \verb?\...post?
7288 % commands form the \meta{text} argument to the \cmd{\thanksscript} command.
7289 % This is initially defined as:
7290 % \begin{lcode}
7291 % \newcommand{\thanksscript}[1]{\textsuperscript{#1}}
7292 % \end{lcode}
7293 % so that \cmd{\thanksscript} typesets its argument as a superscript, which
7294 % is the default for thanks notes. If you would prefer the mark to be
7295 % set at the baseline instead, for example, just do:
7296 % \begin{lcode}
7297 % \renewcommand{\thanksscript}[1]{#1}
7298 % \end{lcode}
7299 % and if you also wanted very small symbols on the baseline you could do:
7300 % \begin{lcode}
7301 % \renewcommand{\thanksscript}[1]{\tiny #1}
7302 % \end{lcode}
7303
7304 % Alternatively
7305 % \begin{lcode}
7306 % \renewcommand{\thanksscript}[1]{#1}
7307 % \thanksfootextra{\bfseries}{.}
7308 % \end{lcode}
7309 % will give a bold baseline mark followed by a dot.
7310
7311 % Using combinations of these macros you can easily define
7312 % different layouts for the thanks footnotes\index{footnote}. Here are some
7313 % sample, but to shorten them I have ignored any
7314 % \cs{renewcommand}s and \cs{setlength}s, leaving these to be implied
7315 % as necessary.
7316 % \begin{itemize}
7317 % \item Setting \verb?\thanksfootextra{}{\hfill}? left justifies the mark
7318 % in its box:
7319 % \begin{itemize}
7320 % \item \verb?\thanksscript{\llap{#1\space}}}, \verb?\thanksmarkwidth{0em}? and \\
7321 % \verb?\thanksmargin{0em}? puts the baseline mark in the margin\index{margin}
7322 % and the text left justified.
7323 % \item Using \verb?\thanksscript{#1}?, \verb?\thanksmarkwidth{1em}? and \\
7324 % \verb?\thanksmargin{-\thanksmarkwidth}? makes the baseline mark
7325 % and text left adjusted.
7326 % \item \verb?\thanksscript{#1}?, \verb?\thanksmarkwidth{1em}? and
7327 % \verb?\thanksmargin{0em}? puts the baseline mark left adjusted
7328 % and the text indented and aligned, like this marked
7329 % sentence is typeset.
7330 % \end{itemize}
7331
7332 % \item Setting \verb?\thanksfootextra{ }? and \verb?\thanksscript{#1}?
7333 % right justifies the baseline mark and a space in the mark box:
7334 % \begin{itemize}
7335 % \item The normal style is
7336 % defined by \verb?\thanksmarkwidth{1.8em}? and \\
7337 % \verb?\thanksmargin{-\thanksmarkwidth}? which put the mark
7338 % indented and the text left adjusted, like a normal indented
7339 % paragraph\index{paragraph!indentation}.
7340 % \item \verb?\thanksmarkwidth{1.8em}? and
7341 % \verb?\thanksmargin{0em}? put the mark indented
7342 % and the text indented and aligned.
7343 % \end{itemize}
7344
7345 % \end{itemize}
7346
7347 % %%%%%%%%%%%%%%%%%%%%%
7348 % \end{comment}
7349 % %%%%%%%%%%%%%%%%%%%%
7350
7351 \begin{syntax}
7352 \cmd{\makethanksmark} \\
7353 \cmd{\makethanksmarkhook} \\
7354 \end{syntax}
7355 \glossary(makethanksmark)%
7356 {\cs{makethanksmark}}%
7357 {Typesets the thanks marker and text at the foot.}
7358 \glossary(makethanksmarkhook)
7359 {\cs{makethanksmarkhook}}
7360 {Code hook into \cs{makethanksmark}.}
7361 The macro \cmd{\makethanksmark} typesets both the thanks marker (via
7362 \cmd{\thanksfootmark}) and the thanks text. You probably will not need
7363 to change its default definition. Just in case, though,
7364 \cmd{\makethanksmark}
7365 calls the macro \cmd{\makethanksmarkhook} before it does any typesetting.
7366 The default definition of this is:
7367 \begin{lcode}
7368 \newcommand{\makethanksmarkhook}{}
7369 \end{lcode}
7370 which does nothing.
7371
7372 You can redefine \cmd{\makethanksmarkhook} to do something useful. For
7373 example, if you wanted a slightly bigger baseline skip you could do:
7374 \begin{lcode}
7375 \renewcommand{\makethanksmarkhook}{\fontsize{8}{11}\selectfont}
7376 \end{lcode}
7377 where the numbers \texttt{8} and \texttt{11} specify the point size of the font
7378 and the baseline skip
7379 respectively. In this example 8pt is the normal \cmd{\footnotesize} in
7380 a 10pt document, and 11pt is the baselineskip for \cmd{\footnotesize}
7381 text in an 11pt document (the normal baseline skip for \cmd{\footnotesize}
7382 in a 10pt document is 9.5pt);
7383 adjust these numbers to suit.
7384
7385 \begin{syntax}
7386 \cmd{\thanksrule} \\
7387 \cmd{\usethanksrule} \\
7388 \cmd{\cancelthanksrule} \\
7389 \end{syntax}
7390 \glossary(thanksrule)%
7391 {\cs{thanksrule}}%
7392 {The rule to be typeset before the thanks in the foot.}
7393 \glossary(usethanksrule)%
7394 {\cs{usethanksrule}}%
7395 {Specifies that the \cs{thanksrule} is to be typeset in the
7396 \texttt{titlingpage} environment.}
7397 \glossary(cancelthanksrule)%
7398 {\cs{cancelthanksrule}}%
7399 {Specifies that the \cs{footnoterule} is to be used from now on.}
7400 By default, there is no rule above \cmd{\thanks}
7401 text that appears in a \Ie{titlingpage} environment.
7402 If you want a rule in that environment, put \cmd{\usethanksrule}
7403 before the \cmd{\maketitle} command, which will then print a rule according
7404 to the current definition of \cmd{\thanksrule}.
7405 \cmd{\thanksrule} is initialised to be a copy of \cmd{\footnoterule} as it
7406 is defined at the
7407 end of the preamble\index{preamble}. The definition of \cmd{\thanksrule} can be changed
7408 after \verb?\begin{document}?. If the definition of \cmd{\thanksrule} is modified
7409 and a \cmd{\usethanksrule} command has been issued, then the redefined
7410 rule may also be used for footnotes\index{footnote}. Issuing the command
7411 \cmd{\cancelthanksrule} will cause the normal \cmd{\footnoterule} definition
7412 to be used from thereon; another \cmd{\usethanksrule}
7413 command can be issued later
7414 if you want to swap back again.
7415
7416 The parameters for the vertical positioning of footnotes\index{footnote}
7417 and thanks notes, and the default \cmd{\footnoterule} are the same
7418 (see \fref{fig:fn} on \pref{fig:fn}).
7419 You will have to change one or more of these if the vertical spacings of
7420 footnotes\index{footnote}
7421 and thanks notes are meant to be different.
7422
7423 \index{thanks!styling|)}
7424
7425 %#% extend
7426 %#% extstart include abstracts.tex
7427
7428 \svnidlong
7429 {$Ignore: $}
7430 {$LastChangedDate: 2019-10-22 18:09:22 +0200 (Tue, 22 Oct 2019) $}
7431 {$LastChangedRevision: 652 $}
7432 {$LastChangedBy: [email protected] $}
7433
7434 \chapter{Abstracts}
7435
7436
7437 Abstracts\index{abstract} do not normally appear in books but
7438 they are often an essential
7439 part of an article in a technical journal. Reports may or may not
7440 include an abstract, but if so it will often be called a `Summary'.
7441 There may be an even shorter abstract as well, often called an
7442 `Executive Summary', for those who feel that details are irrelevant.
7443
7444 In the standard classes appearance of the \Ie{abstract} environment
7445 is fixed. The class provides a set of controls adjusting the appearance of
7446 an \Ie{abstract} environment.
7447
7448 Questions about how to have a
7449 one-column\index{column!single} abstract\index{abstract} in a
7450 two-column\index{column!double} paper
7451 seem to pop up fairly regularly on the
7452 \texttt{comp.text.tex} newsgroup. While an answer based on responses
7453 on \ctt\ is provided in the FAQ,
7454 the class provides a more author-friendly means
7455 of accomplishing this.
7456
7457 \section{Styling}
7458
7459 \index{abstract!styling|(}
7460
7461 Much of this part of the class is a reimplementation of the
7462 \Lpack{abstract} package~\cite{ABSTRACT}.
7463
7464 The typeset format of an \Ie{abstract} in a \Lclass{report} or
7465 \Lclass{article} class document depends on the class
7466 options.\footnote{The \texttt{abstract} environment is not
7467 available for the \Lclass{book} class.} The formats are:
7468 \begin{itemize}
7469 \item \Lopt{titlepage} class option: The abstract
7470 heading\indextwo{heading}{abstract} (i.e., value of
7471 \cmd{\abstractname}) is typeset centered in a bold font; the text is set in
7472 the normal font and to the normal width.
7473 \item \Lopt{twocolumn} class option: The abstract
7474 heading\indextwo{heading}{abstract} is typeset like
7475 an unnumbered section; the text is set in the normal font and to the
7476 normal width (of a single column\index{column!single}).
7477 \item Default (neither of the above class options): The abstract
7478 heading\indextwo{heading}{abstract}
7479 is typeset centered in a small bold font; the text is set in a small
7480 font and indented like the \Ie{quotation} environment.
7481 \end{itemize}
7482
7483 This class provides an \Ie{abstract} environment and
7484 handles to modify the typesetting of an \Ie{abstract}.
7485
7486 \begin{syntax}
7487 \senv{abstract} text \eenv{abstract} \\
7488 \end{syntax}
7489 \glossary(abstract)%
7490 {\senv{abstract}}%
7491 {Environment for typesetting an abstract.}
7492 There is nothing special about using the \Ie{abstract} environment.
7493 Formatting is controlled by the macros described below.
7494
7495 \begin{syntax}
7496 \cmd{\abstractcol} \\
7497 \cmd{\abstractintoc} \\
7498 \cmd{\abstractnum} \\
7499 \cmd{\abstractrunin} \\
7500 \end{syntax}
7501 \glossary(abstractcol)%
7502 {\cs{abstractcol}}%
7503 {Declares that an abstract in a \Popt{twocolumn} document should be
7504 typeset like an unnumbered chapter.}
7505 \glossary(abstractintoc)%
7506 {\cs{abstractintoc}}%
7507 {Specifies that the abstact's title is to be added to the ToC.}
7508 \glossary(abstractnum)%
7509 {\cs{abstractnum}}%
7510 {Specifies that an abstract is to be typeset like a numbered chapter.}
7511 \glossary(abstractrunin)%
7512 {\cs{abstractrunin}}%
7513 {Specifies that the title of an abstract should be set as a run-in heading.}
7514
7515 The normal format for an abstract is with a centered, bold title
7516 and the text in a small font, inset from the margins\index{margin}.
7517
7518 The \cmd{\abstractcol} declaration specifies that an abstract in a
7519 \Lopt{twocolumn} class option document should be typeset like a
7520 normal, unnumbered chapter.
7521 The \cmd{\abstractintoc} specifies that the abstract title should
7522 be added to the \toc. The declaration \cmd{\abstractnum} specifies that the
7523 abstract should be typeset like a numbered chapter and
7524 \cmd{\abstractrunin} specifies that
7525 the title of the abstract should look like a run-in heading; these two
7526 declarations are mutually exclusive. Note that the \cmd{\abstractnum}
7527 declaration has no effect if the abstract is in the \cmd{\frontmatter}.
7528
7529 \begin{syntax}
7530 \cmd{\abstractname} \\
7531 \cmd{\abstractnamefont} \\
7532 \cmd{\abstracttextfont} \\
7533 \end{syntax}
7534 \glossary(abstractname)%
7535 {\cs{abstractname}}%
7536 {An abstract's title.}
7537 \glossary(abstractnamefont)%
7538 {\cs{abstractnamefont}}%
7539 {Font for typesetting and abstract's title (\cs{abstractname}).}
7540 \glossary(abstracttextfont)%
7541 {\cs{abstracttextfont}}%
7542 {Font for typesetting the body text of an abstract.}
7543 \cmd{\abstractname} (default `\abstractname') is used as the title for
7544 the \Ie{abstract} environment and is set using the \cmd{\abstractnamefont}.
7545 The body of the abstract is typeset using the \cmd{\abstracttextfont}.
7546 These two commands can be redefined to change the fonts if you wish.
7547 The default definitions are
7548 \begin{lcode}
7549 \newcommand{\abstractnamefont}{\normalfont\small\bfseries}
7550 \newcommand{\abstracttextfont}{\normalfont\small}
7551 \end{lcode}
7552
7553 \begin{syntax}
7554 \lnc{\absleftindent} \lnc{\absrightindent} \\
7555 \lnc{\absparindent} \lnc{\absparsep} \\
7556 \end{syntax}
7557 \glossary(absleftindent)%
7558 {\cs{absleftindent}}%
7559 {Indentation of the left of the \Pe{abstract} text.}
7560 \glossary(absrightindent)%
7561 {\cs{absrightindent}}%
7562 {Indentation of the right of the \Pe{abstract} text.}
7563 \glossary(absparindent)%
7564 {\cs{absparindent}}%
7565 {Paragraph indent in the \Pe{abstract} environment.}
7566 \glossary(absparsep)%
7567 {\cs{absparsep}}%
7568 {Paragraph separation in the \Pe{abstract} environment.}
7569 This version of \Ie{abstract} uses a \Ie{list} environment for typesetting
7570 the text. These four lengths can be changed (via \cmd{\setlength}
7571 or \cmd{\addtolength}) to adjust
7572 the left and right margins\index{margin}, the paragraph indentation\index{paragraph!indentation}, and the vertical skip
7573 between paragraphs in this environment.
7574 The default values depend on whether or not the \Lopt{twocolumn}
7575 class option is used. The general layout parameters for lists are illustrated
7576 in \fref{fig:listlay}.
7577 \begin{caveat}
7578 The default values for \cmd{\absparindent} and \cmd{\absparsep} are
7579 \cmd{\parindent} and \cmd{\parskip}. But, since users may change
7580 these values in the preamble, we delay setting \cmd{\absparindent}
7581 and \cmd{\absparsep} to the beginning of the document. Thus if you
7582 want to change these values remember to use
7583 \begin{verbatim}
7584 \AtBeginDocument{
7585 \setlength{\absparindent}{...}
7586 \setlength{\absparsep}{...}
7587 }
7588 \end{verbatim}
7589
7590 \end{caveat}
7591
7592
7593
7594
7595 \begin{syntax}
7596 \cmd{\abslabeldelim}\marg{text} \\
7597 \end{syntax}
7598 \glossary(abslabeldelim)%
7599 {\cs{abslabeldelim}\marg{text}}%
7600 {\meta{text} is typeset immediately after \cs{abstractname} in a run-in
7601 heading.}
7602 If the \cmd{\abstractrunin} declaration has been given,
7603 the heading is typeset as a run-in heading. That is, it is the
7604 first piece of text on the first line of the abstract text.
7605 The \meta{text} argument of \cmd{\abslabeldelim} is typeset
7606 immediately after the heading. By default it is defined to do nothing, but
7607 if you wanted, for example, the \cmd{\abstractname} to be followed by
7608 a colon and some extra space you could specify
7609 \begin{lcode}
7610 \abslabeldelim{:\quad}
7611 \end{lcode}
7612
7613 \begin{syntax}
7614 \cmd{\absnamepos} \\
7615 \end{syntax}
7616 \glossary(absnamepos)%
7617 {\cs{absnamepos}}%
7618 {Position of a non run-in title for an \Pe{abstract} (\texttt{flushleft},
7619 \texttt{center}, or \texttt{flushright}).}
7620 If the \cmd{\abstractrunin} declaration is not used then the heading
7621 is typeset in its own environment, specified by
7622 \cmd{\absnamepos}. The default definition is
7623 \begin{lcode}
7624 \newcommand{\absnamepos}{center}
7625 \end{lcode}
7626 It can be defined to be one of \Ie{flushleft}, \Ie{center},
7627 or \Ie{flushright} to give a left, centered or right aligned heading;
7628 or to any
7629 other appropriate environment which is supported by a used package\index{package}.
7630
7631 \begin{syntax}
7632 \lnc{\abstitleskip} \\
7633 \end{syntax}
7634 \glossary(abstitleskip)%
7635 {\cs{abstitleskip}}
7636 {Space around the title of an \Pe{abstract}.}
7637 With the \cmd{\abstractrunin} declaration a horizontal space of length
7638 \lnc{\abstitleskip} is typeset
7639 before the heading. For example, if \lnc{\absparindent} is non-zero, then:
7640 \begin{lcode}
7641 \AtBeginDocument{
7642 \setlength{\abstitleskip}{-\absparindent}
7643 }
7644 \end{lcode}
7645 will typeset the heading flush left (we have to delay as the value of
7646 \cmd{\absparindent} is zero in the preamble and is set at the start of
7647 the doc).
7648
7649 Without the \cmd{\abstractrunin} declaration, \lnc{\abstitleskip} is
7650 aditional vertical space (either positive or negative) that is
7651 inserted between the abstract name and the text of the abstract.
7652
7653 \index{abstract!styling|)}
7654
7655 \section{One column abstracts}
7656
7657 \index{abstract!one column|(}
7658
7659 The usual advice~\cite{FAQ} about creating a
7660 one-column\index{column!double}
7661 \Ie{abstract} in a
7662 \Lopt{twocolumn} document is to write code like this:
7663 \begin{lcode}
7664 \documentclass[twocolumn...]{...}
7665 ...
7666 \twocolumn[
7667 \begin{@twocolumnfalse}
7668 \maketitle need full-width title
7669 \begin{abstract}
7670 abstract text...
7671 \end{abstract}
7672 \end{@twocolumnfalse}
7673 ]
7674 ... hand make footnotes for any \thanks commands
7675 ...
7676 \end{lcode}
7677
7678 \begin{syntax}
7679 \senv{onecolabstract} text \eenv{onecolabstract} \\
7680 \cmd{\saythanks} \\
7681 \end{syntax}
7682 \glossary(onecolabstract)%
7683 {\senv{onecolabstract}}%
7684 {Environment for typesetting a one column abstract in a two column document.}
7685 \glossary(saythanks)%
7686 {\cs{saythanks}}%
7687 {Following a \Pe{onecolabstract} it ensures that \cs{thanks} are printed.}
7688 The class provides a \Ie{onecolabstract} environment that you can use
7689 for a one column\index{column!single} abstract in a \Lopt{twocolumn} document,
7690 and it is used like this:
7691 \begin{lcode}
7692 \documentclass[twocolumn...]{memoir}
7693 ...
7694 \twocolumn[
7695 \maketitle need full-width title
7696 \begin{onecolabstract}
7697 abstract text...
7698 \end{onecolabstract}
7699 ]
7700 \saythanks % typesets any \thanks commands
7701 ...
7702 \end{lcode}
7703 The command \cmd{\saythanks} ensures that any \cmd{\thanks} texts from
7704 an earlier \cmd{\maketitle} are printed out as normal.
7705
7706 If you want, you can use the \Ie{onecolabstract} environment in place
7707 of the \Ie{abstract} environment --- it doesn't have to be within the
7708 optional argument of the \cmd{\twocolumn} command. In fact,
7709 \Ie{onecolabstract} internally uses \Ie{abstract} for the typesetting.
7710
7711
7712 \index{abstract!one column|)}
7713
7714
7715 %#% extend
7716 %#% extstart include document-divisions.tex
7717
7718 \svnidlong
7719 {$Ignore: $}
7720 {$LastChangedDate: 2025-09-19 16:06:27 +0200 (Fri, 19 Sep 2025) $}
7721 {$LastChangedRevision: 873 $}
7722 {$LastChangedBy: [email protected] $}
7723
7724 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%
7725 % chapter style
7726 %\renewcommand{\printchaptername}{}
7727 %\renewcommand{\chapternamenum}{}
7728 %\renewcommand{\chapnumfont}{\normalfont\huge\sffamily}
7729 %\renewcommand{\chaptitlefont}{\chapnumfont}
7730 %\renewcommand{\afterchapternum}{\space}
7731 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%
7732 % section styles
7733 %\setsecheadstyle{\Large\sffamily\raggedright}
7734 %\setsubsecheadstyle{\large\sffamily\raggedright}
7735 %\setsubsubsecheadstyle{\normalsize\sffamily\raggedright}
7736 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
7737
7738 \chapterstyle{pedersen}
7739
7740 \chapter{Document divisions}
7741
7742 For this chapter the \cstyle{pedersen} chapterstyle has been used in
7743 order to demonstrate how it appears.
7744
7745
7746 In this chapter I first discuss the various kinds of divisions within
7747 a book and the commands for typesetting these.
7748
7749 After that I describe the class methods for modifying the appearance
7750 of the chapter and other sectional titles (subheads)\index{subhead}.
7751 The facilities described here provide roughly the same as you would
7752 get if you used the \Lpack{titlesec}~\cite{TITLESEC} and
7753 \Lpack{sectsty}~\cite{SECTSTY} packages together; the commands are
7754 different, though.
7755
7756 \section{Logical divisions}
7757
7758 As described earlier there are three main logical divisions to a book;
7759 the \pixfrontmatter, \pixmainmatter\ and \pixbackmatter. There are three \ltx\
7760 commands that correspond to these, namely \cmd{\frontmatter},
7761 \cmd{\mainmatter} and \cmd{\backmatter}.
7762
7763 \begin{syntax}
7764 \cmd{\frontmatter} \cmd{\frontmatter*} \\
7765 \end{syntax}
7766 \glossary(frontmatter)%
7767 {\cs{frontmatter}}%
7768 {Sets folios to be printed in lowercase roman and prohibits sectional
7769 number.}
7770 \glossary(frontmatter*)%
7771 {\cs{frontmatter*}}%
7772 {Same as \cs{frontmatter} except that folios are unaltered.}
7773 The \cmd{\frontmatter} declaration sets the folios\index{folio} to be
7774 printed in lowercase roman numerals, starts the page numbering from~i,
7775 and prohibits any numbering
7776 of sectional divisions. Caption\index{caption}, equations, etc., will be
7777 numbered continuously. The starred version of the command,
7778 \cmd{\frontmatter*}, is similar to the unstarred version except that it
7779 makes no changes to the page numbering or the print style for the
7780 folios\index{folio}. Even though \cmd{\chapter} and other divisions will not
7781 be numbered their titles will be added to the ToC.
7782
7783 If it is to be used at all, the \cmd{\frontmatter} declaration should
7784 come before any text is set, otherwise the pagination scheme will be
7785 in disarray (in books pagination starts on the first page).
7786
7787 \begin{syntax}
7788 \cmd{\mainmatter} \cmd{\mainmatter*} \\
7789 \end{syntax}
7790 \glossary(mainmatter)%
7791 {\cs{mainmatter}}%
7792 {Sets folio numbers to arabic, starting with 1. Floats, etc., will be
7793 numbered per chapter and sectional divisions will be numbered.}
7794 \glossary(mainmatter*)%
7795 {\cs{mainmatter*}}%
7796 {Same as \cs{mainmatter} except that folios are unaltered.}
7797 The \cmd{\mainmatter} declaration, which is the default at the start of a
7798 document, sets the folios\index{folio} to be printed in arabic numerals, starts
7799 the page numbering from~1, and sections and above will be numbered.
7800 Float\index{float} captions\index{caption}, equations, etc., will be numbered
7801 per chapter\index{chapter}. The starred version of the command,
7802 \cmd{\mainmatter*}, is similar to the unstarred version except that it
7803 makes no changes to the page numbering or the print style for the
7804 folios\index{folio}.
7805
7806 \LMnote{2010/01/23}{Added the following paragraph, just stating what
7807 \cs{mainmatter} does, was not clear before.}
7808 Please note that \cmd{\mainmatter} will not only change the folio
7809 numbers to arabic and restart it at 1, it will also make sure it
7810 starts at the next coming recto page. (Even when running under the
7811 \texttt{openany} option).
7812
7813
7814
7815 \begin{syntax}
7816 \cmd{\backmatter} \\
7817 \end{syntax}
7818 \glossary(backmatter)%
7819 {\cs{backmatter}}%
7820 {Prohibits sectional numbering and floats, etc., will be numbered continuously.}
7821 The \cmd{\backmatter} declaration makes no change to the pagination or
7822 folios\index{folio} but does prohibit sectional division numbering, and
7823 captions\index{caption}, etc., will be numbered continuously.
7824
7825 \fancybreak{}
7826
7827 \LMnote{2009/06/29}{Added the following section}
7828
7829 If you have other types of floats that might be used in the front-
7830 main- or backmatter, then you can change some internals to add these
7831 to be numbered in the same manner as we do with figures and
7832 tables. They are defined as
7833 \begin{lcode}
7834 \newcommand\@memfront@floats{%
7835 \counterwithout{figure}{chapter}
7836 \counterwithout{table}{chapter}}
7837 \newcommand\@memmain@floats{%
7838 \counterwithin{figure}{chapter}
7839 \counterwithin{table}{chapter}}
7840 \newcommand\@memback@floats{%
7841 \counterwithout{figure}{chapter}
7842 \counterwithout{table}{chapter}
7843 \setcounter{figure}{0}
7844 \setcounter{table}{0}}
7845 \end{lcode}
7846 %
7847 The macros can also be changed in case you want to have consecutive
7848 figure numbering throughout, i.e.,
7849 \begin{lcode}
7850 \makeatletter
7851 \counterwithout{figure}{chapter}
7852 \counterwithout{table}{chapter}
7853 \renewcommand\@memfront@floats{}
7854 \renewcommand\@memmain@floats{}
7855 \newcommand\@memback@floats{}
7856 \makeatother
7857 \end{lcode}
7858 in the preamble.
7859
7860
7861
7862
7863 \section{Sectional divisions}
7864
7865 The \theclass{} class lets you divide a document up into eight levels
7866 of named divisions. They range from book\index{book}, part\index{part}
7867 through chapter\index{chapter} and down to
7868 sub-paragraph. A particular sectional division is specified by one of
7869 the commands \cmd{\book}, \cmd{\part}, \cmd{\chapter}, \cmd{\section},
7870 \cmd{\subsection},
7871 which is probably as deep as you want to go. If you really need finer
7872 divisions, they are
7873 \cmd{\subsubsection}, \cmd{\paragraph} and lastly \cmd{\subparagraph}.
7874 The sectional commands, except for \cmd{\book} and \cmd{\part},
7875 have the same form, so rather than describing
7876 each one in turn I will use \cmd{\section} as model for all but the
7877 two exceptions.
7878
7879 \begin{syntax}
7880 \cmd{\section}\oarg{toc-title}\oarg{head-title}\marg{title}\\
7881 \cmd{\section*}\marg{title}\\
7882 \end{syntax}
7883 \glossary(section)%
7884 {\cs{section}\oarg{toc-title}\oarg{head-title}\marg{title}}%
7885 {Typesets a section subhead \meta{title}, adding \meta{title} to the ToC and
7886 possibly the running headers. If given \meta{toc-title}
7887 is used instead of \meta{title} for the ToC and running header. If given
7888 \meta{head-title} is used for a running header.}
7889 \glossary(section*)%
7890 {\cs{section*}\marg{title}}%
7891 {Typesets an unnumbered section subhead \meta{title}. There are no ToC or
7892 running header entries.}
7893
7894 There are two forms of the command;
7895 the starred version is simpler, so I'll describe its
7896 effects first --- it just typesets \meta{title} in the document in the format
7897 for that particular sectional division. Like the starred version, the plain
7898 version also typesets \meta{title} in the document, but it may be numbered.
7899 Diferent forms of the division title are available for the
7900 Table of Contents (\toc) and a running header\index{header}, as follows:
7901 \begin{itemize}
7902 \item No optional argument: \meta{title} is used for the division title,
7903 the ToC title and a page header title.
7904 \item One optional argument: \meta{title} is used for the division title;
7905 \meta{toc-title} is used for the ToC title and a page header\index{header} title.
7906 \item Two optional arguments: \meta{title} is used for the division title;
7907 \meta{toc-title} is used for the ToC title; \meta{head-title}
7908 is used for a page header\index{header} title.
7909 \end{itemize}
7910
7911 A \cmd{\section} command restarts the numbering of any \cmd{\subsection}s
7912 from one.
7913 For most of the divisions the \meta{title} is put on the page where the command
7914 was issued. The \cmd{\book}, \cmd{\part} and \cmd{\chapter} commands behave
7915 a little differently.
7916
7917 The \cmd{\book} and \cmd{\part} commands are simpler and both behave
7918 in the same way.
7919 \begin{syntax}
7920 \cmd{\book}\oarg{toc and head}\marg{title} \\
7921 \cmd{\part}\oarg{toc and head}\marg{title} \\
7922 \end{syntax}
7923 \glossary(book)%
7924 {\cs{book}\marg{title}}%
7925 {Typesets a numbered book \meta{title} on a page by itself, adding
7926 \meta{title} to the ToC.} \glossary(part)%
7927 {\cs{part}\marg{title}}%
7928 {Typesets a numbered part \meta{title} on a page by itself, adding
7929 \meta{title} to the ToC.} The \cmd{\book}\marg{title} command puts
7930 the book name (default \texttt{\bookname}), number and \meta{title} on
7931 a page by itself. The numbering of books\index{book!number} has no
7932 effect on the numbering of \cmd{\part}s\index{part!number} or
7933 \cmd{\chapter}s\index{chapter!number}. Similarly the
7934 \cmd{\part}\marg{title} command puts the part name (default
7935 \texttt{Part}), number and \meta{title} on a page by itself. The
7936 numbering of parts\index{part!number} has no effect on the numbering
7937 of \cmd{\chapter}s\index{chapter!number}. The optional argument can be
7938 used to send something different to the ToC.\footnote{And header,
7939 though this is rarely used.}
7940
7941 Later I'll give a list of LaTeX's default names, like \texttt{Part}.
7942
7943 \begin{syntax}
7944 \cmd{\chapter}\oarg{toc-title}\oarg{head-title}\marg{title} \\
7945 \cmd{\chapter*}\oarg{head-title}\marg{title} \\
7946 \end{syntax}
7947 \glossary(chapter)%
7948 {\cs{chapter}\oarg{toc-title}\oarg{head-title}\marg{title}}
7949 {Starts a new page and puts the chapter number and \meta{title}
7950 at the top of the page, adding \meta{title} to the ToC and possibly
7951 the running headers. If given \meta{toc-title}
7952 is used instead of \meta{title} for the ToC and running header. If given
7953 \meta{head-title} is used for a running header.
7954 It restarts numbering of any subsidiary elements
7955 such as \cs{section} of floats.}
7956 \glossary(chapter*)%
7957 {\cs{chapter*}\oarg{head-title}\marg{title}}
7958 {Starts a new page and puts an unnumbered chapter \meta{title}
7959 at the top of the page. If given \meta{head-title} is used for a
7960 running header.}
7961
7962 The \cmd{\chapter} command starts a new page and puts
7963 the chapter name (default \texttt{Chapter}), number and \meta{title}
7964 at the top of the page. It restarts the numbering of any \cmd{\section}s
7965 from one. If no optional arguments are specified, \meta{title}
7966 is used as the \toc{} entry and for any page headings. If one optional
7967 argument is specified this is \meta{toc-title} and is used for the
7968 \toc{} entry and for page headings. If both optional arguments
7969 are specified the \meta{head-title} is used for page headings.
7970
7971 The \cmd{\chapter*} command starts a new page and puts
7972 \meta{title} at the top of the page. It makes no \toc{} entry,
7973 changes no numbers and by default changes no page headings.
7974 If the optional \meta{head-title} argument is given, this is used
7975 for page headings. Use of the optional argument has the side-effect
7976 that the \Icn{secnumdepth} counter is set to \Icn{maxsecnumdepth} (see below
7977 for an explanation of these).
7978
7979 When the \Lopt{article} option is in effect, however, things are slightly
7980 different. New chapters do not necessarily start on a new page.
7981 The \cmd{\mainmatter} command
7982 just turns on sectional numbering and starts arabic page numbering; the
7983 \cmd{\backmatter} command just turns off sectional numbering.
7984 The \cmd{\tableofcontents} command and friends, as well as any
7985 other commands created via \cmd{\newlistof},
7986 \emph{always}\footnote{This is a consequence of the internal
7987 timing of macro calls.}
7988 call \verb?thispagestyle{chapter}?. If you are using the
7989 \Lopt{article} option you
7990 will probably want to ensure that the \pstyle{chapter} pagestyle is the
7991 same as you normally use for the document.
7992
7993 Unlike the standard classes the \meta{title} is typeset ragged right.
7994 This means that if you need to force a linebreak in the \meta{title} you
7995 have to use \cmd{\newline} instead of the more usual \cmd{\\}. For instance
7996 \begin{lcode}
7997 \section{A broken\newline title}
7998 \end{lcode}
7999
8000 In the standard classes a \cmd{\section} or other
8001 subhead\index{subhead!near bottom of page}\index{subhead!moved}
8002 that is too close to the bottom of a page is moved to the top of the
8003 following page. If this happens and \cmd{\flushbottom} is in effect, the
8004 contents of the short page are stretched to make the last line flush with
8005 the bottom of the typeblock.
8006 \begin{syntax}
8007 \cmd{\raggedbottomsection} \\
8008 \cmd{\normalbottomsection} \\
8009 \lnc{\bottomsectionskip} \\
8010 \cmd{\bottomsectionpenalty}
8011 \end{syntax}
8012 \glossary(raggedbottomsection)%
8013 {\cs{raggedbottomsection}}%
8014 {Pages will be typeset short because of a moved subhead as if
8015 \cs{raggedbottom} was in effect.}
8016 \glossary(normalbottomsection)%
8017 {\cs{normalbottomsection}}%
8018 {Cancels any previous \cs{raggedbottomsection}.}
8019 \glossary(bottomsectionskip)%
8020 {\cs{bottomsectionskip}}%
8021 {Amount of stretch on a \cs{raggedbottomsection} short page.}
8022 \glossary(bottomsectionpenalty)%
8023 {\cs{bottomsectionpenalty}}%
8024 {Penalty on a \cs{raggedbottomsection} short page.}
8025 The \cmd{\raggedbottomsection} declaration will typeset any pages that
8026 are short because of a moved subhead as though \cmd{\raggedbottom}
8027 was in effect for the short page; other pages are not affected. The
8028 length \lnc{\bottomsectionskip} controls the amount of stretch on the short
8029 page. Setting it to zero allows the last line to be flush with the bottom
8030 of the typeblock. The default setting of 10mm appears to remove any
8031 stretch. \cmd{\bottomsectionpenalty} control the penalty it costs to
8032 make a page break at this point. The detault is zero as the stretch is
8033 usually enough, by setting it to
8034 a negative integer one can be a bit more incouraging regarding a
8035 possible page break.
8036
8037 The declaration \cmd{\normalbottomsection}, which is the default,
8038 cancels any previous \cmd{\raggedbottomsection} declaration.
8039
8040 \subsection{Appendices} \label{sec:appendices}
8041
8042 Appendices\index{appendix} normally come after the main text and are
8043 often considered to be part
8044 of the \cmd{\mainmatter} as they are normally numbered (the \cmd{\backmatter}
8045 declaration turns off all sectional numbering).
8046
8047 \begin{syntax}
8048 \cmd{\appendix} \\
8049 \cmd{\appendixname} \\
8050 \end{syntax}
8051 \glossary(appendix)%
8052 {\cs{appendix}}%
8053 {Sets chapter numbering to alphabetic and sets the chapter name to
8054 \cs{appendixname}.}
8055 \glossary(appendixname)%
8056 {\cs{appendixname}}%
8057 {Name given to chapters in appendices (default Appendix).}
8058 The \cmd{\appendix} declaration changes the numbering of
8059 chapters\index{chapter!number} to an alphabetic form and also changes
8060 the names of chapters from \cmd{\chaptername} (default \texttt{Chapter})
8061 to the value of \cmd{\appendixname} (default \texttt{Appendix})\index{appendix}.
8062 Thus, the first and any subsequent \cmd{\chapter}s after
8063 the \cmd{\appendix} command
8064 will be `Appendix A \ldots', `Appendix B \ldots', and so on.
8065 That is as far as the standard classes go but this class provides more ways
8066 of dealing with appendices\index{appendix}.
8067
8068 \begin{syntax}
8069 \cmd{\appendixpage}\\
8070 \cmd{\appendixpage*}\\
8071 \cmd{\appendixpagename}\\
8072 \end{syntax}
8073 \glossary(appendixpage)
8074 {\cs{appendixpage}}%
8075 {Creates an unnumbered anonymous part-like page with the title \cs{appendixpagename} and adds it to the ToC.}
8076 \glossary(appendixpage*)
8077 {\cs{appendixpage*}}%
8078 {Like \cs{appendixpage} but makes no ToC entry.}
8079 \glossary(appendixpagename)
8080 {\cs{appendixpagename}}%
8081 {Title used for an \cs{appendixpage} (default \texttt{Appendices}.}
8082 The \cmd{\appendixpage} command generates a part-like page (but no name
8083 or number) with the title given by the value of \cmd{\appendixpagename}
8084 (default \texttt{Appendices})\index{appendix}. It also makes an entry in
8085 the \toc{} using
8086 \cmd{\addappheadtotoc} (see below). The starred version generates the
8087 appendix\index{appendix} page but makes no \toc{} entry.
8088
8089 \begin{syntax}
8090 \cmd{\addappheadtotoc}\\
8091 \cmd{\appendixtocname}\\
8092 \end{syntax}
8093 \glossary(addappheadtotoc)%
8094 {\cs{addappheadtotoc}}%
8095 {Adds ToC entry with the title \cs{appendixtocname}.}
8096 \glossary(appendixtocname)%
8097 {\cs{appendixtocname}}%
8098 {Title of ToC entry added by \cs{addappheadtotoc} (default \texttt{Appendices}.}
8099 The command \cmd{\addappheadtotoc} adds an entry to the \toc. The title is
8100 given by the value of \cmd{\appendixtocname} (default \texttt{Appendices})\index{appendix}.
8101
8102 \begin{syntax}
8103 \senv{appendices} text \eenv{appendices}\\
8104 \end{syntax}
8105 \glossary(appendices)%
8106 {\senv{appendices}}%
8107 {An environment form of \cs{appendix}; chapters are restored to their condition
8108 (including numbering) after the environment ends.}
8109 The \Ie{appendices} environment acts like the \cmd{\appendix}\index{appendix}
8110 command in that it resets the numbering and naming of chapters\index{chapter}.
8111 However, at the end of the environment, chapters are restored to their original
8112 condition and any chapter numbers continue in sequence as though the
8113 \Ie{appendices} environment had never been there.
8114
8115 \LMnote{2010/11/18}{Wrong names for \cs{namedsubappendices} and
8116 \cs{unnamedsubappendices} fixed}
8117 \begin{syntax}
8118 \senv{subappendices} text \eenv{subappendices} \\
8119 \cmd{\namedsubappendices} \cmd{\unnamedsubappendices} \\
8120 \end{syntax}
8121 \glossary(subappendices)%
8122 {\senv{subappendices}}%
8123 {Like the \Pe{appendices} environment but used at the end of a chapter
8124 for per-chapter sub-appendices.}
8125 \glossary(namedsubappendices)%
8126 {\cs{namedsubappendices}}%
8127 {Precede sub-appendix numbers with the name \cs{appendixname}.}
8128 \glossary(unnamedsubappendices)%
8129 {\cs{unnamedsubappendices}}%
8130 {Do not precede the sub-appendix number with any name (the default).}
8131 The \Ie{subappendices}\index{appendix!subappendix} environment can be used to put appendices\index{appendix} at the end
8132 of a chapter\index{chapter}. Within the environment \cmd{\section} starts a
8133 new sub-appendix\index{appendix}. You may put \cmd{\addappheadtotoc} at the start
8134 of the environment if you want a heading entry in the \toc.
8135 If you put the declaration \cmd{\namedsubappendices}
8136 \emph{before} the \Ie{subappendices} environment, the sub-appendix number
8137 in the body of the document will be preceded by the value of
8138 \cmd{\appendixname}. The \cmd{\unnamedsubappendices} declaration, which is the
8139 default, may be used to switch off this behaviour.
8140
8141 \LMnote{2010/11/19}{Added this caveat, following a question on ctt}
8142 \begin{caveat}
8143 The implementation of the named subappendices make use of
8144 \cmd{\setsecnumformat}, thus if you have used this command to change
8145 the formating of the section number you will need to re-do this in a
8146 special manner inside the \Ie{subappendices} environemt. Something
8147 like this (where a user wanted to use old style numerials for
8148 sectioning numbers)
8149 \begin{verbatim}
8150 \begin{subappendices}
8151 \setsecnumformat{\sectionname\
8152 \oldstylenums{\csname the#1\endcsname\quad}}
8153 \end{verbatim}
8154 The macro \cmd{sectionname} is a special macro that only lives inside
8155 the \Ie{subappendices} environment and is only available when
8156 \cmd{\namedsubappendices} is applied.
8157 \end{caveat}
8158
8159
8160 \section{Numbering} \label{sec:secnumbers}
8161
8162 Each type of sectional division\index{division!sectional} has an
8163 associated \emph{level}\index{sectional division!level number} as shown
8164 in \tref{tab:seclevels}.
8165 Divisions are numbered if the value of the \Icn{secnumdepth} counter
8166 is equal to or greater than their level. For example, with
8167 \begin{lcode}
8168 \setcounter{secnumdepth}{2}
8169 \end{lcode}
8170 then subsections up to book\index{book!number} will be numbered.
8171
8172 \begin{table}
8173 \centering
8174 \caption{Division levels} \label{tab:seclevels}
8175 \begin{tabular}{lr} \toprule
8176 Division & Level \\ \midrule
8177 \cmd{\book} & -2 \\
8178 \cmd{\part} & -1 \\
8179 \cmd{\chapter} & 0 \\
8180 \cmd{\section} & 1 \\
8181 \cmd{\subsection} & 2 \\
8182 \cmd{\subsubsection} & 3 \\
8183 \cmd{\paragraph} & 4 \\
8184 \cmd{\subparagraph} & 5 \\ \bottomrule
8185 \end{tabular}
8186 \end{table}
8187
8188 \begin{syntax}
8189 \cmd{\setsecnumdepth}\marg{secname} \\
8190 \cmd{\maxsecnumdepth}\marg{secname} \\
8191 \end{syntax}
8192 \glossary(setsecnumdepth)%
8193 {\cs{setsecnumdepth}\marg{secname}}%
8194 {Sets division numbering level to \meta{secname}.}
8195 \glossary(maxscnumdepth)%
8196 {\cs{maxsecnumdepth}\marg{secname}}%
8197 {Sets division numbering level in the \cs{mainmatter} to \meta{secname}.}
8198 Instead of having to remember the levels if you want to change what
8199 gets numbered you can use the \cmd{\setsecnumdepth} command. It
8200 sets \Icn{secnumdepth} so that divisions \meta{secname} and above
8201 will be numbered. The argument \meta{secname} is the name of a sectional
8202 division without the backslash. For example, to have subsections
8203 and above numbered:
8204 \begin{lcode}
8205 \setsecnumdepth{subsection}
8206 \end{lcode}
8207 You can also use \texttt{all} or \texttt{none} for \meta{secname} which
8208 will either turn on numbering for all levels, or turn off numbering
8209 altogether.
8210
8211 When used in the preamble\index{preamble} \cmd{\setsecnumdepth} also
8212 calls \cmd{\maxsecnumdepth}, which is the numbering level used once
8213 \cmd{\mainmatter} is called. You can use \cmd{\setsecnumdepth} anywhere
8214 in the \cmd{\mainmatter} to (temporarily) change the numbering level.
8215
8216 By default, the class sets:
8217 \begin{lcode}
8218 \setsecnumdepth{section}
8219 \maxsecnumdepth{section}
8220 \end{lcode}
8221 The \cmd{\frontmatter} commands sets the numbering level to \texttt{none}.
8222 The commands \cmd{\mainmatter} and \cmd{\mainmatter*} set the
8223 numbering level to the value specified by \cmd{\maxsecnumdepth}.
8224
8225 \begin{hint}
8226 One will often set \cmd{\setsecnumdepth} in the preamble and then
8227 wonder why it didn't do anything. That is probably because of
8228 \cmd{\frontmatter} and \cmd{mainmatter}, so make it a habit of
8229 setting them both like above.
8230 \end{hint}
8231
8232
8233
8234 The number setting commands come from the \Lpack{tocvsec2}
8235 package~\cite{TOCVSEC2}.
8236
8237 \section{Book and part headings}
8238
8239 \index{heading!book|(}
8240 \index{heading!part|(}
8241
8242 Book and part headings \emph{always} start on a new page with the
8243 \pstyle{book} and \pstyle{part} pagestyles, respectively. The typical
8244 book and part heading consists of the name (e.g., `Book' or `Part')
8245 followed by a number represented as an uppercase Roman numeral. There is
8246 a vertical space after which the title is printed. Finally a new page is
8247 started.
8248
8249 \PWnote{2009/07/30}{Updated description, etc., for Part and Book pages}
8250 Several aspects of the typesetting of the \cmd{\book} and \cmd{\part}
8251 title are configurable. Ignoring details, such as the optional argument,
8252 the code for printing \cmd{\part} headings looks like this:
8253 \begin{lcode}
8254 \newcommand{\part}[1]{% % THIS IS A VERY SIMPLIFIED VERSION
8255 \cleardoublepage % start a new recto page
8256 \thispagestyle{part} % set the page style
8257 \beforepartskip % space before Name and Number
8258 \printpartname\partnamenum\printpartnum
8259 \midpartskip % space after Name and Number
8260 \printparttitle{#1} % print the title
8261 \partpageend} % finish off
8262 \newcommand{\partpageend}{% THIS IS SIMPLIFIED
8263 \afterpartskip
8264 % ifblankpage then blank next page and restore twocolumn if necessary
8265 }
8266 \end{lcode}
8267 The code for \cmd{\book} headings is similar.
8268
8269 The general layout for \cmd{\book}, \cmd{\part} and \cmd{\chapter} headings
8270 is similar and you may wish to refer to \fref{lay:chap} which, although
8271 it shows the vertical layout for a \cmd{chapter} head, is also applicable
8272 to \cmd{\book} and \cmd{\part} heads with appropriate changes in the
8273 names of the commands.
8274
8275
8276 \begin{syntax}
8277 \cmd{\beforebookskip} \cmd{\afterbookskip} \\
8278 \cmd{\beforepartskip} \cmd{\afterpartskip} \\
8279 \end{syntax}
8280 \glossary(beforebookskip)%
8281 {\cs{beforebookskip}}%
8282 {Spacing above a \cs{book} title.}
8283 \glossary(afterbookskip)%
8284 {\cs{afterbookskip}}%
8285 {Spacing below a \cs{book} title.}
8286 \glossary(beforepartskip)%
8287 {\cs{beforepartskip}}%
8288 {Spacing above a \cs{part} title.}
8289 \glossary(afterpartskip)%
8290 {\cs{afterbookskip}}%
8291 {Spacing below a \cs{part} title.}
8292 These commands effectively control the spacing before and after the book
8293 and part titles. Their default definitions are:
8294 \begin{lcode}
8295 \newcommand*{\beforebookskip}{\null\vfil}
8296 \newcommand*{\afterbookskip}{\vfil\newpage}
8297 \newcommand*{\beforepartskip}{\null\vfil}
8298 \newcommand*{\afterpartskip}{\vfil\newpage}
8299 \end{lcode}
8300 Together, these vertically center any typesetting on the page, and then start
8301 a new page. To move the \cs{part} title upwards on the page, for example,
8302 you could do:
8303 \begin{lcode}
8304 \renewcommand*{\beforepartskip}{\null\vskip 0pt plus 0.3fil}
8305 \renewcommand*{\afterpartskip}{\vskip 0pt plus 0.7fil \newpage}
8306 \end{lcode}
8307
8308 \begin{syntax}
8309 \cmd{\midbookskip} \\
8310 \cmd{\midpartskip} \\
8311 \end{syntax}
8312 \glossary(midbookskip)%
8313 {\cs{midbookskip}}%
8314 {Spacing between a \cs{book}'s number line and the title.}
8315 \glossary(midpartskip)%
8316 {\cs{midpartskip}}%
8317 {Spacing between a \cs{part}'s number line and the title.}
8318 The macros \cmd{\midbookskip} and \cmd{\midpartskip} are the spacings
8319 between the number lines and the titles. The default definitions are:
8320 \begin{lcode}
8321 \newcommand{\midbookskip}{\par\vspace 2\onelineskip}
8322 \newcommand{\midpartskip}{\par\vspace 2\onelineskip}
8323 \end{lcode}
8324 and they can be changed.
8325
8326 \begin{syntax}
8327 \cmd{\printbookname} \cmd{\booknamefont} \\
8328 \cmd{\booknamenum} \\
8329 \cmd{\printbooknum} \cmd{\booknumfont} \\
8330 \cmd{\printpartname} \cmd{\partnamefont} \\
8331 \cmd{\partnamenum} \\
8332 \cmd{\printpartnum} \cmd{\partnumfont} \\
8333 \end{syntax}
8334 \glossary(printbookname)%
8335 {\cs{printbookname}}
8336 {Prints the book name (\cs{bookname}) using the \cs{booknamefont}.}
8337 \glossary(booknamefont)%
8338 {\cs{booknamefont}}%
8339 {Font used by \cs{printbookname} for the book name.}
8340 \glossary(booknamenum)%
8341 {\cs{booknamenum}}%
8342 {Called between printing a book name and number.}
8343 \glossary(printbooknum)%
8344 {\cs{printbooknum}}%
8345 {Prints a book number using the \cs{booknumfont}.}
8346 \glossary(booknumfont)%
8347 {\cs{booknumfont}}%
8348 {Font used by \cs{printbooknum} for the book number.}
8349
8350 \glossary(printpartname)%
8351 {\cs{printpartname}}
8352 {Prints the part name (\cs{partname}) using the \cs{partnamefont}.}
8353 \glossary(partnamefont)%
8354 {\cs{partnamefont}}%
8355 {Font used by \cs{printpartname} for the part name.}
8356 \glossary(partnamenum)%
8357 {\cs{partnamenum}}%
8358 {Called between printing a part name and number.}
8359 \glossary(printpartnum)%
8360 {\cs{printpartnum}}%
8361 {Prints a part number using the \cs{partnumfont}.}
8362 \glossary(partnumfont)%
8363 {\cs{partnumfont}}%
8364 {Font used by \cs{printpartnum} for the part number.}
8365 The macro \cmd{\printbookname} typesets the book name (the value of
8366 \cmd{\bookname}) using the font specified by \cmd{\booknamefont}.
8367 The default is the \cmd{\bfseries} font in the \cmd{\huge} size.
8368 Likewise the book number is typeset by \cmd{\printbooknum}
8369 using the font specified by \cmd{\booknumfont}, which has the same default as
8370 \cmd{\booknamefont}. The macro \cmd{\booknamenum}, which is defined to be
8371 a space, is called between printing the book name and the number. All
8372 these can be changed to obtain different effects.
8373
8374 Similarly, the macro \cmd{\printpartname} typesets the part name
8375 (the value of \cmd{\partname}) using the font specified by
8376 \cmd{\partnamefont}. The default is the \cmd{\bfseries} font in
8377 the \cmd{\huge} size. Likewise the part number is typeset by
8378 \cmd{\printpartnum} using the font specified by \cmd{\partnumfont},
8379 which has the same default as \cmd{\partnamefont}. The macro
8380 \cmd{\partnamenum}, which is defined to be a space, is called between printing
8381 the part name and the number.
8382
8383 For example, to set a \cmd{\part} in a large sans font with the part
8384 name flush left:
8385 \begin{lcode}
8386 \renewcommand{\partnamefont}{\normalfont\huge\sffamily\raggedright}
8387 \renewcommand{\partnumfont}{\normalfont\huge\sffamily}
8388 \end{lcode}
8389 or to only print the part number in the default font:
8390 \begin{lcode}
8391 \renewcommand{\printpartname}{}
8392 \renewcommand{\partnamenum}{}
8393 \end{lcode}
8394
8395
8396 \begin{syntax}
8397 \cmd{\printbooktitle}\marg{title} \cmd{\booktitlefont} \\
8398 \cmd{\printparttitle}\marg{title} \cmd{\parttitlefont} \\
8399 \end{syntax}
8400 \glossary(printbooktitle)%
8401 {\cs{printbooktitle}}%
8402 {Prints the book title using the \cs{booktitlefont}.}
8403 \glossary(booktitlefont)%
8404 {\cs{booktitlefont}}%
8405 {Font used by \cs{printbooktitle} for the title.}
8406 \glossary(printbooktitle)%
8407 {\cs{printbooktitle}}%
8408 {Prints the book title using the \cs{booktitlefont}.}
8409 \glossary(booktitlefont)%
8410 {\cs{booktitlefont}}%
8411 {Font used by \cs{printbooktitle} for the title.}
8412 \glossary(printparttitle)%
8413 {\cs{printparttitle}}%
8414 {Prints the part title using the \cs{parttitlefont}.}
8415 \glossary(parttitlefont)%
8416 {\cs{parttitlefont}}%
8417 {Font used by \cs{printparttitle} for the title.}
8418 A book's title is typeset by \cmd{\printbooktitle} using the font specified
8419 by \cmd{\booktitlefont}.
8420 By default this is a \cmd{\bfseries} font in the \cmd{\Huge} size. This can
8421 be changed to have, say, the title set raggedleft in a small caps font by
8422 \begin{lcode}
8423 \renewcommand{\booktitlefont}{\normalfont\Huge\scshape\raggedleft}
8424 \end{lcode}
8425
8426 Similarly a part's title is typeset by \cmd{\printparttitle} using
8427 the font specified by \cmd{\parttitlefont}.
8428 By default this is a \cmd{\bfseries} font in the \cmd{\Huge} size.
8429
8430 The \cmd{\parttitlefont} font is also used by
8431 \cmd{\appendixpage}, or its starred version, when
8432 typesetting an appendix\index{appendix} page.
8433
8434 \begin{syntax}
8435 \cmd{\bookpagemark}\marg{title} \\
8436 \cmd{\partmark}\marg{title} \\
8437 \end{syntax}
8438 \glossary(bookpagemark)%
8439 {\cs{bookpagemark}\marg{title}}%
8440 {For setting any marks with the title from a \cs{book} for a running header.}
8441 \glossary(partmark)%
8442 {\cs{partmark}\marg{title}}%
8443 {For setting any marks with the title from a \cs{part} for a running header.}
8444 The \cmd{\book} code includes \cmd{\bookpagemark}\marg{title} for capturing
8445 the \meta{title} of the book division if it is going to be used,
8446 for example, in page headers. Its definition is simply:
8447 \begin{lcode}
8448 \newcommand*{\bookpagemark}[1]{}
8449 \end{lcode}
8450 There is the corresponding \cmd{\partmark} for the title of \cmd{\part}
8451 divisions.
8452
8453 \begin{syntax}
8454 \cmd{\bookpageend} \cmd{\bookblankpage} \cmd{\nobookblankpage} \\
8455 \cmd{\partpageend} \cmd{\partblankpage} \cmd{\nopartblankpage} \\
8456 \end{syntax}
8457 \glossary(bookpageend)%
8458 {\cs{bookpageend}}%
8459 {Code to finish off typesetting a book title page.}
8460 \glossary(bookblankpage)%
8461 {\cs{bookblankpage}}%
8462 {Follow a book title page with a blank page (the default).}
8463 \glossary(nobookblankpage)%
8464 {\cs{nobookblankpage}}%
8465 {Do not follow a book title page with a blank page.}
8466 \glossary(partpageend)%
8467 {\cs{partpageend}}%
8468 {Code to finish off typesetting a part title page.}
8469 \glossary(partlankpage)%
8470 {\cs{partblankpage}}%
8471 {Follow a part title page with a blank page (the default).}
8472 \glossary(nopartblankpage)%
8473 {\cs{nopartblankpage}}%
8474 {Do not follow a part title page with a blank page.}
8475
8476 The macro \cmd{\bookpageend} finishes off a book title page. It first
8477 calls \cmd{\afterbookskip}. If the \cmd{\nobookblankpage} is in effect
8478 it does nothing more. If the declaration \cmd{\bookblankpage} (the default)
8479 is in effect then it finishes the current page, outputs a blank page and then,
8480 if twocolumn typesetting was in effect before \cmd{\book} then it restores
8481 twocolumn typesetting. The macro \cmd{\partpageend} performs similar
8482 functions for \cmd{\part} pages.
8483
8484 \LMnote{2011/02/06}{This now uncommented text is wrong!}
8485 % If, for example, you wish to put something on a \cmd{\part} page, and maybe
8486 % something on the following normally blank page, then this is a possible way
8487 % of doing it:\index{text on a part page}
8488 So to add something on the back side of a \cmd{\part} page (assuming
8489 twoside) use something similar to
8490 \begin{lcode}
8491 ...
8492 \nopartblankpage
8493 \part{Title of the Part}
8494 \thispagestyle{simple}
8495 Text on the following (normally blank page)
8496 \clearpage
8497 ...
8498 \end{lcode}
8499 Alternatively you can redefine \cmd{\partpageend}.
8500
8501 If you use the declaration \cmd{\nopartblankpage} (or \cmd{\nobookblankpage})
8502 then you are responsible for setting everything correctly to end off the
8503 \cmd{\part} (or \cmd{\book}) page. This is the default definition of
8504 \cmd{\partpageend} (that for \cmd{\bookpageend} is similar):
8505 \begin{lcode}
8506 \newcommand{\partpageend}{%
8507 \afterpartskip
8508 \ifm@mnopartnewpage% set by \(no)partblankpage
8509 \else% default finish off
8510 \if@twoside
8511 \if@openright% output blank page
8512 \null
8513 \thispagestyle{afterpart}%
8514 \newpage
8515 \fi
8516 \fi
8517 \fi
8518 \if@tempswa% true if twocolumn was being used
8519 \twocolumn
8520 \fi}
8521 \end{lcode}
8522 Here with the default definitions, \cmd{\afterpartskip} ends off the
8523 \cmd{\part} page, and then the rest of the code in \cmd{\partpageend}
8524 takes care of typesetting the blank back side of the \cmd{\part} page
8525 (or send us back to twocolumn mode).
8526
8527 \LMnote{2011/02/06}{Added the example below}
8528 If on the other hand we actually want to write something below the
8529 part title on the \cmd{\part} page, then we need a different
8530 route. The `air' above and below the part title is by default defined as
8531 \begin{lcode}
8532 \newcommand*{\beforepartskip}{\null\vfil}
8533 \newcommand*{\afterpartskip}{\vfil\newpage}
8534 \end{lcode}
8535 Thus we need to redefined this such that it does not change the page
8536 and such that it add useful spacing above and below the part
8537 titling. Something like this may do the trick
8538 \begin{lcode}
8539 \makeatletter
8540 \newcommand*{\beforepartskip}{\null\vskip4cm}
8541 \newcommand*{\afterpartskip}{\par\vskip1cm%
8542 \@afterindentfalse\@afterheading}
8543 \makeatother
8544 \end{lcode}
8545
8546
8547
8548 \index{heading!part|)}
8549 \index{heading!book|)}
8550
8551 \subsection{Leadpage}
8552
8553 \begin{syntax}
8554 \cmd{\newleadpage}\oarg{page-style}\marg{cmdname}\marg{title} \\
8555 %\cmd{\newleadpage*}\oarg{page-style}\marg{cmdname}\marg{title} \\
8556 \cmd{\renewleadpage}\oarg{page-style}\marg{cmdname}\marg{title} \\
8557 %\cmd{\renewleadpage*}\oarg{page-style}\marg{cmdname}\marg{title} \\
8558 \end{syntax}
8559 \glossary(newleadpage)%
8560 {\cs{newleadpage}\oarg{page-style}\marg{cmdname}\marg{title}}%
8561 {Creates a macro to that when used will generate a sort of title
8562 page. Very similar to \cs{appendixpage}.}
8563 \glossary(renewleadpage)%
8564 {\cs{renewleadpage}\oarg{page-style}\marg{cmdname}\marg{title}}%
8565 {Redefines an existing new lead page macro.}
8566 The \cmd{\newleadpage}\footnote{The suggestions for this came from
8567 Danie Els\index{Els, Danie} and Lars Madsen\index{Madsen, Lars}.}
8568 command defines a macro \verb?\cmdname? that when called
8569 will typeset an Appendixpage-like page (see \Sref{sec:appendices}) with a
8570 title \meta{title} using the \meta{page-style} as the pagestyle for
8571 the page. The default is the \pstyle{empty} pagestyle. The macro
8572 \cmd{\renewleadpage} redefines an existing leadpage command.
8573 \cmd{\cmdname} will add an entry to the TOC, the similarly defined
8574 \cmd{\cmdname*} will not.
8575
8576
8577 As an example:
8578 \begin{lcode}
8579 \newleadpage{plates}{Picture Gallery}
8580 \end{lcode}
8581 creates the new command \cs{plates} which when called generates an unnumbered
8582 part-like page with the title \textbf{Picture Gallery}.
8583
8584 \begin{syntax}
8585 \cmd{\leadpagetoclevel} \\
8586 \end{syntax}
8587 \glossary(leadpagetoclevel)%
8588 {\cs{leadpagetoclevel}}%
8589 {Holds the default toc level for \cs{newleadpage} generated macros,
8590 default is \texttt{chapter}.}
8591 When \cs{(re)newleadpage} is used the resulting command adds \meta{title}
8592 to the \toc\ as though it was an unnumbered \cmd{\leadpagetoclevel} entry,
8593 whose definition is
8594 \begin{lcode}
8595 \newcommand*{\leadpagetoclevel}{chapter}
8596 \end{lcode}
8597 If you wished them to be entered like a \cmd{\part} header then simply:
8598 \begin{lcode}
8599 \renewcommand*{\leadpagetoclevel}{part}
8600 \end{lcode}
8601
8602
8603 The layout of the page matches that for unnumbered \cmd{\part} pages, and
8604 internally the resulting commands use \cmd{\partmark} in case you
8605 wish to capture the \meta{title} to use in running headers.
8606
8607
8608
8609 \section{Chapter headings}
8610 \label{sec:chapter-headings}
8611 \index{heading!chapter|(} %| emacs
8612
8613 The chapter headings are configurable in much the same way as book or part
8614 headings, but in addition there are some built in chapter styles that you may
8615 wish to try, or define your own.
8616
8617 Chapters, except when the \Lopt{article} class option is used,
8618 \emph{always} start on a new page with the \pstyle{chapter}
8619 pagestyle. The particular page, recto or verso, that they start on is
8620 mainly controlled by the class options. If the \Lopt{oneside} option is used
8621 they start on the next new page, but if the \Lopt{twoside} option is
8622 used the starting page may differ, as follows.
8623 \begin{itemize}
8624 \item[\Lopt{openright}] The chapter heading is typeset on the next recto page,
8625 which may leave a blank verso leaf.
8626 \item[\Lopt{openleft}] The chapter heading is typeset on the next verso page,
8627 which may leave a blank recto leaf.
8628 \item[\Lopt{openany}] The chapter heading is typeset on the next page and there
8629 will be no blank leaf.
8630 \end{itemize}
8631
8632 \begin{syntax}
8633 \cmd{\openright} \cmd{\openleft} \cmd{\openany} \\
8634 \end{syntax}
8635 \glossary(openright)%
8636 {\cs{openright}}%
8637 {Force chapters to start on a new recto page.}
8638 \glossary(openleft)%
8639 {\cs{openleft}}%
8640 {Force chapters to start on a new verso page.}
8641 \glossary(openany)%
8642 {\cs{openany}}%
8643 {Allow chapters to start on the next new page.}
8644 These three declarations have the same effect as the options of the same name.
8645 They can be used anywhere in the document to change the chapter opening page.
8646
8647 Ignoring many details, like the optional arguments, the code for
8648 printing a \cmd{\chapter} heading is similar to that for \cmd{\book}
8649 and \cmd{\part} (the \cs{chapterhead} command below is \emph{not}
8650 part of the class).
8651 \begin{lcode}
8652 \newcommand{\chapterhead}[1]{ % THIS IS A SIMPLIFIED VERSION
8653 \clearforchapter % move to correct page
8654 \thispagestyle{chapter} % set the page style
8655 \insertchapterspace % Inserts space into LoF and LoT
8656 \chapterheadstart % \beforechapskip space before heading
8657 \printchaptername\chapternamenum\printchapternum
8658 \afterchapternum % \midchapskip space between number and title
8659 \printchaptertitle{#1} % title
8660 \afterchaptertitle} % \afterchapskip space after title
8661 \end{lcode}
8662 The general layout is shown in \fref{lay:chap}.
8663
8664 \begin{figure}
8665 \setlayoutscale{1}
8666 \centering
8667 \chapterdiagram
8668 \caption{Class layout parameters for chapter titles. Working with
8669 \cs{beforechapskip} need a little thought, see the text.}
8670 \label{lay:chap}
8671 \end{figure}
8672
8673 \begin{syntax}
8674 \cmd{\clearforchapter} \\
8675 \end{syntax}
8676 \glossary(clearforchapter)%
8677 {\cs{clearforchapter}}%
8678 {Selects a chapter's opening page.}
8679 The actual macro that sets the opening page for a chapter is
8680 \cmd{\clearforchapter}. The class options \texttt{openright},
8681 \texttt{openleft} and \texttt{openany} (or their macro equivalents
8682 \cmd{\openright}, \cmd{\openleft} and
8683 \cmd{\openany}) define \cmd{\clearforchapter} to be respectively
8684 (see \S\ref{sec:moving})
8685 \cmd{\cleartorecto}, \cmd{\cleartoverso} and \cmd{\clearpage}. You can
8686 obviously change \cmd{\clearforchapter} to do more than just start a
8687 new page.
8688
8689 \begin{syntax}
8690 \cmd{\memendofchapterhook}
8691 \end{syntax}
8692 \glossary(memendofchapterhook)%
8693 {\cs{memendofchapterhook}}%
8694 {Hook executed at the very end of the \cs{chapter} command.}
8695 Where \cmd{\clearforchapter} comes at the very beginning,
8696 \cmd{\memendofchapterhook} comes at the very end of the \cmd{\chapter}
8697 command. It does nothing by default, but could be redefined to insert,
8698 say, \cmd{\clearpage}:
8699 \begin{verbatim}
8700 \makeatletter
8701 \renewcommand\memendofchapterhook{%
8702 \clearpage\m@mindentafterchapter\@afterheading}
8703 \makeatother
8704 \end{verbatim}
8705
8706
8707 Some books have the chapter headings on a verso page, with perhaps
8708 an illustration\index{illustration} or epigraph\index{epigraph}, and
8709 then the text starts on the opposite
8710 recto page. The effect can be achieved like:
8711 \begin{lcode}
8712 \openleft % chapter title on verso page
8713 \chapter{The title} % chapter title
8714 \begin{centering} % include a centered illustration
8715 \includegraphics{...}
8716 \end{centering}
8717 \clearpage % go to recto page
8718 Start of the text % chapter body
8719 \end{lcode}
8720
8721
8722 \begin{syntax}
8723 \cmd{\chapterheadstart} \lnc{\beforechapskip} \\
8724 \cmd{\afterchapternum} \lnc{\midchapskip} \\
8725 \cmd{\afterchaptertitle} \lnc{\afterchapskip} \\
8726 \end{syntax}
8727 \glossary(chapterheadstart)%
8728 {\cs{chapterheadstart}}%
8729 {Called at start of printing a chapter header; by default inserts \cs{beforechapskip} space.}
8730 \glossary(beforechapskip)%
8731 {\cs{beforechapskip}}%
8732 {Space above chapter name and number.}
8733 \glossary(afterchapternum)%
8734 {\cs{afterchapternum}}%
8735 {Called after printing a chapter number; by default inserts \cs{midchapskip} space.}
8736 \glossary(midchapskip)%
8737 {\cs{midchapskip}}%
8738 {Space between chapter name and number and the title.}
8739 \glossary(afterchaptertitle)%
8740 {\cs{afterchaptertitle}}%
8741 {Called after printing a chapter title; by default inserts \cs{afterchapskip} space.}
8742 \glossary(afterchapskip)%
8743 {\cs{afterchapskip}}%
8744 {Space after chapter title.}
8745
8746 The macro \cmd{\chapterheadstart} is called just before printing a chapter
8747 name and number. By default it inserts \lnc{\beforechapskip} space (default
8748 50pt).
8749
8750 The macro \cmd{\afterchapternum} is called just after printing a chapter
8751 number. By default it inserts \lnc{\midchapskip} space (default
8752 20pt).
8753
8754 The macro \cmd{\afterchaptertitle} is called just after printing a chapter
8755 title. By default it inserts \lnc{\afterchapskip} space (default
8756 40pt).
8757
8758 The lengths \lnc{\beforechapskip}, \lnc{\midchapskip} and \lnc{\afterchapskip}
8759 can all be changed by \cmd{\setlength} or \cmd{\addtolength}. Though
8760 as mentioned in \fref{lay:chap} they need some explanation:
8761 \begingroup
8762 \medskip
8763 \setlength\overfullrule{5pt}
8764 \setlength\unitlength{\textwidth}
8765 \addtolength\unitlength{-\labelsep}
8766 \renewcommand\descriptionlabel[1]{\hspace\labelsep\parbox{\unitlength}{\cs{#1}}}
8767 \begin{description}
8768 \item[beforechapskip] See \fref{lay:chap}. The actual distance
8769 between the first baseline of the chapter stuff to the top of the
8770 text block is
8771 \cmd{\beforechapskip}\,+\,\cmd{\topskip}\,+\,\cmd{\baselineskip}.
8772 But because the implementation of \cmd{\chapter} (via
8773 \cmd{\chapterheadstart}) make use of \cmd{\vspace*}, getting rid of
8774 \cmd{\beforechapskip} a strange endeavour. If you want to avoid any
8775 space before the first text in the chapter heading, use
8776 \begin{lcode}
8777 \setlength\beforechapskip{-\baselineskip}
8778 \end{lcode}
8779 or redefine \cmd{\chapterheadstart} to do nothing.
8780 \item[midchapskip]
8781 \item[afterchapskip]
8782 for both, one has to add \cmd{\baselineskip} to
8783 get the distance baseline to baseline.
8784 \end{description}
8785 \endgroup
8786
8787
8788
8789
8790
8791 \begin{syntax}
8792 \cmd{\printchaptername} \cmd{\chapnamefont} \\
8793 \cmd{\chapternamenum} \\
8794 \cmd{\printchapternum} \cmd{\chapnumfont} \\
8795 \end{syntax}
8796 \glossary(printchaptername)%
8797 {\cs{printchaptername}}%
8798 {Prints the chapter name using the \cs{chapnamefont}.}
8799 \glossary(chapnamefont)%
8800 {\cs{chapnamefont}}%
8801 {Font used by \cs{printchaptername}.}
8802 \glossary(chapternamenum)%
8803 {\cs{chapternamenum}}%
8804 {Inserted between printing the chapter name and number.
8805 It is usually a space.}
8806 \glossary(printchapternum)%
8807 {\cs{printchapternum}}%
8808 {Prints the chapter number using the \cs{chapnumfont}.}
8809 \glossary(chapnumfont)%
8810 {\cs{chapnumfont}}%
8811 {Font used by \cs{printchapternum}.}
8812 The macro \cmd{\printchaptername} typesets the chapter name
8813 (default \texttt{Chapter} or \texttt{Appendix}) using the font
8814 specified by \cmd{\chapnamefont}. The default is the \cmd{\bfseries} font in
8815 the \cmd{\huge} size. Likewise the chapter number is typeset by
8816 \cmd{\printchapternum} using the font specified by \cmd{\chapnumfont},
8817 which has the same default as \cmd{\chapnamefont}. The macro
8818 \cmd{\chapternamenum}, which is defined to be a space, is called between
8819 printing the chapter name and the number.
8820
8821 \begin{syntax}
8822 \cmd{\printchaptertitle}\marg{title} \cmd{\chaptitlefont} \\
8823 \end{syntax}
8824 \glossary(printchaptertitle)%
8825 {\cs{printchaptertitle}\marg{title}}%
8826 {Prints the chapter \meta{title} using the \cs{chaptitlefont}.}
8827 \glossary(chaptitlefont)%
8828 {\cs{chaptitlefont}}%
8829 {Font used by \cs{printchaptertitle}.}
8830 The title is typeset by \cmd{\printchaptertitle} using the font specified
8831 by \cmd{\chaptitlefont}.
8832 By default this is a \cmd{\bfseries} font in the \cmd{\Huge} size.
8833
8834 \begin{syntax}
8835 \cmd{\printchapternonum} \\
8836 \end{syntax}
8837 \glossary(printchapternonum)%
8838 {\cs{printchapternonum}}%
8839 {Replaces printing the chapter name and number in unnumbered chapters.}
8840 If a chapter is unnumbered, perhaps because it is in the \cmd{\frontmatter}
8841 or because \cmd{\chapter*} is used, then when printing the command
8842 \cmd{\printchapternonum} is called instead of printing the name and number,
8843 as illustrated below:
8844 \begin{lcode}
8845 \newcommand{\chapterhead}[1]{ % THIS IS A SIMPLIFIED VERSION
8846 \clearforchapter % move to correct page
8847 \thispagestyle{chapter} % set the page style
8848 \insertchapterspace % Inserts space into LoF and LoT
8849 \chapterheadstart % \beforechapskip space before heading
8850 \printchaptername\chapternamenum\printchapternum
8851 \afterchapternum % \midchapskip space between number and title
8852 \printchaptertitle{#1} % title
8853 \afterchaptertitle} % \afterchapskip space after title
8854 \end{lcode}
8855 %
8856 %
8857 %
8858 \LMnote{2010/07/16}{added}
8859 By default the first paragraph following a \cs{chapter} is \emph{not}
8860 indented, this can be controlled by
8861 \begin{syntax}
8862 \cmd{\indentafterchapter}\\
8863 \cmd{\noindentafterchapter}
8864 \end{syntax}
8865 \glossary(indentafterchapter)%
8866 {\cs{indentafterchapter}}%
8867 {Specifies that the first paragraph after a \cs{chapter} should be indented}
8868 \glossary(noindentafterchapter)%
8869 {\cs{noindentafterchapter}}%
8870 {Specifies that the first paragraph after a \cs{chapter} should \emph{not} be indented}
8871 The default is not to indent the first paragraph following a
8872 \cs{chapter}.
8873
8874 \begin{syntax}
8875 \cmd{\insertchapterspace} \\
8876 \end{syntax}
8877 \glossary(insertchapterspace)%
8878 {\cs{insertchapterspace}}%
8879 {Called by \cs{chapter} to insert space into LoF and LoT.}
8880 By default a \cmd{\chapter} inserts a small amount of vertical space
8881 into the List of Figures and List of Tables. It calls \cmd{\insertchapterspace}
8882 to do this. The default definition is:
8883 \begin{lcode}
8884 \newcommand{\insertchapterspace}{%
8885 \addtocontents{lof}{\protect\addvspace{10pt}}%
8886 \addtocontents{lot}{\protect\addvspace{10pt}}%
8887 }
8888 \end{lcode}
8889 If you would prefer no inserted spaces then
8890 \begin{lcode}
8891 \renewcommand{\insertchapterspace}{}
8892 \end{lcode}
8893 will do the job.
8894 Different spacing can be inserted by
8895 changing the value of the length arguments to \cmd{\addvspace}.
8896
8897 By making suitable changes to the above macros you can make some
8898 simple modifications to the layout.
8899
8900 \index{heading!chapter|)}
8901
8902 \subsection{Defining a chapter style} \label{sec:chapterstyle}
8903
8904 \index{chapterstyle|(}
8905
8906 The class provides many ways in which you can implement your designs
8907 for chapter headings.
8908
8909 \begin{syntax}
8910 \cmd{\chapterstyle}\marg{style} \\
8911 \end{syntax}
8912 \glossary(chapterstyle)%
8913 {\cs{chapterstyle}\marg{style}}%
8914 {Sets chapter heading layout to \meta{style}.}
8915 The macro \cmd{\chapterstyle} is rather like the \cmd{\pagestyle} command in
8916 that it sets the style of any subsequent chapter headings to be \meta{style}.
8917
8918 The class provides some predefined chapter styles, including the
8919 \cstyle{default} style which is the familiar LaTeX \Lclass{book} class chapter
8920 headings style. To use the chapterstyle \cstyle{fred} just issue the command
8921 \begin{lcode}
8922 \chapterstyle{fred}
8923 \end{lcode}
8924 Different styles can be used in the same document.
8925
8926 The simpler predefined styles include:
8927 \LMnote{2011/05/25}{I've moved the chapter style images to the
8928 showcase appendix to save some space in the main part of the manual}
8929 \begin{itemize}
8930 \item[\cstyle{default}]
8931 \glossary(defaultcs)%
8932 {\Pcstyle{default}}%
8933 {The default \Ppack{book} class chapterstyle.}
8934 The normal \ltx\ \Lclass{book} class chapter styling; shown in \fref{dcdefault}.
8935 %\begin{demochap}[-3\onelineskip]{default}\end{demochap}
8936
8937 \item[\cstyle{section}]
8938 \glossary(sectioncs)%
8939 {\Pcstyle{section}}%
8940 {Simple chapterstyle looking like a section head.}
8941 The heading is typeset like a section; that is,
8942 there is just the number and the title on one line. This is illustrated
8943 in \fref{dcsection}.
8944 %% See \Cref{chap:topsandtails} on \pref{chap:topsandtails} for an example.
8945 %\begin{demochap}[2\onelineskip]{section}\end{demochap}
8946
8947 \item[\cstyle{hangnum}]
8948 \glossary(hangnumcs)%
8949 {\Pcstyle{hangnum}}%
8950 {Simple chapterstyle looking like a section head but with the number in the margin.}
8951 Like the \pstyle{section} style except that the chapter
8952 number is put in the margin\index{margin!left}, as shown in \fref{dchangnum}.
8953 %% See \Cref{chap:captions} on \pref{chap:captions} for an example.
8954 %\begin{demochap}[2\onelineskip]{hangnum}\end{demochap}
8955
8956 \item[\cstyle{companion}]
8957 \glossary(companioncs)%
8958 {\Pcstyle{companion}}%
8959 {Chapterstyle like those in the \textit{LaTeX companion} series.}
8960 This produces chapter headings like those of the
8961 \textit{LaTeX Companion} series of books. An example is in \fref{dccompanion}.
8962 %% See \Cref{chap:signposts} on \pref{chap:signposts} for an example.
8963 %\begin{demochap}[2\onelineskip]{companion}\end{demochap}
8964
8965 \item[\cstyle{article}]
8966 \glossary(articlecs)%
8967 {\Pcstyle{article}}%
8968 {Chapter style similar to a section head in the \Pclass{article} class but
8969 with different
8970 sized fonts.}
8971 The heading is typeset like a \cmd{\section}
8972 heading in the \Lclass{article} class. This is similar to the
8973 \cstyle{section} style but different fonts and spacings are used,
8974 as shown in \fref{dcarticle}.
8975 %\begin{demochap}[-1\onelineskip]{article}\end{demochap}
8976
8977 \item[\cstyle{reparticle}]
8978 \glossary(reparticlecs)%
8979 {\Pcstyle{reparticle}}%
8980 {With the \Popt{article} class option it replicates a section head in
8981 the \Pclass{article} class.}
8982 When the \Lopt{article} class option is used
8983 the default chapter and section styles are close, but not
8984 identical, to the corresponding division heads in the \Lclass{article}
8985 class. The \cstyle{reparticle} chapterstyle makes \cmd{\chapter}
8986 replicate the appearance of \cmd{\section} in the \Lclass{article}
8987 class.
8988
8989 %%\item[\cstyle{demo}] Try this one to see what it does. On the other
8990 %% hand you can look at \Cref{chap:verse} on \pref{chap:verse} to see
8991 %% what it looks like.
8992 \end{itemize}
8993
8994 If you use only the predefined chapterstyles there is no need to
8995 plough through the rest of this section, except to look at the illustrations
8996 of the remaining predefined chapterstyles shown a little later.
8997
8998 The various macros shown in the \cs{chapterhead} code above are initially
8999 set up as (the code is known as the \cstyle{default} style):
9000 \begin{lcode}
9001 \newcommand{\chapterheadstart}{\vspace*{\beforechapskip}}
9002 \newcommand{\printchaptername}{\chapnamefont \@chapapp}
9003 \newcommand{\chapternamenum}{\space}
9004 \newcommand{\printchapternum}{\chapnumfont \thechapter}
9005 \newcommand{\afterchapternum}{\par\nobreak\vskip \midchapskip}
9006 \newcommand{\printchapternonum}{}
9007 \newcommand{\printchaptertitle}[1]{\chaptitlefont #1}
9008 \newcommand{\afterchaptertitle}{\par\nobreak\vskip \afterchapskip}
9009 \newcommand{\chapnamefont}{\normalfont\huge\bfseries}
9010 \newcommand{\chapnumfont}{\normalfont\huge\bfseries}
9011 \newcommand{\chaptitlefont}{\normalfont\Huge\bfseries}
9012 \setlength{\beforechapskip}{50pt}
9013 \setlength{\midchapskip}{20pt}
9014 \setlength{\afterchapskip}{40pt}
9015 \end{lcode}
9016 (The mysterious \cmd{\@chapapp} is the internal macro that \ltx\ uses
9017 to store normally the chapter name.\footnote{Remember, if you use
9018 a macro that has an \texttt{@} in its name it must be in a place
9019 where \texttt{@} is treated as a letter.} It will normally have
9020 different values,
9021 set automatically, when typesetting a chapter in the main body
9022 (e.g., \texttt{Chapter}) or in the appendices\index{appendix} where
9023 it would usually be set to \texttt{Appendix}, but you can specify
9024 these names yourself.)
9025
9026
9027
9028 A new style is specified by changing the definitions of this last set of
9029 macros and/or the various font and skip specifications.
9030
9031 \begin{syntax}
9032 \cmd{\makechapterstyle}\marg{style}\marg{text} \\
9033 \end{syntax}
9034 Chapter styles are defined via the \cmd{\makechapterstyle} command, where
9035 \meta{style} is the style being defined and \meta{text} is the LaTeX code
9036 defining the style. Please note that the \meta{text} \emph{always}
9037 start by resetting macros and lengths to the values shown above. That
9038 is what you actually get is is the same as
9039 \begin{syntax}
9040 \cmd{\makechapterstyle}\marg{style}\{\\
9041 \cmd{\chapterstyle}\{default\}\\
9042 \meta{text}\\
9043 \}
9044 \end{syntax}
9045
9046
9047
9048 To start things off, the \cstyle{default} chapter
9049 style, which mimics the chapter heads in the standard \Lclass{book} and
9050 \Lclass{report} classes, as it appears in \file{memoir.cls}:
9051 \begin{lcode}
9052 \makechapterstyle{default}{}
9053 \chapterstyle{default}
9054 \end{lcode}
9055 -- since the \cstyle{default} style \emph{is} the initial value of
9056 \cmd{\makechapterstyle}. The actual code is seen above.
9057
9058
9059
9060 As an example of setting up a simple chapterstyle, here is the code for
9061 defining the \cstyle{section} chapterstyle. In this case it is principally
9062 a question of eliminating most of the printing and zeroing some spacing.
9063 \begin{lcode}
9064 \makechapterstyle{section}{%
9065 \renewcommand*{\printchaptername}{}
9066 \renewcommand*{\chapternamenum}{}
9067 \renewcommand*{\chapnumfont}{\chaptitlefont}
9068 \renewcommand*{\printchapternum}{\chapnumfont \thechapter\space}
9069 \renewcommand*{\afterchapternum}{}
9070 }
9071 \end{lcode}
9072 In this style, \cmd{\printchaptername} is vacuous, so the normal `Chapter'
9073 is never typeset. The same font is used for the number and the title, and
9074 the number is typeset with a space after it. The macro \cmd{\afterchapternum}
9075 is vacuous, so the chapter title will be typeset immediately after the number.
9076
9077 In the standard classes the title of an unnumbered chapter is typeset
9078 at the same position on the page as the word `Chapter' for numbered chapters.
9079 The macro \cmd{\printchapternonum} is called just before an unnumbered
9080 chapter title text is typeset. By default this does nothing but you can use
9081 \cmd{\renewcommand} to change this. For example, if you wished the title
9082 text for both numbered and unnumbered chapters to be at the same height on
9083 the page then you could redefine \cmd{\printchapternonum} to insert
9084 the amount of vertical space taken by any `Chapter N' line. For example,
9085 as \cmd{\printchapternonum} is vaucuous in the \cstyle{default} chapterstyle
9086 the vertical position of a title depends on whether or not it is numbered.
9087
9088 The \cstyle{hangnum} style, which is like \cstyle{section} except that it
9089 puts the number in the margin, is defined as follows:
9090 \begin{lcode}
9091 \makechapterstyle{hangnum}{%
9092 \renewcommand*{\chapnumfont}{\chaptitlefont}
9093 % allow for 99 chapters!
9094 \settowidth{\chapindent}{\chapnumfont 999}
9095 \renewcommand*{\printchaptername}{}
9096 \renewcommand*{\chapternamenum}{}
9097 \renewcommand*{\chapnumfont}{\chaptitlefont}
9098 \renewcommand*{\printchapternum}{%
9099 \noindent\llap{\makebox[\chapindent][l]{%
9100 \chapnumfont \thechapter}}}
9101 \renewcommand*{\afterchapternum}{}
9102 }
9103 \end{lcode}
9104 The chapter number is put at the left of a box wide enough for three digits.
9105 The box is put into the margin, via \cmd{\llap}, for typesetting. The
9106 chapter title is then typeset, starting at the left margin.
9107
9108 \begin{syntax}
9109 \lnc{\chapindent} \\
9110 \end{syntax}
9111 \glossary(chapindent)%
9112 {\cs{chapindent}}%
9113 {A length you can use in a defining chapter style (or anything else).}
9114 The length \lnc{\chapindent} is provided for use in specifying chapterstyles,
9115 but you could use it for any other purposes.
9116
9117 The definition of the \cstyle{companion} chapterstyle is more complicated.
9118 \begin{lcode}
9119 \makechapterstyle{companion}{%
9120 \renewcommand*{\chapnamefont}{\normalfont\LARGE\scshape}
9121 \renewcommand*{\chapnumfont}{\normalfont\Huge}
9122 \renewcommand*{\printchaptername}{%
9123 \raggedleft\chapnamefont \@chapapp}
9124 \setlength{\chapindent}{\marginparsep}
9125 \addtolength{\chapindent}{\marginparwidth}
9126 \renewcommand{\printchaptertitle}[1]{%
9127 \begin{adjustwidth}{}{-\chapindent}
9128 \raggedleft \chaptitlefont ##1\par\nobreak
9129 \end{adjustwidth}}
9130 }
9131 \end{lcode}
9132 \PWnote{2009/09/07}{Fixed adjuswidth typo.}
9133 As shown in \fref{dccompanion} the chapter name is in small caps and set
9134 flushright. The title is also set flushright aligned with the outermost
9135 part of the marginal notes. This is achieved by use of the \Ie{adjustwidth}
9136 environment\footnote{See \S\ref{sec:adjustwidth}.} to make \ltx\ think
9137 that the typeblock is locally wider than it actually is.
9138
9139 \subsection{Further chapterstyles}
9140
9141
9142 The class provides more chapterstyles, which are listed here.
9143 Some are mine and others are from postings to \ctt\ by \Pclass{memoir}
9144 users. I have modified some of the posted ones to cater for things like
9145 appendices, multiline titles, and unnumbered chapters which were not
9146 considered in the originals. The code
9147 for some of them is given later to help you see how they are done.
9148 Separately, Lars Madsen\index{Madsen, Lars} has collected a wide variety of
9149 styles~\cite{CHAPSTYLES} and shows how they were created.
9150
9151 If you want to try several chapterstyles in one document, request the
9152 \cstyle{default} style before each of the others to ensure that a previous
9153 style's changes are not passed on to a following one.
9154
9155 \LMnote{2011/05/25}{I've moved the chapter style images to the
9156 showcase appendix to save some space in the main part of the manual}
9157
9158
9159 \newcommand\PScaveat[1]{
9160 \smallskip\noindent
9161 \textbf{Caveat:} The \Pcstyle{#1} style requires the
9162 \Lpack{graphicx} package.
9163 \smallskip
9164 }
9165
9166
9167 \begin{itemize}
9168
9169 \item[\cstyle{bianchi}]
9170 \glossary(bianchics)%
9171 {\Pcstyle{bianchi}}%
9172 {A two line, centered chapterstyle with rules above and below.}
9173 This style was created by
9174 Stefano\index{Bianchi, Stefano} Bianchi\footnote{\ctt,
9175 \textit{New chapter style: chapter vs chapter*}, 2003/12/09} and is a two
9176 line centered arrangement with rules above and below the large bold
9177 sanserif title line.
9178 The chapter number line is in a smaller italic font. An example
9179 is in \fref{dcbianchi}.
9180
9181 %\begin{demochap}[2\onelineskip]{bianchi}\end{demochap}
9182 %\begin{demochap}[-2\onelineskip]{bianchi}\end{demochap}
9183
9184 \item[\cstyle{bringhurst}] The \cstyle{bringhurst} chapterstyle described
9185 in the manual and illustrated in \fref{dcbringhurst}.
9186 \glossary(bringhurstcs)%
9187 {\Pcstyle{bringhurst}}%
9188 {A raggedright, unnumbered, small caps chapterstyle with a textwidth
9189 rule below.}
9190
9191 %\begin{demochap}{bringhurst}\end{demochap}
9192
9193
9194 \item[\cstyle{brotherton}]
9195 \glossary(brothertoncs)%
9196 {\Pcstyle{brotherton}}%
9197 {A chapterstyle like the default but with the number spelled out.}%
9198 A very simple style designed by
9199 William\index{Adams, William} Adams\footnote{\ctt,
9200 \textit{An example of a novel?}, 2006/12/09} for the science fiction novel
9201 \textit{Star Dragon} by Mike Brotherton. The novel is freely downloadable
9202 from Brotherton's web site. The style is the same as the \cstyle{default}
9203 except that the number is spelt out in words. It is demonstrated in
9204 \fref{dcbrotherton}. In the novel the chapters are actually
9205 untitled i.e., via \verb?\chapter{}?.
9206
9207 %\begin{demochap}[2\onelineskip]{brotherton}\end{demochap}
9208 %\begin{demochap}[-2\onelineskip]{brotherton}\end{demochap}
9209
9210
9211 \item[\cstyle{chappell}]
9212 \glossary(chappellcs)%
9213 {\Pcstyle{chappell}}%
9214 { A centered chapterstyle with a rule between
9215 the number line (in a roman font) and the title line in italics.}
9216 The name and number are centered above a rule and the
9217 title in italics is below, again centered. It is illustrated in
9218 \fref{dcchappell}.
9219
9220 %\begin{demochap}{chappell}\end{demochap}
9221
9222 \item[\cstyle{crosshead}]
9223 \glossary(crossheadcs)%
9224 {\Pcstyle{crosshead}}%
9225 { A centered chapterstyle in a bold font.}
9226 The number and title are centered and set with a large bold font.
9227 It is illustrated in
9228 \fref{dccrosshead}.
9229
9230 %\begin{demochap}[-2\onelineskip]{crosshead}\end{demochap}
9231
9232
9233 \item[\cstyle{culver}]
9234 \glossary(culvercs)%
9235 {\Pcstyle{culver}}%
9236 {One line, centered, bold chapterstyle using Roman numerals.}
9237 A chapter style I created for
9238 Christopher\index{Culver, Christopher}
9239 Culver\footnote{\ctt, \textit{"Biblical" formatting, how?}, 2004/03/29}
9240 based on the format of `ancient' texts.
9241 It is one line, centered, bold and with the number printed as Roman numerals,
9242 as shown in \fref{dcculver}.
9243
9244 % \begin{comment}
9245 % \makechapterstyle{culver}{
9246 % \chapterstyle{default}
9247 % \chapterstyle{article}
9248 % \renewcommand*{\thechapter}{\Roman{chapter}}
9249 % \renewcommand*{\printchapternum}{% center number/title
9250 % \centering\chapnumfont \thechapter\space\space}%
9251 % \renewcommand*{\printchapternonum}{\centering}
9252 % \renewcommand*{\clearforchapter}{}% no new page
9253 % \aliaspagestyle{chapter}{headings}% no special pagestyle
9254 % }
9255 % \end{comment}
9256
9257 %\begin{demochap}[-\onelineskip]{culver}\end{demochap}
9258
9259 He also wanted sections to just start with the number and the text to
9260 immediately follow on the same line. That can be accomplished like this:
9261 \begin{lcode}
9262 \renewcommand*{\thesection}{\arabic{section}}
9263 \renewcommand*{\section}[1]{%
9264 \refstepcounter{section}%
9265 \par\noindent
9266 \textbf{\thesection.}%
9267 \space\nolinebreak}
9268 \end{lcode}
9269
9270 \item[\cstyle{dash}]
9271 \glossary(dashcs)%
9272 {\Pcstyle{dash}}%
9273 {Two line, centered, regular font, chapterstyle. The number has a dash on
9274 either side.}
9275 A simple two line centered chapterstyle. There is a short
9276 dash on either side of the number and a slightly larger
9277 version of the regular font is used for both the number and the title.
9278 This style is shown in \fref{dcdash}.
9279
9280 %\begin{demochap}[-2\onelineskip]{dash}\end{demochap}
9281 %\begin{demochap}[-4\onelineskip]{dash}\end{demochap}
9282
9283 %\item[\cstyle{default}] This was already in the class but it has been revised
9284 % to re-initialize all the settings.
9285 %\glossary(defaultcs)%
9286 % {\Pcstyle{default}}%
9287 % {The default \Ppack{book} class chapterstyle.}
9288
9289 \item[\cstyle{demo2}]
9290 \glossary(demo2cs)%
9291 {\Pcstyle{demo2}}%
9292 {A two line chapterstyle with a large sanserif title; the number is above,
9293 centered and written (e.g., Six instead of 6) in a bold font.
9294 There are rules above and below the title.}
9295 A two line chapterstyle with a large sanserif title; the number is above,
9296 centered and written (e.g., Six instead of 6) in a bold font.
9297 There are rules above and below the title. An example is shown in
9298 \fref{dcdemo2}.
9299
9300
9301 %\begin{demochap}[-2\onelineskip]{demo2}\end{demochap}
9302 %\begin{demochap}[-\onelineskip]{demo2}\end{demochap}
9303
9304 \item[\cstyle{demo3}]
9305 \glossary(demo3cs)%
9306 {\Pcstyle{demo3}}%
9307 {A two line chapterstyle with a large sanserif title; the number is above,
9308 centered and written (e.g., Six instead of 6) in an italic font.
9309 There are rules above and below
9310 the title line. It is a modified version of the \Pcstyle{demo2} style.}
9311 The chapterstyle used in this document. It is a
9312 modified version of the \cstyle{demo2} chapterstyle, using an italic
9313 rather than bold font for the number.
9314
9315 \item[\cstyle{dowding}]
9316 \glossary(dowdingcs)%
9317 {\Pcstyle{dowding}}%
9318 { A centered two line chapterstyle in an italic font and the number
9319 is spelled out.}
9320 A centered style where the name and number are set in a bold font, with the
9321 number spelled out. The title is below in a large italic font. The style
9322 is based on the design used in Dowding's \textit{Finer Points}~\cite{DOWDING96}.
9323 It is illustrated in
9324 \fref{dcdowding}.
9325
9326 %\begin{demochap}[-2\onelineskip]{dowding}\end{demochap}
9327
9328
9329 \item[\cstyle{ell}]
9330 \glossary(ellcs)%
9331 {\Pcstyle{ell}}%
9332 {A raggedleft large sanserif chapterstyle with the number in the margin. An
9333 `L' shaped rule separates the number and title lines.}
9334 A raggedleft sanserif chapterstyle.
9335 The number line is separated
9336 from the title by rules like an `L' on its side and the number is placed
9337 in the margin, as shown in \fref{dcell}.
9338 I will probably use this in my next book.
9339
9340 %\begin{demochap}[6\onelineskip]{ell}\end{demochap}
9341 %\begin{demochap}{ell}\end{demochap}
9342
9343 \item[\cstyle{ger}]
9344 \glossary(gercs)%
9345 {\Pcstyle{ger}}%
9346 {A raggedright, large, bold, two line chapterstyle with rules
9347 above and below.}
9348 This style was created by
9349 Gerardo\index{Garcia, Gerardo} Garcia\footnote{\ctt,
9350 \textit{Fancy Headings, Chapter Headings}, 2002/04/12} and is a two line,
9351 raggedright, large bold style with rules above and below. It is
9352 demonstrated in \fref{dcger}.
9353
9354 %\begin{demochap}{ger}\end{demochap}
9355 %\begin{demochap}[-4\onelineskip]{ger}\end{demochap}
9356
9357 \item[\cstyle{komalike}]
9358 \glossary(komalikecs)%
9359 {\Pcstyle{komalike}}%
9360 { A section-like chapterstyle in a sans serif font.}
9361 A section-like style set with a sans serif type. It is like that in the
9362 \Lclass{scrbook} class (part of the KOMA bundle).
9363 It is illustrated in
9364 \fref{dckomalike}.
9365
9366 %\begin{demochap}[-2\onelineskip]{komalike}\end{demochap}
9367
9368
9369 \item[\cstyle{lyhne}]
9370 \glossary(lyhnecs)%
9371 {\Pcstyle{lyhne}}%
9372 {A raggedleft bold sanserif chapter title set between two rules, with the
9373 name and number above. It requires the \Ppack{graphicx} package.}
9374 A style created by Anders\index{Lyhne, Anders}
9375 Lyhne\footnote{\ctt, \textit{Glossary}, 2006/02/09} and shown in \fref{dclyhne}
9376 where the raggedleft
9377 sanserif title is between two rules, with the name and number above.
9378 I modified the original to cater for unnumbered chapters.
9379
9380 \PScaveat{lyhne}
9381
9382 %\begin{demochap}[-\onelineskip]{lyhne}\end{demochap}
9383 %\begin{demochap}[-2\onelineskip]{lyhne}\end{demochap}
9384
9385 \item[\cstyle{madsen}]
9386 \glossary(madsencs)%
9387 {\Pcstyle{madsen}}%
9388 {A raggedleft large bold sanserif chapterstyle with the number in the
9389 margin and a rule between the number and title lines.
9390 It requires the \Ppack{graphicx} package.}
9391 This was created by
9392 Lars\index{Madsen, Lars} Madsen\footnote{\ctt,
9393 \textit{New chapter style: chapter vs chapter*}, 2003/12/09}
9394 and is shown in \fref{dcmadsen}.
9395 It is a large sanserif raggedleft style with the number in the margin
9396 and a rule between the number and title lines.
9397
9398 \PScaveat{madsen}
9399
9400 %\begin{demochap}[2\onelineskip]{madsen}\end{demochap}
9401 %\begin{demochap}[-2\onelineskip]{madsen}\end{demochap}
9402
9403 \item[\cstyle{ntglike}]
9404 \glossary(ntglikecs)%
9405 {\Pcstyle{ntglike}}%
9406 { A smaller version of the standard chapterstyle.}
9407 A smaller version of the standard chapterstyle; it is like that in the NTG
9408 classes (\Lclass{boek} class) developed by the Dutch \tx\ User Group.
9409 It is illustrated in
9410 \fref{dcntglike}.
9411
9412 %\begin{demochap}[-3\onelineskip]{ntglike}\end{demochap}
9413
9414
9415
9416 \item[\cstyle{pedersen}]
9417 \glossary(pedersencs)%
9418 {\Pcstyle{pedersen}}%
9419 {A single line chapterstyle in large italics with the number set in the
9420 righthand margin. The title and/or number may be colored. The
9421 \Ppack{graphicx} package is required and the \Ppack{color}
9422 (or \Ppack{xcolor}) package if you want to color.}
9423 This was created by
9424 Troels\index{Pedersen, Troels} Pedersen\footnote{\ctt,
9425 \textit{Chapter style}, 2006/01/31} and requires the \Lpack{graphicx}
9426 package, and, to get the full effect, the \Lpack{color} package as well.
9427 The title is raggedright in large italics while the number is much larger
9428 and placed in the righthand margin (I changed the means of placing the
9429 number). The head of this chapter is set with the \cstyle{pedersen} style,
9430 because it cannot be adequately demonstrated in an illustration.
9431
9432 \PScaveat{pedersen}
9433
9434 %%%%\begin{demochap}{pedersen}\end{demochap}
9435
9436 \item[\cstyle{southall}]
9437 \glossary(southallcs)%
9438 {\Pcstyle{southall}}%
9439 { A raggedright chapterstyle with the number and title on the same line
9440 and a rule below.}
9441 This style was created by Thomas\index{Dye, Thomas} Dye. It
9442 is a simple numbered heading with the title set as a block
9443 paragraph, and with a horizontal rule underneath. It is illustrated
9444 in \fref{dcsouthall}.
9445
9446 %\begin{demochap}[-\onelineskip]{southall}\end{demochap}
9447
9448 \item[\cstyle{tandh}]
9449 \glossary(tandhcs)%
9450 {\Pcstyle{tandh}}%
9451 {A simple section-like chapterstyle in a bold font.}
9452 A simple section-like style in a bold font. It is based on the design used in
9453 the Thames \& Hudson \textit{Manual of Typography}~\cite{MCLEAN80} and
9454 is illustrated in
9455 \fref{dctandh}.
9456
9457 %\begin{demochap}[-1\onelineskip]{tandh}\end{demochap}
9458
9459
9460 \item[\cstyle{thatcher}]
9461 \glossary(thatchercs)%
9462 {\Pcstyle{thatcher}}%
9463 {A centered small caps chapterstyle with the number line separated from
9464 the title by a short rule.}
9465 A style created by
9466 Scott\index{Thatcher, Scott} Thatcher\footnote{\ctt,
9467 \textit{memoir: chapter headings capitalize math symbols}, 2006/01/18}
9468 which has the chapter name and number centered with the
9469 title below, also centered, and all set in small caps. There is a short rule
9470 between the number line and the title, as shown in \fref{dcthatcher}.
9471 I have modified the original to
9472 cater for multiline titles, unnumbered chapters, and appendices.
9473
9474 %\begin{demochap}{thatcher}\end{demochap}
9475
9476
9477
9478 \item[\cstyle{veelo}]
9479 \glossary(veelocs)%
9480 {\Pcstyle{veelo}}%
9481 {A raggedleft large bold chapterstyle with a large black square
9482 in the margin by the number line. It requires the \Ppack{graphicx} package.}
9483 This style created by Bastiaan\index{Veelo, Bastiaan} Veelo
9484 is shown in \fref{dcveelo} and is raggedleft, large, bold and with a
9485 black square in the margin by the number line.
9486
9487 \PScaveat{veelo}
9488
9489 %\cleardoublepage
9490
9491 %%\savefigcnt=1
9492 %\demochapcnt=8
9493 %\begin{demochap}{veelo}\end{demochap}
9494 %\begin{demochap}[-2\onelineskip]{veelo}\end{demochap}
9495
9496 \item[\cstyle{verville}]
9497 \glossary(vervillecs)%
9498 {\Pcstyle{verville}}%
9499 {A single line, large, centered, chapterstyle with rules above and below.}
9500 A chapterstyle I created for
9501 Guy\index{Verville, Guy} Verville\footnote{\ctt,
9502 \textit{Headers and special formatting of sections}, 2005/01/18}.
9503 It is a single line, large centered style with rules above
9504 and below, as in \fref{dcverville}. Unlike my posted version,
9505 this one properly caters for unnumbered chapters.
9506
9507 %\begin{demochap}{verville}\end{demochap}
9508
9509 \item[\cstyle{wilsondob}]
9510 \glossary(wilsondobcs)%
9511 {\Pcstyle{wilsondob}}%
9512 {A one line flushright chapterstyle in a large italic font.}
9513 A one line flushright (raggedleft) section-like style in a large italic font.
9514 It is based on the design used in
9515 Adrian Wilson's \textit{The Design of Books}~\cite{ADRIANWILSON93} and
9516 is illustrated in
9517 \fref{dcwilsondob}.
9518
9519 %\begin{demochap}[-1\onelineskip]{wilsondob}\end{demochap}
9520
9521 \end{itemize}
9522
9523
9524 The code for some of these styles is given in
9525 \Sref{sec:chapter-styles} within the Showcase Appendix. For
9526 details of how the other chapter styles are defined, look at the
9527 documented class code. This should give you ideas if you want to
9528 define your own style.
9529
9530 Note that it is not necessary to define a new chapterstyle if you want
9531 to change the chapter headings --- you can just change the individual
9532 macros without putting them into a style.
9533
9534
9535
9536 \index{chapterstyle|)}
9537
9538 \subsection{Chapter precis}
9539 \label{sec:chapter-precis}
9540
9541 \index{chapter!precis|(}
9542
9543
9544 Some old style novels, and even some modern text
9545 books,\footnote{For example, Robert Sedgewick, \textit{Algorithms},
9546 Addison-Wesley, 1983.} include a short synopsis of the contents of
9547 the chapter either immediately
9548 after the chapter heading\index{heading!chapter} or in the \toc, or in both places.
9549
9550 \begin{syntax}
9551 \cmd{\chapterprecis}\marg{text} \\
9552 \end{syntax}
9553 \glossary(chapterprecis)%
9554 {\cs{chapterprecis}\marg{text}}%
9555 {Prints \meta{text} and also adds it to the ToC.}
9556 The command \cmd{\chapterprecis} prints its argument
9557 both at the
9558 point in the document where it is called, and also adds it to the \file{.toc}
9559 file. For example:
9560 \begin{lcode}
9561 ...
9562 \chapter{}% first chapter
9563 \chapterprecis{Our hero is introduced; family tree; early days.}
9564 ...
9565 \end{lcode}
9566
9567 Now for the details.
9568
9569 \begin{syntax}
9570 \lnc{\prechapterprecisshift} \\
9571 \end{syntax}
9572 \glossary(prechapterprecisshift)%
9573 {\cs{prechapterprecisshift}}%
9574 {Spacing between a chapter head and a chapter precis.}
9575 The length \lnc{\prechapterprecisshift} controls the vertical spacing before
9576 a \cmd{\chapterprecis}. If the precis immediately follows a \cmd{\chapter}
9577 then a different space is required depending on whether or not the
9578 \Lopt{article} class option is used. The class sets:
9579 \begin{lcode}
9580 \ifartopt
9581 \setlength{\prechapterprecisshift}{0pt}
9582 \else
9583 \setlength{\prechapterprecisshift}{-2\baselineskip}
9584 \fi
9585 \end{lcode}
9586
9587
9588 \begin{syntax}
9589 \cmd{\chapterprecishere}\marg{text} \\
9590 \cmd{\chapterprecistoc}\marg{text} \\
9591 \end{syntax}
9592 \glossary(chapterprecishere)%
9593 {\cs{chapterprecishere}\marg{text}}%
9594 {Typesets \meta{text} for a chapter precis.}
9595 \glossary(chapterprecistoc)%
9596 {\cs{chapterprecistoc}\marg{text}}%
9597 {Adds \meta{text} for a chapter precis to the ToC.}
9598 The \cmd{\chapterprecis} command calls these two commands to print the
9599 \meta{text} in the document (the \cmd{\chapterprecishere} command)
9600 and to put it into the \toc{} (the \cmd{\chapterprecistoc} command).
9601 These can be used individually if required.
9602
9603 \begin{syntax}
9604 \cmd{\precisfont} \\
9605 \cmd{\prechapterprecis} \cmd{\postchapterprecis} \\
9606 \end{syntax}
9607 The \cmd{\chapterprecishere} macro is intended for use immediately after
9608 a \cmd{\chapter}. The \meta{text} argument is typeset in
9609 the \cmd{\precisfont} font in a \Ie{quote} environment. The macro's
9610 definition is:
9611 \begin{lcode}
9612 \newcommand{\chapterprecishere}[1]{%
9613 \prechapterprecis #1\postchapterprecis}
9614 \end{lcode}
9615 where \cmd{\prechapterprecis}, \cmd{\postchapterprecis} and \cmd{\precisfont}
9616 are defined as:
9617 \begin{lcode}
9618 \newcommand{\prechapterprecis}{%
9619 \vspace*{\prechapterprecisshift}%
9620 \begin{quote}\precisfont}
9621 \newcommand{\postchapterprecis}{\end{quote}}
9622 \newcommand*{\precisfont}{\normalfont\itshape}
9623 \end{lcode}
9624 Any or all of these can be changed if another style of typesetting is required.
9625
9626 \LMnote{2010/06/09}{Changed a bit, and moved the glossary stuff here
9627 where it naturally belong}
9628 Next the following macros control the formatting of the precis text in
9629 the ToC.
9630 \begin{syntax}
9631 \cmd{\precistoctext}\marg{text} \cmd{\precistocfont} \cmd{\precistocformat} \\
9632 \end{syntax}
9633 \glossary(precistoctext)%
9634 {\cs{precistoctext}\marg{text}}%
9635 {ToC entry for chapter precis \meta{text}}
9636 \glossary(precistocfont)%
9637 {\cs{precistocfont}}%
9638 {Font for typesetting \cs{precistoctext}.}
9639 \glossary(precistocformat)%
9640 {\cs{precistocformat}}%
9641 {Format for typesetting \cs{precistoctext}.}
9642 The \cmd{\chapterprecistoc} macro puts \cmd{\precistoctext}\marg{text} into
9643 the \pixfile{toc} file. The default definition similar to (but not
9644 exactly\footnote{Internally we use a different name for \cs{leftskip}
9645 and \cs{rightskip} to make it easier to do right to left documents
9646 with the class and the \texttt{bidi} package.})
9647 \begin{lcode}
9648 \DeclareRobustCommand{\precistoctext}[1]{%
9649 {\nopagebreak\leftskip \cftchapterindent\relax
9650 \advance\leftskip \cftchapternumwidth\relax
9651 \rightskip \@tocrmarg\relax
9652 \precistocformat\precistocfont #1\par}}
9653 \end{lcode}
9654 Effectively, in the \toc{} \cmd{\precistoctext} typesets its argument like
9655 a chapter title using the \cmd{\precistocfont} (default
9656 \cmd{\itshape}), and \cmd{\precistocformat} (default \cmd{\noindent}).
9657
9658 \index{chapter!precis|)}
9659
9660
9661 \section{Lower level headings}
9662
9663 \index{heading!sections|(}
9664
9665 The lower level heads --- sections down to subparagraphs --- are also
9666 configurable, but there is nothing corresponding to chapter styles.
9667
9668 There are essentially three things that may be adjusted for these
9669 heads: (a) the vertical distance between the baseline of the text
9670 above the heading to the baseline of the title text, (b) the
9671 indentation of the heading from the left hand
9672 margin\index{margin!left}, and (c) the style (font) used for the
9673 heading title. Additionally, a heading may be run-in to the text or
9674 as a display before the following text; in the latter case the
9675 vertical distance between the heading and the following text may also
9676 be adjusted. \fref{fig:displaysechead} shows the parameters
9677 controlling a displayed sectional heading and \fref{fig:runsechead}
9678 shows the parameters for a run-in heading. The default values of the
9679 parameters for the different heads are in \tref{tab:defdisplaySvals}
9680 for the display heads and \tref{tab:defruninSvals} for the run-in
9681 heads.
9682
9683
9684 \begin{figure}
9685 \centering
9686 \setlayoutscale{1}
9687 \drawparameterstrue
9688 \drawheading{}
9689 \caption{Displayed sectional headings} \label{fig:displaysechead}
9690 \end{figure}
9691
9692 \begin{figure}
9693 \centering
9694 \setlayoutscale{1}
9695 \drawparameterstrue
9696 \runinheadtrue
9697 \drawheading{}
9698 \caption{Run-in sectional headings} \label{fig:runsechead}
9699 \end{figure}
9700
9701 \begin{table}
9702 \centering
9703 \caption{Default display sectioning layout parameter values}\label{tab:defdisplaySvals}
9704 \begin{tabular}{lccc} \toprule
9705 & section & subsection & subsubsection \\ \midrule
9706 beforeskip (-ex) & 3.5+1-.2 & 3.25+1-.2 & 3.25+1-.2 \\
9707 indent & 0 & 0 & 0 \\
9708 afterskip (ex) & 2.3+.2 & 1.5+.2 & 1.5+.2 \\
9709 font & \cs{Large}\cs{bfseries} & \cs{large}\cs{bfseries} & \cs{bfseries} \\
9710 \bottomrule
9711 \end{tabular}
9712 \end{table}
9713
9714
9715 \begin{table}
9716 \centering
9717 \caption{Default run-in sectioning layout parameter values}\label{tab:defruninSvals}
9718 \begin{tabular}{lcc} \toprule
9719 & paragraph & subparagraph \\ \midrule
9720 beforeskip (+ex) & 3.25+1-.2 & 3.25+1-.2 \\
9721 indent & 0 & \cs{parindent} \\
9722 afterskip & -1em & -1em \\
9723 font & \cs{bfseries} & \cs{bfseries} \\
9724 \bottomrule
9725 \end{tabular}
9726 \end{table}
9727
9728
9729 In the following I will use \texttt{S} to stand for one of \texttt{sec},
9730 \texttt{subsec}, \texttt{subsubsec}, \texttt{para} or \texttt{subpara},
9731 which are in turn shorthand for \texttt{section} through to
9732 \texttt{subparagraph}, as summarised in \tref{tab:Sshort}.
9733
9734 \begin{table}
9735 \centering
9736 \caption{Values for \texttt{S} in section styling macro names.} \label{tab:Sshort}
9737 \ttfamily
9738 \begin{tabular}{llllll}\toprule
9739 S & sec & subsec & subsubsec & para & subpara \\
9740 & section & subsection & subsubsection & paragraph & subparagraph \\
9741 \bottomrule
9742 \end{tabular}
9743 \end{table}
9744
9745 \begin{syntax}
9746 \cmd{\setbeforeSskip}\marg{skip} \\
9747 \end{syntax}
9748 \glossary(setbeforeSskip)%
9749 {\cs{setbeforeSskip}\marg{skip}}%
9750 {Sets the \cs{beforeskip} for an S head.}
9751 \glossary(setbeforesecskip)%
9752 {\cs{setbeforesecskip}\marg{skip}}%
9753 {Sets the \cs{beforeskip} for a \cs{section} head.}
9754 \glossary(setbeforesubsecskip)%
9755 {\cs{setbeforesubsecskip}\marg{skip}}%
9756 {Sets the \cs{beforeskip} for a \cs{subsection} head.}
9757 \glossary(setbeforesubsubsecskip)%
9758 {\cs{setbeforesubsubsecskip}\marg{skip}}%
9759 {Sets the \cs{beforeskip} for a \cs{subsubsection} head.}
9760 \glossary(setbeforeparaskip)%
9761 {\cs{setbeforeparaskip}\marg{skip}}%
9762 {Sets the \cs{beforeskip} for a \cs{paragraph} head.}
9763 \glossary(setbeforesubparaskip)%
9764 {\cs{setbeforesubparaskip}\marg{skip}}%
9765 {Sets the \cs{beforeskip} for a \cs{subparagraph} head.}
9766 The absolute value of the \meta{skip} length argument is the space to leave
9767 above the heading. If the actual value is negative then the first line
9768 after the heading will not be indented. The default \meta{skip} depends on the
9769 particular level of heading, but for a \cmd{\section}
9770 (i.e., when \verb?S = sec?) it is
9771 \begin{lcode}
9772 -3.5ex plus -1ex minus -.2ex
9773 \end{lcode}
9774 where the plus and minus values are the
9775 allowable stretch and shrink; note that all the values are negative so that
9776 there is no indentation of the following text. If you wanted indentation then
9777 you could do
9778 \begin{lcode}
9779 \setbeforesecskip{3.5ex plus 1ex minus .2ex}
9780 \end{lcode}
9781
9782
9783 \begin{syntax}
9784 \cmd{\setSindent}\marg{length} \\
9785 \end{syntax}
9786 \glossary(setSindent)
9787 {\cs{setSindent}\marg{length}}%
9788 {Sets the \cs{indent} for an S head.}
9789 \glossary(setsecindent)
9790 {\cs{setsecindent}\marg{length}}%
9791 {Sets the \cs{indent} for a \cs{section} head.}
9792 \glossary(setsubsecindent)
9793 {\cs{setsubsecindent}\marg{length}}%
9794 {Sets the \cs{indent} for a \cs{subsection} head.}
9795 \glossary(setsubsubsecindent)
9796 {\cs{setsubsubsecindent}\marg{length}}%
9797 {Sets the \cs{indent} for a \cs{subsubsection} head.}
9798 \glossary(setparaindent)
9799 {\cs{setparaindent}\marg{length}}%
9800 {Sets the \cs{indent} for a \cs{paragraph} head.}
9801 \glossary(setsubparaindent)
9802 {\cs{setsubparaindent}\marg{length}}%
9803 {Sets the \cs{indent} for a \cs{subparagraph} head.}
9804 The value of the \meta{length} length argument is the indentation of
9805 the heading (number and title) from the lefthand margin\index{margin!left}.
9806 This is normally 0pt.
9807
9808 \begin{syntax}
9809 \cmd{\setSheadstyle}\marg{font} \\
9810 \end{syntax}
9811 \glossary(setSheadstyle)%
9812 {\cs{setSheadstyle}\marg{font}}%
9813 {Sets the style (font) for an S head.}
9814 \glossary(setsecheadstyle)%
9815 {\cs{setsecheadstyle}\marg{font}}%
9816 {Sets the style (font) for a section head.}
9817 \glossary(setsubsecheadstyle)%
9818 {\cs{setsubsecheadstyle}\marg{font}}%
9819 {Sets the style (font) for a subsection head.}
9820 \glossary(setsubsubsecheadstyle)%
9821 {\cs{setsubsubsecheadstyle}\marg{font}}%
9822 {Sets the style (font) for a subsubsection head.}
9823 \glossary(setparaheadstyle)%
9824 {\cs{setparaheadstyle}\marg{font}}%
9825 {Sets the style (font) for a paragraph head.}
9826 \glossary(setsubparaheadstyle)%
9827 {\cs{setsubparaheadstyle}\marg{font}}%
9828 {Sets the style (font) for a subparagraph head.}
9829 This macro specifies the style (font) for the sectional number and title.
9830 As before, the default value of the \meta{font} argument depends on the
9831 level of the heading. For a \cmd{\subsection} (i.e., \verb?S=subsec?) it is
9832 \verb?\large\bfseries\raggedright?, to typeset in the \cmd{\bfseries} font
9833 in the \cmd{\large} size; the title will also be set ragged right (i.e.,
9834 there will be no hyphenation in a multiline title).
9835
9836 Note that the very last element in the \meta{font} argument may be a
9837 macro that takes one argument (the number and title of the heading). So,
9838 if for some reason you wanted \cmd{\subsubsection} titles to be all uppercase,
9839 centered, and in the normal font, you can do
9840 \begin{lcode}
9841 \setsubsubsecheadstyle{\normalfont\centering\MakeUppercase}
9842 \end{lcode}
9843
9844 \fancybreak{$***$}
9845
9846 Under very special circumstances, one might want to get completely rid
9847 of the sectional header (for example, if you are using a very small
9848 paper size, and you are placing the section information in the header
9849 instead), by creating a macro that takes on argument and ignores it
9850 \begin{lcode}
9851 \newcommand\ignoreMe[1]{}
9852 \setsecheadstyle{\ignoreMe}
9853 \end{lcode}
9854
9855 \fancybreak{$***$}
9856
9857 As another example, although I don't recommend this, you can draw a
9858 horizontal line under section titles via:
9859 \begin{lcode}
9860 \newcommand{\ruledsec}[1]{%
9861 \Large\bfseries\raggedright #1 \rule{\textwidth}{0.4pt}}
9862 \setsecheadstyle{\ruledsec}
9863 \end{lcode}
9864
9865
9866 \begin{syntax}
9867 \cmd{\setafterSskip}\marg{skip} \\
9868 \end{syntax}
9869 \glossary(setafterSskip)%
9870 {\cs{setafterSskip}\marg{skip}}%
9871 {Sets the \cs{afterskip} for an S head.}
9872 \glossary(setaftersecskip)%
9873 {\cs{setaftersecskip}\marg{skip}}%
9874 {Sets the \cs{afterskip} for a section head.}
9875 \glossary(setaftersubsecskip)%
9876 {\cs{setaftersubsecskip}\marg{skip}}%
9877 {Sets the \cs{afterskip} for a subsection head.}
9878 \glossary(setaftersubsubsecskip)%
9879 {\cs{setaftersubsubsecskip}\marg{skip}}%
9880 {Sets the \cs{afterskip} for a subsubsection head.}
9881 \glossary(setafterparaskip)%
9882 {\cs{setafterparaskip}\marg{skip}}%
9883 {Sets the \cs{afterskip} for a paragraph head.}
9884 \glossary(setaftersubparaskip)%
9885 {\cs{setaftersubparaskip}\marg{skip}}%
9886 {Sets the \cs{afterskip} for a subparagraph head.}
9887 If the value of the \meta{skip} length argument is positive it is the space
9888 to leave between the display heading and the following text. If it is negative,
9889 then the heading will be run-in and the value is the horizontal space
9890 between the end of the heading and the following text.
9891 The default \meta{skip} depends on the
9892 particular level of heading, but for a \cmd{\section} (i.e., when
9893 \verb?S = sec?) it is \verb?2.3ex plus .2ex?,
9894 and for a \cmd{\subparagraph} (i.e., \verb?S = subpara?), which is a run-in
9895 heading, it is \verb?-1em?.
9896
9897 \fancybreak{$*$}
9898 \fancybreak{}
9899
9900 \begin{syntax}
9901 \cmd{\@hangfrom}\marg{code} \\
9902 \cmd{\sethangfrom}\marg{code} \\
9903 \end{syntax}
9904 \glossary(hangfromat)%
9905 {\cs{@hangfrom}\marg{code}}%
9906 {Kernel macro aiding the setting hanging paragraphs.}
9907 \glossary(sethangfrom)%
9908 {\cs{sethangfrom}\marg{code}}%
9909 {User macro redefining \cs{@hangfrom} to \meta{code}.}
9910 Internally all the titling macros use a macro called \cmd{\@hangfrom} which
9911 by default makes multiline titles look like a hanging paragraph\index{paragraph!hanging}. The
9912 default definition of \cmd{\@hangfrom} (in file \file{ltsect.dtx}) is
9913 effectively:
9914 \begin{lcode}
9915 \newcommand{\@hangfrom}[1]{\setbox\@tempboxa\hbox{{#1}}%
9916 \hangindent \wd\@tempboxa\noindent\box\@tempboxa}
9917 \end{lcode}
9918 The argument is put into a box and its width is measured, then a hanging
9919 paragraph\index{paragraph!hanging} is started with the argument as the
9920 first thing and second and later lines indented by the argument's width.
9921
9922 The \cmd{\sethangfrom} macro redefines \cmd{\@hangfrom} to be \meta{code}.
9923 For example, to have the titles set as block paragraphs\index{paragraph!block} instead of hanging
9924 paragraphs\index{paragraph!hanging}, simply do:
9925 \begin{lcode}
9926 \sethangfrom{\noindent #1}
9927 \end{lcode}
9928 Note that you have to use \verb?#1? at the position in the replacement
9929 code for \cmd{\@hangfrom} where the argument to \cmd{\@hangfrom}
9930 is to be located.
9931
9932 \begin{syntax}
9933 \cmd{\@seccntformat}\marg{code} \\
9934 \cmd{\setsecnumformat}\marg{code} \\
9935 \end{syntax}
9936 \glossary(seccntformatat)%
9937 {\cs{@seccntformat}\marg{code}}%
9938 {Kernel macro that formats the number in a sectional head.}
9939 \glossary(setsecnumformat)%
9940 {\cs{setsecnumformat}\marg{code}}%
9941 {Redefines \cs{@seccntformat} to \meta{code}.}
9942 Internally all the titling macros like \cmd{\section},
9943 \cmd{\subsection} etc. use a kernel macro called
9944 \cmd{\@seccntformat}
9945 which defines the formatting of sectional numbers in a title. Its
9946 default definition (in file \file{ltsect.dtx}) is
9947 effectively:\footnote{Because they all internally use the
9948 \cmd{\@startsection} macro.}
9949 \begin{lcode}
9950 \newcommand{\@seccntformat}[1]{\csname the#1\endcsname\quad}
9951 \end{lcode}
9952 which formats the sectional numbers as \verb?\thesec...? with a space
9953 afterwards.
9954 The command \cmd{\setsecnumformat} redefines \cmd{\@seccntformat}
9955 to be \meta{code}.
9956 For example, to put a colon and space after the number
9957 \begin{lcode}
9958 \setsecnumformat{\csname the#1\endcsname:\quad}
9959 \end{lcode}
9960 Note that you have to use \verb?#1? where you want the argument
9961 (sectional number) of \cmd{\@seccntformat} to go.
9962
9963 Note that \cmd{\setsecnumformat} applies to all \cmd{\section},
9964 \cmd{\subsection}, etc. If you want to change it only for, say,
9965 \cmd{\subsection}, use the \cmd{\setsubsechook} described below.
9966
9967
9968 \fancybreak{$*$}
9969 \fancybreak{}
9970
9971 \begin{syntax}
9972 \cmd{\hangsecnum} \\
9973 \cmd{\defaultsecnum} \\
9974 \end{syntax}
9975 \glossary(hangsecnum)%
9976 {\cs{hangsecnum}}%
9977 {Declaration making sectioning numbers hang in the margin.}
9978 \glossary(defaultsecnum)%
9979 {\cs{defaultsecnum}}%
9980 {Declaration reversing the effect of \cs{hangsecnum}.}
9981 The macro \cmd{\hangsecnum} is a declaration that makes sectional numbers hang
9982 in the margin\index{margin!left}. The macro \cmd{\defaultsecnum} is a declaration that reverses the
9983 effect of \cmd{\hangsecnum}, that is, sectional numbers will be typeset in
9984 their familiar places.
9985
9986
9987 \begin{syntax}
9988 \cmd{\Shook} \\
9989 \cmd{\setShook}\marg{text} \\
9990 \end{syntax}
9991 \glossary(Shook)%
9992 {\cs{Shook}}%
9993 {Hook called immediately before typesetting the title of an S head.}
9994 \glossary(setShook)%
9995 {\cs{setShook}\marg{text}}%
9996 {Redefines \cs{Shook} to be \meta{text}.}
9997 \glossary(sechook)%
9998 {\cs{sechook}}%
9999 {Hook called immediately before typesetting the title of a section head.}
10000 \glossary(setsechook)%
10001 {\cs{setsechook}\marg{text}}%
10002 {Redefines \cs{sechook} to be \meta{text}.}
10003 \glossary(subsechook)%
10004 {\cs{subsechook}}%
10005 {Hook called immediately before typesetting the title of a subsection head.}
10006 \glossary(setsubsechook)%
10007 {\cs{setsubsechook}\marg{text}}%
10008 {Redefines \cs{subsechook} to be \meta{text}.}
10009 \glossary(subsubsechook)%
10010 {\cs{subsubsechook}}%
10011 {Hook called immediately before typesetting the title of a subsubsection head.}
10012 \glossary(setsubsubsechook)%
10013 {\cs{setsubsubsechook}\marg{text}}%
10014 {Redefines \cs{subsubsechook} to be \meta{text}.}
10015 \glossary(parahook)%
10016 {\cs{parahook}}%
10017 {Hook called immediately before typesetting the title of a paragraph head.}
10018 \glossary(setparahook)%
10019 {\cs{setparahook}\marg{text}}%
10020 {Redefines \cs{parahook} to be \meta{text}.}
10021 \glossary(subparahook)%
10022 {\cs{subparahook}}%
10023 {Hook called immediately before typesetting the title of a subparagraph head.}
10024 \glossary(setsubparahook)%
10025 {\cs{setsubparahook}\marg{text}}%
10026 {Redefines \cs{subparahook} to be \meta{text}.}
10027 The macro \cmd{\Shook} is called immediately before the typesetting of the
10028 title; its default definition does nothing. The macro \cmd{\setShook}
10029 redefines \cmd{\Shook} to be \meta{text}. You can use this hook, for example,
10030 to insert a \cmd{\sethangfrom} or \cmd{\setsecnumformat} command into the
10031 definition of a particular section division command. In that case,
10032 remember that if you want to refer to the \verb|#1| argument, in the
10033 argument for \cmd{\setsecnumformat}, then you have to double the
10034 \verb|#|, i.e. use \verb|##1|, see the example below.
10035
10036 Here are some example lower level heads and the code used to produce them.
10037
10038
10039
10040 \newcommand*{\shortcenter}[1]{%
10041 \sethangfrom{\noindent ##1}%
10042 \normalfont\boldmath\bfseries
10043 \centering
10044 \parbox{3in}{\centering #1}\par}
10045
10046 \begin{egsource}{egsubheads}
10047 \setsubsubsecheadstyle{\bfseries\raggedright}
10048 \subsubsection*{Bold raggedright}
10049 \setsubsubsecheadstyle{\scshape\raggedright}
10050 \subsubsection*{Small caps raggedright}
10051 \setsubsubsecheadstyle{\itshape\raggedright}
10052 \subsubsection*{Italic raggedright}
10053 \setsubsubsecheadstyle{\Large\centering}
10054 \subsubsection*{Large centered}
10055 \setsubsubsecheadstyle{\large\centering\MakeUppercase}
10056 \subsubsection*{large centered uppercase}
10057 \setsubsubsecheadstyle{\bfseries\centering}
10058 \subsubsection*{Bold centered}
10059 \setsubsubsecheadstyle{\scshape\centering}
10060 \subsubsection*{Small caps centered}
10061 \setsubsubsecindent{2\parindent}
10062 \setsubsubsecheadstyle{\scshape\raggedright}
10063 \subsubsection*{Small caps indented}
10064 \setsubsubsecindent{0pt}
10065 \setsubsubsecheadstyle{\itshape\raggedleft}
10066 \subsubsection*{Italic flushright}
10067 \newcommand*{\shortcenter}[1]{%
10068 \sethangfrom{\noindent ##1}%
10069 \normalfont\boldmath\bfseries
10070 \centering
10071 \parbox{3in}{\centering #1}\par}
10072 \setsubsubsecheadstyle{\shortcenter}
10073 \subsubsection*{Bold centered but taking up no more than 3 inches
10074 if a long title}
10075 \end{egsource}
10076
10077 \FloatBlock
10078
10079
10080 \begin{egresult}[A variety of subhead styles]{egsubheads}
10081 \setsubsubsecheadstyle{\bfseries\raggedright}
10082 \subsubsection*{Bold raggedright}
10083
10084 \setsubsubsecheadstyle{\scshape\raggedright}
10085 \subsubsection*{Small caps raggedright}
10086
10087 \setsubsubsecheadstyle{\itshape\raggedright}
10088 \subsubsection*{Italic raggedright}
10089
10090 \setsubsubsecheadstyle{\Large\centering}
10091 \subsubsection*{Large centered}
10092
10093 \setsubsubsecheadstyle{\large\centering\MakeUppercase}
10094 \subsubsection*{large centered uppercase}
10095
10096 \setsubsubsecheadstyle{\bfseries\centering}
10097 \subsubsection*{Bold centered}
10098
10099 \setsubsubsecheadstyle{\scshape\centering}
10100 \subsubsection*{Small caps centered}
10101
10102 \setsubsubsecindent{2\parindent}
10103 \setsubsubsecheadstyle{\scshape\raggedright}
10104 \subsubsection*{Small caps indented}
10105
10106 \setsubsubsecindent{0pt}
10107 \setsubsubsecheadstyle{\itshape\raggedleft}
10108 \subsubsection*{Italic flushright}
10109
10110 \setsubsubsecheadstyle{\shortcenter}
10111 \subsubsection*{Bold centered but taking up no more than 3 inches
10112 if a long title}
10113 \end{egresult}
10114
10115 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
10116 %%% back to default settings
10117 %\setsubsubsecindent{0pt}
10118 %\setsubsubsecheadstyle{\bfseries\raggedright}
10119 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
10120
10121
10122
10123 \LMnote{2015/02/23}{Replaced \cs{mbox} with \cs{leavevmode} in def of
10124 \cs{marginbox}, suggested in \url{http://tex.stackexchange.com/a/222178/3929} }
10125
10126 \newcommand{\marginbox}[1]{%
10127 \parbox[t][0pt]{6em}{\itshape\raggedleft\leavevmode #1}}
10128 \newcommand{\marginhead}[1]{%
10129 {\llap{\marginbox{#1}\kern0.5em}}}
10130 \setparaindent{0em}
10131 \setafterparaskip{0em}
10132 \setparaheadstyle{\marginhead}
10133 \setparahook{\setsecnumformat{\csname the##1\endcsname\ }}
10134 %%%\setsecnumdepth{paragraph}
10135 \paragraph{Hang the whole heading in the margin}%%%\setsecnumdepth{subsection}
10136 A less traditional style is to put the whole heading into the margin.
10137 I have done this here for a \cmd{\paragraph} heading (which is not otherwise
10138 used in this manual). The code is:
10139 \begin{lcode}
10140 \newcommand{\marginbox}[1]{%
10141 \parbox[t][0pt]{6em}{\itshape\raggedleft\leavevmode #1}}
10142 \newcommand{\marginhead}[1]{%
10143 {\llap{\marginbox{#1}\kern0.5em}}}
10144 \setparaindent{0em}
10145 \setafterparaskip{0em}
10146 \setparaheadstyle{\marginhead}
10147 \setparahook{\setsecnumformat{\csname the##1\endcsname\ }}
10148 \paragraph{Hang the whole heading in the margin}%
10149 \end{lcode}
10150 The macro \cmd{\marginbox} puts its argument, raggedleft, into a zero height
10151 \cmd{\parbox} of width 6em, aligned at the top.
10152 The \cmd{\marginhead} macro puts its argument into a
10153 \cmd{\marginbox} and puts the \cmd{\marginbox} 0.5em to the left.
10154 The \cmd{\paragraph} head style is then set to use \cmd{\marginhead} to
10155 typeset the heading. The format for the number is reset via
10156 \cmd{\setparahook} and \cmd{\setsecnumformat}.
10157
10158
10159 \fancybreak{$*$}
10160 \fancybreak{}
10161
10162
10163 A different approach is to create new macros, each named by the type
10164 of sectional macro it formats, and then make the number format call
10165 these macros.
10166 In this example we will provide separate formatting for \cmd{\section} and \cmd{\subsection}.
10167 \begin{lcode}
10168 \setsecnumformat{\csname #1secnumformat\endcsname}
10169 \newcommand\sectionsecnumformat{\thesection:\quad}
10170 \newcommand\subsectionsecnumformat{\fbox{\enspace\thesubsection\enspace}\enspace}
10171 \end{lcode}
10172 Since the macro is only called in the proper context, we can use
10173 \cmd{\thesection} directly in the code for \cmd{\section}. However,
10174 this requires you to define formatting macros for all sectional
10175 headings. Here is how to reverse it, that is see if a format exists,
10176 use it, otherwise use a default:
10177 \begin{lcode}
10178 \makeatletter
10179 \setsecnumformat{%
10180 \@ifundefined{#1secnumformat}{% nope, use a default
10181 \csname the#1\endcsname\quad%
10182 }{%
10183 \csname #1secnumformat\endcsname%
10184 }%
10185 }
10186 \makeatother
10187 \end{lcode}
10188
10189
10190
10191
10192 \index{heading!sections|)}
10193
10194 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
10195
10196
10197
10198 \section{Fancy anonymous breaks}
10199
10200 Often, in novels, there is a need to break up the text to indicate that
10201 there is a major break in the story, but not enough to warrant starting a new
10202 chapter. I have called these
10203 \emph{anonymous divisions}\index{anonymous division}\index{division!anonymous}
10204 as there is neither number nor title associated with them.
10205
10206 \begin{syntax}
10207 \cmd{\plainbreak}\marg{num} \cmd{\plainbreak*}\marg{num} \\
10208 \cmd{\fancybreak}\marg{text} \cmd{\fancybreak*}\marg{text} \\
10209 \end{syntax}
10210 \glossary(plainbreak)%
10211 {\cs{plainbreak}\marg{num}}%
10212 {An anonymous division of \meta{num} blank lines and the following
10213 paragraph is not indented.}
10214 \glossary(plainbreak*)%
10215 {\cs{plainbreak*}\marg{num}}%
10216 {Like \cs{plainbreak} except that the following paragraph is indented.}
10217 \glossary(fancybreak)%
10218 {\cs{fancybreak}\marg{text}}%
10219 {An anonymous division with \meta{text} centered and the following
10220 paragraph is not indented.}
10221 \glossary(fancybreak*)%
10222 {\cs{fancybreak*}\marg{text}}%
10223 {Like \cs{fancybreak} except that the following paragraph is indented.}
10224
10225 The \cmd{\plainbreak} is an anonymous division. It puts \meta{num}
10226 blank lines into the typescript and the first line of the following
10227 paragraph is not indented\index{paragraph!indentation}. Another anonymous
10228 division is \cmd{\fancybreak} which puts \meta{text} centered into the
10229 typescript and the initial line of the following paragraph is not
10230 indented\index{paragraph!indentation}. For
10231 example:
10232 \begin{lcode}
10233 \fancybreak{{*}\\{* * *}\\{*}}
10234 \end{lcode}
10235 typesets a little diamond made of asterisks.
10236
10237 The starred versions of the commands indent the first line of the
10238 following paragraph\index{paragraph!indentation}.
10239
10240 \begin{syntax}
10241 \cmd{\plainfancybreak}\marg{space}\marg{num}\marg{text} \\
10242 \cmd{\plainfancybreak*}\marg{space}\marg{num}\marg{text} \\
10243 \end{syntax}
10244 \glossary(plainfancybreak)%
10245 {\cs{plainfancybreak}\marg{space}\marg{num}\marg{text}}%
10246 {An anonymous division that acts like \cs{fancybreak} at the top
10247 of the page, or at the bottom if there is less than \meta{space}
10248 left on the page, otherwise it acts like \cs{plainbreak}.
10249 The following paragraph is not indented.}
10250 \glossary(plainfancybreak*)%
10251 {\cs{plainfancybreak*}\marg{space}\marg{num}\marg{text}}%
10252 {Like \cs{plainfancybreak} except that the following paragraph is indented.}
10253 If a plain break comes at the top or bottom of a page then it is very
10254 difficult for a reader to discern that there is a break at all.
10255 If there is text on the page and enough space left to put some text
10256 after a break the \cmd{\plainfancybreak} command will use a \cmd{\plainbreak}
10257 with \meta{num} lines,
10258 otherwise (the break would come at the top or bottom of the page) it
10259 will use a \cmd{\fancybreak} with \meta{text}. The \meta{space} argument is a
10260 length specifying the space needed for the \meta{num} blank lines and some
10261 number of text lines for after the plain break. The starred version of
10262 the command uses the starred versions of the \cmd{\plainbreak} and
10263 \cmd{\fancybreak} commands.
10264
10265
10266 Unfortunately there is an interaction between the requested, plain,
10267 and fancy break spaces.
10268 Let $P$ be the space (in lines) required for the plain break,
10269 $F$ the space (in lines)
10270 required for the fancy break, and $S$ the \meta{space} argument (in lines).
10271 From some experiments it appears that the condition for the plain break
10272 to avoid the top and bottom of the page is that $S - P > 1$.
10273 Also, the condition for the fancy break to avoid being put in the middle
10274 of a page (i.e., not at the top or bottom) is that $S - F < 3$.
10275 For example, if the plain and fancy breaks take the same vertical space
10276 then $S = P +2$ is the only value that matches the conditions. In general,
10277 if $F = P + n$ then the condition is $1 < S-P < 3+n$, which means that
10278 for the \cmd{\plainfancybreak} command the
10279 fancy break must always take at least as much space as the plain break.
10280
10281
10282 \fancybreak{\pfbreakdisplay}
10283
10284 The \cmd{\plainfancybreak} macro inserts a plain break in the middle of
10285 a page or if the break would come at the bottom or top of a page it
10286 inserts a fancy break instead.
10287
10288 \begin{syntax}
10289 \cmd{\pfbreak} \cmd{\pfbreak*} \\
10290 \lnc{\pfbreakskip} \\
10291 \cmd{\pfbreakdisplay}\marg{text} \\
10292 \end{syntax}
10293 \glossary(pfbreak)
10294 {\cs{pfbreak}}%
10295 {An alternative for \cs{plainfancybreak} using \cs{pfbreakskip}
10296 and \cs{pfbreakdisplay}.}
10297 \glossary(pfbreak*)
10298 {\cs{pfbreak*}}%
10299 {An alternative for \cs{plainfancybreak*} using \cs{pfbreakskip}
10300 and \cs{pfbreakdisplay}.}
10301 \glossary(pfbreakskip)%
10302 {\cs{pfbreakskip}}%
10303 {Space for a \cs{pfbreak}'s \cs{plainbreak}.}
10304 \glossary(pfbreakdisplay)%
10305 {\cs{pfbreakdisplay}\marg{text}}%
10306 {\meta{text} for a \cs{pfbreak}'s \cs{fancybreak}.}
10307
10308 The \cmd{\pfbreak} macro is an alternate for \cmd{\plainfancybreak} that may
10309 be more convenient to use. The gap for the plain break is given by the
10310 length \lnc{\pfbreakskip} which is initialised to produce two blank lines.
10311 The fancy break, which takes the same vertical space, is given by the
10312 \meta{text} argument of \cmd{\pfbreakdisplay}. The default definition:
10313 \LMnote{2010/11/22}{typo, not spelled pfbt}
10314 \begin{lcode}
10315 \newcommand*{\pfbreakdisplay}{*\quad*\quad*}
10316 \end{lcode}
10317 typesets three asterisks, as shown a few lines before this.
10318
10319 \index{anonymous division!styling|(}
10320
10321 %%\renewcommand{\pfbreakdisplay}{\huge \ding{167}\quad\ding{167}\quad\ding{167}}
10322 \renewcommand{\pfbreakdisplay}{%
10323 \ensuremath{\clubsuit\quad\diamondsuit\quad\clubsuit}}
10324 \fancybreak{\pfbreakdisplay}
10325
10326 You can change the definition of \cmd{\pfbreakdisplay} for a different
10327 style if you wish. The
10328 fancy break just before this was produced via:
10329 \begin{lcode}
10330 \renewcommand{\pfbreakdisplay}{%
10331 \ensuremath{\clubsuit\quad\diamondsuit\quad\clubsuit}}
10332 \fancybreak{\pfbreakdisplay}
10333 \end{lcode}
10334 I used \cmd{\fancybreak} as I'm not sure where the break will come on the
10335 page and the simple \cmd{\pfbreak} macro might just have produced a couple
10336 of blank lines instead of the fancy display.
10337
10338 The paragraph following \cmd{\pfbreak} is not indented. If you want
10339 it indented use the \cmd{\pfbreak*} starred version.
10340
10341 \renewcommand{\pfbreakdisplay}{\ding{167}\quad\ding{167}\quad\ding{167}}
10342 \fancybreak{\pfbreakdisplay}
10343
10344 The fancy break using
10345 fleurons\index{fleuron} just before this paragraph was produced by:
10346 \begin{lcode}
10347 \renewcommand{\pfbreakdisplay}{%
10348 \ding{167}\quad\ding{167}\quad\ding{167}}
10349 \fancybreak{\pfbreakdisplay}
10350 \end{lcode}
10351 where the \cmd{\ding} command is from the \Lpack{pifont} package.
10352
10353 \makeatletter
10354 \newcommand{\motif}[1]{\cleaders\hbox{#1}\hfil}
10355 \newcommand{\chain}[2]{\leavevmode\hbox to #2{\motif{#1}}}
10356 \newcommand{\diamondpattern}{\m@th$\mkern-.6mu \diamond \mkern-.6mu$}
10357 \makeatother
10358
10359 \fancybreak{\chain{\diamondpattern}{0.25\textwidth}}
10360
10361 The fancy break made with fleurons was simple to specify. There are
10362 many other symbols that you can
10363 use in \ltx\ and these can be combined in potentially attractive ways to
10364 produce a fancy break like the one just above.
10365
10366 The following idea was originally suggested by Christina
10367 Thiele~\cite{ORNAMENTAL}, and can
10368 be used to string together mathematical symbols. It works following the same
10369 principles as the dot leaders in the Table of Contents.
10370
10371 Define a macro called with the syntax \cs{motif}\marg{shape}, where
10372 \meta{shape} is a symbol or other shape to be repeated in a chain,
10373 \begin{lcode}
10374 \newcommand{\motif}[1]{\cleaders\hbox{#1}\hfil}
10375 \end{lcode}
10376 The definition of \cs{motif} is basically taken from \tx, and is part of the
10377 code for making things like dot leaders. \cmd{\hbox}\marg{stuff} puts
10378 \meta{stuff} into a horizontal box, and \cmd{\cleaders}\meta{box} fills
10379 a specified amount of space using whatever number of copies of the
10380 \meta{box} as is needed; if there is
10381 too much space to be filled by a whole number of boxes, the spare space
10382 is spread around equally. \cmd{\hfil} is stretchy space. The \cs{motif} macro
10383 essentially says, fill up a space with with copies of \meta{shape}.
10384
10385 We also need another macro, \cs{chain}\marg{shape}\marg{length},
10386 where \marg{shape}
10387 is a shape to be repeated as many times as it takes to fill up a distance
10388 \meta{length}.
10389 \begin{lcode}
10390 \newcommand{\chain}[2]{\leavevmode\hbox to #2{\motif{#1}}}
10391 \end{lcode}
10392 The \cmd{\leavevmode} makes sure that we are typesetting horizontally, and
10393 \cmd{\hbox} \verb?to? \verb?<length>{stuff}? puts \meta{stuff} into a horizontal
10394 box with the
10395 fixed length of \meta{length}. Roughly, what \cs{chain} and \cs{motif}
10396 do together is typeset enough copies of \meta{shape} to make up
10397 a distance \meta{length}.
10398
10399 That is what we have been aiming for. All that
10400 remains is to decide on what shape we might want to use. Here is one
10401 consisting of diamonds.
10402 \begin{lcode}
10403 \makeatletter
10404 \newcommand{\diamonds}{\m@th$\mkern-.6mu \diamond \mkern-.6mu$}
10405 \makeatother
10406 \end{lcode}
10407 The \cmd{\diamond} symbol can only be used in math mode, hence it
10408 is surrounded by the shorthand \verb?$...$?. \tx\ usually leaves a little
10409 space around maths but the \cmd{\m@th} command stops that. \cmd{\mkern}
10410 adjusts space in math mode, and in this case we are eliminating
10411 the spaces\footnote{It is usually a matter for experiment to find
10412 the right values for the kerning.\label{fn:kerning}}
10413 that would normally be on either
10414 side of the diamond symbol.
10415 The whole effect gives us a diamond symbol with zero space around it.
10416
10417 The fancy break at the start of this discussion was typeset by
10418 \begin{lcode}
10419 % define \motif, \chain, \diamonds and then
10420 \fancybreak{\chain{\diamonds}{0.25\textwidth}}
10421 \end{lcode}
10422 The code is not part of the \Lclass{memoir} class; I defined it just
10423 as indicated in the body of the book. It would more naturally go
10424 into the preamble or a package. You might like to try specifying your
10425 own pattern, say \cs{clubs}, using the \cmd{\club} math symbol but leaving
10426 some space between them.
10427
10428 \index{anonymous division!styling|)}
10429
10430
10431 \section{Footnotes in division headings}
10432
10433 \index{footnote!in heading|(}
10434
10435 With the sectioning commands the text of the required argument
10436 \meta{title} is used as the text for the section title in the body
10437 of the document.
10438
10439 When the optional argument \meta{toc-title} is used in a sectioning
10440 command it is moving and any fragile\index{fragile command}
10441 commands must be \cmd{\protect}ed\index{protect},
10442 while the \meta{title} argument is fixed. The \meta{toc-title} also
10443 serves double duty:
10444 \begin{enumerate}
10445 \item It is used as the text of the title in the \toc;
10446 \item It is used as the text in page headers\index{header}.
10447 \end{enumerate}
10448
10449 If the optional argument is not present, then the \meta{title} is
10450 moving and serves the triple duty of providing the text for the body and \toc{}
10451 titles and for page headers\index{header}.
10452
10453 Some folk feel an urge to add a footnote\index{footnote} to a sectioning
10454 title, which
10455 should be resisted. If their flesh is weak, then the optional argument must
10456 be used and the \cmd{\footnote} attached to the required argument only.
10457 If the optional argument is not used then the footnote mark\index{footnote!mark} and text is
10458 likely to be scattered all over the place, on the section page, in the \toc,
10459 on any page that includes \meta{title} in its headers\index{header}. This is
10460 unacceptable to any reader. So, a footnoted\index{footnote} title should look like
10461 this:
10462 \begin{lcode}
10463 \chapter[Title]{Title\footnote{Do you really have to do this?}}
10464 \end{lcode}
10465
10466 \index{footnote!in heading|)} %| emacs
10467
10468 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
10469
10470 \section{Predefined heading styles}
10471
10472 All \ltx\ classes for typesetting books and reports provide a particular
10473 style for sectional headings. The \Mname\ class is unusual in that it provides
10474 several sets of heading styles. Each set has different spacing around the
10475 division heads, and different fonts in different sizes.
10476 As a reference, \tref{tab:secfonts} lists the default fonts used
10477 for the sectional headings. These fonts are all bold but in different
10478 sizes depending on the division level.
10479
10480 \begin{table}
10481 \centering
10482 \caption{Default fonts for sectional headings}\label{tab:secfonts}
10483 \begin{tabular}{lll} \toprule
10484 \cmd{\booknamefont} & \verb?\huge\bfseries? & \huge\bfseries huge \\
10485 \cmd{\booknumfont} & \verb?\huge\bfseries? & \huge\bfseries huge \\
10486 \cmd{\booktitlefont} & \verb?\Huge\bfseries? & \Huge\bfseries Huge \\
10487 \cmd{\partnamefont} & \verb?\huge\bfseries? & \huge\bfseries huge \\
10488 \cmd{\partnumfont} & \verb?\huge\bfseries? & \huge\bfseries huge \\
10489 \cmd{\parttitlefont} & \verb?\Huge\bfseries? & \Huge\bfseries Huge \\
10490 \cmd{\chapnamefont} & \verb?\huge\bfseries? & \huge\bfseries huge \\
10491 \cmd{\chapnumfont} & \verb?\huge\bfseries? & \huge\bfseries huge \\
10492 \cmd{\chaptitlefont} & \verb?\Huge\bfseries? & \Huge\bfseries Huge \\
10493 \cmd{\secheadstyle} & \verb?\Large\bfseries? & \Large\bfseries Large \\
10494 \cmd{\subsecheadstyle} & \verb?\large\bfseries? & \Large\bfseries Large \\
10495 \cmd{\subsubsecheadstyle} & \verb?\normalsize\bfseries? & \bfseries normal \\
10496 \cmd{\paraheadstyle} & \verb?\normalsize\bfseries? & \bfseries normal \\
10497 \cmd{\subparaheadstyle} & \verb?\normalsize\bfseries? & \bfseries normal \\
10498 \bottomrule
10499 \end{tabular}
10500 \end{table}
10501
10502 \begin{syntax}
10503 \cmd{\makeheadstyles}\marg{name}\marg{code} \\
10504 \cmd{\headstyles}\marg{name} \\
10505 \end{syntax}
10506 \glossary(makeheadstyles)%
10507 {\cs{makeheadstyles}\marg{name}\marg{code}}%
10508 {Create a new set of sectional division headstyles called \meta{name}
10509 defined by \meta{code}.}
10510 \glossary(headstyles)%
10511 {\cs{headstyles}\marg{name}}%
10512 {Use the \meta{name} set of headstyles for sectional division heads.}
10513 The default sectional division head styles provided by \Mname\ form the
10514 \hstyle{default} headstyles and give the same appearance as the standard
10515 \Lclass{book} and \Lclass{report} classes. The set is created via the
10516 \cmd{\makeheadstyles} macro and called for via the \cmd{headstyles}
10517 declaration.
10518 \begin{lcode}
10519 \makeheadstyles{default}{%
10520 \renewcommand*{\booknamefont}{\normalfont\huge\bfseries}
10521 %% and so on down to subparagraph specification
10522 \renewcommand*{\subparaheadstyle}{\normalfont\normalsize\bfseries}
10523 }
10524 \headstyles{default}
10525 \end{lcode}
10526
10527 A somewhat different set of headstyles is used for this manual. When using
10528 \cmd{\makeheadstyles} you only need to specify things that differ from
10529 the \hstyle{default}. Within the class the \hstyle{memman} set of headstyles
10530 is defined as:
10531 \begin{lcode}
10532 \newcommand*{\addperiod}[1]{#1.}
10533 \makeheadstyles{memman}{%
10534 % book changes
10535 \renewcommand*{\booknamefont}{\normalfont\huge\sffamily}
10536 \renewcommand*{\booknumfont}{\normalfont\huge\sffamily}
10537 \renewcommand*{\booktitlefont}{\normalfont\Huge\sffamily}
10538 \renewcommand*{\midbookskip}{\par\vskip 2\onelineskip}%
10539 % part changes
10540 \renewcommand*{\partnamefont}{\normalfont\huge\sffamily}
10541 \renewcommand*{\partnumfont}{\normalfont\huge\sffamily}
10542 \renewcommand*{\parttitlefont}{\normalfont\Huge\sffamily}
10543 \renewcommand*{\midpartskip}{\par\vskip 2\onelineskip}%
10544 % chapter
10545 \chapterstyle{demo3}
10546 % section
10547 \setbeforesecskip{-1.333\onelineskip
10548 \@plus -0.5\onelineskip \@minus -.5\onelineskip}%
10549 \setaftersecskip{0.667\onelineskip \@plus 0.1\onelineskip}%
10550 \setsecheadstyle{\normalfont\scshape\raggedright}%
10551 % subsection
10552 \setbeforesubsecskip{-0.667\onelineskip
10553 \@plus -0.25\onelineskip \@minus -0.25\onelineskip}%
10554 \setaftersubsecskip{0.333\onelineskip \@plus 0.1\onelineskip}%
10555 \setsubsecheadstyle{\normalfont\bfseries\raggedright}%
10556 % subsubsection
10557 \setbeforesubsubsecskip{-0.667\onelineskip
10558 \@plus -0.25\onelineskip \@minus -0.25\onelineskip}%
10559 \setaftersubsubsecskip{0.333\onelineskip \@plus 0.1\onelineskip}%
10560 \setsubsubsecheadstyle{\normalfont\normalsize\itshape\raggedright}%
10561 % paragraph
10562 \setbeforeparaskip{1.0\onelineskip
10563 \@plus 0.5\onelineskip \@minus 0.2\onelineskip}%
10564 \setafterparaskip{-1em}%
10565 \setparaheadstyle{\normalfont\normalsize\itshape\addperiod}%
10566 % subparagraph
10567 \setsubparaindent{\parindent}%
10568 \setbeforesubparaskip{1.0\onelineskip
10569 \@plus 0.5\onelineskip \@minus 0.2\onelineskip}%
10570 \setaftersubparaskip{-1em}%
10571 \setsubparaheadstyle{\normalfont\normalsize\itshape\addperiod}}
10572 \end{lcode}
10573 You can see the effect throughout this document. This chapter is
10574 slightly different in that I have used the \cstyle{pedersen} chapterstyle
10575 instead of the \cstyle{demo3} chapterstyle that I have normally used.
10576
10577 \begin{table}
10578 \centering
10579 \caption{Fonts used by different headstyles}\label{tab:headfonts}
10580 \begin{tabular}{llllllll} \toprule
10581 Headstyles & & chapter & section & subsec & subsubsec & para & subpara \\ \midrule
10582 \hstyle{bringhurst} & & CAPS & \textsc{s. caps} & \textit{Italic} & \textsc{s. caps} & \textit{Italic} & \textit{Italic} \\
10583 \hstyle{crosshead} & & \textbf{Bold} & CAPS & \textbf{Bold} & \textsc{s. caps} & \textit{Italic} & \textsc{s. caps} \\
10584 \hstyle{default} & & \textbf{Bold} & \textbf{Bold} & \textbf{Bold} & \textbf{Bold} & \textbf{Bold} & \textbf{Bold} \\
10585 \hstyle{dowding} & & \textit{Italic} & CAPS & \textsc{s. caps} & \textit{Italic} & \textit{Italic} & \textit{Italic} \\
10586 \hstyle{komalike} & & \textsf{Sans} & \textsf{Sans} & \textsf{Sans} & \textsf{Sans} & \textsf{Sans} & \textsf{Sans} \\
10587 \hstyle{memman} & & \textsf{Sans} & \textsc{s. caps} & \textbf{Bold} & \textit{Italic} & \textit{Italic} & \textit{Italic} \\
10588 \hstyle{ntglike} & & \textbf{Bold} & \textbf{Bold} & \textbf{Bold} & \textsl{Slanted} & \textsl{Slanted} & \textsl{Slanted} \\
10589 \hstyle{tandh} & & \textbf{Bold} & CAPS & \textit{Italic} & \textbf{Bold} & \textit{Italic} & \textit{Italic} \\
10590 \hstyle{wilsondob} & & \textit{Italic} & CAPS & \textit{Italic} & \textsc{s. caps } & \textit{Italic} & \textit{Italic} \\ \bottomrule
10591 \end{tabular}
10592 \end{table}
10593
10594
10595 Several other sets of headstyles are provided as well and the full list
10596 is below. The different fonts used are given in \tref{tab:headfonts} and
10597 generally speaking they start off being large for chapter heads but are
10598 normal size by the time subsubsection heads are reached, or before.
10599
10600 \begin{itemize}
10601 \item[\hstyle{bringhurst}] A set based on Bringhurst's \btitle{Elements of
10602 Typographic Style}~\cite{BRINGHURST99}. It uses the \cstyle{bringhurst}
10603 chapterstyle (\fref{dcbringhurst}).
10604 \item[\hstyle{crosshead}] This set uses the \cstyle{crosshead} chapterstyle
10605 and the lower level division titles are set as crossheads.
10606 \item[\hstyle{default}] The default set corresponding the \ltx\
10607 \Lclass{book} class.
10608 \item[\hstyle{dowding}] A set based on Dowding's
10609 \btitle{Finer Points}~\cite{DOWDING96}. It uses the \cstyle{dowding}
10610 chapterstyle (\fref{dcdowding}).
10611 \item[\hstyle{komalike}] A set based on the kind of headings used in
10612 the KOMA \Lclass{scrbook} class, where there are all in a bold sans serif font.
10613 It uses the \cstyle{komalike} chapterstyle (\fref{dckomalike}).
10614 \item[\hstyle{memman}] The set used in this document, including the
10615 \cstyle{demo3} chapterstyle.
10616 \item[\hstyle{ntglike}] A set based on the kind of headings used in
10617 the NTG (Dutch TUG) \Lclass{boek} class. It uses the \cstyle{ntglike}
10618 chapterstyle (\fref{dcntglike}) and the headings are quiter than the
10619 default.
10620 \item[\hstyle{tandh}] A set based the heads used in Thames \& Hudson
10621 \btitle{Manual of Typography}~\cite{MCLEAN80}. It uses the \cstyle{tandh}
10622 chapterstyle (\fref{dctandh})
10623 \item[\hstyle{wilsondob}] A set based on those used in Adrian Wilson's
10624 \btitle{Design of Books}~\cite{ADRIANWILSON93}. It uses the \cstyle{wilsondob}
10625 chapterstyle (\fref{dcwilsondob}).
10626
10627 \end{itemize}
10628
10629
10630
10631 %#% extend
10632 %#% extstart include pagination-and-headers.tex
10633
10634 \svnidlong
10635 {$Ignore: $}
10636 {$LastChangedDate: 2025-08-08 14:39:37 +0200 (Fri, 08 Aug 2025) $}
10637 {$LastChangedRevision: 859 $}
10638 {$LastChangedBy: [email protected] $}
10639
10640 \chapterstyle{demo3}
10641
10642
10643 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
10644 \chapter{Pagination and headers} \label{chap:pagination}
10645 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
10646
10647 %\section{Introduction}
10648
10649 The focus of this chapter is on marking the pages
10650 with signposts so that the reader can more readily navigate through
10651 the document.
10652
10653 \section{Pagination and folios}
10654
10655 Every page in a \ltx\ document is included in the
10656 pagination\index{pagination}. That is,
10657 there is a number associated with every page and this is the value of
10658 the \Icn{page} counter. This value\index{pagination!changing}
10659 can be changed at any time via either \cmd{\setcounter} or
10660 \cmd{\addtocounter}.
10661
10662 \begin{syntax}
10663 \cmd{\pagenumbering}\marg{rep} \\
10664 \cmd{\pagenumbering*}\marg{rep} \\
10665 \end{syntax}
10666 \glossary(pagenumbering)%
10667 {\cs{pagenumbering}\marg{rep}}%
10668 {Resets the page number to 1, and causes the folios (page numbers) to be
10669 printed using the \meta{rep}
10670 representation (e.g., \texttt{arabic}, \texttt{roman}, \ldots)}
10671 \glossary(pagenumbering*)%
10672 {\cs{pagenumbering*}\marg{rep}}%
10673 {Like \cs{pagenumbering} except that the page number is not reset.}
10674 The macros \cmd{\pagenumbering} and \cmd{\pagenumbering*} cause
10675 the folios\index{folio}\index{folio!changing representation}
10676 to be printed using the
10677 counter representation\index{counter representation}
10678 \meta{rep} for the page number, where \meta{rep} can be one of:
10679 \pixcrep{Alph}, \pixcrep{alph}, \pixcrep{arabic}, \pixcrep{Roman} or
10680 \pixcrep{roman} for uppercase and lowercase letters, arabic numerals, and
10681 uppercase and lowercase Roman numerals,
10682 respectively.\index{alphabetic numbering}\index{roman numerals} As there
10683 are only 26~letters, \pixcrep{Alph} or \pixcrep{alph} can only be
10684 used for a limited number of pages. Effectively, the macros redefine
10685 \cmd{\thepage} to be \verb?\rep{page}?.
10686
10687 Additionally, the \cmd{\pagenumbering}\index{pagination!changing}
10688 command resets the \Icn{page} counter to one; the starred version does not
10689 change the counter.
10690 It is usual to reset the page number back to one each time the style
10691 is changed, but sometimes it may be desirable to have a continuous sequence
10692 of numbers irrespective of their displayed form, which is where
10693 the starred version comes in handy.
10694
10695 \begin{hint}
10696 If you are using \Lpack{hyperref} and include a title page, the
10697 following setup might be useful
10698 \begin{lcode}
10699 \pagenumbering{Alpha}
10700 \begin{titlingpage}
10701 ...
10702 \end{titlingpage}
10703 \frontmatter
10704 ... % this has roman numbering
10705 \mainmatter
10706 ... % this has arabic numbering
10707 \end{lcode}
10708 The code has the advantage that \Lpack{hyperref} does not warn that
10709 the page anchors for pages 1 and 2 are already defined (the
10710 \Ie{titlingpage} env does not show the A, B page numbers).
10711 \end{hint}
10712
10713
10714
10715 \begin{syntax}
10716 \cmd{\savepagenumber} \\
10717 \cmd{\restorepagenumber} \\
10718 \end{syntax}
10719 \glossary(savepagenumber)%
10720 {\cs{savepagenumber}}%
10721 {Saves the current page number.}
10722 \glossary(restorepagenumber)%
10723 {\cs{restorepagenumber}}%
10724 {Sets the page number to that saved by the most recent \cs{savepagenumber}.}
10725 The macro \cmd{\savepagenumber} saves the current page number, and the
10726 macro \cmd{\restorepagenumber} sets the page number to the saved value.
10727 This pair of commands may be used to apparently
10728 interrupt\index{pagination!interrupt} the pagination.
10729 For example, perhaps some full page illustrations\index{illustration}
10730 will be electronically tipped in\index{tip in} to the document and
10731 pagination is not required for these.
10732 This could be done along the lines of:
10733 \begin{lcode}
10734 \clearpage % get onto next page
10735 \savepagenumber % save the page number
10736 \pagestyle{empty} % no headers or footers
10737 %% insert the illustrations
10738 \clearpage
10739 \pagestyle{...}
10740 \restorepagenumber
10741 ...
10742 \end{lcode}
10743 If you try this sort of thing, you may have to adjust the restored page
10744 number by one.
10745 \begin{lcode}
10746 \restorepagenumber
10747 % perhaps \addtocounter{page}{1} or \addtocounter{page}{-1}
10748 \end{lcode}
10749 Depending on the timing of the \cs{...pagenumber} commands and \tx's
10750 decisions on page breaking, this may or may not be necessary.
10751
10752
10753
10754 \section{Page styles} \label{sec:pagestyles}
10755
10756 \index{pagestyle!specifying|(}
10757
10758 The class provides a selection of pagestyles that you can use and if
10759 they don't suit, then there are means to define your own.
10760
10761 These facilities were inspired by the \Lpack{fancyhdr}
10762 package~\cite{FANCYHDR}, although the command set is different.
10763
10764 The standard classes provide for a footer\index{footer} and
10765 header\index{header} for odd and even
10766 pages. Thus there are four elements to be specified for a pagestyle.
10767 This class partitions the headers\index{header} and footers\index{footer}
10768 into left, center and right
10769 portions, so that overall there is a total of 12 elements that have
10770 to be specified
10771 for a pagestyle. You may find, though, that one of the built in pagestyles
10772 meets your needs so you don't have to worry about all these specifications.
10773
10774 \begin{syntax}
10775 \cmd{\pagestyle}\marg{style} \\
10776 \cmd{\thispagestyle}\marg{style} \\
10777 \end{syntax}
10778 \glossary(pagestyle)%
10779 {\cs{pagestyle}\marg{style}}%
10780 {Sets the current pagestyle to \meta{style}.}
10781 \glossary(thispagestyle)%
10782 {\cs{thispagestyle}\marg{style}}%
10783 {Sets the pagestyle to \meta{style} for the current page only.}
10784 \cmd{\pagestyle} sets the current pagestyle to \meta{style}, where
10785 \meta{style} is a word containing only letters. On a particular
10786 page \cmd{\thispagestyle} can be used to override the current pagestyle for
10787 the one page.
10788
10789 Some of the class' commands automatically call \cmd{\thispagestyle}.
10790 For example:
10791 \begin{itemize}
10792 \item the \Ie{titlingpage} environment calls
10793 \begin{lcode}
10794 \thispagestyle{titlingpagestyle}
10795 \end{lcode}
10796 \item if \cmd{\cleardoublepage} will result in an empty verso page it calls
10797 \begin{lcode}
10798 \thispagestyle{cleared}
10799 \end{lcode}
10800 for the empty page.
10801 \end{itemize}
10802 For reference, the full list is given in \tref{tab:callthispagestyle}.
10803
10804 \PWnote{2009/07/26}{Added the simple pagestyle}
10805 The page styles provided by the class\index{pagestyle!class} are:
10806 \begin{plainlist}
10807 \item[\pstyle{empty}] The headers\index{header} and footers\index{footer} are empty.
10808 \item[\pstyle{plain}] The header\index{header} is empty and the folio\index{folio} (page number)
10809 is centered at the bottom of the page.
10810 \item[\pstyle{headings}] The footer\index{footer} is empty. The header\index{header} contains
10811 the folio\index{folio} at the outer side of the page; on verso
10812 pages the chapter name, number and title, in slanted uppercase is
10813 set at the spine margin and on recto pages the section number
10814 and uppercase title is set by the spine margin.
10815 \item[\pstyle{myheadings}] Like the \pstyle{headings} style the footer
10816 is empty. You have to specify what is to go in the headers\index{header}.
10817 \item[\pstyle{simple}] The footer\index{footer} is empty and the
10818 header\index{header} contains the folio\index{folio} (page number)
10819 at the outer side of the page. It is like the \pstyle{headings}
10820 style but without any title texts.
10821 \item[\pstyle{ruled}] The footer\index{footer} contains the
10822 folio\index{folio} at the outside. The header\index{header}
10823 on verso pages contains the chapter number and title in small caps
10824 at the outside; on recto pges the section title is typeset at the
10825 outside using the normal font. A line is drawn
10826 underneath the header\index{header}.
10827 \item[\pstyle{Ruled}] This is like the \pstyle{ruled} style except that
10828 the headers\index{header} and footers\index{footer} extend into
10829 the \foredge\ margin\index{margin!foredge?\foredge}.
10830 \item[\pstyle{companion}] This is a copy of the pagestyle in the
10831 \textit{Companion} series (e.g., see~\cite{COMPANION}). It is
10832 similar to the \pstyle{Ruled} style in that the header has a rule which
10833 extends to the outer edge of the marginal notes. The folios are set
10834 in bold at the outer ends of the header. The chapter title is set in
10835 a bold font flushright in the verso headers, and the section number
10836 and title, again in bold, flushleft in the recto headers\index{header}.
10837 There are no footers\index{footer}.
10838 \item[\pstyle{book}] This is the same as the \pstyle{plain} pagestyle.
10839 \item[\pstyle{chapter}] This is the same as the \pstyle{plain} pagestyle.
10840 \item[\pstyle{cleared}] This is the same as the \pstyle{empty} pagestyle.
10841 \item[\pstyle{part}] This is the same as the \pstyle{plain} pagestyle.
10842 \item[\pstyle{title}] This is the same as the \pstyle{plain} pagestyle.
10843 \item[\pstyle{titlingpage}] This is the same as the \pstyle{empty} pagestyle.
10844 \end{plainlist}
10845
10846 \begin{table}
10847 \centering
10848 \caption{The use of \protect\cs{thispagestyle}} \label{tab:callthispagestyle}
10849 \begin{tabular}{l !{\qquad} l} \toprule
10850 Called from & Style \\ \midrule
10851 \cmd{\book} & \pstyle{book} \\
10852 \cmd{\chapter} & \pstyle{chapter} \\
10853 \cmd{\cleardoublepage} & \pstyle{cleared} \\
10854 \cmd{\cleartorecto} & \pstyle{cleared} \\
10855 \cmd{\cleartoverso} & \pstyle{cleared} \\
10856 \cmd{\epigraphhead} & \pstyle{epigraph} \\
10857 \cmd{\listoffigures} & \pstyle{chapter} \\
10858 \cmd{\listoftables} & \pstyle{chapter} \\
10859 \cmd{\maketitle} & \pstyle{title} \\
10860 \cmd{\part} & \pstyle{part} \\
10861 \cmd{\tableofcontents} & \pstyle{chapter} \\
10862 \Ie{thebibliography} & \pstyle{chapter} \\
10863 \Ie{theindex} & \pstyle{chapter} \\
10864 \Ie{titlingpage} & \pstyle{titlingpage} \\
10865 \bottomrule
10866 \end{tabular}
10867 \end{table}
10868
10869 \begin{syntax}
10870 \cmd{\uppercaseheads} \cmd{\nouppercaseheads} \\
10871 \end{syntax}
10872 \glossary(uppercaseheads)%
10873 {\cs{uppercaseheads}}%
10874 {Set the titles in the headings pagestyle in Uppercase.}
10875 \glossary(nouppercaseheads)%
10876 {\cs{nouppercaseheads}}%
10877 {Do not uppercase the titles in the headings.}
10878 Following the declaration \cmd{\nouppercaseheads} the titles in the
10879 \pstyle{headings} pagestyle will not be automatically uppercased. The default
10880 is \cmd{\uppercaseheads} which specifies that the titles are to be
10881 automatically uppercased.
10882
10883 % \begin{note*}{Change 2012} The upper casing macro used by
10884 % \cmd{\uppercaseheads} has been changed into \cmd{\MakeTextUppercase}
10885 % (from the \Lpack{textcase} package) such that the upper casing does
10886 % not touch math, references or citations.
10887 % \end{note*}
10888 \begin{note*}{Changed 2025} The upper casing macro used by
10889 \cmd{\uppercaseheads} has been changed back into
10890 \cmd{\MakeUppercase} as it now provides all the features from the
10891 previously used \Lpack{textcase}.
10892 \end{note*}
10893
10894
10895
10896 For the \pstyle{myheadings} pagestyle above, you have to define your own
10897 titles to go into the header\index{header}. Each sectioning command,
10898 say \cs{sec},
10899 calls a macro called \cs{secmark}. A pagestyle usually defines this command
10900 so that it picks up the title, and perhaps the number, of the \cs{sec}. The
10901 pagestyle can then use the information for its own purposes.
10902
10903 \begin{syntax}
10904 \cmd{\markboth}\marg{left}\marg{right} \\
10905 \cmd{\markright}\marg{right} \\
10906 \end{syntax}
10907 \glossary(markboth)%
10908 {\cs{markboth}\marg{left}\marg{right}}%
10909 {Sets values of two markers to \meta{left} and \meta{right} respectively
10910 (see \cs{leftmark} and \cs{rightmark}).}
10911 \glossary(markright)%
10912 {\cs{markright}\marg{right}}%
10913 {Sets value of one marker to \meta{right} (see \cs{rightmark}).}
10914 \cmd{\markboth} sets the values of two \emph{markers}\index{markers}
10915 to \meta{left} and \meta{right} respectively, at the point in the text
10916 where it is called. Similarly, \cmd{\markright} sets the value of a
10917 marker to \meta{right}.
10918
10919 \begin{syntax}
10920 \cmd{\leftmark} \cmd{\rightmark} \\
10921 \end{syntax}
10922 \glossary(leftmark)%
10923 {\cs{leftmark}}%
10924 {Contains the value of the \meta{left} argument of the last \cs{markboth}.}
10925 \glossary(rightmark)%
10926 {\cs{rightmark}}%
10927 {Contains the value of the \meta{right} argument of the first \cs{markboth}
10928 or \cs{markright} on the page; if there is none then the value of the most
10929 recent \meta{right} argument.}
10930 The macro \cmd{\leftmark} contains the value of the \meta{left} argument
10931 of the \emph{last} \cmd{\markboth} on the page. The macro \cmd{\rightmark}
10932 contains the value of the \meta{right} argument of the \emph{first}
10933 \cmd{\markboth} or \cmd{\markright} on the page, or if there is not one it
10934 contains the value of the most recent \meta{right} argument.
10935
10936 A pagestyle can define the \cs{secmark} commands in terms of
10937 \cmd{\markboth} or \cmd{\markright}, and then use \cmd{\leftmark} and/or
10938 \cmd{\rightmark} in the headers\index{header} or footers\index{footer}.
10939 I'll show examples of how this
10940 works later, and this is often how the \pstyle{myheadings} style gets
10941 implemented.
10942
10943 All the division commands include a macro that you can define to set
10944 marks related to that heading. Other commands also include macros that
10945 you can redefine for setting marks.
10946
10947 \begin{table}
10948 \centering
10949 \caption{Mark macros for page headers} \label{tab:markmacros}
10950 \begin{tabular}{ll} \toprule
10951 Main macro & default mark definition \\ \midrule
10952 \cs{book(*)} & \verb?\newcommand*{\bookpagemark}[1]{}? \\
10953 \cs{part(*)} & \verb?\newcommand*{\partmark}[1]{}? \\
10954 \cs{chapter(*)} & \verb?\newcommand*{\chaptermark}[1]{}? \\
10955 \cs{section(*)} & \verb?\newcommand*{\sectionmark}[1]{}? \\
10956 \cs{subsection(*)} & \verb?\newcommand*{\subsectionmark}[1]{}? \\
10957 \cs{subsubsection(*)} & \verb?\newcommand*{\subsubsectionmark}[1]{}? \\
10958 \cs{paragraph(*)} & \verb?\newcommand*{\paragraphmark}[1]{}? \\
10959 \cs{subparagraph(*)} & \verb?\newcommand*{\subparagraphmark}[1]{}? \\
10960 \cs{tableofcontents(*)} & \verb?\newcommand*{\tocmark}{}? \\
10961 \cs{listoffigures(*)} & \verb?\newcommand*{\lofmark}{}? \\
10962 \cs{listoftables(*)} & \verb?\newcommand*{\lotmark}{}? \\
10963 \cs{thebibliography} & \verb?\newcommand*{\bibmark}{}? \\
10964 \cs{theindex} & \verb?\newcommand*{\indexmark}{}? \\
10965 \cs{theglossary} & \verb?\newcommand*{\glossarymark}{}? \\
10966 \cs{PoemTitle} & \verb?\newcommand*{\poemtitlemark}[1]{}? \\
10967 \cs{PoemTitle*} & \verb?\newcommand*{\poemtitlestarmark}[1]{}? \\
10968 \bottomrule
10969 \end{tabular}
10970 \end{table}
10971
10972 The \cs{...mark} commands are listed in \tref{tab:markmacros}. When they are
10973 called by the relevant main macro, those that take an argument are called with
10974 the `title' as the argument's value. For example, the \cmd{\chapter} macro
10975 calls \cmd{\chaptermark} with the value of the title specified as being
10976 for the header.
10977
10978 Please remember that the macros listed in \tref{tab:markmacros} are
10979 `provider' macros, i.e. they provide information for \cmd{\leftmark}
10980 and \cmd{\rightmark} for you to use later on. To gain access to the
10981 section title, you do \emph{not} use \cmd{\sectionmark} in the header
10982 or footer. It is a macro that provides information, but you need to
10983 use \cmd{\leftmark} or \cmd{\rightmark} to access depending on how you
10984 have defined \cmd{\sectionmark}.
10985
10986
10987 \section{Making headers and footers}
10988
10989 As mentioned, the class provides for left, center, and right slots in
10990 even and odd headers\index{header} and footers\index{footer}.
10991 This section describes how you can make
10992 your own pagestyle using these 12 slots. The 6 slots for a page
10993 are diagrammed in \fref{lay:header}.
10994
10995 \begin{figure}
10996 \setlayoutscale{1}
10997 \centering
10998 \headerfooterdiagram
10999 \caption{Header and footer slots} \label{lay:header}
11000 \end{figure}
11001
11002 The class itself uses the commands from this section. For example,
11003 the \pstyle{plain} pagestyle is defined as
11004 \begin{lcode}
11005 \makepagestyle{plain}
11006 \makeevenfoot{plain}{}{\thepage}{}
11007 \makeoddfoot{plain}{}{\thepage}{}
11008 \end{lcode}
11009 which centers the page number at the bottom of the page.
11010
11011
11012 \begin{syntax}
11013 \cmd{\makepagestyle}\marg{style} \\
11014 \cmd{\aliaspagestyle}\marg{alias}\marg{original} \\
11015 \cmd{\copypagestyle}\marg{copy}\marg{original}\\
11016 \end{syntax}
11017 \glossary(makepagestyle)%
11018 {\cs{makepagestyle}\marg{style}}%
11019 {Used to define a pagestyle \meta{style}.}
11020 \glossary(aliaspagestyle)%
11021 {\cs{aliaspagestyle}\marg{alias}{original}}%
11022 {Defines the \meta{alias} pagestyle to be the same as the \meta{original}
11023 pagestyle.}
11024 \glossary(copypagestyle)%
11025 {\cs{copypagestyle}\marg{copy}{original}}%
11026 {Creates a new pagestyle called \meta{copy} using the \meta{original}
11027 pagestyle specification.}
11028
11029 The command \cmd{\makepagestyle} specifies a pagestyle \meta{style} which
11030 is initially equivalent to the \pstyle{empty} pagestyle. On the other hand,
11031 \cmd{\aliaspagestyle} defines the \meta{alias} pagestyle to be the same as
11032 the \meta{original} pagestyle. As an example of the latter, the class includes
11033 the code
11034 \begin{lcode}
11035 \aliaspagestyle{part}{plain}
11036 \aliaspagestyle{chapter}{plain}
11037 \aliaspagestyle{cleared}{empty}
11038 \end{lcode}
11039 The \cmd{\copypagestyle} command creates a new pagestyle called \meta{copy}
11040 using the \meta{original} pagestyle specification.
11041
11042 If an alias and a copy pagestyle are created based on the same
11043 \meta{original} and later the \meta{original} is modified,
11044 the alias and copy behave differently.
11045 The appearance of the alias pagestyle will continue to match the
11046 modified \meta{original} but the copy pagestyle is unaffected by any change
11047 to the \meta{original}. You cannot modify an alias pagestyle but you can
11048 modify a copy pagestyle.
11049
11050 \begin{syntax}
11051 \cmd{\makeevenhead}\marg{style}\marg{left}\marg{center}\marg{right} \\
11052 \cmd{\makeoddhead}\marg{style}\marg{left}\marg{center}\marg{right} \\
11053 \cmd{\makeevenfoot}\marg{style}\marg{left}\marg{center}\marg{right} \\
11054 \cmd{\makeoddfoot}\marg{style}\marg{left}\marg{center}\marg{right} \\
11055 \end{syntax}
11056 \glossary(makeevenhead)%
11057 {\cs{makeevenhead}\marg{style}\marg{left}\marg{center}\marg{right}}%
11058 {Defines the \meta{left}, \meta{center} and \meta{right} parts of the
11059 even (verso) page header of the \meta{style} pagetstyle.}
11060 \glossary(makeoddhead)%
11061 {\cs{makeoddhead}\marg{style}\marg{left}\marg{center}\marg{right}}%
11062 {Defines the \meta{left}, \meta{center} and \meta{right} parts of the
11063 odd (recto) page header of the \meta{style} pagetstyle.}
11064 \glossary(makeevenfoot)%
11065 {\cs{makeevenfoot}\marg{style}\marg{left}\marg{center}\marg{right}}%
11066 {Defines the \meta{left}, \meta{center} and \meta{right} parts of the
11067 even (verso) page footer of the \meta{style} pagetstyle.}
11068 \glossary(makeoddfoot)%
11069 {\cs{makeoddfoot}\marg{style}\marg{left}\marg{center}\marg{right}}%
11070 {Defines the \meta{left}, \meta{center} and \meta{right} parts of the
11071 odd (recto) page footer of the \meta{style} pagetstyle.}
11072 The macro \cmd{\makeevenhead} defines the \meta{left}, \meta{center}, and
11073 \meta{right} portions of the \meta{style} pagestyle header\index{header}
11074 for even numbered (verso) pages.
11075 Similarly \cmd{\makeoddhead}, \cmd{\makeevenfoot}, and
11076 \cmd{\makeoddfoot} define the \meta{left}, \meta{center} and \meta{right}
11077 portions of the \meta{style} header\index{header} for odd numbered
11078 (recto) pages, and the footers\index{footer} for verso and recto pages.
11079 These commands for \meta{style}
11080 should be used after the corresponding \cmd{\makepagestyle} for \meta{style}.
11081
11082 \begin{syntax}
11083 \cmd{\makerunningwidth}\marg{style}\oarg{footwidth}\marg{headwidth} \\
11084 \lnc{\headwidth} \\
11085 \end{syntax}
11086 \glossary(makerunningwidth)%
11087 {\cs{makerunningwidth}\marg{style}\oarg{footwidth}\marg{headwidth}}%
11088 {Sets the width of the \meta{style} pagestyle headers to \meta{headwidth}.
11089 The footers are set to \meta{headwidth}, or \meta{footwidth} if it
11090 is given.}
11091 \glossary(headwidth)%
11092 {\cs{headwith}}%
11093 {A (scratch) length normally used in the definition of headers and footers.}
11094 The macro \cmd{\makerunningwidth} sets the widths of the \meta{style}
11095 pagestyle headers\index{header} and footers\index{footer}. The header
11096 width is set to \meta{headwidth}. If the optional \meta{footwidth} is
11097 present, then the footer width is set to that, otherwise to \meta{headwidth}.
11098 The header width is stored as the length \cs{\meta{style}headrunwidth}
11099 and the footer width as \cs{\meta{style}footrunwidth}.
11100
11101 The \cmd{\makepagestyle} initialises the widths to be the textwidth,
11102 so the macro need only be used if some
11103 other width is desired. The length \lnc{\headwidth} is provided as a
11104 (scratch) length that may be used for headers\index{header} or
11105 footers\index{footer}, or any other purpose.
11106
11107 \begin{syntax}
11108 \cmd{\makeheadrule}\marg{style}\marg{width}\marg{thickness} \\
11109 \cmd{\makefootrule}\marg{style}\marg{width}\marg{thickness}\marg{skip} \\
11110 \cmd{\makeheadfootruleprefix}\marg{style}\marg{for headrule}\marg{for footrule}\\
11111 \end{syntax}
11112 \glossary(makeheadrule)%
11113 {\cs{makeheadrule}\marg{style}\marg{width}\marg{thickness}}%
11114 {Specifies the \meta{width} and \meta{thickness} of the rule drawn below the
11115 headers of the \meta{style} pagestyle.}%
11116 \glossary(makefootrule)%
11117 {\cs{makefootrule}\marg{style}\marg{width}\marg{thickness}\marg{skip}}%
11118 {Specifies the \meta{width} and \meta{thickness} of the rule drawn
11119 \meta{skip} (see \cs{footskip}) above the footers of the
11120 \meta{style} pagestyle.}%
11121 \glossary(makeheadfootruleprefix)
11122 {\cs{makeheadfootruleprefix}\marg{style}\marg{for headrule}\marg{for
11123 footrule}}%
11124 {Can be used to add alternative colors to the head/foot rule}%
11125 A header\index{header} may have a rule drawn between it and the top of
11126 the typeblock\index{typeblock}, and similarly a rule may be drawn
11127 between the bottom of the typeblock\index{typeblock} and the
11128 footer\index{footer}.
11129 The \cmd{\makeheadrule} macro specifies the \meta{width}
11130 and \meta{thickness} of the rule below the \meta{style} pagestyle
11131 header\index{header}, and the \cmd{\makefootrule} does the same for
11132 the rule above the footer\index{footer}; the
11133 additional \meta{skip} argument is a distance that specifies the vertical
11134 positioning of the foot rule (see \cmd{\footruleskip}).
11135 The \cmd{\makepagestyle} macro initialises the \meta{width} to the
11136 \lnc{\textwidth} and the \meta{thickness} to 0pt, so by default no rules
11137 are visible. The macro \cmd{\makeheadfootruleprefix} is intended for
11138 adding alternative colors to the head/foot rules, e.g.
11139 \begin{lcode}
11140 \makeheadfootruleprefix{mystyle}{\color{red}}{\color{blue}}
11141 \end{lcode}
11142
11143
11144 \begin{syntax}
11145 \lnc{\normalrulethickness} \\
11146 \end{syntax}
11147 \glossary(normalrulethickness)%
11148 {\cs{normalrulethickness}}%
11149 {The normal thickness of a visible rule (default 0.4pt).}
11150 \lnc{\normalrulethickness} is the normal\index{rule!thickness}
11151 thickness of a visible rule, by
11152 default 0.4pt. It can be changed using \cmd{\setlength}, although I suggest
11153 that you do not unless perhaps when using at least the \Lopt{14pt} class
11154 option.
11155
11156 \begin{syntax}
11157 \cmd{\footruleheight} \\
11158 \cmd{\footruleskip} \\
11159 \end{syntax}
11160 \glossary(footruleheight)%
11161 {\cs{footruleheight}}%
11162 {Macro specifying the height of a normal rule above a footer.}
11163 \glossary(footruleskip)%
11164 {\cs{footruleskip}}%
11165 {Macro specifying a distance sufficient to ensure that a rule above a footer
11166 will lie in the space between the footer and the typeblock.}
11167 The macro \cmd{\footruleheight} is the height of a normal
11168 rule above a footer\index{footer} (default zero).
11169 \cmd{\footruleskip} is a distance
11170 sufficient to ensure that a foot rule will be placed between the bottom
11171 of the typeblock\index{typeblock} and the footer\index{footer}.
11172 Despite appearing to be lengths, if you really need to change the values
11173 use \cmd{\renewcommand}, not \cmd{\setlength}.
11174
11175 \begin{syntax}
11176 \cmd{\makeheadposition}\marg{style}\\
11177 \marg{eheadpos}\marg{oheadpos}\marg{efootpos}\marg{ofootpos} \\
11178 \end{syntax}
11179 \glossary(makeheadposition)%
11180 {\cs{makeheadposition}\marg{style}\marg{eheadpos}\marg{oheadpos}\marg{efootpos}\marg{ofootpos}}%
11181 {Specifies the horizontal positioning of the even and odd headers and
11182 footers respectively for the \meta{style} pagestyle.}
11183 The \cmd{\makeheadposition} macro specifies the horizontal positioning
11184 of the even and odd headers\index{header} and footers\index{footer},
11185 respectively, for the \meta{style} pagestyle.
11186 Each of the \meta{...pos} arguments may be \texttt{flushleft}, \texttt{center},
11187 or \texttt{flushright}, with the obvious meanings. An empty, or unrecognised,
11188 argument is equivalent to \texttt{center}. This macro is really only of use
11189 if the header/footer\index{header}\index{footer} width is not the
11190 same as the \lnc{\textwidth}.
11191
11192 \begin{syntax}
11193 \cmd{\makepsmarks}\marg{style}\marg{code} \\
11194 \end{syntax}
11195 \glossary(makepsmark)
11196 {\cs{makepsmarks}\marg{style}\marg{code}}%
11197 {Hook into the \meta{style} pagestyle, usually used for the \meta{code}
11198 setting any marks.}
11199 The last thing that the \cmd{\pagestyle}\marg{style} does is call the
11200 \meta{code} argument of the \cmd{\makepsmarks} macro for \meta{style}.
11201 If specified, this code will often redefine the various macros that
11202 provide the automated data for the headers (or footers). For example
11203 how \cmd{\chapter} makes the title and chapter number avaialble for
11204 the header. If no \meta{code} is specified (or \cmd{\makepsmarks} is
11205 not setup for this \meta{style}, the providing macros already active
11206 will be used.
11207
11208 \LMnote{2010/06/25}{Added a mentioning of \cs{makeheadfootstrut}}
11209 \begin{syntax}
11210 \cmd{\makeheadfootstrut}\marg{style}\marg{head strut}\marg{foot strut}
11211 \end{syntax}
11212 The headers and footers are each made up of three separate
11213 entities. At the front and end of these a special \meta{style} related
11214 strut is inserted. By default \cmd{\makepagestyle} will initialize
11215 them to \cmd{\strut} (except the \pstyle{empty} style where the struts
11216 are empty). One can use the macro above to change these struts to
11217 something different.
11218
11219 \fancybreak{$***$}
11220
11221 \LMnote{2019/11/07}{Moved the explanation for \cmd{createmark} and
11222 friends}
11223
11224 Writing the \meta{code} part for \cmd{\makepsmarks} can be very
11225 daunting, as you will be needing to define most of the macros listed
11226 in \tref{tab:markmacros}
11227
11228 However, most uses are very similar, so we have provided some helper
11229 macros:
11230 \begin{syntax}
11231 \cmd{\createmark}\marg{sec}\marg{marks}\marg{show}\marg{prefix}\marg{postfix} \\
11232 \cmd{\createplainmark}\marg{type}\marg{marks}\marg{text} \\
11233 \cmd{\memUChead}\marg{text} \\
11234 \cmd{\uppercaseheads} \cmd{\nouppercaseheads} \\
11235 \end{syntax}
11236 \glossary(createplainmark)%
11237 {\cs{createplainmark}\marg{type}\marg{marks}\marg{text}}%
11238 {Defines the \cs{typemark} macro using \meta{text} as the mark, where
11239 \meta{marks} is \texttt{left}, \texttt{both} or \texttt{right}.}
11240 \glossary(createmark)%
11241 {\cs{createmark}\marg{sec}\marg{marks}\marg{show}\marg{prefix}\marg{postfix}}%
11242 {Defines the \cs{secmark} macro where \meta{show} (\texttt{shownumber}
11243 or \texttt{nonumber}) controls whether the division number will be
11244 displayed within \cs{mainmatter}, \meta{marks} is \texttt{left},
11245 \texttt{both} or \texttt{right}, and \meta{prefix} and \meta{postfix}
11246 are affixed before and after the \meta{sec} (division) number.}
11247 \glossary(memUChead)%
11248 {\cs{memUChead}\marg{text}}%
11249 {May uppercase \meta{text}, depending on \cs{uppercaseheads} and
11250 \cs{nouppercaseheads}.}
11251 \glossary(uppercaseheads)%
11252 {\cs{uppercaseheads}}%
11253 {Defines \cs{memUChead} as equivalent to \cs{MakeUppercase}.}
11254 \glossary(nouppercaseheads)%
11255 {\cs{nouppercaseheads}}%
11256 {Defines \cs{memUChead} as \cs{relax} (i.e., do nothing).}
11257
11258 \noindent
11259 The macro \cmd{\createmark}\marg{sec}\marg{marks}\marg{show}\marg{prefix}\marg{postfix}
11260 defines a new macro \verb?\?\meta{sec}\verb?mark? that will take one argument, where
11261 \begin{description}
11262 \item[\meta{marks}] is either \texttt{left}, \texttt{right} or \texttt{both},
11263 \item[\meta{sec}] is a sectional division
11264 such as \texttt{part}, \texttt{chapter}, \texttt{section}, etc.,
11265 \item[\meta{show}] is one of the terms \texttt{shownumber}, \texttt{nonumber} or
11266 \texttt{notitle}. They control what is available in the provided
11267 header text. The terms \texttt{shownumber}, \texttt{nonumber}
11268 control whether the number is displayed within \cmd{\mainmatter}
11269 (under \cmd{\frontmatter} no numbers are displayed.
11270
11271 The term \texttt{notitle} (which implies \texttt{shownumber}) will
11272 only show the number part (including the \meta{postfix} and
11273 \meta{prefix} parts described below) and \emph{no} title.
11274
11275 \item[\meta{pre-/postfix}] are affixed before and after the division number.
11276 \end{description}
11277 For example:
11278 \begin{lcode}
11279 \createmark{section}{left}{nonumber}{}{}
11280 \createmark{section}{both}{nonumber}{}{}
11281 \createmark{section}{right}{nonumber}{}{}
11282 \end{lcode}
11283 is equivalent to, respectively
11284 \begin{lcode}
11285 \def\sectionmark#1{\markboth{\memUChead{#1}}{}}
11286 \def\sectionmark#1{\markboth{\memUChead{#1}}{\memUChead{#1}}}
11287 \def\sectionmark#1{\markight{\memUChead{#1}}}
11288 \end{lcode}
11289 whereas
11290 \begin{lcode}
11291 \createmark{section}{left}{shownumber}{}{}
11292 \end{lcode}
11293 is equivalent to the following pseudo code
11294 \begin{lcode}
11295 \def\sectionmark#1{\markboth{
11296 \memUChead{
11297 if secnumdepth > number:
11298 if mainmatter:
11299 prefix \thesection postfix
11300 fi
11301 fi
11302 #1% aka the section title
11303 }
11304 }{}}
11305 \end{lcode}
11306 and
11307 \begin{lcode}
11308 \createmark{section}{left}{notitle}{}{}
11309 \end{lcode}
11310 is equivalent to the following pseudo code
11311 \begin{lcode}
11312 \def\sectionmark#1{\markboth{
11313 \memUChead{
11314 if secnumdepth > number:
11315 if mainmatter:
11316 prefix \thesection postfix
11317 fi
11318 fi
11319 }
11320 }{}}
11321 \end{lcode}
11322
11323 \fancybreak{}
11324
11325 The macro \cmd{\createplainmark} defines the
11326 \verb?\?\meta{type}\verb?mark?, where \meta{type} is an unnumbered
11327 division-like head, such as \texttt{toc}, \texttt{lof},
11328 \texttt{index}, using \meta{text} as the mark value, and \meta{marks}
11329 is \texttt{left}, \texttt{both} or \texttt{right}. For example:
11330 \begin{lcode}
11331 \createplainmark{toc}{left}{\contentsname}
11332 \createplainmark{lot}{right}{\listtablename}
11333 \createplainmark{bib}{both}{\bibname}
11334 \end{lcode}
11335 is equivalent to
11336 \begin{lcode}
11337 \def\tocmark{\markboth{\memUChead{\contentsname}}{}}
11338 \def\lotmark{\markright{\memUChead{\listtablename}}}
11339 \def\lofmark{\markboth{\memUChead{\bibname}}{\memUChead{\bibname}}}
11340 \end{lcode}
11341
11342 \fancybreak{}
11343
11344 Lastly the macro \cmd{\memUChead} is an internal macro handling the
11345 upper- or non-uppercasing. Its definition is usually controlled using
11346 \cmd{\uppercaseheads} which sets \cmd{\memUChead} to
11347 \cmd{\MakeUppercase} whereas \cmd{\nouppercaseheads} defines it to
11348 output the argument unchanged. The class default is
11349 \cmd{\uppercaseheads}.
11350
11351 \fancybreak{}
11352
11353 The class' default page style is \pstyle{headings}, which has the
11354 following setup for \cmd{\makepsmarks} (slight pseudocode):
11355 \begin{lcode}
11356 if twopage setup:
11357 \makepsmarks{headings}{%
11358 \createmark{chapter}{left}{shownumber}{\@chapapp\ }{. \ }
11359 \createmark{section}{right}{shownumber}{}{. \ }
11360 \createplainmark{toc}{both}{\contentsname}
11361 \createplainmark{lof}{both}{\listfigurename}
11362 \createplainmark{lot}{both}{\listtablename}
11363 \createplainmark{bib}{both}{\bibname}
11364 \createplainmark{index}{both}{\indexname}
11365 \createplainmark{glossary}{both}{\glossaryname}
11366 }
11367 else: % aka oneside
11368 \makepsmarks{headings}{%
11369 \createmark{chapter}{right}{shownumber}{\@chapapp\ }{. \ }
11370 \createplainmark{toc}{right}{\contentsname}
11371 \createplainmark{lof}{right}{\listfigurename}
11372 \createplainmark{lot}{right}{\listtablename}
11373 \createplainmark{bib}{right}{\bibname}
11374 \createplainmark{index}{right}{\indexname}
11375 \createplainmark{glossary}{right}{\glossaryname}
11376 }
11377 fi
11378 \end{lcode}
11379 Where \cmd{\@chapapp} is a special macro what equals
11380 \cmd{\chaptername} unless \cmd{\appendix} is active, where it is then
11381 equal to \cmd{\appendixname}.
11382
11383 Note how the twosided setup only include marks for \cmd{\chapter} and
11384 \cmd{\section} and onesided only for \cmd{\chapter}.
11385
11386 \fancybreak{}
11387
11388 So what if we wanted to add support for \cmd{\subsection} to an
11389 already defined page style? Use this:
11390 \begin{syntax}
11391 \cmd{\addtopsmarks}\marg{pagestyle}\marg{prepend}\marg{append} \\
11392 \end{syntax}
11393 \glossary(addtopsmarks)%
11394 {\cs{addtopsmarks}\marg{pagestyle}\marg{prepend}\marg{append}}%
11395 {Inserts \meta{prepend} and \meta{append} before and after the current
11396 definition of \cs{makepsmarks} for \meta{pagestyle}.}
11397 Here \meta{prepend} and \meta{append} is inserted
11398 \emph{before} and \emph{after} the current definition of \cs{makepsmarks}
11399 for \meta{pagestyle}. So to answer our question we could use
11400 \begin{lcode}
11401 \addtopsmarks{headings}{}{%
11402 \createmark{subsection}{right}{shownumber}{}{. \space}}
11403 \pagestyle{headings}
11404 \end{lcode}
11405 -- always remember to activate the page style afterwards.
11406
11407 \begin{note}
11408 In my (maintainer) own documents I normally change the chapter mark
11409 to use \texttt{both} instead of \texttt{left}. This is useful when
11410 no sections are used or the chapter has a very long intro.
11411 \begin{lcode}
11412 \makeatletter
11413 \addtopsmarks{headings}{}{%
11414 \createmark{chapter}{both}{shownumber}{\@chapapp\ }{. \ }
11415 }
11416 \makeatother
11417 \pagestyle{headings}
11418 \end{lcode}
11419 \end{note}
11420
11421
11422
11423 \fancybreak{}
11424
11425 \LMnote{2010/02/08}{fixed typo}
11426
11427 When the class runs the marks part of page style, it does not zero out
11428 old marks, i.e.\ if an old \cmd{\sectionmark} exist, it still exist
11429 even if we do not change it. This is both a good and a bad thing. To
11430 help users redefine these marks to doing nothing we provide
11431 \begin{syntax}
11432 \cmd{\clearplainmark}\marg{type}\\
11433 \cmd{\clearmark}\marg{type}\\
11434 \end{syntax}
11435 The used types are the same as for \cmd{\createplainmark} and \cmd{\createmark}.
11436
11437
11438
11439
11440
11441 \subsection{Example pagestyles}
11442
11443 Perhaps when preparing drafts you want to note on each page
11444 that it is a draft\index{draft document} document. Assuming that
11445 you are using the
11446 \pstyle{headings} page style and that the default \pstyle{plain}
11447 page style is used on chapter openings, then you could define
11448 the following in the preamble (\piif{ifdraftdoc} is provided by
11449 the class and is set \ptrue\ when the \Lopt{draft} option is used).
11450 \label{ex:draft.pagestyle}
11451 \begin{lcode}
11452 \ifdraftdoc
11453 \makeevenfoot{plain}{}{\thepage}{\textit{Draft: \today}}
11454 \makeoddfoot{plain}{\textit{Draft: \today}}{\thepage}{}
11455 \makeevenfoot{headings}{}{}{\textit{Draft: \today}}
11456 \makeoddfoot{headings}{\textit{Draft: \today}}{}{}
11457 \fi
11458 \end{lcode}
11459 Now when the \Lopt{draft} option is used the word `Draft:' and the current
11460 date will be typeset in italics at the bottom of each page by the spine
11461 margin. If any \pstyle{empty} pages should be marked as well, specify
11462 similar footers for that style as well.
11463
11464 \fancybreak{}
11465
11466
11467 Here is part of the standard definition of the \pstyle{headings}
11468 pagestyle for the \Lclass{book} class which uses many internal \ltx\ commands;
11469 but note that the class does not use this!
11470 \begin{lcode}
11471 \def\ps@headings{%
11472 \let\@oddfoot\@empty\let\@evenfoot\@empty
11473 \def\@evenhead{\thepage\hfil\slshape\leftmark}%
11474 \def\@oddhead{{\slshape\rightmark}\hfil\thepage}%
11475 \def\chaptermark##1{%
11476 \markboth{\MakeUppercase{%
11477 \ifnum\c@secnumdepth > \m@ne
11478 \if@mainmatter
11479 \@chapapp\ \thechapter. \ %
11480 \fi
11481 \fi
11482 ##1}}{}}%
11483 \def\sectionmark##1{%
11484 \markright{\MakeUppercase{%
11485 \ifnum\c@secnumdepth > \z@
11486 \thesection. \ %
11487 \fi
11488 ##1}}}}
11489 \end{lcode}
11490 You don't need to understand this but in outline the first three lines specify
11491 the contents of the footers and headers, and the remainder of the code sets
11492 the marks that will be used in the headers. The \cmd{\leftmark} is specified to be
11493 the word `chapter',
11494 followed by the number if it is in the \cmd{\mainmatter} and the \texttt{secnumdepth}
11495 is such that chapters are numbered, followed by the chapter's title; all this
11496 is made to be in upper case (via the \cmd{\MakeUppercase} macro). Similarly
11497 the other mark, \cmd{\rightmark}, is the section number, if there is one, and
11498 the section's title, again all in upper case.
11499
11500 A transliteration of this code into \Mname's original coding style is:
11501 \begin{lcode}
11502 \makepagestyle{headings}
11503 \makeevenhead{headings}{\thepage}{}{\slshape\leftmark}
11504 \makeoddhead{headings}{\slshape\rightmark}{}{\thepage}
11505 \makepsmarks{headings}{%
11506 \def\chaptermark##1{%
11507 \markboth{\MakeUppercase{%
11508 \ifnum\c@secnumdepth > \m@ne
11509 \if@mainmatter
11510 \@chapapp\ \thechapter. \ %
11511 \fi
11512 \fi
11513 ##1}}{}}%
11514 \def\sectionmark##1{%
11515 \markright{\MakeUppercase{%
11516 \ifnum\c@secnumdepth > \z@
11517 \thesection. \ %
11518 \fi
11519 ##1}}}
11520 \def\tocmark{\markboth{\MakeUppercase{\contentsname}}{}}
11521 \def\lofmark{\markboth{\MakeUppercase{\listfigurename}}{}}
11522 \def\lotmark{\markboth{\MakeUppercase{\listtablename}}{}}
11523 \def\bibmark{\markboth{\MakeUppercase{\bibname}}{}}
11524 \def\indexmark{\markboth{\MakeUppercase{\indexname}}{}}
11525 \def\glossarymark{\markboth{\MakeUppercase{\glossaryname}}{}}}
11526 \end{lcode}
11527 As you can see, defining the marks for a pagestyle is not necessarily the
11528 simplest thing in the world. With the extra tools described above,
11529 this code can be reduced to
11530 \begin{lcode}
11531 \makepagestyle{headings}
11532 \makeevenhead{headings}{\thepage}{}{\slshape\leftmark}
11533 \makeoddhead{headings}{\slshape\rightmark}{}{\thepage}
11534 \makepsmarks{headings}{%
11535 \createmark{chapter}{left}{shownumber}{\@chapapp\ }{. \ }
11536 \createmark{section}{right}{shownumber}{}{. \ }
11537 \createplainmark{toc}{both}{\contentsname}
11538 \createplainmark{lof}{both}{\listfigurename}
11539 \createplainmark{lot}{both}{\listtablename}
11540 \createplainmark{bib}{both}{\bibname}
11541 \createplainmark{index}{both}{\indexname}
11542 \createplainmark{glossary}{both}{\glossaryname}
11543 }
11544 \end{lcode}
11545
11546
11547
11548
11549
11550 % However, courtesy of Lars\index{Madsen, Lars} Madsen,
11551 % help is at hand.
11552
11553 % \begin{syntax}
11554 % \cmd{\createplainmark}\marg{type}\marg{marks}\marg{text} \\
11555 % \cmd{\memUChead}\marg{text} \\
11556 % \cmd{\uppercaseheads} \cmd{\nouppercaseheads} \\
11557 % \cmd{\createmark}\marg{sec}\marg{marks}\marg{show}\marg{prefix}\marg{postfix} \\
11558 % \end{syntax}
11559 % \glossary(createplainmark)%
11560 % {\cs{createplainmark}\marg{type}\marg{marks}\marg{text}}%
11561 % {Defines the \cs{typemark} macro using \meta{text} as the mark, where
11562 % \meta{marks} is \texttt{left}, \texttt{both} or \texttt{right}.}
11563 % \glossary(createmark)%
11564 % {\cs{createmark}\marg{sec}\marg{marks}\marg{show}\marg{prefix}\marg{postfix}}%
11565 % {Defines the \cs{secmark} macro where \meta{show} (\texttt{shownumber}
11566 % or \texttt{nonumber}) controls whether the division number will be
11567 % displayed within \cs{mainmatter}, \meta{marks} is \texttt{left},
11568 % \texttt{both} or \texttt{right}, and \meta{prefix} and \meta{postfix}
11569 % are affixed before and after the \meta{sec} (division) number.}
11570 % \glossary(memUChead)%
11571 % {\cs{memUChead}\marg{text}}%
11572 % {May uppercase \meta{text}, depending on \cs{uppercaseheads} and
11573 % \cs{nouppercaseheads}.}
11574 % \glossary(uppercaseheads)%
11575 % {\cs{uppercaseheads}}%
11576 % {Defines \cs{memUChead} as equivalent to \cs{MakeTextUppercase}.}
11577 % \glossary(nouppercaseheads)%
11578 % {\cs{nouppercaseheads}}%
11579 % {Defines \cs{memUChead} as \cs{relax} (i.e., do nothing).}
11580
11581
11582 % The macro \cmd{\createplainmark} defines the \verb?\<type>mark?, where
11583 % \meta{type} is an unnumbered division-like head, such as \texttt{toc},
11584 % \texttt{lof}, \texttt{index}, using \meta{text} as the mark value, and
11585 % \meta{marks} is \texttt{left}, \texttt{both} or \texttt{right}. For example:
11586 % \begin{lcode}
11587 % \createplainmark{toc}{left}{\contentsname}
11588 % \createplainmark{lot}{right}{\listtablename}
11589 % \createplainmark{bib}{both}{\bibname}
11590 % \end{lcode}
11591 % is equivalent to
11592 % \begin{lcode}
11593 % \def\tocmark{\markboth{\memUChead{\contentsname}}{}}
11594 % \def\lotmark{\markright{\memUChead{\listtablename}}}
11595 % \def\lofmark{\markboth{\memUChead{\bibname}}{\memUChead{\bibname}}}
11596 % \end{lcode}
11597
11598 % Following the declaration \cmd{\uppercaseheads} the \cmd{\memUChead}
11599 % command is equivalent to \cmd{\MakeTextUppercase} but after the
11600 % \cmd{\nouppercaseheads} it is equivalent to \cmd{\relax} (which does nothing).
11601 % The \cmd{\createplainmark} macro wraps \cmd{\memUChead} around the \meta{text}
11602 % argument within the generated \cs{mark(both/right)} macro. By using the
11603 % \cs{(no)uppercaseheads} declarations you can control the uppercasing, or
11604 % otherwise, of the mark texts. The default is \cmd{\uppercaseheads}.
11605
11606 \LMnote{2010/02/08}{added the following paragraph}
11607 Note that if you want to use a predefined page style, but would like
11608 to not use automatic uppercasing, then issue \cs{nouppercaseheads} and
11609 reload the page style, for example with the default page style in \theclass\
11610 \begin{lcode}
11611 \nouppercaseheads
11612 \pagestyle{headings}
11613 \end{lcode}
11614
11615
11616 % The macro \cmd{\createmark}\marg{sec}\marg{marks}\marg{show}\marg{prefix}\marg{postfix}
11617 % defines the \verb?\<sec>mark? macro where \meta{sec} is a sectional division
11618 % such as \texttt{part}, \texttt{chapter}, \texttt{section}, etc.,
11619 % and \meta{show} (\texttt{shownumber}, \texttt{nonumber} or
11620 % \texttt{notitle} (implies \texttt{shownumber})) controls whether the division number will be
11621 % displayed within \cs{mainmatter}. The \meta{marks} argument is \texttt{left},
11622 % \texttt{both} or \texttt{right}, and \meta{prefix} and \meta{postfix}
11623 % are affixed before and after the division number. For example:
11624 % \begin{lcode}
11625 % \createmark{section}{left}{nonumber}{}{}
11626 % \createmark{section}{both}{nonumber}{}{}
11627 % \createmark{section}{right}{nonumber}{}{}
11628 % \end{lcode}
11629 % is equivalent to, respectively
11630 % \begin{lcode}
11631 % \def\sectionmark#1{\markboth{#1}{}}
11632 % \def\sectionmark#1{\markboth{#1}{#1}}
11633 % \def\sectionmark#1{\markight{#1}}
11634 % \end{lcode}
11635
11636 % The difference between \cmd{\createmark} and \cmd{\createplainmark} is
11637 % that the former create a macro that takes an argument, whereas
11638 % \cmd{\createplainmark} does not.
11639
11640
11641 % Using these macros \Mname's current definition of
11642 % \verb?\makepsmarks{headings}? is much simpler (it also leads to a
11643 % slightly different result as the \texttt{toc} etc., marks set both
11644 % the \cmd{\leftmark} and \cmd{\rightmark} instead of just the
11645 % \cmd{\leftmark}):
11646 % \begin{lcode}
11647 % \makepsmarks{headings}{%
11648 % \createmark{chapter}{left}{shownumber}{\@chapapp\ }{. \ }
11649 % \createmark{section}{right}{shownumber}{}{. \ }
11650 % \createplainmark{toc}{both}{\contentsname}
11651 % \createplainmark{lof}{both}{\listfigurename}
11652 % \createplainmark{lot}{both}{\listtablename}
11653 % \createplainmark{bib}{both}{\bibname}
11654 % \createplainmark{index}{both}{\indexname}
11655 % \createplainmark{glossary}{both}{\glossaryname}}
11656 % \end{lcode}
11657
11658
11659
11660
11661
11662 \PWnote{2009/07/30}{Added sections on Document title and Part title in headers}
11663 \subsubsection{Header with the document title}
11664
11665 As mentioned before, some publishers like the title of the book
11666 to be in the header. A simple header is probably all that is needed
11667 as it is unlikely to be a technical publication. Here is a
11668 use for \pstyle{myheadings}.
11669 \begin{lcode}
11670 \makevenhead{myheadings}{\thepage}{}{DOCUMENT TITLE}
11671 \makeoddhead{myheadings}{Chapter~\thechapter}{}{\thepage}
11672 \end{lcode}
11673
11674 \subsubsection{Part and chapter in the header}
11675
11676 Some documents have both part and chapter divisions and in such
11677 cases it may be useful for the reader to have the current part and chapter
11678 titles in the header. The \pstyle{headings} pagestyle can be easily modified
11679 to accomplish this by simply resetting the marks for part and chapter:
11680 \begin{lcode}
11681 \makepsmarks{headings}{%
11682 \createmark{part}{left}{shownumber}{\partname\ }{. \ }
11683 \createmark{chapter}{right}{shownumber}{\@chapapp\ }{. \ }
11684 \createplainmark{toc}{both}{\contentsname}
11685 \createplainmark{lof}{both}{\listfigurename}
11686 \createplainmark{lot}{both}{\listtablename}
11687 \createplainmark{bib}{both}{\bibname}
11688 \createplainmark{index}{both}{\indexname}
11689 \createplainmark{glossary}{both}{\glossaryname}}
11690 \end{lcode}
11691
11692
11693 \subsubsection{The Companion pagestyle}
11694
11695 This example demonstrates most of the page styling commands.
11696 In the \textit{\ltx\ Companion} series of
11697 books~\cite{COMPANION,GCOMPANION,WCOMPANION} the header\index{header} is wider
11698 than the typeblock\index{typeblock}, sticking out into the outer
11699 margin\index{margin!outer}, and has a rule underneath it.
11700 The page number is in
11701 bold and at the outer end of the header\index{header}.
11702 Chapter titles are in verso headers\index{header} and section titles
11703 in recto headers\index{header}, both in bold font and at the inner
11704 margin\index{margin!inner}. The footers\index{footer} are empty.
11705
11706 The first thing to do in implementing this style is to calculate
11707 the width of the headers\index{header}, which extend to cover any
11708 marginal\index{marginalia} notes.
11709 \begin{lcode}
11710 \setlength{\headwidth}{\textwidth}
11711 \addtolength{\headwidth}{\marginparsep}
11712 \addtolength{\headwidth}{\marginparwidth}
11713 \end{lcode}
11714 Now we can set up an empty \pstyle{companion} pagestyle and start to change
11715 it by specifying the new header\index{header} and footer\index{footer} width:
11716 \begin{lcode}
11717 \makepagestyle{companion}
11718 \makerunningwidth{companion}{\headwidth}
11719 \end{lcode}
11720 and specify the width and thickness for the header\index{header} rule,
11721 otherwise it will be invisible.
11722 \begin{lcode}
11723 \makeheadrule{companion}{\headwidth}{\normalrulethickness}
11724 \end{lcode}
11725
11726 In order to get the header\index{header} to stick out into the \foredge\
11727 margin\index{margin!foredge?\foredge}, verso headers\index{header}
11728 have to be flushright
11729 (raggedleft) and recto headers\index{header} to be flushleft (raggedright).
11730 As the footers\index{footer} are empty, their position is immaterial.
11731 \begin{lcode}
11732 \makeheadposition{companion}{flushright}{flushleft}{}{}
11733 \end{lcode}
11734
11735 The current chapter and section titles are obtained from the
11736 \cmd{\leftmark} and \cmd{\rightmark} macros which are defined via the
11737 \cmd{\chaptermark} and \cmd{\sectionmark} macros. Remember that
11738 \cmd{\leftmark} is the last \meta{left} marker and \cmd{\rightmark}
11739 is the first \meta{right} marker\index{markers} on the page.
11740
11741 Chapter numbers are not
11742 put into the header\index{header} but the section number,
11743 if there is one, is put into
11744 the header\index{header}. We have to make sure that
11745 the correct definitions are used for these as well as for the
11746 \toc\footnote{The \toc\ and friends are described in detail
11747 in \protect\Cref{chap:toc}.}
11748 and other similar elements, and this is where the
11749 \cmd{\makepsmarks} macro comes into play.
11750 \begin{lcode}
11751 \makepsmarks{companion}{%
11752 \nouppercaseheads
11753 \createmark{chapter}{both}{nonumber}{}{}
11754 \createmark{section}{right}{shownumber}{}{. \space}
11755 \createplainmark{toc}{both}{\contentsname}
11756 \createplainmark{lof}{both}{\listfigurename}
11757 \createplainmark{lot}{both}{\listtablename}
11758 \createplainmark{bib}{both}{\bibname}
11759 \createplainmark{index}{both}{\indexname}
11760 \createplainmark{glossary}{both}{\glossaryname}
11761 \end{lcode}
11762
11763 The preliminaries have all been completed, and it just remains to specify
11764 what goes into each header\index{header} and footer\index{footer} slot
11765 (but the footers\index{footer} are empty).
11766 \begin{lcode}
11767 \makeevenhead{companion}%
11768 {\normalfont\bfseries\thepage}{}{%
11769 \normalfont\bfseries\leftmark}
11770 \makeoddhead{companion}%
11771 {\normalfont\bfseries\rightmark}{}{%
11772 \normalfont\bfseries\thepage}
11773 \end{lcode}
11774
11775 Now issuing the command \verb?\pagestyle{companion}? will produce pages
11776 typeset with \pstyle{companion} pagestyle headers\index{header}. This pagestyle
11777 is part of the class.
11778
11779 % \begin{syntax}
11780 % \cmd{\addtopsmarks}\marg{pagestyle}\marg{prepend}\marg{append} \\
11781 % \end{syntax}
11782 % \glossary(addtopsmarks)%
11783 % {\cs{addtopsmarks}\marg{pagestyle}\marg{prepend}\marg{append}}%
11784 % {Inserts \meta{prepend} and \meta{append} before and after the current
11785 % definition of \cs{makepsmarks} for \meta{pagestyle}.}
11786 % \cmd{\addtopsmarks}\marg{pagestyle}\marg{prepend}\marg{append} is the last
11787 % of this group of helper macros. It inserts \meta{prepend} and \meta{append}
11788 % before and after the current definition of \cs{makepsmarks}
11789 % for \meta{pagestyle}.
11790 For instance, if you wanted \cs{subsection} titles to appear
11791 in the page headers of the \pstyle{companion} pagestyle then this would be a way
11792 of doing it:
11793 \begin{lcode}
11794 \addtopsmarks{companion}{}{%
11795 \createmark{subsection}{right}{shownumber}{}{. \space}}
11796 \end{lcode}
11797
11798
11799 \subsubsection{The ruled pagestyle}
11800
11801 For practical reasons I prefer a page style with headings
11802 where the chapter title is at least in the center
11803 of the page, and for technical works is at the \foredge. I also prefer the
11804 page number to be near the outside edge. When picking up a book and skimming
11805 through it, either to get an idea of what is in it or to find something more
11806 specific, I hold it in one hand at the spine and use the other for flicking
11807 the pages. The book is half closed while doing this and it's much easier
11808 to spot things at the \foredge\ than those nearer the spine.
11809 The \pstyle{ruled} page style is like this. The general plan is defined as:
11810 \begin{lcode}
11811 \makepagestyle{ruled}
11812 \makeevenfoot {ruled}{\thepage}{}{} % page numbers at the outside
11813 \makeoddfoot {ruled}{}{}{\thepage}
11814 \makeheadrule {ruled}{\textwidth}{\normalrulethickness}
11815 \makeevenhead {ruled}{\scshape\leftmark}{}{} % small caps
11816 \makeoddhead {ruled}{}{}{\rightmark}
11817 \end{lcode}
11818 The other part of the specification has to ensure that the \cmd{\chapter}
11819 and \cmd{\section} commands make the appropriate marks for the headers.
11820 I wanted the numbers to appear in the headers, but not those for sections. The following
11821 code sets these up, as well as the marks for the other document elements.
11822 \begin{lcode}
11823 \makepsmarks{ruled}{%
11824 \nouppercaseheads
11825 \createmark{chapter}{left}{shownumber}{}{. \space}
11826 \createmark{section}{right}{nonumber}{}{}
11827 \createplainmark{toc}{both}{\contentsname}
11828 \createplainmark{lof}{both}{\listfigurename}
11829 \createplainmark{lot}{both}{\listtablename}
11830 \createplainmark{bib}{both}{\bibname}
11831 \createplainmark{index}{both}{\indexname}
11832 \createplainmark{glossary}{both}{\glossaryname}
11833 }
11834 \end{lcode}
11835
11836 \index{pagestyle!specifying|)}
11837
11838
11839
11840 \subsection{Index headers}
11841
11842 \index{pagestyle!index pages|(}
11843
11844 If you look at the Index\index{index} you will see that the header\index{header}
11845 shows the first and last entries on the page.
11846 A main entry in the index\index{index} looks like:
11847 \begin{lcode}
11848 \item \idxmark{entry}, page number(s)
11849 \end{lcode}
11850 and in the preamble\index{preamble} to this book \cmd{\idxmark} is defined as
11851 \begin{lcode}
11852 \newcommand{\idxmark}[1]{#1\markboth{#1}{#1}}
11853 \end{lcode}
11854 This typesets the entry and also uses the entry as markers so that
11855 the first entry on a page is held in \cmd{\rightmark} and the last
11856 is in \cmd{\leftmark}.
11857
11858 As index\index{index} entries are usually very short, the
11859 Index\index{index} is set in two columns\index{column!double}.
11860 Unfortunately \ltx's marking mechanism can be very
11861 fragile on twocolumn\index{column!double} pages.\footnote{This was
11862 fixed in the \LaTeX{} kernel, but including the functionality from
11863 the \Lpack{fixltx2e} package.}
11864
11865 The index\index{index} itself is called by\index{indexing}
11866 \begin{lcode}
11867 \clearpage
11868 \pagestyle{index}
11869 \renewcommand{\preindexhook}{%
11870 The first page number is usually, but not always,
11871 the primary reference to
11872 the indexed topic.\vskip\onelineskip}
11873 \printindex
11874 \end{lcode}
11875
11876 \makepagestyle{index}
11877 \makeheadrule{index}{\textwidth}{\normalrulethickness}
11878 \makeevenhead{index}{\rightmark}{}{\leftmark}
11879 \makeoddhead{index}{\rightmark}{}{\leftmark}
11880 \makeevenfoot{index}{\thepage}{}{}
11881 \makeoddfoot{index}{}{}{\thepage}
11882
11883 The \pstyle{index} pagestyle, which is the crux of
11884 this example, is defined here as:
11885 \begin{lcode}
11886 \makepagestyle{index}
11887 \makeheadrule{index}{\textwidth}{\normalrulethickness}
11888 \makeevenhead{index}{\rightmark}{}{\leftmark}
11889 \makeoddhead{index}{\rightmark}{}{\leftmark}
11890 \makeevenfoot{index}{\thepage}{}{}
11891 \makeoddfoot{index}{}{}{\thepage}
11892 \end{lcode}
11893 This, as you can hopefully see, puts the first and last index\index{index}
11894 entries on the page into the header\index{header} at the left and right,
11895 with the folios\index{folio} in the footers\index{footer} at the
11896 outer margin\index{margin!outer}.
11897
11898 \index{pagestyle!index pages|)}
11899
11900 \subsection{Float pages}
11901
11902 \index{pagestyle!float pages|(}
11903 \index{float!page|(}
11904
11905 \begin{syntax}
11906 \piif{ifonlyfloats}\marg{yes}\marg{no} \\
11907 \end{syntax}
11908 \glossary(ifonlyfloats)%
11909 {\cs{ifonlyfloats}\marg{yes}\marg{no}}%
11910 {Processes \meta{yes} on a page containing only floats, otherwise process
11911 \meta{no}.}
11912 There are occasions when it is desirable to have different
11913 headers\index{header} on pages that only contain figures\index{figure}
11914 or tables\index{table}. If the command \piif{ifonlyfloats}
11915 is issued on a page that contains no text and only floats then the \meta{yes}
11916 argument is processed, otherwise on a normal page the \meta{no} argument
11917 is processed. The command is most useful when defining a pagestyle that
11918 should be different on a float-only page\index{page!of floats}.
11919
11920 For example, assume that the \pstyle{companion} pagestyle is to be
11921 generally used, but on float-only pages all that is required is a pagestyle
11922 similar to \pstyle{plain}. Borrowing some code from the \pstyle{companion}
11923 specification this can be accomplished like:
11924 \begin{lcode}
11925 \makepagestyle{floatcomp}
11926 % \headwidth has already been defined for the companion style
11927 \makeheadrule{floatcomp}{\headwidth}%
11928 {\ifonlyfloats{0pt}{\normalrulethickness}}
11929 \makeheadposition{floatcomp}{flushright}{flushleft}{}{}
11930 \makepsmarks{floatcomp}{\companionpshook}
11931 \makeevenhead{floatcomp}%
11932 {\ifonlyfloats{}{\normalfont\bfseries\thepage}}%
11933 {}%
11934 {\ifonlyfloats{}{\normalfont\bfseries\leftmark}}
11935 \makeoddhead{floatcomp}%
11936 {\ifonlyfloats{}{\normalfont\bfseries\rightmark}}%
11937 {}%
11938 {\ifonlyfloats{}{\normalfont\bfseries\thepage}}
11939 \makeevenfoot{floatcomp}{}{\ifonlyfloats{\thepage}{}}{}
11940 \makeoddfoot{floatcomp}{}{\ifonlyfloats{\thepage}{}}{}
11941 \end{lcode}
11942 The code above for the \pstyle{floatcomp} style should be compared with
11943 that for the earlier \pstyle{companion} style.
11944
11945 The headrule is invisible\index{rule!thickness}\index{rule!invisible}
11946 on float pages by giving it zero thickness,
11947 otherwise it has the \cmd{\normalrulethickness}. The head position is
11948 identical for both pagestyles. However, the headers\index{header} are empty for
11949 \pstyle{floatcomp} and the footers\index{footer} have centered page numbers
11950 on float pages; on ordinary pages the footers\index{footer} are empty
11951 while the headers\index{header}
11952 are the same as the \pstyle{companion} headers\index{header}.
11953
11954 The code includes one `trick'. The macro \cmd{\makepsmarks}\verb?{X}{code}?
11955 is equivalent to
11956 \begin{lcode}
11957 \newcommand{\Xpshook}{code}
11958 \end{lcode}
11959 I have used this knowledge in the line:
11960 \begin{lcode}
11961 \makepsmarks{floatcomp}{\companionpshook}
11962 \end{lcode}
11963 which avoids retyping the code from
11964 \verb?\makepsmarks{companion}{...}?,
11965 and ensures that the code is actually the same for the two pagestyles.
11966
11967 \begin{syntax}
11968 \cmd{\mergepagefloatstyle}\marg{style}\marg{textstyle}\marg{floatstyle} \\
11969 \end{syntax}
11970 If you have two pre-existing pagestyles, one that will be used for
11971 text pages and the other that can be used for float pages, then the
11972 \cmd{\mergepagefloatstyle} command provides a simpler means of
11973 combining\index{pagestyle!combining}
11974 them than the above example code for \pstyle{floatcomp}. The argument
11975 \meta{style} is the name of the pagestyle being defined. The
11976 argument \meta{textstyle}
11977 is the name of the pagestyle for text pages and \meta{floatstyle} is the
11978 name of the pagestyle for float-only pages. Both of these must have been
11979 defined before calling \cmd{\mergepagefloatstyle}. So, instead of the long
11980 winded, and possibly tricky, code I could have simply said:
11981 \begin{lcode}
11982 \mergepagefloatstyle{floatcomp}{companion}{plain}
11983 \end{lcode}
11984
11985
11986 One author thought it would be nice to be able to have different
11987 page headings according
11988 to whether the page was a floatpage, or there was a float at the top of
11989 the page, or a float at the bottom of a page or there was text at the
11990 top and bottom.
11991
11992 This, I think, is not a common requirement and, further, that to provide
11993 this involves changing parts of the LaTeX output routine --- something only
11994 to be tackled by the bravest of the brave. If it were to be done then were
11995 best done in a package that could be easily ignored. The following is an
11996 outline of what might be done; I do not recommend it and if you try this
11997 and all your work dissappears then on your own head be it.
11998
11999 \begin{lcode}
12000 % notefloat.sty
12001 \newif\iffloatattop
12002 \floatattopfalse
12003 \newif\iffloatatbot
12004 \floatatbotfalse
12005
12006 \renewcommand*{\@addtotoporbot}{%
12007 \@getfpsbit \tw@
12008 \ifodd \@tempcnta
12009 \@flsetnum \@topnum
12010 \ifnum \@topnum>\z@
12011 \@tempswafalse
12012 \@flcheckspace \@toproom \@toplist
12013 \if@tempswa
12014 \@bitor\@currtype{\@midlist\@botlist}%
12015 \if@test
12016 \else
12017 \@flupdates \@topnum \@toproom \@toplist
12018 \@inserttrue
12019 \global\floatattoptrue
12020 \fi
12021 \fi
12022 \fi
12023 \fi
12024 \if@insert
12025 \else
12026 \@addtobot
12027 \fi}
12028
12029 \renewcommand*{\@addtobot}{%
12030 \@getfpsbit 4\relax
12031 \ifodd \@tempcnta
12032 \@flsetnum \@botnum
12033 \ifnum \@botnum>\z@
12034 \@tempswafalse
12035 \@flcheckspace \@botroom \@botlist
12036 \if@tempswa
12037 \global \maxdepth \z@
12038 \@flupdates \@botnum \@botroom \@botlist
12039 \@inserttrue
12040 \global\floatatbottrue
12041 \fi
12042 \fi
12043 \fi}
12044
12045 \let\p@wold@output\@outputpage
12046 \renewcommand*{\@outputpage}{%
12047 \p@wold@output
12048 \global\floatattopfalse
12049 \global\floatatbotfalse}
12050
12051 \endinput
12052 \end{lcode}
12053 \cs{floatattop} is probably set \ptrue\ if there is a float at the
12054 top of the page and
12055 \cs{floatatbot} is probably set \ptrue\ if there is a float at the bottom
12056 of the page.
12057
12058
12059 \index{float!page|)}
12060 \index{pagestyle!float pages|)}
12061
12062 \section{The showlocs pagestyle}
12063
12064 The \pstyle{showlocs} pagestyle is somewhat special as it is meant to be
12065 used as an aid when designing a page layout. Lines are drawn showing the
12066 vertical positions of the headers and footers and a box is drawn around
12067 the textblock. It is implemented using two
12068 zero-sized\index{zero-sized picture} pictures.\verbfootnote{A
12069 zero-sized picture starts off with \verb?begin{picture}(0,0)...?.}
12070 \begin{syntax}
12071 \cmd{\framepichead} \\
12072 \cmd{\framepictextfoot} \\
12073 \cmd{\framepichook} \\
12074 \cmd{\showheadfootlocoff} \\
12075 \cmd{\showtextblockoff} \\
12076 \end{syntax}
12077 \glossary(framepichead)%
12078 {\cs{framepichead}}%
12079 {Used by the \Ppstyle{showlocs} pagestyle to draw a line at the header
12080 location.}
12081 \glossary(framepictextfoot)%
12082 {\cs{framepictextfoot}}%
12083 {Used by the \Ppstyle{showlocs} pagestyle to draw a box around the textblock
12084 and a line at the footer location.}
12085 \glossary(framepichook)%
12086 {\cs{framepichook}}%
12087 {First thing called inside the zero width pictures provided by
12088 \cs{framepichead} and \cs{framepictextfoot}. Empty by default.}%
12089 \glossary(showtextblockoff)%
12090 {\cs{showtextblockoff}}%
12091 {Prevents \cs{framepictextfoot} from drawing a box around the textblock.}
12092 \glossary(showheadfootlocoff)%
12093 {\cs{showheadfootlocoff}}%
12094 {Prevents \cs{framepichead} and \cs{framepictextfoot} from drawing
12095 lines at the header and footer locations.}
12096 %
12097 The macro \cmd{\framepichead} creates a zero-sized\index{zero-sized picture}
12098 picture that draws a line at the header location, and the macro
12099 \cmd{\framepictextfoot} creates a zero-sized\index{zero-sized picture}
12100 picture that draws a line at the footer location
12101 and also draws a box around the typeblock. Following the declaration
12102 \cmd{\showheadfootlocoff} the macros \cmd{\framepichead} and
12103 \cmd{\framepictextfoot} do not draw lines showing the header and footer
12104 locations. The declaration \cmd{\showtextblockoff} prevents
12105 \cmd{\framepictextfoot} from drawing a box around the textblock.
12106
12107 In case you want to change the color of the \pstyle{showlocs}, simply do
12108 \begin{lcode}
12109 \renewcommnand\framepichook{\color{red}}
12110 \end{lcode}
12111
12112
12113
12114 If you generally want a box around the textblock you may want to create
12115 your own pagestyle using \cmd{\framepictextfoot} and the \pstyle{showlocs}
12116 code as a starting point, see \path{memoir.cls} for details.
12117
12118
12119 \section{Other things to do with page styles}
12120 \label{sec:other-things-do}
12121
12122 Back on \pref{ex:draft.pagestyle} we presented a way of adding some
12123 draft information. Here is a more advanced example of this.
12124
12125 One interesting use for page styles is to provide extra information
12126 below the footer. This might be some kind of copyright information. Or
12127 if your document is under version control with a system like
12128 Subversion, and you have all your chapter laying in seperate files,
12129 then why not add information at the start of very chapter, specifying
12130 who did the last change to this chapter at which time. See the
12131 \texttt{svn-multi} package (\cite{svn-multi}) and the Prac\TeX{}
12132 Journal article \cite{practex-2007-3-ms} by the same author. Then this
12133 information can be added to the start of every chapter using something
12134 like:
12135 \begin{lcode}
12136 \usepackage[filehooks]{svn-multi}
12137 \makeatletter
12138 % remember to define a darkgray color
12139 \newcommand\addRevisionData{%
12140 \begin{picture}(0,0)%
12141 \put(0,-10){%
12142 \tiny%
12143 \expandafter\@ifmtarg\expandafter{\svnfiledate}{}{%
12144 \textcolor{darkgray}{Chapter last updated
12145 \svnfileyear/\svnfilemonth/\svnfileday
12146 \enspace \svnfilehour:\svnfileminute\ (revision \svnfilerev)}
12147 }%
12148 }%
12149 \end{picture}%
12150 }
12151 \makeatother
12152 % chapter is normally an alias to the plain style, we want to change
12153 % it, so make it a real pagestyle
12154 \makepagestyle{chapter}
12155 \makeoddfoot{chapter}{\addRevisionData}{\thepage}{}
12156 \makeevenfoot{chapter}{\addRevisionData}{\thepage}{}
12157 \end{lcode}
12158
12159
12160 %#% extend
12161 %#% extstart include paragraphs-and-lists.tex
12162
12163 \svnidlong
12164 {$Ignore: $}
12165 {$LastChangedDate: 2025-08-08 14:39:37 +0200 (Fri, 08 Aug 2025) $}
12166 {$LastChangedRevision: 859 $}
12167 {$LastChangedBy: [email protected] $}
12168
12169 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
12170
12171
12172
12173 \chapter{Paragraphs and lists}
12174
12175 %%%%%%%%%%%%%%%%%%%%%
12176 %\tightlists
12177 %%%%%%%%%%%%%%%%%%%%%
12178
12179 Within a sectional division the text is typically broken up into
12180 paragraphs. Sometimes there may be text that is set off from the normal
12181 paragraphing, like quotations\index{quotation} or lists.
12182
12183 \section{Paragraphs}
12184
12185 \index{paragraph|(} %|
12186
12187 There are basically two parameters that control the appearance of normal
12188 paragraphs.
12189
12190 \begin{syntax}
12191 \lnc{\parindent} \lnc{\parskip} \\
12192 \end{syntax}
12193 \glossary(parskip)%
12194 {\cs{parskip}}%
12195 {(Extra) vertical space between paragraphs (default 0pt).}
12196
12197 The length \lnc{\parindent} is the indentation of the first line of a
12198 paragraph\index{paragraph!indentation} and the length \lnc{\parskip} is the vertical spacing between
12199 paragraphs, as illustrated in \fref{fig:para}. The value of \lnc{\parskip}
12200 is usually 0pt, and \lnc{\parindent} is usually defined in terms of ems so
12201 that the actual indentation depends on the font being used. If \lnc{\parindent}
12202 is set to a negative length, then the first line of the paragraphs will be
12203 `outdented'\index{paragraph!outdentation} into the lefthand
12204 margin\index{margin!left}.
12205
12206 \begin{figure}
12207 \centering
12208 \drawparameterstrue
12209 \drawparagraph
12210 \caption{Paragraphing parameters}\label{fig:para}
12211 \end{figure}
12212
12213 \subsection{Block paragraph}
12214
12215 A block paragraph\index{paragraph!block} is obtained by setting
12216 \lnc{\parindent} to 0em;
12217 \lnc{\parskip} should be set to some positive value so that there is some
12218 space between paragraphs to enable them to be identified. Most typographers
12219 heartily dislike block paragraphs, not only on aesthetical grounds but also
12220 on practical\index{paragraph!block!reasons against} considerations.
12221 Consider what happens if the last line of a block
12222 paragraph is full and also is the last line on the page. The following
12223 block paragraph will start at the top of the next page but there will be
12224 no identifiable space to indicate an inter-paragraph break.
12225
12226 It is important to know that \ltx\
12227 typesets\index{paragraph!typeset as a unit}
12228 paragraph by paragraph.
12229 For example, the \lnc{\baselineskip} that is used for a paragraph is the value
12230 that is in effect at the end of the paragraph, and the font size used for a
12231 paragraph is according to the size declaration (e.g., \cmd{\large} or
12232 \cmd{\normalsize} or \cmd{\small}) at the end of the paragraph,
12233 and the raggedness or otherwise of the whole paragraph depends on
12234 the declaration (e.g., \cmd{\centering}) in effect at the end of
12235 the paragraph. If a pagebreak occurs in the middle of a paragraph \tx\
12236 will not reset the part of the paragraph that goes onto the following
12237 page, even if the textwidths on the two pages are different.
12238
12239 \subsection{Hanging paragraphs}
12240
12241 \index{paragraph!hanging|(} %|
12242
12243 A hanging paragraph is one where the length of the first few lines differs
12244 from the length of the remaining lines. (A normal indented paragraph
12245 may be considered
12246 to be a special case of a hanging paragraph where `few = one').
12247
12248 \begin{syntax}
12249 \cmd{\hangpara}\marg{indent}\marg{num} \\
12250 \end{syntax}
12251 \glossary(hangpara)%
12252 {\cs{hangpara}\marg{indent}\marg{num}}%
12253 {Apply \meta{indent} for \meta{num} lines to the immediately following
12254 paragraph.}
12255
12256 \hangpara{3em}{-3}%
12257 Using \cmd{\hangpara} at the start of a paragraph will cause the paragraph
12258 to be hung. If the length \meta{indent} is positive the lefthand end of the
12259 lines will be indented but if it is negative the righthand ends will be
12260 indented by the specified amount.
12261 If the number \meta{num}, say N, is negative the first N lines of
12262 the paragraph will be indented while if N is positive the N+1 th lines onwards
12263 will be indented. This paragraph was set with \verb?\hangpara{3em}{-3}?. There
12264 should be no space between the \cmd{\hangpara} command and the start of the
12265 paragraph.
12266
12267 \begin{syntax}
12268 \senv{hangparas}\marg{indent}\marg{num} text \eenv{hangparas} \\
12269 \end{syntax}
12270 \glossary(hangparas)%
12271 {\senv{hangparas}\marg{indent}\marg{num}}%
12272 {Environment form of \cs{hangpara}, applying it to every paragraph in the
12273 environment.}
12274 The \Ie{hangparas} environment is like the \cmd{\hangpara} command except
12275 that every paragraph in the environment will be hung.
12276
12277 The code implementing the hanging paragraphs is the same as for
12278 the \Lpack{hanging} package~\cite{HANGING}. Examples of some uses
12279 can be found in~\cite{TTC199}.
12280
12281 As noted eleswhere the sectioning commands use the internal
12282 macro \cmd{\@hangfrom} as part of the formatting of the titles.
12283
12284 \begin{syntax}
12285 \cmd{\hangfrom}\marg{text} \\
12286 \end{syntax}
12287 \glossary(hangfrom)%
12288 {\cs{hangfrom}\marg{stuff}}%
12289 {Hangs a paragraph from \meta{stuff}.}
12290 The \cmd{\hangfrom} macro is provided as an author's version of the
12291 internal \cmd{\@hangfrom} macro used, among other things, in typesetting
12292 section titles.
12293
12294 \hangfrom{Simple hung paragraphs }(like this one) can be specified
12295 using the \cmd{\hangfrom} macro. The macro puts \meta{text} in a box
12296 and then makes a hanging paragraph of the following material. This
12297 paragraph commenced with \\
12298 \verb?\hangfrom{Simple hung paragraphs }(like ...? \\
12299 and you are now reading the result.
12300
12301 The commands for hanging paragraphs do not quite work as might be
12302 expected when they are used in a list\index{paragraph!hanging!in list}
12303 environment, for example inside
12304 an \Ie{enumerate}. If you wish for a hanging paragraph inside such an
12305 environment you will have to define your own commands for this. If you
12306 feel capable of doing so then, with my congratulations, move on to the
12307 next section. If you are not so confident you could try using the following
12308 non-guaranteed code, which is based on an idea by Patrik
12309 Nyman\index{Nyman, Patrick} which he posted on \ctt{} in January 2004.
12310 \begin{lcode}
12311 %\makeatletter
12312 % A version of \hangpara for use in a list
12313 % \listhanging{indent}{num} text text text ...
12314 \def\listhanging#1#2#3\par{%
12315 \@tempdima\textwidth \advance\@tempdima -\leftmargin
12316 \parbox{\@tempdima}{\hangpara{#1}{#2}#3}\par}
12317 % A version of \hangfrom for use in a list
12318 % \listhangfrom{stuff} text text text ...
12319 \def\listhangfrom#1#2\par{%
12320 \@tempdima\textwidth \advance\@tempdima -\leftmargin
12321 \parbox{\@tempdima}{\@hangfrom{#1}#2}\par}
12322 %\makeatother
12323 \end{lcode}
12324
12325
12326 \index{paragraph!hanging|)}%|
12327
12328 \index{paragraph|)} %|
12329
12330 \section{Flush and ragged}
12331
12332 Flushleft\index{flushleft} text has the lefthand end of the lines
12333 aligned vertically at the lefthand margin\index{margin!left} and
12334 flushright\index{flushright} text has the righthand end of the lines
12335 aligned vertically at the righthand margin\index{margin!right}. The
12336 opposites of these are raggedleft\index{raggedleft} text where the
12337 lefthand ends are not aligned
12338 and raggedright\index{raggedright} where the righthand end of lines are
12339 not aligned. LaTeX normally typesets flushleft and flushright.
12340
12341 \begin{syntax}
12342 \senv{flushleft} text \eenv{flushleft} \\
12343 \senv{flushright} text \eenv{flushright} \\
12344 \senv{center} text \eenv{center} \\
12345 \end{syntax}
12346 \glossary(flushleft)%
12347 {\senv{flushleft}}%
12348 {Text to be typeset flushleft and raggedright.}
12349 \glossary(flushright)%
12350 {\senv{flushright}}%
12351 {Text to be typeset flushright and raggedleft.}
12352 \glossary(center)%
12353 {\senv{center}}%
12354 {Text to be set raggedleft and raggedright, with each line centered.}
12355 Text in a \Ie{flushleft} environment is typeset flushleft and raggedright,
12356 while in a \Ie{flushright} environment is typeset raggedleft and flushright.
12357 In a \Ie{center} environment the text is set raggedleft and raggedright,
12358 and each line is centered. A small vertical space is put before and after
12359 each of these environments.
12360
12361 \begin{syntax}
12362 \cmd{\raggedleft} \cmd{\raggedright} \cmd{\centering} \\
12363 \end{syntax}
12364 \glossary(raggedleft)
12365 {\cs{raggedleft}}%
12366 {Declaration for text to be set raggedleft and flushright.}
12367 \glossary(raggedright)
12368 {\cs{raggedright}}%
12369 {Declaration for text to be set flushleft and raggedright.}
12370 \glossary(centering)%
12371 {\cs{centering}}%
12372 {Declaration for text to be set raggedleft and raggedright,
12373 with each line centered.}
12374 The \cmd{\raggedleft} declaration can be used to have text typeset
12375 raggedleft and flushright, and similary the declaration \cmd{\raggedright}
12376 causes typesetting to be flushleft and raggedright. The declaration
12377 \cmd{\centering} typesets raggedleft and raggedright with each line centered.
12378 Unlike the environments, no additional space is added.
12379
12380 \begin{syntax}
12381 \cmd{\centerfloat} \\
12382 \end{syntax}
12383 \glossary(centerfloat)%
12384 {\cs{centerfloat}}%
12385 {Within a float, centers it with respect to the typeblock; the float
12386 may extend into both margins.}
12387 \indextwo{float}{centering}
12388 The contents of floats like tables or figures are usually centered
12389 and \cmd{\centering}
12390 should be used for this, not the \Ie{center} environment which adds extra,
12391 usually undesired, vertical space. For example:
12392 \begin{lcode}
12393 \begin{figure}
12394 \centering
12395 ...
12396 \caption{...}
12397 \end{figure}
12398 \end{lcode}
12399 However, if the float is wider than the
12400 textblock then it is aligned with the left margin and extends into the right
12401 margin. The command \cmd{\centerfloat} is a special version of \cmd{\center}
12402 that when used in a wide float will center it with respect to the textblock,
12403 i.e., it will extend equally into both margins. Note that \cmd{\centerfloat}
12404 needs to be applied where there is a known width; if applied to a regular
12405 text paragraph it will center the paragraph but put all the text on one line.
12406
12407 \begin{syntax}
12408 \cmd{\raggedyright}\oarg{space} \\
12409 \lnc{\ragrparindent} \\
12410 \end{syntax}
12411 \glossary(raggedyright)%
12412 {\cs{raggedyright}\oarg{space}}%
12413 {Version of \cs{raggedright} with \meta{space} providing control
12414 over the amount of raggedness.}
12415 \glossary(ragrparindent)%
12416 {\cs{ragrparindent}}%
12417 {The \cs{parindent} for \cs{raggedyright} paragraphs.}
12418 When using \cmd{\raggedright} in narrow columns the right hand edge tends to
12419 be too ragged, and paragraphs are not indented.
12420 Text set \cmd{\raggedyright} usually fills more of the available
12421 width and paragraphs are indented by \lnc{\ragrparindent}, which is initially
12422 set to \lnc{\parindent}. The optional \meta{space} argument, whose default
12423 is 2em, can be used to adjust the amount of raggedness. As examples:
12424 \begin{lcode}
12425 \raggedyright[0pt] % typeset flushright
12426 \raggedyright[1fil] % same as \raggedright
12427 \raggedyright[0.5em] % less ragged than \raggedright
12428 \end{lcode}
12429
12430 Remember that \ltx\ typesets on a per-paragraph\index{paragraph!typeset as a unit}
12431 basis, so that putting
12432 the sequence of \cmd{\centering}, \cmd{\raggedleft} declarations in the same
12433 paragraph\index{paragraph} will cause the entire paragraph to be typeset
12434 raggedleft and
12435 flushright --- the \cmd{\centering} declaration is not the one in effect
12436 at the end of the paragraph.
12437
12438 \section{Quotations}
12439
12440 LaTeX provides two environments that are typically used for typesetting
12441 quotations\index{quotation}.
12442
12443 \begin{syntax}
12444 \senv{quote} text \eenv{quote} \\
12445 \senv{quotation} text \eenv{quotation} \\
12446 \end{syntax}
12447 \glossary(quote)%
12448 {\senv{quote}}%
12449 {Contents set justified in a narrower measure, with zero \cs{parindent}.}
12450 \glossary(quotation)%
12451 {\senv{quotation}}%
12452 {Contents set justified in a narrower measure with normal \cs{parindent}.}
12453
12454 In both of these environments the text is set flushleft and flushright
12455 in a measure that is smaller than the normal textwidth. The only difference
12456 between the two environments is that paragraphs\index{paragraph!indentation}
12457 are not indented in the \Ie{quote}
12458 environment but normal paragraphing is used in the \Ie{quotation} environment.
12459
12460
12461 \begin{egresult}[Setting the source of a quotation]{eg:quotesource}
12462 \begin{quotation}
12463 \hspace*{-0.5\parindent}This quotation has a short last line so there there is enough space
12464 for the source to be set at
12465 the end of the line.\sourceatright{I. M. Short}
12466 \end{quotation}
12467
12468 \begin{quotation}
12469 The last line of this quotation turns out to be too long for
12470 the source to be set at the end, so it is automatically
12471 set flushright on the following line.\sourceatright{N. O. Space}
12472 \end{quotation}
12473 \end{egresult}
12474
12475 \begin{syntax}
12476 \cmd{\sourceatright}\oarg{length}\marg{text} \\
12477 \end{syntax}
12478 \glossary(sourceatright)%
12479 {\cs{sourceatright}\oarg{length}\marg{text}}%
12480 {At the end of a paragraph puts \meta{text} at the end of the line
12481 if the line is short enough for a space \meta{length} and the \meta{text},
12482 otherwise puts \meta{text} flushright on the following line.}
12483 Some quotations are completed by giving the source or author. Using
12484 \cmd{\sourceatright} at the end of the quotation will typeset \meta{text}
12485 flushright at the end of the line if there is enough space, otherwise it
12486 typesets it flushright on the next line. A space \meta{length} (default 2em)
12487 is left between the end of the quote and \meta{text}.
12488
12489 \begin{egsource}{eg:quotesource}
12490 \begin{quotation}
12491 This quotation has a short last line so there there is enough space
12492 for the source to be set at
12493 the end of the line.\sourceatright{I. M. Short}
12494 \end{quotation}
12495
12496 \begin{quotation}
12497 The last line of this quotation turns out to be too long for
12498 the source to be set at the end, so it is automatically
12499 set flushright on the following line.\sourceatright{N. O. Space}
12500 \end{quotation}
12501 \end{egsource}
12502
12503 \section{Some less common paragraph shapes}
12504
12505 The paragraph shapes described in this section are based on a series
12506 that I presented in my \emph{Glisterings} column~\cite{GLISTER07,GLISTER08}.
12507 Like the earlier \cmd{\centering}, etc., paragraph style declarations, the
12508 style that applies is the one in effect at the \emph{end} of the paragraph.
12509 Thus the general usage is:
12510 \begin{lcode}
12511 \bgroup% a group to keep changes local % or could be { or \begin...
12512 \paragraphstyle
12513 .... text
12514 \par% ensure the end of a paragraph
12515 \egroup% end the group % or could be } or \end...
12516 \end{lcode}
12517
12518 If you use one of these paragraph shapes then using \cmd{\\} to break
12519 a line may give a surprising result. If so, the following may help.
12520 \begin{syntax}
12521 \cmd{\atcentercr} \\
12522 \cmd{\break} \\
12523 \cmd{\memorigdbs} \\
12524 \cmd{\memorigpar} \\
12525 \end{syntax}
12526 \glossary(atcentercr)%
12527 {\cs{atcentercr}}%
12528 {Breaks a line in a (unusual) paragraph.}
12529 \glossary(break)%
12530 {\cs{break}}%
12531 {TeX macro to break a line.}
12532 \glossary(memorigdbs)%
12533 {\cs{memorigdbs}}%
12534 {Stores the original definition of \texttt{\bs}\texttt{\bs}.} % not \cs{\}
12535 \glossary(memorigpar)%
12536 {\cs{memorigpar}}%
12537 {Stores the original definition of %\texttt{\bs}\texttt{par}.}
12538 \cs{par}.}
12539 You could try \cmd{\atcentcr}, which is user level version of an internal
12540 \ltx\ command used in some paragraph settings for line breaking,
12541 or \cmd{\break}, which is a \tx\ command to end a line.
12542
12543 In some cases the paragraph shaping commands change the definitions
12544 of \cmd{\\} or \cs{par}. Just in case you need to restore them, copies
12545 of the original definitions are in
12546 \cmd{\memorigdbs} (for \cmd{\\}) and \cmd{\memorigpar} (for \cs{par}).
12547
12548 \begin{syntax}
12549 \cmd{\flushleftright} \\
12550 \end{syntax}
12551 \glossary(flushleftright)%
12552 {\cs{flushleftright}}%
12553 {Following this declaration paragraphs are set in their usual form.}
12554
12555 If you use one of the shapes listed later in this section and things
12556 go wrong, the declaration \cmd{\flushleftright} returns all paragraphing
12557 parameters\footnote{Except for the \cs{parindent}, which it leaves at its
12558 current value.}
12559 to their normal values, thus producing paragraphs as normal ---
12560 justified left and right with the last line flushleft and raggedright.
12561
12562
12563 \subsection{Last line not short}
12564
12565 On occasion a paragraph may end with a single short word as the last
12566 line.
12567
12568 \begin{syntax}
12569 \cmd{\linenottooshort}\oarg{length} \\
12570 \end{syntax}
12571 \glossary(linenottooshort)%
12572 {\cs{linenottooshort}\oarg{length}}%
12573 {Following this declaration the last line of a paragraph will not be
12574 shorter than \meta{length} (default 2em).}
12575 Following the \cmd{\linenottooshort} declaration paragraphs will be set
12576 as normal, except that the last line will not be shorter than
12577 \meta{length} (default 2em).
12578
12579
12580 \begin{egresult}[Paragraph's line not too short]{eg:nottooshort}
12581 \linenottooshort[4em]
12582 The last line of this paragraph will be no shorter than a particular
12583 length. a b c d e f g h i % j k l m n
12584
12585 The last line of this paragraph will be no shorter than a particular
12586 length. a b c d e f g h i j k % l m n
12587 \end{egresult}
12588
12589 \begin{egsource}{eg:nottooshort}
12590 \linenottooshort[4em]
12591 The last line of this paragraph will be no shorter than a particular
12592 length. a b c d e f g h i % j k l m n
12593
12594 The last line of this paragraph will be no shorter than a particular
12595 length. a b c d e f g h i j k % l m n
12596 \end{egsource}
12597
12598 \subsection{Russian typography}
12599
12600 Apparently in the Russian typographic tradition the last line of a
12601 multiline paragraph must either be at least as long as the \lnc{\parindent}
12602 and have at least \lnc{\parindent} at the end, or it must fill
12603 the whole line (i.e., flushleft and flushright).
12604
12605 \begin{syntax}
12606 \cmd{\russianpar} \\
12607 \end{syntax}
12608 \glossary(russianpar)%
12609 {\cs{russianpar}}%
12610 {Ending a paragraph with \cs{russianpar} causes it to be set
12611 following Russian typographic rules.}
12612 Ending a paragraph with \cmd{\russianpar} causes it to be set following
12613 Russian typographic rules.
12614
12615 If you have many such paragraphs it may be more convenient to do it like:
12616 \begin{lcode}
12617 \let\par\russianpar
12618 ... many paragraphs
12619 \let\par\memorigpar
12620 \end{lcode}
12621 or as:
12622 \begin{lcode}
12623 \begingroup% start a group
12624 \let\par\russianpar
12625 ... many paragraphs
12626 \endgroup% end the group
12627 \end{lcode}
12628
12629
12630 \subsection{Fill with rules}
12631
12632 In some legal documents there must be no space at the end of the lines
12633 in order to prevent anyone inserting something at a later date. Typically
12634 it is only the last line in a paragraph that needs this treatment.
12635
12636 \begin{syntax}
12637 \cmd{\lastlinerulefill} \\
12638 \cmd{\lastlineparrule} \\
12639 \end{syntax}
12640 \glossary(lastlinerulefill)%
12641 {\cs{lastlinerulefill}}%
12642 {Ending a paragraph with this will cause any spaces at the ends of
12643 the lines will be filled with a rule (\cs{lastlineparrule}).}
12644 \glossary(lastlineparrule)%
12645 {\cs{lastlineparrule}}%
12646 {The rule used by \cs{lastlinerulefill} to eliminate spaces at
12647 the ends of lines.}
12648
12649 \begin{egresult}[Rules for spaces]{eg:rulefill}
12650 The last line of this paragraph will be be set by ending it with
12651 a rule to fill up any space.\lastlinerulefill
12652 \end{egresult}
12653
12654
12655 \begin{egsource}{eg:rulefill}
12656 The last line of this paragraph will be be set by ending it with
12657 a rule to fill up any space.\lastlinerulefill
12658 \end{egsource}
12659
12660
12661 Using \cmd{\lastlinerulefill} to end a paragraph will cause any spaces
12662 at the ends of the lines to be filled with the \cmd{\lastlineparrule} rule.
12663 If you have many paragraphs of this kind then try:
12664 \begin{lcode}
12665 \let\par\lastlinerulefill
12666 .... many paragraphs
12667 \let\par\memorigpar
12668 \end{lcode}
12669 Remember that \ltx\ treats many constructs (like section headings or captions)
12670 as paragraphs, so you may have to alternate between filled text paragraphs
12671 and regular paragraphing.
12672
12673
12674
12675 \subsection{Some ragged paragraphs}
12676
12677 A few paragraph shapes with unusual ragged lines are available.
12678
12679 \begin{egresult}[Ragged paragraphs]{eg:raggeds}
12680 \justlastraggedleft
12681 Paragraphs following the \verb?\justlastraggedleft? declaration, as
12682 this one does, have their lines justified except for the last which
12683 is set raggedleft. The demonstration works best if there are three
12684 or more lines.
12685
12686 \raggedrightthenleft
12687 This paragraph is set following the \verb?\raggedrightthenleft?
12688 declaration. The first line is set raggedright and all the remaining
12689 lines are set raggedleft. The demonstration is better if there are three or
12690 more lines.
12691
12692 \leftcenterright
12693 This paragraph is set following the \verb?\leftcenterright?
12694 declaration. We really need three, \\ or four may be better, \\
12695 lines to show the effect of this.
12696 \everypar{}
12697 \end{egresult}
12698
12699
12700
12701 \begin{syntax}
12702 \cmd{\justlastraggedleft} \\
12703 \cmd{\raggedrightthenleft} \\
12704 \cmd{\leftcenterright} \\
12705 \end{syntax}
12706 \glossary(justlastraggedleft)%
12707 {\cs{justlastraggedleft}}%
12708 {Following this declaration paragraphs will be set justified except the
12709 last line will be set raggedleft.}
12710 \glossary(raggedrightthenleft)%
12711 {\cs{raggedrightthenleft}}%
12712 {Following this declaration paragraphs will be
12713 set with the first line raggedright and the rest raggedleft.}
12714 \glossary(raggedrightthenleft)%
12715 {\cs{leftcenterright}}%
12716 {Following this declaration paragraphs will be
12717 set with the first line raggedright, the last raggedleft, and those
12718 in the middle centered.}
12719
12720 Following the \cmd{\justlastraggedleft} declaration paragraphs will be
12721 set justified except the last line will be set raggedleft.
12722
12723 Following the declaration \cmd{\raggedrightthenleft} paragraphs will be
12724 set with the first line raggedright and the remainder set raggedleft.
12725
12726 Following the declaration \cmd{\leftcenteright} paragraphs will be
12727 set with the first line flushleft (and raggedright) and the last line
12728 flushright (and raggedleft) and those in the middle will be centered.
12729 This declaration should be used within a group; also \cmd{\everypar}\verb?{}?
12730 should be called at the end.
12731
12732 \begin{egsource}{eg:raggeds}
12733 \justlastraggedleft
12734 Paragraphs following the \verb?\justlastraggedleft? declaration, as
12735 this one does, have their lines justified except for the last which
12736 is set raggedleft. The demonstration works best if there are three
12737 or more lines.
12738
12739 \raggedrightthenleft
12740 This paragraph is set following the \verb?\raggedrightthenleft?
12741 declaration. The first line is set raggedright and all the remaining
12742 lines are set raggedleft. The demonstration is better if there are three or
12743 more lines.
12744
12745 \leftcenterright
12746 This paragraph is set following the \verb?\leftcenterright?
12747 declaration. We really need three, \\ or four may be better, \\
12748 lines to show the effect of this.
12749 \everypar{}
12750 \end{egsource}
12751
12752
12753 \subsection{Left spring right}
12754
12755 Typically the lines of a paragraph are both flushleft and flushright and
12756 filled with text, but sometimes filling is not desired.
12757
12758 \begin{egresult}[A sprung paragraph]{eg:sprung}
12759 \leftspringright{0.3}{0.6}%
12760 {Text at the left is set flushleft and raggedright.}
12761 {But the text at the right is set raggedleft and flushright.
12762 It's as though there was a spring pushing the lines apart.}
12763 \vspace*{0.25\baselineskip}
12764 \end{egresult}
12765
12766
12767 \begin{syntax}
12768 \cmd{\leftspringright}\marg{lfrac}\marg{rfrac}\marg{ltext}\marg{rtext} \\
12769 \end{syntax}
12770 \glossary(leftspringright)%
12771 {\cs{leftspringright}\marg{lfrac}\marg{rfrac}\marg{ltext}\marg{rtext}}%
12772 {Sets \meta{ltext} flushleft and raggedright, and \meta{rtext} raggedleft
12773 and flushright with horizontal space between the two texts.}
12774 The \cmd{\leftspringright} macro sets \meta{ltext} flushleft and raggedright
12775 in a column whose width is \meta{lfrac} of the textwidth and, in parallel,
12776 it also sets \meta{rtext} raggedleft and flushright in a column that is
12777 \meta{rfrac} of the textwidth; the effect is as though there are springs
12778 between the lines of the two texts. The sum of \meta{lfrac} and \meta{rfac}
12779 must be less than one.
12780
12781 \begin{egsource}{eg:sprung}
12782 \leftspringright{0.3}{0.6}%
12783 {Text at the left is set flushleft and raggedright.}
12784 {But the text at the right is set raggedleft and flushright.
12785 It's as though there was a spring pushing the lines apart.}
12786 \end{egsource}
12787
12788 \section{Changing the textwidth}\label{sec:adjustwidth}
12789
12790 The \Ie{quote} and \Ie{quotation} environments both locally change the
12791 textwidth, or more precisely, they temporarily increase the left and right
12792 margins\index{margin!left}\index{margin!right} by equal amounts.
12793 Generally speaking it is not a
12794 good idea to change the textwidth but sometimes it may be called for.
12795
12796 The commands and environment described below are similar to those in
12797 the originally found in the \Lpack{chngpage} package, but do differ in
12798 some respects.
12799
12800 \begin{syntax}
12801 \senv{adjustwidth}\marg{left}\marg{right} text \eenv{adjustwidth} \\
12802 \senv{adjustwidth*}\marg{left}\marg{right} text \eenv{adjustwidth*} \\
12803 \end{syntax}
12804 \glossary(adjustwidth)%
12805 {\senv{adjustwidth}\marg{left}\marg{right}}%
12806 {Temporarily adds the lengths \marg{left} and \marg{right} to the left
12807 and right margins.}
12808 \glossary(adjustwidth*)%
12809 {\senv{adjustwidth*}\marg{left}\marg{right}}%
12810 {A sophisticated form of \texttt{adjustwidth}.
12811 Temporarily adds the lengths \marg{left} and \marg{right} to the spine
12812 and outer margins on odd (recto) pages, and on even (verso) pages adds
12813 them to the outer and spine margins, respectively.}
12814 The \Ie{adjustwidth} environment temporarily adds the length \meta{left}
12815 to the lefthand margin\index{margin!left} and \meta{right} to the righthand
12816 margin\index{margin!right}. That is, a positive length value increases the
12817 margin\index{margin} and hence reduces the textwidth,
12818 and a negative value reduces the margin\index{margin} and increases the
12819 textwidth. The \Ie{quotation} environment is roughly equivalent to
12820 \begin{lcode}
12821 \begin{adjustwidth}{2.5em}{2.5em}
12822 \end{lcode}
12823
12824 The starred version of the environment, \Ie{adjustwidth*}, is really only
12825 useful if the left and right margin\index{margin} adjustments are different.
12826 The starred version checks the page number and if it is odd then adjusts
12827 the left (spine) and right (outer) margins\index{margin}
12828 by \meta{left} and \meta{right} respectively; if the page number is even
12829 (a verso page) it adjusts the left (outer) and right (spine)
12830 margins\index{margin} by \meta{right} and \meta{left} respectively.
12831
12832 \begin{syntax}
12833 \cmd{\strictpagecheck} \cmd{\easypagecheck} \\
12834 \end{syntax}
12835
12836 Odd/even page checking may be either strict (\cmd{\strictpagecheck})
12837 or easy (or one might call it lazy) (\cmd{\easypagecheck}). Easy
12838 checking works most of the time but if it fails at any point then the
12839 strict checking should be used.
12840
12841 As an example, if a figure\index{figure} is wider than the textwidth
12842 it will stick out into the righthand margin\index{margin!right}. It may be
12843 desireable to have any wide figure\index{figure} stick out into the
12844 outer margin\index{margin!outer} where there is usually more room than at
12845 the spine margin\index{margin!spine}. This can be accomplished by
12846 \begin{lcode}
12847 \begin{figure}
12848 \centering
12849 \strictpagecheck
12850 \begin{adjustwidth*}{0em}{-3em}
12851 % the illustration
12852 \caption{...}
12853 \end{adjustwidth*}
12854 \end{figure}
12855 \end{lcode}
12856
12857 A real example in this manual is \tref{tab:fpp} on \pref{tab:fpp},
12858 which is wider than the typeblock\index{typeblock}. In that case I
12859 just centered it by using \Ie{adjustwidth} to decrease each
12860 margin\index{margin} equally. In brief, like
12861 \begin{lcode}
12862 \begin{table}
12863 \begin{adjustwidth}{-1cm}{-1cm}
12864 \centering
12865 ...
12866 \end{adjustwidth}
12867 \end{table}
12868 \end{lcode}
12869
12870 Note that the \Ie{adjustwidth} environment applies to complete paragraphs;
12871 you can't change the width of part of a paragraph\index{paragraph}
12872 except for hanging paragraphs\index{paragraph!hanging} or more esoterically
12873 via \cmd{\parshape}. Further, if the adjusted paragraph crosses a
12874 page boundary the margin\index{margin} changes are constant; a paragraph
12875 that is, say, wider at the right on the first page will also be wider at
12876 the right as it continues onto the following page.
12877
12878 The \Ie{center} environment horizontally centers its contents
12879 with respect to the typeblock\index{typeblock}.
12880 Sometimes you may wish to horizontally center some text with respect
12881 to the physical page, for example when typesetting a
12882 colophon\index{colophon} which may look odd centered with respect
12883 to the (unseen) typeblock\index{typeblock}.
12884
12885 The calculation of the necessary changes to the spine and \foredge{}
12886 margins\index{margin} is simple. Using the same symbols as earlier in
12887 \Sref{sec:typeblock2} ($P_{w}$ and $B_{w}$ are the width of the
12888 trimmed page and the typeblock\index{typeblock}, respectively; $S$ and
12889 $E$ are the spine and \foredge{} margins\index{margin}, respectively)
12890 then the amount $M$ to be added to the spine margin\index{margin} and
12891 subtracted from the \foredge{} margin\index{margin} is calculated as:
12892 \begin{displaymath}
12893 M = \tfrac12(P_{w} - B_{w}) - S
12894 \end{displaymath}
12895
12896 For example, assume that the \lnc{\textwidth} is 5 inches and the
12897 \lnc{\spinemargin} is 1 inch. On US letterpaper\index{paper!size!letterpaper}
12898 (\lnc{\paperwidth} is 8.5 inches) the \foredge{} margin\index{margin} is
12899 then 2.5 inches, and 0.75 inches\footnote{On A4\index{paper!size!A4}
12900 paper the result would be different.} must be added to the spine
12901 margin\index{margin} and subtracted from the \foredge{} to center the
12902 typeblock\index{typeblock}.
12903 The \Ie{adjustwidth} environment can be used to make the (temporary) change.
12904 \begin{lcode}
12905 \begin{adjustwidth*}{0.75in}{-0.75in} ...
12906 \end{lcode}
12907
12908 \begin{syntax}
12909 \cmd{\calccentering}\marg{length} \\
12910 \end{syntax}
12911 \glossary(calccentering)%
12912 {\cs{calccentering}\marg{length}}%
12913 {Sets the \meta{length} command to the value to add/subtract from margins
12914 to center text on the physical page.}
12915 If you don't want to do the above calculations by hand,
12916 \cmd{\calccentering} will do it for you.
12917 The \meta{length}
12918 argument must be the name of a pre-existing length command,
12919 including the backslash. After calling
12920 \cmd{\calccentering}, \meta{length} is the amount to be added to the
12921 spine margin\index{margin} and subtracted from the foredge margin\index{margin} to center the typeblock\index{typeblock}.
12922 An example usage is
12923 \begin{lcode}
12924 \calccentering{\mylength}
12925 \begin{adjustwidth*}{\mylength}{-\mylength}
12926 text horizontally centered on the physical page
12927 \end{adjustwidth*}
12928 \end{lcode}
12929
12930 You do not necessarily have to define a new length for the purposes
12931 of \cmd{\calccentering}. Any existing length will do, such as
12932 \lnc{\unitlength}, provided it will be otherwise unused between performing
12933 the calculation and changing the margins\index{margin} (and that you can,
12934 if necessary reset it to its original value --- the default value for
12935 \lnc{\unitlength} is 1pt).
12936
12937 \section{Lists}
12938
12939 \LMnote{2013/05/16}{Added hint about enumitem}
12940 \LMnote{2018/03/09}{Changed hint to be a recommended section}
12941 \begin{recommended}
12942 The class does not provide high level interfaces to configure the
12943 appearance of lists. We provide some simple tools to adjust vertical
12944 spacing, described below.
12945
12946 Users seeking more control can have a look at the excellent
12947 \Lpack{enumitem} package by Javier Bezos. If loaded as
12948 \begin{lcode}
12949 \usepackage[shortlabels]{enumitem}
12950 \end{lcode}
12951 then our
12952 \begin{lcode}
12953 \begin{enumerate}[i)]
12954 \item \label{item:tst} ...
12955 \end{lcode}
12956 syntax will also work out of the box.
12957
12958 \fancybreak{}
12959
12960 One key difference: In the class \verb?\ref{item:tst}? will give you
12961 `i', whereas, if \Lpack{enumitem} is loaded the full formatting is
12962 returned from the cross reference, i.e., `i)'. This is fully
12963 configurable in \Lpack{enumitem}.
12964
12965 Note that, \cmd{\tightlists}, \cmd{\defaultlists}, \cmd{\firmlists},
12966 \cmd{\firmlists*} presented below, are not supported by
12967 \Lpack{enumitem}, it provides a high level key based interface
12968 instead.
12969
12970 \fancybreak{}
12971
12972 \textbf{Tip:} If you use the the new kernel environment hooks (see
12973 \cite{LTHOOKS}, or use \cmd{\AtBeginEnvironment} from
12974 \Lpack{etoolbox}), then you can e.g. add default formatting of
12975 \Pe{enumerate} to all of your theorem constructions and then there
12976 is no need to use
12977 \begin{lcode}
12978 \begin{enumerate}[(a)]
12979 \end{lcode}
12980 every single time, because you wanted lists use use letters inside
12981 theorems, and something else outside. Run this for each theorem like
12982 env.
12983 \begin{lcode}
12984 \AddToHook{env/theorem/begin}
12985 {\setlist[enumerate]{label=\textup{(\alph*)}}}
12986 \end{lcode}
12987 The \Lpack{enumitem} package even allows you to add your own keys to
12988 load entire collections of keys. Hightly recommended package.
12989 \end{recommended}
12990
12991
12992
12993 \index{list|(} %|
12994
12995 Standard \ltx\ provides four kinds of lists. There is a general \Ie{list}
12996 environment which you can use to define your own particular kind of list,
12997 and the \Ie{description}, \Ie{itemize} and \Ie{enumerate} lists (which are
12998 internally defined in terms of the general \Ie{list}
12999 environment\footnote{The \Ie{quote} and \Ie{quotation} environments are also
13000 defined in terms of the general \Ie{list} environment. You may be
13001 surprised where it crops up.}).
13002
13003 \PWnote{2009/04/25}{Added the blockdescription, labelled and flexlabelled environments}
13004
13005 This class provides the normal \Ie{description} list, plus a couple of others
13006 of the same kind, but the \Ie{itemize}
13007 and \Ie{enumerate} lists are extended versions of the normal ones.
13008
13009 \begin{syntax}
13010 \senv{description} \cmd{\item}\oarg{label} ... \eenv{description} \\
13011 \senv{blockdescription} \cmd{\item}\oarg{label} ... \eenv{blockdescription} \\
13012 \cmd{\descriptionlabel}\meta{label} \\
13013 \cmd{\blockdescriptionlabel}\meta{label} \\
13014 \end{syntax}
13015 \glossary(description)%
13016 {\senv{description}}%
13017 {A list of descriptions of \cs{item}s formatted as regular paragraphs.}
13018 \glossary(blockdescription)%
13019 {\senv{blockdescription}}%
13020 {A list of descriptions of \cs{item}s formatted as indented block paragraphs.}
13021 \glossary(item)%
13022 {\cs{item}\oarg{label}}%
13023 {Intoduces a new element in a list. The effect of \meta{label} depends
13024 on the particular list form.}
13025 \glossary(descriptionlabel)%
13026 {\cs{descriptionlabel}\marg{label}}%
13027 {Specifies the format of the \meta{label} of an \cs{item} in a
13028 \Pe{description} environment.}
13029 \glossary(blockdescriptionlabel)%
13030 {\cs{blockdescriptionlabel}\marg{label}}%
13031 {Specifies the format of the \meta{label} of an \cs{item} in a
13032 \Pe{blockdescription} environment.}
13033 In a \Ie{description} list an \cs{item}'s \meta{label} is typeset by
13034 \cmd{descriptionlabel}. The default definition is
13035 \begin{lcode}
13036 \newcommand*{\descriptionlabel}[1]{\hspace\labelsep
13037 \normalfont\bfseries #1}
13038 \end{lcode}
13039 which gives a bold label. To have, for example, a sans label instead, do
13040 \begin{lcode}
13041 \renewcommand*{\descriptionlabel}[1]{\hspace\labelsep
13042 \normalfont\sffamily #1}
13043 \end{lcode}
13044
13045 The only noticeable difference between a \Ie{description} list and a
13046 \Ie{blockdescription} list is that the latter is set as indented block paragraphs;
13047 invisibly, it also has its own \cmd{\blockdescriptionlabel}.
13048
13049 \begin{syntax}
13050 \senv{labelled}\marg{name} \cmd{\item}\oarg{label} ... \eenv{labelled} \\
13051 \senv{flexlabelled}\marg{name}\marg{labelwidth}\marg{labelsep}\marg{itemindent}\% \\
13052 \marg{leftmargin}\marg{rightmargin} \\
13053 \cmd{\item}\oarg{label} ... \eenv{flexlabelled} \\
13054 \end{syntax}
13055 \glossary(labelled)%
13056 {\senv{labelled}\marg{name}}%
13057 {A list of descriptions of \cs{item}s with the labels formatted according to \cs{name}}.
13058 \glossary(flexlabelled)%
13059 {\senv{labelled}\marg{name}\marg{width}\marg{sep}\marg{indent}\marg{left}\marg{right}}%
13060 {A list of descriptions of \cs{item}s with the labels formatted according to \cs{name}
13061 and the overall layout specified by the other list length arguments.}
13062
13063 The \Ie{labelled} environment is like the \Ie{description} environment except that
13064 you can specify the label format via the \meta{name} argument where \cs{name} is
13065 the formatting macro. For example, if you wanted the item labels set in italics, then
13066 \begin{lcode}
13067 \newcommand*{\itlabel}[1]{\hspace\labelsep \normalfont\itshape #1}
13068 \begin{labelled}{itlabel}
13069 \item[First] ...
13070 ...
13071 \end{lcode}
13072
13073 The \Ie{flexlabelled} environment adds additional controls to the \Ie{labelled} one.
13074 The \meta{name} argument is the same as that for \Ie{labelled} and the remainder are
13075 lengths that correspond to the dimensions shown in \fref{fig:listlay}. If you want
13076 any of the dimensions to retain their current values, use \verb?*? instead of a length
13077 as the value for that particular argument.
13078
13079 \begin{egsource}{eg:flexlabelled}
13080 This example shows how the \texttt{flexlabelled} list can be used to
13081 change the formatting of a description-like list.
13082 \newcommand*{\sclabel}[1]{\normalfont\scshape #1}
13083 \begin{flexlabelled}{sclabel}{0pt}{0.5em}{0.5em}{*}{\leftmargin}
13084 \item[First] The labels should be typeset using smallcaps and the first
13085 paragraph should be set as block paragraph.
13086
13087 Further paragraphs completing an \cs{item}'s descriptive text
13088 will be set with the normal paragraph indent.
13089 \item[Second] The list should be indented from each margin like the
13090 \texttt{quote} and \texttt{quotation} environments.
13091 \end{flexlabelled}
13092 More major changes to a description-like list will probably involve writing
13093 the code for a new environment.
13094 \end{egsource}
13095
13096 \begin{egresult}[Smallcap quote style description list]{eg:flexlabelled}
13097 This example shows how the \texttt{flexlabelled} list can be used to
13098 change the formatting of a description-like list.
13099 \newcommand*{\sclabel}[1]{\normalfont\scshape #1}
13100 \begin{flexlabelled}{sclabel}{0pt}{0.5em}{0.5em}{*}{\leftmargin}
13101 \item[First] The labels should be typeset using smallcaps and the first
13102 paragraph should be set as block paragraph.
13103
13104 Further paragraphs completing an \cs{item}'s descriptive text
13105 will be set with the normal paragraph indent.
13106 \item[Second] The list should be indented from each margin like the
13107 \texttt{quote} and \texttt{quotation} environments.
13108 \end{flexlabelled}
13109 More major changes to a description-like list will probably involve writing
13110 the code for a new environment.
13111 \end{egresult}
13112
13113
13114
13115 The \Ie{itemize} and \Ie{enumerate} environments below are based on
13116 the \Lpack{enumerate} package~\cite{ENUMERATE}.
13117
13118 \begin{syntax}
13119 \senv{itemize}\oarg{marker} \cmd{\item} ... \eenv{itemize} \\
13120 \end{syntax}
13121 \glossary(itemize)%
13122 {\senv{itemize}\oarg{marker}}%
13123 {An unordered list of \cs{item}s. If given, the \meta{marker} overrides the
13124 default marker for the elements.}
13125 The normal markers for \cmd{\item}s in an \Ie{itemize} list are:
13126 \begin{enumerate}
13127 \item bullet (\textbullet \cmd{\textbullet}),
13128 \item bold en-dash ({\normalfont\bfseries \textendash} \cmd{\bfseries}\cmd{\textendash}),
13129 \item centered asterisk (\textasteriskcentered \cmd{\textasteriskcentered}), and
13130 \item centered dot (\textperiodcentered \cmd{\textperiodcentered}).
13131 \end{enumerate}
13132 The optional \meta{marker} argument can be used to specify the marker for the
13133 list items in a particular list. If for some reason you wanted to use a
13134 pilcrow\index{pilcrow (\P)} symbol as the item marker for a particular list
13135 you could do
13136 \begin{lcode}
13137 \begin{itemize}[\P]
13138 \item ...
13139 ...
13140 \end{lcode}
13141
13142
13143
13144 \begin{syntax}
13145 \senv{enumerate}\oarg{style} \cmd{\item} ... \eenv{enumerate} \\
13146 \end{syntax}
13147 \glossary(enumerate)%
13148 {\senv{enumerate}\oarg{style}}%
13149 {An ordered list of \cs{item}s. If \meta{style} is given it overrides the
13150 default scheme for indicating the item order.}
13151 The normal markers for, say, the third item in an \Ie{enumerate} list are:
13152 3., c., iii., and C. The optional \meta{style} argument can be used to
13153 specify the style used to typeset the item counter. An occurrence of
13154 one of the special characters \texttt{A}, \texttt{a}, \texttt{I}, \texttt{i}
13155 or \texttt{1} in \meta{style} specifies that the counter will be typeset using
13156 uppercase letters (\texttt{A}), lowercase letters (\texttt{a}),
13157 uppercase Roman numerals (\texttt{I}), lowercase Roman numerals (\texttt{i}),
13158 or arabic numerals (\texttt{1}). These characters
13159 may be surrounded by any LaTeX commands or characters, but if so the special
13160 characters must be put inside braces (e.g., \verb?{a}?) if they are to be
13161 considered as ordinary characters instead of as special styling characters.
13162 For example, to have the
13163 counter typeset as a lowercase Roman numeral followed by a single parenthesis
13164 \begin{lcode}
13165 \begin{enumerate}[i)]
13166 ...
13167 \end{lcode}
13168
13169 \index{list!tight|(} %|
13170
13171
13172 \begin{syntax}
13173 \cmd{\tightlists} \cmd{\defaultlists} \\
13174 \cmd{\firmlists} \cmd{\firmlists*} \\
13175 \end{syntax}
13176 \glossary(tightlists)%
13177 {\cs{tightlists}}%
13178 {Declaration removing extra vertical space from \texttt{list}-based
13179 environments.}
13180 \glossary(defaultlists)%
13181 {\cs{defaultlists}}%
13182 {Declaration specifying the default vertical spacing \texttt{list}-based
13183 environments.}
13184 \glossary(firmlists)%
13185 {\cs{firmlists}}%
13186 {Declaration for some vertical spacing in \texttt{list}-based
13187 environments. There may be some extra space before and after the
13188 environments.}
13189 \glossary(firmlists*)%
13190 {\cs{firmlists*}}%
13191 {The same as \cs{firmlists} except that there is no space before and after
13192 the environments.}
13193
13194
13195
13196 The normal LaTeX \Ie{description}, \Ie{itemize} and \Ie{enumerate} lists
13197 have an open
13198 look about them when they are typeset as there is significant vertical space
13199 between the items in the lists. After the declaration \cmd{\tightlists} is
13200 issued, the extra vertical spacing between the list items is deleted. The open
13201 list appearance is used after the \cmd{\defaultlists} declaration is issued.
13202 These declarations, if used, must come \emph{before} the relevant list
13203 environment(s). The class initially sets \cmd{\defaultlists}. This manual,
13204 though, uses \cmd{\tightlists}. The spacing following the \cmd{\firmlists}
13205 declaration is intermediate between \cmd{\defaultlists} and \cmd{\tightlists}.
13206 The starred version, \cmd{\firmlists*}, allows sligthly less space around
13207 the lists when they are preceded by a blank line than does the
13208 unstarred \cmd{\firmlists}.
13209 \begin{caveat}
13210 Due to the manner in which \cmd{\small} and \cmd{\footnotesize} are
13211 implemented, \cmd{\tightlists} and \cmd{\firmlists} will have \emph{no
13212 effect} on lists typeset under \cmd{\small} or
13213 \cmd{\footnotesize}.
13214
13215 A comprehensible solution can be done via the \Lpack{enumitem}
13216 package via
13217 \begin{lcode}
13218 % \tightlists equivalent
13219 \usepackage[shortlabels]{enumitem}
13220 \setlist{ noitemsep }
13221 \end{lcode}
13222 \end{caveat}
13223
13224
13225
13226
13227 \begin{syntax}
13228 \cmd{\firmlist} \cmd{\tightlist} \\
13229 \end{syntax}
13230 \glossary(firmlist)
13231 {\cs{firmlist}}%
13232 {In a standard list, sets the vertical spacing intermediate between
13233 the default and \cs{tightlist}(s).}
13234 \glossary(tightlist)
13235 {\cs{tightlist}}%
13236 {In a standard list, removes extra vertical spacing.}
13237 The command \cmd{\firmlist} or \cmd{\tightlist} can be used immediately
13238 after the start of a list environment to reduce the vertical space within
13239 that list. The \cmd{\tightlist} removes all the spaces while the
13240 \cmd{\firmlist} produces a list that still has some space but not as much
13241 as in an ordinary list.
13242
13243 \index{list!tight|)} %|
13244
13245
13246 \begin{figure}
13247 \centering
13248 \drawparameterstrue
13249 \drawlist
13250 \caption{The layout parameters for general lists}\label{fig:listlay}
13251 \end{figure}
13252
13253 \index{list!new|(} %|
13254
13255 \begin{syntax}
13256 \senv{list}\marg{default-label}\marg{code} items \eenv{list} \\
13257 \end{syntax}
13258 \glossary(list)%
13259 {\senv{list}\marg{default-label}\marg{code}}%
13260 {The general \Pe{list} environment. \meta{default-label} is code that
13261 is used for an \cs{item} with no \meta{label} and \meta{code} is
13262 used to specify the list layout parameters.} \ltx's list
13263 environments are defined in terms of a general \Ie{list} environment;
13264 some other environments, such as the \Ie{quote}, \Ie{quotation} and
13265 \Ie{adjustwidth} are also defined in terms of a \Ie{list}.
13266 \fref{fig:listlay} shows the parameters controlling the layout of the
13267 \Ie{list} environment.
13268
13269 The \Ie{list} environment takes two arguments. The \meta{default-label}
13270 argument is the code that should be used when the \cmd{\item} macro is
13271 used without its optional \meta{label} argument. For lists like \Ie{enumerate}
13272 this is specified but often it is left empty, such as for the \Ie{adjustwidth}
13273 environment.
13274
13275 The \meta{code} argument is typically used for setting the particular
13276 values of the list layout parameters. When defining your own types of lists
13277 it is advisable to set each of the parameters unless you know that the default
13278 values are suitable for your purposes. These parameters can all be modified
13279 with either the \cmd{\setlength} or \cmd{\addtolength} commands.
13280
13281 As an example, here is the specification for a description-like list
13282 that uses an italic rather than bold font for the items, and is somewhat
13283 tighter than the normal \Ie{description} list.
13284
13285 \begin{lcode}
13286 %%%%% An italic and tighter description environment
13287 \newcommand{\itlabel}[1]{\hspace\labelsep\normalfont\itshape #1}
13288 \newenvironment{itdesc}{%
13289 \list{}{%
13290 \setlength{\labelsep}{0.5em}
13291 \setlength{\itemindent}{0pt}
13292 \setlength{\leftmargin}{\parindent}
13293 \setlength{\labelwidth}{\leftmargin}
13294 \addtolength{\labelwidth}{-\labelsep}
13295 \setlength{\listparindent}{\parindent}
13296 \setlength{\parsep}{\parskip}
13297 \setlength{\itemsep}{0.5\onelineskip}
13298 \let\makelabel\itlabel}}{\endlist}
13299 \end{lcode}
13300
13301 This gets used like any other list:
13302 \begin{lcode}
13303 \begin{itdesc}
13304 \item[label] ....
13305 \end{itdesc}
13306 \end{lcode}
13307
13308 Here is another kind of list called \Ie{symbols} that might be used
13309 for a list of symbols or other similar kind of listing.
13310 \begin{lcode}
13311 % Symbol list
13312 \newenvironment{symbols}%
13313 {\list{}% empty label
13314 {\setlength{\topsep}{\baselineskip}
13315 \setlength{\partopsep}{0pt}
13316 \setlength{\itemsep}{0.5\baselineskip}
13317 \setlength{\parsep}{0pt}
13318 \setlength{\leftmargin}{2em}
13319 \setlength{\rightmargin}{0em}
13320 \setlength{\listparindent}{1em}
13321 \setlength{\itemindent}{0em}
13322 \setlength{\labelwidth}{0em}
13323 \setlength{\labelsep}{2em}}}%
13324 {\endlist}
13325 \newcommand{\symb}[1]{\item[#1]\mbox{}\\\nopagebreak}
13326 \end{lcode}
13327 In this case it gets used like this
13328 \begin{lcode}
13329 \begin{symbols}
13330 \symb{SYMBOL 1} definition
13331 \symb{SYMBOL 2} ...
13332 \end{symbols}
13333 \end{lcode}
13334
13335 In the code for the \Pe{symbols} list I used the command forms (i.e.,
13336 \cmd{\list} and \cmd{\endlist}) for specifying the start and end of a list.
13337 It is a matter of taste whether you use the command or \verb?\begin{...}?
13338 and \verb?\end{...}? forms, but the latter does make it more obvious that
13339 an environment is being dealt with.
13340
13341 \index{list!new|)} %|
13342
13343 Several \ltx\ environments are defined in terms of a very simple list,
13344 called a \Ie{trivlist}. Such a list has little internal structure
13345 but like the \Ie{list} environment the vertical space before and after
13346 a \Ie{trivlist} (or any list based on it) is set by \lnc{\topsep} and
13347 \lnc{\partopsep}, as shown in \fref{fig:listlay}.
13348
13349 \begin{syntax}
13350 \cmd{\zerotrivseps} \cmd{\savetrivseps} \cmd{\restoretrivseps} \\
13351 \end{syntax}
13352 \glossary(zerotrivseps)%
13353 {\cs{zerotrivseps}}%
13354 {Eliminate space before and after a \Pe{trivlist}.}
13355 \glossary(savetrivseps)%
13356 {\cs{savetrivseps}}%
13357 {Stores the current \cs{topsep} and \cs{partopsep} for \Pe{trivlist}s.}
13358 \glossary(restoretrivseps)%
13359 {\cs{restoretrivseps}}%
13360 {Sets the current \cs{topsep} and \cs{partopsep} to the values saved
13361 by \cs{savetrivseps}.}
13362 The \Ie{center} environment is one of several that is based on
13363 a \Ie{trivlist}, and so has space before and after it. If you don't want this
13364 the \cmd{\zerotrivseps} declaration eliminates those spaces. You can
13365 think of it as being defined as:
13366 \begin{lcode}
13367 \newcommand*{\zerotrivseps}{%
13368 \setlength{\topsep}{0pt}%
13369 \setlength{\partopsep}{0pt}}
13370 \end{lcode}
13371 Before doing this, though, you might consider calling \cmd{\savetrivseps}
13372 which stores the current values of \lnc{\topsep} and \lnc{\partopsep};
13373 it is initially defined to store the default values.
13374 The command \cmd{\restoretrivseps} sets the current values of these
13375 lengths to the ones saved by \cmd{\savetrivseps}.
13376
13377 \begin{egresult}[Changing space before and after lists]{eg:trivseps}
13378 \restoretrivseps%% need this because egresult env reduces the trivseps
13379 This example shows that the space around the \topsep=0.5\onelineskip
13380 \begin{center}
13381 CENTER AND OTHER LIST ENVIRONMENTS
13382 \end{center}
13383 can be minimised by using the \zerotrivseps
13384 \begin{center}
13385 \verb?\zerotrivseps? declaration.
13386 \end{center}
13387 The normal spacing can be restored by using the \restoretrivseps \topsep=0.5\onelineskip
13388 \begin{center}
13389 \verb?\restoretrivseps? command.
13390 \end{center}
13391 An alternative is to use the \verb?\centering? macro.
13392 \end{egresult}
13393
13394
13395 \begin{egsource}{eg:trivseps}
13396 This example shows that the space around the
13397 \begin{center}
13398 CENTER AND OTHER LIST ENVIRONMENTS
13399 \end{center}
13400 can be minimised by using the \zerotrivseps
13401 \begin{center}
13402 \verb?\zerotrivseps? declaration.
13403 \end{center}
13404 The normal spacing can be restored by using the \restoretrivseps
13405 \begin{center}
13406 \verb?\restoretrivseps? command.
13407 \end{center}
13408 An alternative is to use the \verb?\centering? macro.
13409 \end{egsource}
13410
13411 %%%%\enlargethispage{\onelineskip}
13412 Among the environments defined in terms of a \Ie{trivlist} are:
13413 \Ie{flushleft},
13414 \Ie{center},
13415 \Ie{flushright},
13416 \Ie{verbatim}, and others.
13417 \eref{eg:trivseps} shows how it is possible to change the
13418 spacing around the \Ie{center} environment, but it applies equally to the
13419 other environments.
13420
13421 \index{list|)} %|
13422
13423 %#% extend
13424 %#% extstart include content-lists.tex
13425
13426 \svnidlong
13427 {$Ignore: $}
13428 {$LastChangedDate: 2025-09-19 16:06:27 +0200 (Fri, 19 Sep 2025) $}
13429 {$LastChangedRevision: 873 $}
13430 {$LastChangedBy: [email protected] $}
13431
13432 %%%%%%%%%%%%%%%%%%%%%%%%%%
13433 %%\chapterstyle{section}
13434 %%%%%%%%%%%%%%%%%%%%%%%%%%
13435 %\chapter{Tops and tails} \label{chap:topsandtails}
13436 \chapter{Contents lists} \label{chap:toc}
13437
13438 This chapter describes how to change the appearance of the Table of Contents
13439 (\toc) and similar lists like the List of Figures (\lof). In the standard
13440 classes the typographic design of these is virtually fixed as it is buried
13441 within the class definitions.
13442
13443 As well as allowing these lists to appear multiple times in a
13444 document, the \Mname\ class gives handles to easily manipulate the design
13445 elements. The class also provides means for you to define your own new kinds of
13446 `\listofx'.
13447
13448 The functionality described is equivalent to the combination
13449 of the \Lpack{tocloft} and \Lpack{tocbibind}
13450 packages~\cite{TOCLOFT,TOCBIBIND}.
13451
13452 \begin{syntax}
13453 \cmd{\tableofcontents} \cmd{\tableofcontents*} \\
13454 \cmd{\listoffigures} \cmd{\listoffigures*} \\
13455 \cmd{\listoftables} \cmd{\listoftables*} \\
13456 \end{syntax}
13457 The commands \cmd{\tableofcontents}, \cmd{\listoffigures} and
13458 \cmd{\listoftables} typeset, repectively, the Table of Contents (\toc),
13459 List of Figures (\lof) and List of Tables (\lot). In \Mname, unlike the
13460 standard classes, the unstarred versions add their respective titles to
13461 the \toc. The starred versions act like the standard classes' unstarred
13462 versions as they don't add their titles to the \toc.
13463
13464 This chapter explains the inner workings behind the \toc\ and friends,
13465 how to change their appearance and the apperance of the entries, and how to
13466 create new \listofx. If you don't need any of these then you can
13467 skip the remainder of the chapter.
13468
13469 \section{General \prtoc\ methods}
13470
13471 In \Sref{sec:class-prtoc-methods} we will provide the class
13472 configuration interface for the various parts of the ToC.
13473
13474 In order to understand how these macros are used, we start by
13475 providing some background information this is a general description of
13476 how the standard \ltx\ classes process a Table of Contents (\toc). As
13477 the processing of List of Figures (\lof) and List of Tables (\lot) is
13478 similar I will just discuss the \toc. You may wish to skip this
13479 section on your first reading.
13480
13481 The basic process is that each sectioning command writes out
13482 information about itself --- its number, title, and page --- to the
13483 \pixfile{toc} file. The \cmd{\tableofcontents} command reads this
13484 file and typesets the contents.
13485
13486 First of all, remember that each sectional division has an associated
13487 level as listed in in \tref{tab:seclevels} on
13488 \pref{tab:seclevels}. \ltx\ will not typeset an entry in the \toc{}
13489 unless the value of the \Icn{tocdepth} counter is equal to or greater
13490 than the level of the entry. The value of the \Icn{tocdepth} counter
13491 can be changed by using \cmd{\setcounter} or \cmd{\settocdepth}.
13492
13493 \begin{syntax}
13494 \cmd{\addcontentsline}\marg{file}\marg{kind}\marg{text} \\
13495 \end{syntax}
13496 \glossary(addcontentsline)%
13497 {\cs{addcontentsline}\marg{file}\marg{kind}\marg{text}}%
13498 {Writes heading/caption data to the \meta{file} in the form of
13499 the \cs{contentsline} macro.}
13500 \ltx\ generates a \pixfile{toc} file if the document contains a
13501 \cmd{\tableofcontents} command. The sectioning
13502 commands\footnote{For figures and tables it is the
13503 \cmd{\caption} command
13504 that populates the \pixfile{lof} and \pixfile{lot} files.}
13505 put entries into the \pixfile{toc} file by calling the
13506 \cmd{\addcontentsline}
13507 command, where \meta{file} is the file extension (e.g., \texttt{toc}),
13508 \meta{kind} is the kind of entry (e.g., \texttt{section} or \texttt{subsection}),
13509 and \meta{text} is the (numbered) title text. In the cases where
13510 there is a number, the \meta{text} argument is given in the
13511 form \verb?{\numberline{number}title text}?.
13512
13513 \begin{syntax}
13514 \cmd{\contentsline}\marg{kind}\marg{text}\marg{page}\verb!{}! \\
13515 \end{syntax}
13516 \glossary(contentsline)%
13517 {\cs{contentsline}\marg{kind}\marg{text}\marg{page}}%
13518 {An entry in a `\listofx' file for a \meta{kind} entry, with
13519 \meta{text} being the title which was on \meta{page}.} The
13520 \cmd{\addcontentsline} command writes an entry to the given file
13521 in the form: \\
13522 \cmd{\contentsline}\marg{kind}\marg{text}\marg{page}\verb!{}! \\
13523 where \meta{page} is the page number. The empty arg is preparation for
13524 \Lpack{hyperref}, and will then normally contain the target for the
13525 entry.
13526
13527 For example, if \verb?\section{Head text}? was typeset as
13528 `\textbf{3.4 Head text}' on page 27, then there would be the following
13529 entry in the \pixfile{toc} file:
13530 \begin{lcode}
13531 \contentsline{section}{\numberline{3.4} Head text}{27}{}
13532 \end{lcode}
13533 Extracts from \pixfile{toc}, \pixfile{lof} and \pixfile{lot} files are shown in
13534 \fref{fig:tocloflotfiles}.
13535
13536 \begin{figure}
13537 \centering
13538 Parts of a \file{toc} file:
13539 \begin{lcode}
13540 ...
13541 \contentsline{section}{\numberline{10.1}The spread}{77}{}
13542 \contentsline{section}{\numberline{10.2}Typeblock}{89}{}
13543 \contentsline{subsection}{\numberline{10.2.1}Color}{77}{}
13544 ...
13545 \contentsline{chapter}{Index}{226}{}
13546
13547 \end{lcode}
13548
13549 Part of a \file{lof} file:
13550
13551 \begin{lcode}
13552 ...
13553 \contentsline{figure}{\numberline{8.6}Measuring scales}{56}{}
13554 \addvspace{10pt}
13555 \addvspace{10pt}
13556 \contentsline{figure}{\numberline{10.1}Two subfigures}{62}{}
13557 \contentsline{subfigure}{\numberline{(a)}Subfigure 1}{62}{}
13558 \contentsline{subfigure}{\numberline{(b)}Subfigure 2}{62}{}
13559 ...
13560 \end{lcode}
13561
13562 Part of a \file{lot} file:
13563
13564 \begin{lcode}
13565 ...
13566 \contentsline{table}{\numberline{1.7}Font declarations}{11}{}
13567 \contentsline{table}{\numberline{1.8}Font sizes}{13}{}
13568 \addvspace
13569 \contentsline{table}{\numberline{3.1}Division levels}{21}{}
13570 ...
13571 \end{lcode}
13572 \caption{Example extracts from \file{toc}, \file{lof} and \file{lot} files}
13573 \label{fig:tocloflotfiles}
13574 \end{figure}
13575
13576 For each \meta{kind} that might appear in a \file{toc}
13577 (\file{lof}, \file{lot}) file, \ltx\ provides a command: \\
13578 \cmd{\l@kind}\marg{title}\marg{page} \\
13579 which performs the actual typesetting of the \cmd{\contentsline} entry.
13580
13581
13582 \begin{figure}
13583 \setlayoutscale{0.8}
13584 \drawtoc
13585 \caption{Layout of a \prtoc{} (\prlof, \prlot) entry} \label{fig:ltoc}
13586 \end{figure}
13587
13588
13589 \begin{syntax}
13590 \cmd{\@pnumwidth}\marg{length} \\
13591 \cmd{\@tocrmarg}\marg{length} \\
13592 \cmd{\@dotsep}\marg{number} \\
13593 \end{syntax}
13594 \glossary(@pnumwidth)%
13595 {\cs{@pnumwidth}\marg{length}}%
13596 {Space for a page number in the \prtoc\ etc.}
13597 \glossary(@tocrmarg)%
13598 {\cs{@tocrmarg}\marg{length}}%
13599 {Right hand margin for titles in the \prtoc\ etc.}
13600 \glossary(@dotsep)%
13601 {\cs{@docsep}\marg{num}}%
13602 {Distance, as \meta{num} math units, bewteen dots in the dotted lines
13603 in the \prtoc\ etc.}
13604 The general layout of a typeset entry is illustrated in \fref{fig:ltoc}.
13605 There are three
13606 internal \ltx\ commands that are used in the typesetting. The page
13607 number is typeset flushright in a box of width \cmd{\@pnumwidth}, and the box
13608 is at the righthand margin\index{margin!right}. If the page number is too long
13609 to fit into the box it will stick out into the righthand
13610 margin\index{margin!right}.
13611 The title text is indented from the righthand margin\index{margin!right} by an
13612 amount given by \cmd{\@tocrmarg}.
13613 Note that \cmd{\@tocrmarg} should be greater than \cmd{\@pnumwidth}. Some
13614 entries are typeset with a dotted leader between the end of the title
13615 title text and the righthand margin\index{margin!right} indentation.
13616 The distance, in
13617 \index{math unit}\emph{math units}\footnote{There are 18mu to 1em.}
13618 between the dots in the leader is given by the value of \cmd{\@dotsep}.
13619 In the standard classes the same values are used for the \toc, \lof{} and
13620 the \lot.
13621
13622 The standard values for these internal commands are:
13623 \begin{itemize}
13624 \item \cmd{\@pnumwidth} = 1.55em
13625 \item \cmd{\@tocrmarg} = 2.55em
13626 \item \cmd{\@dotsep} = 4.5
13627 \end{itemize}
13628 The values can be changed by using \cmd{\renewcommand}, in spite of the
13629 fact that the first two appear to be lengths.
13630
13631 Dotted leaders are not available for Part\index{part} and
13632 Chapter\index{chapter} \toc{} entries.
13633
13634 \begin{syntax}
13635 \cmd{\numberline}\marg{number} \\
13636 \end{syntax}
13637 Each \cmd{\l@kind} macro is responsible for setting the general
13638 \textit{indent} from the lefthand margin\index{margin!left}, and the
13639 \textit{numwidth}.
13640 The \cmd{\numberline} macro is responsible for typesetting the number
13641 flushleft in a box of width \textit{numwidth}. If the number is too long
13642 for the box then it will protrude into the title text. The title text is
13643 indented by (\textit{indent + numwidth}) from the lefthand
13644 margin\index{margin!left}. That is, the title text is typeset in a
13645 block of width \\
13646 (\lnc{\linewidth} - \textit{indent} - \textit{numwidth} - \cmd{\@tocrmarg}).
13647
13648 \begin{table}
13649 \centering
13650 \caption[Indents and Numwidths]{Indents and Numwidths (in ems)} \label{tab:indents}
13651 \begin{tabular}{lcrrrr} \toprule
13652 Entry & Level & \multicolumn{2}{c}{Standard} & \multicolumn{2}{c}{\Lclass{memoir} class} \\
13653 & & indent & numwidth & indent & numwidth \\ \midrule
13654 book & -2 & --- & --- & 0 & --- \\
13655 part & -1 & 0 & --- & 0 & 1.5 \\
13656 chapter & 0 & 0 & 1.5 & 0 & 1.5 \\
13657 section & 1 & 1.5 & 2.3 & 1.5 & 2.3 \\
13658 subsection & 2 & 3.8 & 3.2 & 3.8 & 3.2 \\
13659 subsubsection & 3 & 7.0 & 4.1 & 7.0 & 4.1 \\
13660 paragraph & 4 & 10.0 & 5.0 & 10.0 & 5.0 \\
13661 subparagraph & 5 & 12.0 & 6.0 & 12.0 & 6.0 \\
13662 figure/table & (1) & 1.5 & 2.3 & 0 & 1.5 \\
13663 subfigure/table & (2) & ---& ---& 1.5 & 2.3 \\
13664 \bottomrule
13665 \end{tabular}
13666 \end{table}
13667
13668 \tref{tab:indents} lists the standard values for the \textit{indent}
13669 and \textit{numwidth}. There is no explicit \textit{numwidth} for a
13670 part\index{part}; instead a gap of 1em is put between the number and
13671 the title text. Note that for a sectioning command the values depend
13672 on whether or not the document class provides the \cmd{\chapter}
13673 command; the listed values are for the \Lclass{book} and
13674 \Lclass{report} classes --- in the \Lclass{article} class a
13675 \cmd{\section} is treated like a \cmd{\chapter}, and so on. Also,
13676 which somewhat surprises me, the table\index{table} and
13677 figure\index{figure} entries are all indented.
13678
13679 \begin{syntax}
13680 \cmd{\@dottedtocline}\marg{level}\marg{indent}\marg{numwidth} \\
13681 \end{syntax}
13682 \glossary(@dottedtocline)%
13683 {\cs{@dottedtocline}\marg{level}\marg{indent}\marg{numwidth}}%
13684 {For a \prtoc, (\prlof, \prlot) entry at \meta{level} specifies the
13685 \meta{indent} and \meta{numwidth} and draws a dotted line between
13686 the title and page number.}
13687 Most of the \verb?\l@kind? commands are defined in terms of the
13688 \cmd{\@dottedtocline} command. This command takes three arguments:
13689 the \meta{level} argument is the level as shown in \tref{tab:indents},
13690 and \meta{indent} and \meta{numwidth} are the \textit{indent} and
13691 \textit{numwidth} as illustrated in \fref{fig:ltoc}.
13692 For example, one definition of the \cmd{\l@section} command is:
13693 \begin{lcode}
13694 \newcommand*{\l@section}{\@dottedtocline{1}{1.5em}{2.3em}}
13695 \end{lcode}
13696 If it is necessary to change the default typesetting of the entries,
13697 then it is usually necessary to change these definitions, but \Mname\
13698 gives you handles to easily alter things without having to know the \ltx\
13699 internals.
13700
13701 You can use the \cmd{\addcontentsline} command to add
13702 \cmd{\contentsline} commands to a file.
13703 \index{add to contents}\index{insert in contents}
13704
13705 \begin{syntax}
13706 \cmd{\addtocontents}\marg{file}\marg{text} \\
13707 \end{syntax}
13708 \glossary(addtocontents)%
13709 {\cs{addtocontents}\marg{file}\marg{text}}%
13710 {Inserts \meta{text} into \meta{file} (\prtoc, etc).}
13711 \ltx\ also provides the \cmd{\addtocontents}
13712 command that will insert \meta{text} into \meta{file}. You can use
13713 this for adding extra text and/or macros into the file, for processing
13714 when the file is typeset by \cmd{\tableofcontents} (or whatever other
13715 command is used for \meta{file} processing, such as \cmd{\listoftables}
13716 for a \file{lot} file).
13717
13718 As \cmd{\addcontentsline} and \cmd{\addtocontents} write their arguments to a
13719 file, any fragile commands used in their arguments must be \cmd{\protect}ed.
13720
13721 You can make certain adjustments to the \toc, etc., layout by modifying
13722 some of the above macros. Some examples are:
13723 \begin{itemize}
13724 \item If your page numbers stick out into the righthand margin\index{margin!right}
13725 \begin{lcode}
13726 \renewcommand{\@pnumwidth}{3em}
13727 \renewcommand{\@tocrmarg}{4em}
13728 \end{lcode}
13729 but using lengths appropriate to your document.
13730
13731 \item To have the (sectional) titles in the \toc, etc., typeset ragged
13732 right with no hyphenation
13733 \begin{lcode}
13734 \renewcommand{\@tocrmarg}{2.55em plus1fil}
13735 \end{lcode}
13736 where the value \texttt{2.55em} can be changed for whatever
13737 margin\index{margin} space you want.
13738
13739 \item The dots in the leaders can be eliminated by increasing \cmd{\@dotsep}
13740 to a large value:
13741 \begin{lcode}
13742 \renewcommand{\@dotsep}{10000}
13743 \end{lcode}
13744
13745 \item To have dotted leaders in your \toc\ and \lof\ but not in your \lot:
13746 \begin{lcode}
13747 ...
13748 \tableofcontents
13749 \makeatletter \renewcommand{\@dotsep}{10000} \makeatother
13750 \listoftables
13751 \makeatletter \renewcommand{\@dotsep}{4.5} \makeatother
13752 \listoffigures
13753 ...
13754 \end{lcode}
13755
13756 \item To add a horizontal line across the whole width of the \toc\ below
13757 an entry for a Part\index{part}:
13758 \begin{lcode}
13759 \part{Part title}
13760 \addtocontents{toc}{\protect\mbox{}\protect\hrulefill\par}
13761 \end{lcode}
13762 As said earlier any fragile commands in the arguments to
13763 \cmd{\addtocontents} and \cmd{\addcontentsline} must be protected
13764 by preceding each fragile command with \cmd{\protect}.
13765 The result of the example above
13766 would be the following two lines in the \file{.toc} file (assuming that it
13767 is the second Part and is on page 34):
13768 \begin{lcode}
13769 \contentsline {part}{II\hspace {1em}Part title}{34}{}
13770 \mbox {}\hrulefill \par
13771 \end{lcode}
13772 If the \cmd{\protect}s were not used, then the second line would
13773 instead be:
13774 \begin{lcode}
13775 \unhbox \voidb@x \hbox {}\unhbox \voidb@x \leaders \hrule \hfill
13776 \kern \z@ \par
13777 \end{lcode}
13778 which would cause \ltx\ to stop and complain because of the commands
13779 that included the \texttt{@}\idxatincode (\seeatincode).
13780 If you are modifying any command that includes an
13781 \texttt{@}\idxatincode\
13782 sign then this must be done in either a \file{.sty} file or if in the
13783 document itself it must be surrounded by \cmd{\makeatletter} and
13784 \cmd{\makeatother}. For example, if you
13785 want to modify \cmd{\@dotsep} in the preamble\index{preamble} to your
13786 document you have to do it like this:
13787 \begin{lcode}
13788 \makeatletter
13789 \renewcommand{\@dotsep}{9.0}
13790 \makeatother
13791 \end{lcode}
13792
13793 \item To change the level of entries printed in the \toc\ (for example
13794 when normally subsections are listed in the \toc\ but for
13795 appendices\index{appendix} only the main title is required)
13796 \begin{lcode}
13797 \appendix
13798 \addtocontents{toc}{\protect\setcounter{tocdepth}{0}}
13799 \chapter{First appendix}
13800 ...
13801 \end{lcode}
13802
13803 \end{itemize}
13804
13805 \section{The class \prtoc{} methods}
13806 \label{sec:class-prtoc-methods}
13807
13808 The class provides various means of changing the look of the \toc, etc.,
13809 without having to go through some of the above.
13810
13811 \begin{syntax}
13812 \cmd{\tableofcontents} \cmd{\tableofcontents*} \\
13813 \cmd{\listoffigures} \cmd{\listoffigures*} \\
13814 \cmd{\listoftables} \cmd{\listoftables*} \\
13815 \end{syntax}
13816 \glossary(tableofcontents)%
13817 {\cs{tableofcontents}}%
13818 {Typeset the \prtoc, adding its title to the \prtoc\ itself.}
13819 \glossary(tableofcontents*)%
13820 {\cs{tableofcontents*}}%
13821 {Typeset the \prtoc.}
13822 \glossary(listoffigures)%
13823 {\cs{listoffigures}}%
13824 {Typeset the \prlof, adding its title to the \prtoc.}
13825 \glossary(listoffigures*)%
13826 {\cs{listoffigures*}}%
13827 {Typeset the \prlof.}
13828 \glossary(listoftables)%
13829 {\cs{listoftables}}%
13830 {Typeset the \prlot, adding its title to the \prtoc.}
13831 \glossary(listoftables*)%
13832 {\cs{listoftables*}}%
13833 {Typeset the \prlot.}
13834 The \toc, \lof, and \lot\ are printed at the point in the document where
13835 these commands are called, as per normal \ltx.
13836 You can use \cmd{\tableofcontents}, \cmd{\listoffigures}, etc., more
13837 than once in a \Lclass{memoir} class document.
13838
13839
13840 However, there are
13841 two differences between the standard \ltx\ behaviour and the behaviour
13842 with this class. In the standard \ltx\ classes
13843 that have \cmd{\chapter} headings\index{heading}, the \toc, \lof\ and \lot\
13844 each appear on a new page. With this class they do not necessarily
13845 start new pages; if you want them to be on new pages you may have to
13846 specifically issue an appropriate command beforehand. For example:
13847 \begin{lcode}
13848 ...
13849 \clearpage
13850 \tableofcontents
13851 \clearpage
13852 \listoftables
13853 ...
13854 \end{lcode}
13855 Also, the unstarred versions of the commands put their headings\index{heading}
13856 into the \toc, while the starred versions do not.
13857
13858 % \PWnote{2009/08/09}{Added description of KeepFromToc}
13859 \begin{syntax}
13860 \senv{KeepFromToc} \cs{listof...} \eenv{KeepFromToc} \\
13861 \end{syntax}
13862 \glossary(KeepFromToc)%
13863 {\senv{KeepFromToc}}%
13864 {Stop the titles of the enclosed \cs{listof...} commands from
13865 being added to the ToC.}
13866
13867 There is at least one package that uses \cs{tableofcontents} for its
13868 own \listofx. When used with the class this will put the package's
13869 \listofx\
13870 title into the \toc, and the package doesn't seem to know about
13871 \cs{tableofcontents*}.
13872 The heading of any \cs{listof...} command that is in the \Ie{KeepFromToc}
13873 environment will not be added to the \toc. For example:
13874 \begin{lcode}
13875 \begin{KeepFromToc}
13876 \listoffigures
13877 \end{KeepFromToc}
13878 \end{lcode}
13879 is equivalent to \cs{listoffigures*}.
13880
13881
13882 \PWnote{2009/03/17}{Added \cs{(one|two|doc)coltocetc} descriptions.}
13883 \begin{syntax}
13884 \cmd{\onecoltocetc} \\
13885 \cmd{\twocoltocetc} \\
13886 \cmd{\doccoltocetc} \\
13887 \end{syntax}
13888 \glossary(onecoltocetc)%
13889 {\cs{onecoltocetc}}%
13890 {Set the ToC, etc., in one column.}
13891 \glossary(twocoltocetc)%
13892 {\cs{twocoltocetc}}%
13893 {Set the ToC, etc., in two columns.}
13894 \glossary(doccoltocetc)%
13895 {\cs{doccoltocetc}}%
13896 {Set the ToC, etc., in one or two columns according to the class option.}
13897
13898
13899 In the standard classes the \toc, etc., are set in one column even if the
13900 document as a whole is set in two columns. This limitation is removed.
13901 Following the \cmd{\onecoltocetc} declaration, which is the default, the
13902 \toc\ and friends will be set in one column but after the \cmd{\twocoltocetc}
13903 declaration they will be set in two columns. Following the \cmd{\doccoltocetc}
13904 declaration they will be set in either one or two columns to match the
13905 document class \Lopt{onecolumn} or \Lopt{twocolumn} option.
13906
13907 \begin{syntax}
13908 \cmd{\maxtocdepth}\marg{secname} \\
13909 \cmd{\settocdepth}\marg{secname} \qquad \cmd{\settocdepth*}\marg{secname}\\
13910 \end{syntax}
13911 \glossary(maxtocdepth)%
13912 {\cs{maxtocdepth}\marg{secname}}%
13913 {Sets the maximum value of the \Pcn{tocdepth} counter.}
13914 \glossary(settocdepth)%
13915 {\cs{settocdepth}\marg{secname}}%
13916 {Sets the value of the \Pcn{tocdepth} counter in the \file{toc} file.}
13917 % The class \cmd{\maxtocdepth} command sets the maximum
13918 % allowable value
13919 % for the \Icn{tocdepth} counter. If used, the command must appear
13920 % before the \cmd{\tableofcontents} command. By default, the class
13921 % sets \verb?\maxtocdepth{section}?.
13922 \LMnote{2013/04/24}{As far as I can see \cs{maxtocdepth} is not used
13923 anywhere. Manual clarified, see http://tex.stackexchange.com/a/97018/3929}
13924 The class \cmd{\maxtocdepth} command sets the \Icn{tocdepth}
13925 counter. It is currently not used in the \Lclass{memoir} class.
13926
13927
13928 The \Lclass{memoir} class command \cmd{\settocdepth} is somewhat
13929 analagous to the \cmd{\setsecnumdepth} command described in
13930 \S\ref{sec:secnumbers}. It sets the value of the \Icn{tocdepth}
13931 counter and puts it into the \toc{} to (temporarily) modify what will
13932 appear. The \cmd{\settocdepth} and \cmd{\maxtocdepth} macros are from
13933 the \Lpack{tocvsec2} package~\cite{TOCVSEC2}.
13934 \begin{caveat}[February 2024]
13935 In a situation like this
13936 \begin{verbatim}
13937 \settocdepth{section}
13938 \include{fileA}
13939 \end{verbatim}
13940 The TOC data (\verb+section+) may be writen \emph{after} the data from \verb+fileA+!
13941
13942 In such a case try using \cmd{\settocdepth*} instead. As it may
13943 insert a \cmd{\clearpage}, this code is not the default.
13944 \end{caveat}
13945
13946 \fancybreak{}
13947
13948 When we want to manually add something to the table of contents and we
13949 are using \Lpack{hyperref} we often do not have anything suitable for
13950 the hyperlink to. We therefore have to manually help. Traditionally one would use
13951 \begin{syntax}
13952 \cmd{\phantomsection} \\
13953 \end{syntax}
13954 \glossary(phantomsection) {\cs{phantomsection}}%
13955 {A method to add a link target for a hyperlink or label to latch on to
13956 when the \Ppack{hyperref} package is used.}
13957 As of 2022 we can also use one (see \cite{CLSGUIDE})
13958 \begin{syntax}
13959 %\cmd{\MakeLinkTarget}\oarg{prefix}\marg{counter name}\\
13960 \cmd{\MakeLinkTarget}\oarg{prefix}\verb|{}| %\verb|% similar to \phantomsection|
13961 \\
13962 \cmd{\MakeLinkTarget*}\marg{target name}\\
13963 \end{syntax}
13964 \glossary(phantomsection)
13965 {\cs{MakeLinkTarget}}%
13966 {A way to generate a target for a hyperlink with or without the name of a counter}
13967 \glossary(phantomsection)
13968 {\cs{MakeLinkTarget*}}%
13969 {Similar to \cs{MakeLinkTarget}, but here we determine the target name}
13970 %
13971 A typical example:
13972 \begin{lcode}
13973 ...some code...
13974 \MakeLinkTarget[section]{}
13975 \addcontentsline{toc}{section}{Dedication}
13976 \end{lcode}
13977 Here we directly specified that the prefix should be \meta{section},
13978 which is exactly what \cs{phantomsection} does. But now we can easily
13979 change this if this is, say, a chapter instead. With macros like
13980 \cs{section(*)} and friends, \Lpack{hyperrer} make sure the target is
13981 at the right place above the title.
13982
13983
13984
13985 \subsection{Changing the titles} \label{sec:titles}
13986
13987 Commands are provided for controlling the appearance of the
13988 \toc, \lof\ and \lot\ titles.
13989
13990 \begin{syntax}
13991 \cmd{\contentsname} \cmd{\listfigurename} \cmd{\listtablename} \\
13992 \end{syntax}
13993 \glossary(contentsname)%
13994 {\cs{contentsname}}%
13995 {The title for the Table of Contents.}
13996 \glossary(listfigurename)%
13997 {\cs{listfigurename}}%
13998 {The title for the List of Figures.}
13999 \glossary(listtablename)%
14000 {\cs{listtablename}}%
14001 {The title for the List of Tables.}
14002 Following \ltx\ custom, the title texts are the values
14003 of the \cmd{\contentsname}, \cmd{\listfigurename} and \cmd{\listtablename}
14004 commands.
14005 \begin{caveat}
14006 Most people use \Lpack{babel} which then controls the actual text
14007 storred in, say \cmd{\contentsname}. Any redefinition is the reset
14008 whenever a language is reset.
14009
14010 The proper method to change, say, a Danish \cmd{\contentsname} to
14011 \emph{FooBar} would be
14012 \begin{lcode}
14013 \setlocalecaption{danish}{contents}{FooBar}
14014 \end{lcode}
14015 Note how here the \texttt{name} part of the macro is ignored. The old
14016 style of using \verb?\addto\captionsdanish{\renewcommand...}?, is also
14017 available, but the \cs{setlocalecaption} method is preferred and
14018 easier to use.
14019 \end{caveat}
14020
14021
14022 The commands for controlling the typesetting of the \toc, \lof\ and \lot\
14023 titles all follow a similar pattern, so for convenience (certainly mine,
14024 and hopefully yours) in the following descriptions I will use \texttt{X},
14025 as listed in \tref{tab:Xlistofxtitles},
14026 to stand for the file extension for the appropriate \listofx. That is, any
14027 of the following:
14028 \begin{itemize}
14029 \item \texttt{toc} or
14030 \item \texttt{lof} or
14031 \item \texttt{lot}.
14032 \end{itemize}
14033 For example, \verb?\Xmark? stands for \cmd{\tocmark} or \cmd{\lofmark} or
14034 \cmd{\lotmark}.
14035
14036 \begin{table}
14037 \centering
14038 \caption{Values for \texttt{X} in macros for styling the titles of \listofx}
14039 \label{tab:Xlistofxtitles}
14040 \begin{tabular}{cccc}\toprule
14041 \texttt{toc} & \texttt{lof} & \texttt{lot} & \texttt{\ldots} \\
14042 \bottomrule
14043 \end{tabular}
14044 \end{table}
14045
14046 The code for typesetting the \toc\ title looks like:
14047 \begin{lcode}
14048 \tocheadstart
14049 \printtoctitle{\contentsname}
14050 \tocmark
14051 \thispagestyle{chapter}
14052 \aftertoctitle
14053 \end{lcode}
14054 where the macros are described below.
14055
14056 \begin{syntax}
14057 \cmd{\Xheadstart} \\
14058 \end{syntax}
14059 \glossary(Xheadstart)%
14060 {\cs{Xheadstart}}%
14061 {Generic macro called before printing a 'X List of' title.}
14062 % \begin{comment}
14063 % \glossary(tocheadstart)%
14064 % {\cs{tocheadstart}}%
14065 % {Called before printing the \prtoc\ title.}
14066 % \glossary(lofheadstart)%
14067 % {\cs{lofheadstart}}%
14068 % {Called before printing the \prlof\ title.}
14069 % \glossary(lotheadstart)%
14070 % {\cs{lotheadstart}}%
14071 % {Called before printing the \prlot\ title.}
14072 % \end{comment}
14073 This macro is called before the title is actually printed.
14074 Its default definition is
14075 \begin{lcode}
14076 \newcommand{\Xheadstart}{\chapterheadstart}
14077 \end{lcode}
14078
14079 \begin{syntax}
14080 \cmd{\printXtitle}\marg{title} \\
14081 \end{syntax}
14082 \glossary(printXtitle)%
14083 {\cs{printXtitle}\marg{title}}%
14084 {Generic macro printing \meta{title} as the title for the `X List of'.}
14085 % \begin{comment}
14086 % \glossary(printtoctitle)%
14087 % {\cs{printtoctitle}\marg{title}}%
14088 % {Prints \meta{title} as the title for the \prtoc.}
14089 % \glossary(printloftitle)%
14090 % {\cs{printloftitle}\marg{title}}%
14091 % {Prints \meta{title} as the title for the \prlof.}
14092 % \glossary(printlottitle)%
14093 % {\cs{printlottitle}\marg{title}}%
14094 % {Prints \meta{title} as the title for the \prlot.}
14095 % \end{comment}
14096 The title is typeset via \cmd{\printXtitle}, which defaults to
14097 using \cmd{\printchaptertitle} for the actual typesetting.
14098
14099 \begin{syntax}
14100 \cmd{\Xmark} \\
14101 \end{syntax}
14102 \glossary(Xmark)%
14103 {\cs{Xmark}}%
14104 {Generic macro setting the marks for the 'X List of'.}
14105 % \begin{comment}
14106 % \glossary(tocmark)%
14107 % {\cs{tocmark}}%
14108 % {Macro setting the marks for the \prtoc.}
14109 % \glossary(lofmark)%
14110 % {\cs{lofmark}}%
14111 % {Macro setting the marks for the \prlof.}
14112 % \glossary(lotmark)%
14113 % {\cs{lotmark}}%
14114 % {Macro setting the marks for the \prlot.}
14115 % \end{comment}
14116 These macros sets the marks for use by the running heads on the \toc, \lof, and
14117 \lot\ pages. The default definition is equivalent to:
14118 \begin{lcode}
14119 \newcommand{\Xmark}{\markboth{\...name}{\...name}}
14120 \end{lcode}
14121 where \verb?\...name? is \cmd{\contentsname} or \cmd{\listfigurename} or
14122 \cmd{\listtablename} as appropriate. You probably don't need to change these, and
14123 in any case they may well be changed by the particular \cmd{\pagestyle} in
14124 use.
14125
14126 \begin{syntax}
14127 \cmd{\afterXtitle} \\
14128 \end{syntax}
14129 \glossary(afterXtitle)%
14130 {\cs{afterXtitle}}%
14131 {Generic macro called after typesetting the title of the `X List of'.}
14132 % \begin{comment}
14133 % \glossary(aftertoctitle)%
14134 % {\cs{aftertoctitle}}%
14135 % {Macro called after typesetting the title of the \prtoc.}
14136 % \glossary(afterloftitle)%
14137 % {\cs{afterloftitle}}%
14138 % {Macro called after typesetting the title of the \prlof.}
14139 % \glossary(afterlottitle)%
14140 % {\cs{afterlottitle}}%
14141 % {Macro called after typesetting the title of the \prlot.}
14142 % \end{comment}
14143 This macro is called after the title is typeset and by
14144 default it is defined to be \cmd{\afterchaptertitle}.
14145
14146 Essentially, the \toc, \lof\ and \lot\ titles use the same format
14147 as the chapter titles, and will be typeset according to the current
14148 chapterstyle. You can modify their appearance by either using a
14149 different chapterstyle for them than for the actual chapters, or
14150 by changing some of the macros. As examples:
14151 \begin{itemize}
14152 \item Doing
14153 \begin{lcode}
14154 \renewcommand{\printXtitle}[1]{\hfill\Large\itshape #1}
14155 \end{lcode}
14156 will print the title right justified in a Large italic font.
14157 \item For a Large bold centered title you can do
14158 \begin{lcode}
14159 \renewcommand{\printXtitle}[1]{\centering\Large\bfseries #1}
14160 \end{lcode}
14161 \item Writing
14162 \begin{lcode}
14163 \renewcommand{\afterXtitle}{%
14164 \thispagestyle{empty}\afterchaptertitle}
14165 \end{lcode}
14166 will result in the first page of the listing using the \pstyle{empty}
14167 pagestyle instead of the default \pstyle{chapter} pagestyle.
14168 \item Doing
14169 \begin{lcode}
14170 \renewcommand{\afterXtitle}{%
14171 \par\nobreak \mbox{}\hfill{\normalfont Page}\par\nobreak}
14172 \end{lcode}
14173 will put the word `Page' flushright on the line following
14174 the title.
14175 \end{itemize}
14176
14177
14178 \subsection{Typesetting the entries} \label{sec:entries}
14179
14180 Commands are also provided to enable finer control over the typesetting
14181 of the different kinds of entries. The parameters defining the default
14182 layout of the entries are illustrated as part of the \Lpack{layouts}
14183 package~\cite{LAYOUTS} or in~\cite[p. 51]{COMPANION}, and are repeated in
14184 \fref{fig:ltoc}.
14185
14186 Most of the commands in this section start as \cs{cft...}, where
14187 \texttt{cft} is intended as a mnemonic for \textit{Table of \textbf{C}ontents,
14188 List of \textbf{F}igures, List of \textbf{T}ables}.
14189
14190 \begin{syntax}
14191 \cmd{\cftdot} \\
14192 \end{syntax}
14193 \glossary(cftdot)%
14194 {\cs{cftdot}}%
14195 {The `dot' in the dotted leaders in \listofx.}
14196 In the default \toc{} typesetting only the more minor entries have dotted
14197 leader lines between the sectioning title and the page number. The
14198 class provides for general leaders for all entries.
14199 The `dot' in a leader is given by the value of \cmd{\cftdot}. Its default
14200 definition is \verb?\newcommand{\cftdot}{.}? which gives the default
14201 dotted leader. By changing \cmd{\cftdot} you can use symbols other than
14202 a period in the leader. For example
14203 \begin{lcode}
14204 \renewcommand{\cftdot}{\ensuremath{\ast}}
14205 \end{lcode}
14206 will result in a dotted leader using asterisks as the symbol.
14207
14208 \begin{syntax}
14209 \cmd{\cftdotsep} \\
14210 \cmd{\cftnodots} \\
14211 \end{syntax}
14212 \glossary(cftdotsep)%
14213 {\cs{cftdotsep}}%
14214 {The separation between dots in a dotted leader in a \listofx.}
14215 \glossary(cftnodots)%
14216 {\cs{cftnodots}}%
14217 {A separation between dots in a dotted leader in a \listofx\
14218 that is too large for any dots to occur.}
14219 Each kind of entry can control the separation between the dots
14220 in its leader (see below). For consistency though, all dotted leaders
14221 should use the same spacing. The macro \cmd{\cftdotsep} specifies the
14222 default spacing.
14223 However, if the separation is too large
14224 then no dots will be actually typeset. The macro \cmd{\cftnodots} is
14225 a separation value that is `too large'.
14226
14227 \begin{syntax}
14228 \cmd{\setpnumwidth}\marg{length} \\
14229 \cmd{\setrmarg}\marg{length} \\
14230 \end{syntax}
14231 \glossary(setpnumwidth)%
14232 {\cs{setpnumwidth}\marg{length}}%
14233 {Sets the width of the page number box (\cs{@pnumwidth}) in a \listofx\ to
14234 \meta{length}.}
14235 \glossary(setrmarg)%
14236 {\cs{setrmarg}\marg{length}}%
14237 {Sets the right hand title margin (\cs{@tocrmarg}) in a \listofx\ to
14238 \meta{length}.}
14239 The page numbers are typeset in a fixed width box. The command
14240 \cmd{\setpnumwidth} can be used to change the width
14241 of the box (LaTeX 's internal \cmd{\@pnumwidth}).
14242 The title texts will end before reaching the righthand
14243 margin\index{margin!right}.
14244 \cmd{\setrmarg} can be used to set this distance
14245 (LaTeX 's internal \cmd{\@tocrmarg}).
14246 Note that the length used in \cmd{\setrmarg} should be greater
14247 than the length set in \cmd{\setpnumwidth}. These values should remain
14248 constant in any given document.
14249
14250 This manual requires more space for the page numbers than the default,
14251 so the following was set in the preamble\index{preamble}:
14252 \begin{lcode}
14253 \setpnumwidth{2.55em}
14254 \setrmarg{3.55em}
14255 \end{lcode}
14256
14257
14258 \begin{syntax}
14259 \lnc{\cftparskip} \\
14260 \end{syntax}
14261 \glossary(cftparskip)%
14262 {\cs{cftparskip}}%
14263 {The \cs{parskip} to be used in a \listofx.}
14264 Normally the \lnc{\parskip} in the \toc, etc., is zero. This may be changed
14265 by changing the length \lnc{\cftparskip}. Note that the current value
14266 of \lnc{\cftparskip} is used for the \toc, \lof\ and \lot, but you can change
14267 the value before calling \cmd{\tableofcontents} or \cmd{\listoffigures} or
14268 \cmd{\listoftables} if one or other of these should have different values
14269 (which is not a good idea).
14270
14271
14272 Again for convenience, in the following I will use \texttt{K} to stand
14273 for the \emph{kind} of entry, as listed in \tref{tab:Klistofxtitles}; that is,
14274 any of the following:
14275 \begin{itemize}
14276 \item \texttt{book} for \cmd{\book} titles.
14277 \item \texttt{part} for \cmd{\part} titles
14278 \item \texttt{chapter} for \cmd{\chapter} titles
14279 \item \texttt{section} for \cmd{\section} titles
14280 \item \texttt{subsection} for \cmd{\subsection} titles
14281 \item \texttt{subsubsection} for \cmd{\subsubsection} titles
14282 \item \texttt{paragraph} for \cmd{\paragraph} titles
14283 \item \texttt{subparagraph} for \cmd{\subparagraph} titles
14284 \item \texttt{figure} for figure \cmd{\caption} titles
14285 \item \texttt{subfigure} for subfigure \cmd{\caption} titles
14286 \item \texttt{table} for table \cmd{\caption} titles
14287 \item \texttt{subtable} for subtable \cmd{\caption} titles
14288 \end{itemize}
14289
14290 \begin{table}
14291 \centering
14292 \caption{Value of \texttt{K} in macros for styling entries in a \listofx}
14293 \label{tab:Klistofxtitles}
14294 \begin{tabular}{llcll} \toprule
14295 \multicolumn{1}{c}{\texttt{K}} & \multicolumn{1}{c}{Kind of entry} & &
14296 \multicolumn{1}{c}{\texttt{K}} & \multicolumn{1}{c}{Kind of entry} \\ \midrule
14297 \texttt{book} & \cmd{\book} title & & \texttt{subparagraph} & \cmd{\subparagraph} title \\
14298 \texttt{part} & \cmd{\part} title & & \texttt{figure} & figure caption \\
14299 \texttt{chapter} & \cmd{\chapter} title & & \texttt{subfigure} & subfigure caption \\
14300 \texttt{section} & \cmd{\section} title & & \texttt{table} & table caption \\
14301 \texttt{subsection} & \cmd{\subsection} title & & \texttt{subtable} & subtable caption \\
14302 \texttt{subsubsection} & \cmd{\subsubsection} title & & \texttt{\ldots} & \ldots \\
14303 \bottomrule
14304 \end{tabular}
14305 \end{table}
14306
14307 \fancybreak{$*{}*{}*$}
14308
14309 The toc macros for \cmd\book, \cmd\part\ and \cmd\chapter\ slightly
14310 differs from the other. Two ways, firstly the spacing above the entry
14311 (see \cs{cftbeforeXskip} later on), is factored out into the following
14312 macros\label{cftbreak-start}
14313 \begin{syntax}
14314 \cmd{\cftbookbreak} \\
14315 \cmd{\cftpartbreak} \\
14316 \cmd{\cftchapterbreak} \\
14317 % \cmd{\cftbeforebookpenalty} \\
14318 % \cmd{\cftbeforepartpenalty} \\
14319 % \cmd{\cftbeforechapterpenalty} \\
14320 \end{syntax}
14321 \glossary(cftbookbreak)%
14322 {\cs{cftbookbreak}}%
14323 {Starts a \cs{book} entry in the \prtoc.}
14324 \glossary(cftpartbreak)%
14325 {\cs{cftpartbreak}}%
14326 {Starts a \cs{part} entry in the \prtoc.}
14327 \glossary(cftchapterbreak)%
14328 {\cs{cftchapterbreak}}%
14329 {Starts a \cs{chapter} entry in the \prtoc.}
14330 %
14331 Besides adding the vertical space they \emph{also} add a penalty to
14332 encourage \ltx\ to do page breaking before it rahter than after
14333 it. In pseudo code it can be though of as (Y being one of book, part
14334 or chapter).
14335 \begin{verbatim}
14336 \newcommand\cftYbreak{
14337 add a penanalty
14338 add \cftbeforeYskip as vertical space
14339 }
14340 \end{verbatim}
14341 The penalty part is \emph{not} present in the other constructions.
14342
14343 % When \cmd{\l@book} starts to typeset a \cmd{\book} entry in the
14344 % \toc{} the first thing it does is to call the macro \cmd{\cftbookbreak}.
14345 % This is defined as:
14346 % \begin{lcode}
14347 % \newcommand{\cftbookbreak}{%
14348 % \addpenalty{-\@highpenalty}
14349 % \addvspace{\cftbeforebookskip}
14350 % }
14351 % \end{lcode}
14352 % which encourages a page break before rather than after the entry. As
14353 % usual, you can change \cmd{\cftbookbreak} to do other things that you
14354 % feel might be useful. The macros \cmd{\cftpartbreak} and
14355 % \cmd{\cftchapterbreak} apply to \cmd{\part} and \cmd{\chapter}
14356 % entries, respectively. Whereas \cmd{\cftpartbreak} has the same
14357 % definition as \cmd{\cftbookbreak}, \cmd{\cftchapterbreak} does not. By
14358 % default it uses \cs{vskip} instead of \cs{addvspace}, mimicking the
14359 % \Lclass{book} class.
14360 \begin{Changed}[March 2025]
14361 Where the vertical spacing was already a part of \cmd{\cftbookbreak}
14362 and \cmd{\cftpartbreak}, it was not the case for
14363 \cmd{\cftchapterbreak}. This discrepancy was fixed in 2025. Please
14364 note that this will cause issues with existing documents if you have
14365 modified \cs{cftchapterbreak}. Which was one of the reasons for factoring out the penalties, see below.
14366 \end{Changed}
14367
14368 As of March 2025, we have factored out the penalties used in the to
14369 entries for \cmd\book, \cmd\part\ and \cmd\chapter. They all have a default value of \verb|-\@highpenalty|, aka
14370 \makeatletter
14371 $-\the\@highpenalty$.
14372 \makeatother
14373 Negative values will encourage breaking at this point. The macros can be changed using \cs{renewcommand}.
14374 \begin{syntax}
14375 \cmd{\cftbeforebookpenalty} \\
14376 \cmd{\cftbeforepartpenalty} \\
14377 \cmd{\cftbeforechapterpenalty} \\
14378 \end{syntax}
14379 \glossary(cftbeforebookpenalty)%
14380 {\cs{cftbeforebookpenalty}}%
14381 {Penalty before a book entry in ToC.}
14382 \glossary(cftbeforepartpenalty)%
14383 {\cs{cftbeforepartpenalty}}%
14384 {Penalty before a part entry in ToC.}
14385 \glossary(cftbeforechapterpenalty)%
14386 {\cs{cftbeforechapterpenalty}}%
14387 {Penalty before a chapter entry in ToC.}
14388
14389
14390 \begin{Changed}[March 2025]
14391 There is an interesting inheritance from the standard book
14392 class. Both \cs{cftbeforebookskip} and \cs{cftbeforepartskip} are
14393 applied using \cs{addvspace} whereas \cs{cftbeforechapterskip} uses
14394 \cs{vskip}. Nobody really knows why the standard classes split it
14395 like this, but it has been like this for more than 35 years.
14396
14397 Why is this relevant? Because overall \cs{addvspace} would be a better choice.
14398 The difference can be seen with these two documents
14399 \begin{verbatim}
14400 \documentclass{memoir}
14401 \setlength\cftbeforechapterskip{5em} % more noticeable
14402 \begin{document}
14403 \tableofcontents*
14404 \chapter{Foo}
14405 \end{document}
14406 %
14407 \documentclass{memoir}
14408 \setlength\cftbeforepartskip{5em} % more noticeable
14409 \begin{document}
14410 \tableofcontents*
14411 \part{Foo}
14412 \end{document}
14413 \end{verbatim}
14414 As we see \cs{cftbeforechapterskip} is always applied when it is the
14415 first element in the ToC. But this is not the case for \cs{part}. The
14416 difference is down to \cmd{\addvspace} vs. \cmd{\vskip}. For user
14417 convenience we have now made this difference configurable, see below.
14418 \end{Changed}
14419 \begin{syntax}
14420 \lnc{\setcftvspacecmd}\marg{macro}
14421 \end{syntax}
14422 \glossary(setcftvspacecmd)
14423 {\cs{setcftvspacecmd}}
14424 {Macro to set which vertical spacing command is by \cs{chapter} and friends that stem from \cs{newlistentry}}
14425 %
14426 This macro can set the vertical spacing command used by \cs{chapter}
14427 and the friends that stem from \cmd{\newlistentry}. The default is
14428 \cs{vskip}, a better option would be to use \cs{addvspace}. But as the
14429 comment above shows, changing the command to be \cs{addvspace} by
14430 default, would change the first page of the ToC for thousands of
14431 existing documents. Thus we leave it to the user to manually reset the
14432 macro using
14433 \begin{verbatim}
14434 \setcftvspacecmd{\addvspace}
14435 \end{verbatim}
14436 in your preamble.\label{cftbreak-end}
14437
14438 \fancybreak{}
14439
14440 Back to the macros that control the look of the entries:
14441 \begin{syntax}
14442 \lnc{\cftbeforeKskip} \\
14443 \end{syntax}
14444 \glossary(cftbeforeKskip)%
14445 {\cs{cftbeforeKskip}}%
14446 {Generic vertical space before a `K' entry in a \listofx.}
14447 This length controls the vertical space before an entry. It can be changed
14448 by using \cmd{\setlength}.
14449
14450
14451
14452
14453
14454
14455 \begin{syntax}
14456 \lnc{\cftKindent} \\
14457 \end{syntax}
14458 \glossary(cftKindent)%
14459 {\cs{cftKindent}}%
14460 {Generic indent of an `K' entry from the left margin in a \listofx.}
14461 This length controls the indentation of an entry from the left
14462 margin\index{margin!left} (\textit{indent} in \fref{fig:ltoc}). It
14463 can be changed using \cmd{\setlength}.
14464
14465 \begin{syntax}
14466 \lnc{\cftKnumwidth} \\
14467 \end{syntax}
14468 \glossary(cftKnumwidth)%
14469 {\cs{cftKnumwidth}}%
14470 {Generic space for the number of a `K' entry in a \listofx.}
14471 This length controls the space allowed for typesetting title numbers
14472 (\textit{numwidth} in \fref{fig:ltoc}). It can
14473 be changed using \cmd{\setlength}. Second and subsequent lines of a multiline
14474 title will be indented by this amount.
14475
14476 The remaining commands are related to the specifics of typesetting
14477 an entry.
14478 This is a simplified pseudo-code version for the typesetting of numbered
14479 and unnumbered entries.
14480 \LMnote{2012/07/29}{Added extra brace pair}
14481 \begin{lcode}
14482 {\cftKfont {{\cftKname \cftKpresnum SNUM\cftKaftersnum\hfil} \cftKaftersnumb TITLE}}
14483 {\cftKleader}{\cftKformatpnum{PAGE}}\cftKafterpnum\par
14484
14485 {\cftKfont TITLE}{\cftKleader}{\cftKformatpnum{PAGE}}\cftKafterpnum\par
14486 \end{lcode}
14487 where \texttt{SNUM} is the section number, \texttt{TITLE} is the title text
14488 and \texttt{PAGE}
14489 is the page number. In the numbered entry the pseudo-code
14490 \begin{lcode}
14491 {\cftKpresnum SNUM\cftKaftersnum\hfil}
14492 \end{lcode}
14493 is typeset within a box of width \lnc{\cftKnumwidth}, see the
14494 \cs{...numberlinebox} macros later on.
14495
14496 \begin{syntax}
14497 \cmd{\cftKfont} \\
14498 \end{syntax}
14499 \glossary(cftKfont)%
14500 {\cs{cftKfont}}%
14501 {Controls the appearance of the number and title of a `K' entry in a \listofx.}
14502 This controls the appearance of the title (and its preceding number,
14503 if any). It may be changed using \cmd{\renewcommand}.
14504
14505 \cmd{\cftKfont} takes no arguments as such, but the the number and
14506 title is presented to it as an argument. Thus one may end
14507 \cmd{\cftKfont} with a macro taking one argument, say
14508 \cmd{\MakeUppercase}, and which then readjust the text as needed.
14509
14510 \begin{caveat}
14511 Please read the section entitled
14512 \emph{\titleref{sec:about-upper-or}} on
14513 page~\pageref{sec:about-upper-or} if you consider using upper/lower
14514 cased TOC entries and especially if you are also using the
14515 \Lpack{hyperref} package.
14516 \end{caveat}
14517
14518 \begin{caveat}
14519 In some specialised designs it can be necessary to patch some
14520 \cs{l@...} commands in order to get rid of some of the grouping
14521 described in the pseudo code above. How to do this is not described
14522 in this manual.
14523 \end{caveat}
14524
14525
14526
14527 \begin{syntax}
14528 \cmd{\cftKname} \\
14529 \end{syntax}
14530 \glossary(cftKname)
14531 {\cs{cftKname}}%
14532 {Called as the first element of the `K' entry line in a \listofx.}
14533 The first element typeset in an entry is
14534 \cmd{\cftKname}.\footnote{Suggested by Danie\index{Els, Danie} Els.}
14535 Its default definition is
14536 \begin{lcode}
14537 \newcommand*{\cftKname}{}
14538 \end{lcode}
14539 so it does nothing. However, to put the word `Chapter' before each chapter
14540 number in a \toc\ and `Fig.' before each figure number in a \lof\ do:
14541 \begin{lcode}
14542 \renewcommand*{\cftchaptername}{Chapter\space}
14543 \renewcommand*{\cftfigurename}{Fig.\space}
14544 \end{lcode}
14545
14546 \begin{syntax}
14547 \cmd{\cftKpresnum} \cmd{\cftKaftersnum} \cmd{\cftKaftersnumb} \\
14548 \end{syntax}
14549 \glossary(cftKpresnum)%
14550 {\cs{cftKpresnum}}%
14551 {Called immediately before typesetting the number of a `K' entry in a \listofx.}
14552 \glossary(cftKaftersnum)%
14553 {\cs{cftKaftersnum}}%
14554 {Called immediately after typesetting the number of a `K' entry in a \listofx.}
14555 \glossary(cftKaftersnumb)%
14556 {\cs{cftKaftersnumb}}%
14557 {Called immediately after typesetting the number box of a `K' entry in a \listofx.}
14558 The section number is typeset within a box of width \lnc{\cftKnumwidth}.
14559 Within the box the macro \cmd{\cftKpresnum} is first called, then the
14560 number is typeset, and the \cmd{\cftKaftersnum}
14561 macro is called after the number is typeset. The last command
14562 within the box is \cmd{\hfil} to make the box contents flushleft.
14563 After the box is
14564 typeset the \cmd{\cftKaftersnumb} macro is called before typesetting
14565 the title text. All three of these can be changed by \cmd{\renewcommand}.
14566 By default they are defined to do nothing.
14567
14568
14569 \begin{syntax}
14570 \cmd{\numberline}\marg{num} \\
14571 \cmd{\partnumberline}\marg{num} \\
14572 \cmd{\partnumberline}\marg{num} \\
14573 \cmd{\chapternumberline}\marg{num} \\
14574 \end{syntax}
14575 \glossary(numberline)
14576 {\cs{numberline}\marg{num}}
14577 {Typeset sectional number for \cs{section} and siblings in ToC}
14578 \glossary(partnumberline)
14579 {\cs{partnumberline}\marg{num}}
14580 {Typeset part number in ToC}
14581 \glossary(booknumberline)
14582 {\cs{booknumberline}\marg{num}}
14583 {Typeset book number in ToC}
14584 \glossary(chapternumberline)
14585 {\cs{chapternumberline}\marg{num}}
14586 {Typeset chapter number in ToC}
14587 In the \toc, the macros \cmd{\booknumberline}, \cmd{\partnumberline} and
14588 \cmd{\chapternumberline}
14589 are responsible respectively for typesetting the \cmd{\book}, \cmd{\part}
14590 and \cmd{\chapter}
14591 numbers, whereas \cmd{\numberline} does the same for the sectional
14592 siblings. Internally they use \cmd{\cftKpresnum}, \cmd{\cftKaftersnum}
14593 and \cmd{\cftKaftersnumb} as above. If you do not want, say,
14594 the \cmd{\chapter} number to appear you
14595 can do:
14596 \begin{lcode}
14597 \renewcommand{\chapternumberline}[1]{}
14598 \end{lcode}
14599
14600
14601 \begin{syntax}
14602 \cmd{\numberlinehook}\marg{num}\\
14603 \cmd{\cftwhatismyname}\\
14604 \cmd{\booknumberlinehook}\marg{num}\\
14605 \cmd{\partnumberlinehook}\marg{num}\\
14606 \cmd{\chapternumberlinehook}\marg{num}\\
14607 \cmd{\numberlinebox}\marg{length}\marg{code}\\
14608 \cmd{\booknumberlinebox}\marg{length}\marg{code}\\
14609 \cmd{\partnumberlinebox}\marg{length}\marg{code}\\
14610 \cmd{\chapternumberlinebox}\marg{length}\marg{code}\\
14611 \end{syntax}
14612 \glossary(numberlinehook)
14613 {\cs{numberlinehook}\marg{num}}
14614 {The first thing to be called within \cs{numberline}, does nothing by
14615 default.}
14616 \glossary(cftwhatismyname)
14617 {\cs{cftwhatismyname}}
14618 {Since \cs{numberline} is shared by \cs{section} and siblings,
14619 \cs{cftwhatismyname} can be used to tell which section type is
14620 calling \cs{numberlinehook}}
14621 \glossary(partnumberlinehook)
14622 {\cs{partnumberlinehook}\marg{num}}
14623 {The first thing to be called within \cs{partnumberline}, does nothing by
14624 default.}
14625 \glossary(booknumberlinehook)
14626 {\cs{booknumberlinehook}\marg{num}}
14627 {The first thing to be called within \cs{booknumberline}, does nothing by
14628 default.}
14629 \glossary(chapternumberlinehook)
14630 {\cs{chapternumberlinehook}\marg{num}}
14631 {The first thing to be called within \cs{chapternumberline}, does nothing by
14632 default.}
14633 \glossary(numberlinebox)
14634 {\cs{numberlinebox}\marg{length}\marg{code}}
14635 {The box command used to typeset the sectional number within the ToC,
14636 note that it will automatically align to the left}
14637 \glossary(partnumberlinebox)
14638 {\cs{partnumberlinebox}\marg{length}\marg{code}}
14639 {The box command used to typeset the part number within the ToC,
14640 note that it will automatically align to the left}
14641 \glossary(booknumberlinebox)
14642 {\cs{booknumberlinebox}\marg{length}\marg{code}}
14643 {The box command used to typeset the book number within the ToC,
14644 note that it will automatically align to the left}
14645 \glossary(chapternumberlinebox)
14646 {\cs{chapternumberlinebox}\marg{length}\marg{code}}
14647 {The box command used to typeset the chapter number within the ToC,
14648 note that it will automatically align to the left}
14649 Inside the four \cs{...numberline} macros, the first thing we do is to
14650 give the \cs{...numberline} argument to a hook. By default this hook
14651 does nothing. But, with the right
14652 tools,\footnote{Which we do not currently supply\dots, but have a look
14653 at Sniplet~\ref{snip:autotoc} on page~\pageref{snip:autotoc}.}
14654 they can be used to record the widths of the sectional number. Which then
14655 can be used to automatically adjust the various \meta{numwidth} and
14656 \meta{indent} within the \cs{cftsetindents} macro. In order to
14657 tell the section types apart (they all use \cmd{\numberline}), the
14658 value of the \cmd{\cftwhatismyname} macro will locally reflect the
14659 current type.
14660
14661 As mentioned earlier, the \cmd{\book}, \cmd{\part} and \cmd{\chapter}
14662 numbers are typeset inside a box of certain fixed widths. Sometimes it
14663 can be handy \emph{not} having this box around. For this you can
14664 redefine one of the four \cs{...numberlinebox} macros listed
14665 above. For example via
14666 \begin{lcode}
14667 \renewcommand\chapternumberlinebox[2]{#2}
14668 \end{lcode}
14669 The first argument is the width of the box to be made. All four
14670 macros are defined similar to this (where \texttt{\#1} is a length)
14671 \begin{lcode}
14672 \newcommand\chapternumberlinebox[2]{%
14673 \hb@xt@#1{#2\hfil}}
14674 \end{lcode}
14675
14676
14677 % \begin{comment}
14678 % \Note{} Because the \Lpack{hyperref} package~\cite{HYPERREF}
14679 % does not understand
14680 % the \cmd{\partnumberline} and \cmd{\chapternumberline} commands,
14681 % if you use the \Lpack{hyperref} package you will also have to use
14682 % the \Lpack{memhfixc} package, which comes with memoir.
14683 % \end{comment}
14684
14685
14686 \begin{syntax}
14687 \cmd{\cftKleader} \\
14688 \cmd{\cftKdotsep} \\
14689 \end{syntax}
14690 \glossary(cftKleader)
14691 {\cs{cftKleader}}%
14692 {Leader between the title and page number of a `K' entry in a \listofx.}
14693 \glossary(cftKdotsep)
14694 {\cs{cftKdotsep}}%
14695 {Separation between dots in a leader between the title and page number of a `K' entry in a \listofx.}
14696 \cmd{\cftKleader} defines the leader between the title and the page number;
14697 it can be changed by \cmd{\renewcommand}.
14698 The spacing between any dots in the leader is controlled by \cmd{\cftKdotsep}
14699 (\cmd{\@dotsep} in \fref{fig:ltoc}).
14700 It can be changed by \cmd{\renewcommand} and its value must be either a
14701 number (e.g., 6.6 or \cmd{\cftdotsep}) or \cmd{\cftnodots} (to
14702 disable the dots). The spacing is in terms of \emph{math units} where
14703 there are 18mu to 1em.
14704
14705 The default leaders macro is similar to
14706 \begin{lcode}
14707 \newcommand{\cftsectionleader}{\normalfont\cftdotfill{\cftsectiondotsep}}
14708 \end{lcode}
14709 Note that the spacing of the dots is affected by the font size (as the
14710 math unit is affected by the font size). Also note that the
14711 \cmd{\cftchapterleader} is bold by default.
14712
14713 \begin{syntax}
14714 \cmd{\cftKformatpnum}\marg{pnum} \\
14715 \cmd{\cftKformatpnumhook}\marg{num}\\
14716 \cmd{\cftKpagefont} \\
14717 \end{syntax}
14718 \glossary(cftKformatpnum)%
14719 {\cs{cftKformatpnum}\marg{pnum}}%
14720 {Typesets the page number \meta{pnum} of a `K' entry in a \listofx.}
14721 \glossary(cftKpagefont)%
14722 {\cs{cftKpagefont}}%
14723 {Font for the page number of a `K' entry in a \listofx.}
14724 \glossary(cftKformatpnumhook)%
14725 {\cs{cftKformatpnumhook}\marg{num}}%
14726 {When formatting the page number in the ToC (via
14727 \cs{cftKformatpnum}) this hook is given the page value. Does nothing by default}%
14728 The macro \cmd{\cftKformatpnum} typesets an entry's page number, using
14729 the \cmd{\cftKpagefont}.\footnote{This addition to the class was suggested
14730 by Dan\index{Luecking, Daniel} Luecking, \ctt\ \textit{Re: setting numbers in toc in their natural width box,} 2007/08/15.}
14731 The default definition is essentially:
14732 \begin{lcode}
14733 \newcommand*{\cftKformatpnum}[1]{%
14734 \cftKformatpnumhook{#1}%
14735 \hbox to \@pnumwidth{\hfil{\cftKpagefont #1}}}
14736 \end{lcode}
14737 which sets the number right justified in a box \lnc{\@pnumwidth} wide.
14738 To have, say, a \cmd{\part} page number left justified in its box, do:
14739 \begin{lcode}
14740 \renewcommand*{\cftpartformatpnum}[1]{%
14741 \cftpartformatpnumhook{#1}%
14742 \hbox to \@pnumwidth{{\cftpartpagefont #1}}}
14743 \end{lcode}
14744 The \cmd{\cftKformatpnumhook} does nothing by default (other than
14745 eating the argument), but could be redefined to record the widest page
14746 number and report it back, even reusing it to auto adjust on the next
14747 run to set \cs{@pnumwidth} (see \cmd{\setpnumwidth}).
14748
14749
14750 \begin{syntax}
14751 \cmd{\cftKafterpnum} \\
14752 \end{syntax}
14753 \glossary(cftKafterpnum)
14754 {\cs{cftKafterpnum}}%
14755 {Called after typesetting the page number of a `K' entry in a \listofx.}
14756 This macro is called after the page number has been typeset. Its default
14757 is to do nothing. It can be changed by \cmd{\renewcommand}.
14758
14759 \begin{syntax}
14760 \cmd{\cftsetindents}\marg{kind}\marg{indent}\marg{numwidth} \\
14761 \end{syntax}
14762 \glossary(cftsetindents)%
14763 {\cs{cftsetindents}\marg{kind}\marg{indent}\marg{numwidth}}%
14764 {Set the \meta{kind} entry \textit{indent} to \meta{indent} and
14765 its \textit{numwidth} to \meta{numwidth}.}
14766 The command
14767 \cmd{\cftsetindents} sets the \meta{kind} entries \textit{indent} to the
14768 length \meta{indent} and its
14769 \textit{numwidth} to the length \meta{numwidth}. The \meta{kind} argument
14770 is the name of one of the standard entries (e.g., \texttt{subsection}) or the
14771 name of entry that has been defined within the document.
14772 For example
14773 \begin{lcode}
14774 \cftsetindents{figure}{0em}{1.5em}
14775 \end{lcode}
14776 will make figure\index{figure} entries left justified.
14777
14778 This manual requires more space for section numbers in the \toc{} than
14779 the default (which allows for three digits). Consequently the preamble\index{preamble}
14780 contains the following:
14781 \begin{lcode}
14782 \cftsetindents{section}{1.5em}{3.0em}
14783 \cftsetindents{subsection}{4.5em}{3.9em}
14784 \cftsetindents{subsubsection}{8.4em}{4.8em}
14785 \cftsetindents{paragraph}{10.7em}{5.7em}
14786 \cftsetindents{subparagraph}{12.7em}{6.7em}
14787 \end{lcode}
14788 Note that changing the indents at one level implies that any lower level
14789 indents should be changed as well.
14790
14791
14792 Various effects can be achieved by changing the definitions of \cmd{\cftKfont},
14793 \cmd{\cftKaftersnum}, \cmd{\cftKaftersnumb}, \cmd{\cftKleader} and
14794 \cmd{\cftKafterpnum},
14795 either singly or in combination.
14796 For the sake of some examples, assume that we have the following initial
14797 definitions
14798 \begin{lcode}
14799 \newcommand*{\cftKfont}{}
14800 \newcommand*{\cftKaftersnum}{}
14801 \newcommand*{\cftKaftersnumb}{}
14802 \newcommand*{\cftKleader}{\cftdotfill{\cftKdotsep}}
14803 \newcommand*{\cftKdotsep}{\cftdotsep}
14804 \newcommand*{\cftKpagefont}{}
14805 \newcommand*{\cftKafterpnum}{}
14806 \end{lcode}
14807 Note that the same font should be used for the title, leader and page
14808 number to provide a coherent appearance.
14809
14810 \begin{itemize}
14811 \item To eliminate the dots in the leader:
14812 \begin{lcode}
14813 \renewcommand*{\cftKdotsep}{\cftnodots}
14814 \end{lcode}
14815
14816 \item To put something (e.g., a name) before the title (number):
14817 \begin{lcode}
14818 \renewcommand*{\cftKname}{SOMETHING }
14819 \end{lcode}
14820
14821 \item To add a colon after the section number:
14822 \begin{lcode}
14823 \renewcommand*{\cftKaftersnum}{:}
14824 \end{lcode}
14825
14826 \item To put something before the title number, add a double colon after
14827 the title number, set everything in bold font,
14828 and start the title text on the following line:
14829 \begin{lcode}
14830 \renewcommand*{\cftKfont}{\bfseries}
14831 \renewcommand*{\cftKleader}{\bfseries\cftdotfill{\cftKdotsep}}
14832 \renewcommand*{\cftKpagefont}{\bfseries}
14833 \renewcommand*{\cftKname}{SOMETHING }
14834 \renewcommand{\cftKaftersnum}{::}
14835 \renewcommand{\cftKaftersnumb}{\\}
14836 \end{lcode}
14837
14838 If you are adding text in the number box in addition to the number,
14839 then you will probably have to increase the width of the box so that
14840 multiline titles have a neat vertical alignment; changing box widths
14841 usually implies that the indents will require modification as
14842 well. One possible method of adjusting the box width for the above example
14843 is:
14844 \begin{lcode}
14845 \newlength{\mylen} % a "scratch" length
14846 \settowidth{\mylen}{\bfseries\cftKaftersnum}
14847 \addtolength{\cftKnumwidth}{\mylen} % add the extra space
14848 \end{lcode}
14849
14850 \LMnote{2012/07/29}{Added this example}
14851 \item To set the chapter number and title as just
14852 `NUM\enspace\textperiodcentered\enspace TITLE', i.e. un-boxed number
14853 plus a symbolic separator, use
14854 \begin{lcode}
14855 \renewcommand\cftchapteraftersnumb{\enspace\textperiodcentered\enspace}
14856 \renewcommand\chapternumberlinebox[2]{#2}
14857 \end{lcode}
14858 -- of couse, it works best, only if the TITLE is a single line.
14859
14860
14861 \item Make chapter titles lower case small caps
14862 \begin{lcode}
14863 \renewcommand\cftchapterfont{\scshape\MakeLowercase}
14864 \end{lcode}
14865 -- here we do not touch the case of any math.
14866
14867 \item To set the section numbers flushright:
14868 \begin{lcode}
14869 \setlength{\mylen}{0.5em} % extra space at end of number
14870 \renewcommand{\cftKpresnum}{\hfill} % note the double `l'
14871 \renewcommand{\cftKaftersnum}{\hspace*{\mylen}}
14872 \addtolength{\cftKnumwidth}{\mylen}
14873 \end{lcode}
14874 In the above, the added initial \cmd{\hfill} in the box overrides the
14875 final \cmd{\hfil} in the box, thus shifting everything to the right hand
14876 end of the box. The extra space is so that the number is not typeset
14877 immediately at the left of the title text.
14878
14879 \item To set the entry ragged left (but this only looks good for single
14880 line titles):
14881 \begin{lcode}
14882 \renewcommand{\cftKfont}{\hfill\bfseries}
14883 \renewcommand{\cftKleader}{}
14884 \end{lcode}
14885
14886 \item To set the titles ragged right instead of the usual flushright.
14887 Assuming that there are more than 100 pages in the document (otherwise
14888 adjust the length):
14889 \begin{lcode}
14890 \setrmarg{3.55em plus 1fil}
14891 \end{lcode}
14892 where the last four characters before the closing brace are: digit 1,
14893 lowercase F, lowercase I, and lowercase L.
14894
14895 \item To set the page number immediately after the entry text instead of at
14896 the righthand margin\index{margin!right}:
14897 \begin{lcode}
14898 \renewcommand{\cftKleader}{}
14899 \renewcommand{\cftKafterpnum}{\cftparfillskip}
14900 \end{lcode}
14901
14902 \end{itemize}
14903
14904 \begin{syntax}
14905 \cmd{\cftparfillskip} \\
14906 \end{syntax}
14907 \glossary(cftparfillskip)%
14908 {\cs{cftparfillskip}}%
14909 {Fills the last line in a paragraph in a \listofx.}
14910 By default the \cmd{\parfillskip} value is locally set to fill up the last
14911 line of a paragraph\index{paragraph}. Just changing \cmd{\cftKleader} as
14912 in the above example puts horrible interword
14913 spaces into the last line of the title. The \cmd{\cftparfillskip}
14914 command is provided just so that the above effect can be achieved.
14915
14916 \begin{syntax}
14917 \cmd{\cftpagenumbersoff}\marg{kind} \\
14918 \cmd{\cftpagenumberson}\marg{kind} \\
14919 \end{syntax}
14920 \glossary(cftpagenumbersoff)%
14921 {\cs{cftpagenumbersoff}\marg{kind}}%
14922 {Eliminates page numbers for the \meta{kind} entries in a \listofx.}
14923 \glossary(cftpagenumberson)%
14924 {\cs{cftpagenumberson}\marg{kind}}%
14925 {Reverses the effect of \cs{cftpagenumbersoff}.}
14926 The command \cmd{\cftpagenumbersoff} will
14927 eliminate the page numbers for \meta{kind} entries in the listing, where
14928 \meta{kind} is the name of one of the standard
14929 kinds of entries (e.g., \texttt{subsection}, or \texttt{figure}) or the
14930 name of a new entry defined in the document.
14931
14932 The command \cmd{\cftpagenumberson} reverses
14933 the effect of a corresponding \cmd{\cftpagenumbersoff} for \meta{kind}.
14934
14935 For example, to eliminate page numbers for appendices\index{appendix}
14936 in the \toc:
14937 \begin{lcode}
14938 ...
14939 \appendix
14940 \addtocontents{toc}{\cftpagenumbersoff{chapter}}
14941 \chapter{First appendix}
14942 \end{lcode}
14943 If there are other chapter type headings\index{heading!chapter} to go
14944 into the \toc{} after the appendices\index{appendix} (perhaps a
14945 bibliography\index{bibliography} or an index\index{index}),
14946 then it will be necessary to do a similar
14947 \begin{lcode}
14948 \addtocontents{toc}{\cftpagenumberson{chapter}}
14949 \end{lcode}
14950 after the appendices\index{appendix} to restore the page numbering in
14951 the \toc.
14952
14953 Sometimes it may be desirable to make a change to the global parameters
14954 for an individual entry. For example, a figure\index{figure} might be
14955 placed on the end paper\index{paper!end} of a book (the inside of the front
14956 or back cover), and this needs to be placed in a \lof\ with the page number
14957 set as, say, `inside front cover'. If `inside front cover' is typeset as
14958 an ordinary page number it will stick out into the margin\index{margin}.
14959 Therefore, the parameters for this particular entry need to be changed.
14960
14961 \begin{syntax}
14962 \cmd{\cftlocalchange}\marg{ext}\marg{pnumwidth}\marg{tocrmarg} \\
14963 \end{syntax}
14964 \glossary(cftlocalchange)%
14965 {\cs{cftlocalchange}\marg{ext}\marg{pnumwidth}\marg{tocrmarg}}%
14966 {Writes commands to the \meta{ext} \listofx\ file resetting
14967 \cs{@pnumwidth} and \cs{@tocrmarg} to the specified values.}
14968 The command \cmd{\cftlocalchange}
14969 will write an entry into the file with extension \meta{ext} to reset
14970 the global \cmd{\@pnumwidth} and \cmd{\@tocrmarg} parameter lengths.
14971 The command should be called again after any special entry to reset
14972 the parameters back to their usual values. Any fragile commands used
14973 in the arguments must be protected.
14974
14975 \begin{syntax}
14976 \cmd{\cftaddtitleline}\marg{ext}\marg{kind}\marg{title}\marg{page} \\
14977 \cmd{\cftaddnumtitleline}\marg{ext}\marg{kind}\marg{num}\marg{title}\marg{page} \\
14978 \end{syntax}
14979 \glossary(cftaddtitleline)%
14980 {\cs{cftaddtitleline}\marg{ext}\marg{kind}\marg{title}\marg{page}}%
14981 {Writes a \cs{contentsline} to the \listofx\ \meta{ext} file for
14982 a \meta{kind} entry with \meta{title} and \meta{page} number.}
14983 \glossary(cftaddnumtitleline)%
14984 {\cs{cftaddnumtitleline}\marg{ext}\marg{kind}\marg{num}\marg{title}\marg{page}}%
14985 {Writes a \cs{contentsline} to the \listofx\ \meta{ext} file for
14986 a \meta{kind} entry with number \meta{number} and \meta{title} and
14987 \meta{page} number.}
14988 The command \cmd{\cftaddtitleline}
14989 will write a \cmd{\contentsline} entry into \meta{ext} for a \meta{kind}
14990 entry with title \meta{title} and page number \meta{page}.
14991 Any fragile commands used in the arguments must be protected.
14992 That is,
14993 an entry is made of the form:
14994 \begin{lcode}
14995 \contentsline{kind}{title}{page}{}
14996 \end{lcode}
14997 The command \cmd{\cftaddnumtitleline}
14998 is similar to \cmd{\cftaddtitleline} except that it also includes
14999 \meta{num} as the argument to
15000 \cmd{\numberline}. That is, an entry is made of the form
15001 \begin{lcode}
15002 \contentsline{kind}{\numberline{num}title}{page}{}
15003 \end{lcode}
15004
15005 As an example of the use of these commands,
15006 noting that the default LaTeX values for
15007 \cmd{\@pnumwidth} and \cmd{\@tocrmarg} are 1.55em and 2.55em respectively,
15008 one might do the following for a figure\index{figure} on the
15009 frontispiece\index{frontispiece} page.
15010 \begin{lcode}
15011 ...
15012 this is the frontispiece page with no number
15013 draw or import the picture (with no \caption)
15014 \cftlocalchange{lof}{4em}{5em} % make pnumwidth big enough for
15015 % frontispiece and change margin
15016 \cftaddtitleline{lof}{figure}{The title}{frontispiece}
15017 \cftlocalchange{lof}{1.55em}{2.55em} % return to normal settings
15018 \clearpage
15019 ...
15020 \end{lcode}
15021 Recall that a \cmd{\caption} command will put an entry in the \file{lof}
15022 file, which is not wanted here. If a caption\index{caption} is required,
15023 then you can either craft one youself or, assuming that your general
15024 captions\index{caption} are not too exotic, use the \cmd{\legend} command
15025 (see later). If the illustration\index{illustration} is numbered, use
15026 \cmd{\cftaddnumtitleline} instead of \cmd{\cftaddtitleline}.
15027
15028
15029 \LMnote{2010/06/09}{Thought we needed a break here}
15030 \subsubsection{Inserting stuff into the content lists}
15031 \label{sec:inserting-stuff-into}
15032
15033
15034 The next functions were suggested by Lars\index{Madsen, Lars} Madsen who
15035 found them useful if, for example, you had two versions of the
15036 \toc\ and you needed some aspects to be formatted differently.
15037 \begin{syntax}
15038 \cmd{\cftinsertcode}\marg{name}\marg{code} \\
15039 \cmd{\cftinserthook}\marg{file}\marg{name} \qquad
15040 \cmd{\cftinserthook*}\marg{file}\marg{name} \\
15041 \end{syntax}
15042 \glossary(cftinsertcode)
15043 {\cs{cftinsertcode}\marg{name}\marg{code}}%
15044 {Defines Toc (LoF, LoT) \meta{name} insertion to be \meta{code}.}
15045 \glossary(cftinserthook)
15046 {\cs{cftinserthook}\marg{file}\marg{name}}%
15047 {Inserts code \meta{name} into \meta{file} (e.g., \texttt{toc}, \texttt{lof}, etc.}
15048 The \cmd{\cftinserthook} is somewhat like \cmd{\addtocontents} in that it
15049 enables you to insert a code hook into the \toc, etc., where \meta{file} is
15050 the (\texttt{toc}, \texttt{lof}, \ldots) file and \meta{name} is the `name'
15051 of the hook. The \meta{code} for the hook is specified via \cmd{\cftinsertcode}
15052 where \meta{name} is the name you give to the hook. These can be used to make
15053 alterations to a \listofx\ on the fly.
15054
15055 \begin{caveat}[February 2024]
15056 If \cmd{\cftinserthook} is placed between \cmd{\include}'s, one may experience
15057 a timing issue, such that, say,
15058 \begin{verbatim}
15059 \cftinserthook{toc}{preB}
15060 \include{fileB}
15061 \end{verbatim}
15062 inserts \verb+preB+ \emph{after} the data from \verb+fileB+!, making
15063 it rather unusable.
15064
15065 In that case use try \cmd{\cftinserthook*}. Given that
15066 \cmd{\cftinserthook*} may issue a \cmd{\clearpage}, which might be
15067 undesirable in documents without \cmd{\include}, the starred version
15068 is \emph{not} the default default.
15069 \end{caveat}
15070
15071 For example:
15072 \begin{lcode}
15073 \cftinsertcode{A}{%
15074 \renewcommand*{\cftchapterfont}{\normalfont\scshape}
15075 ... }% code for ToC
15076 ...
15077 \frontmatter
15078 \tableofcontents
15079 \cftinsertcode{G}{...}% code for LoF
15080 \cftinsertcode{F}{...}% code for LoF
15081 \listoffigures
15082 ...
15083 \cftinserthook{lof}{G}
15084 ...
15085 \chapter{...}
15086 ...
15087 \mainmatter
15088 \cftinserthook{toc}{A}
15089 \cftinserthook{lof}{F}
15090 \chapter{...}
15091 ...
15092 \end{lcode}
15093 If you do not use \cmd{\cftinsertcode} \emph{before} calling the command to
15094 type the \listofx\ that it is intended for then nothing will happen. No
15095 harm will come if a matching \cmd{\cftinserthook} is never used. No harm
15096 occurs either if you call \cmd{\cftinserthook} and there is no prior
15097 matching \cmd{\cftinsertcode}.
15098
15099 One use of these \toc{} hooks is reusing the \toc{} data to, say,
15100 create chapter \toc's. The code for this is shown in
15101 \snipref{snip:chaptertoc} on \pref{snip:chaptertoc}. In the sniplet we
15102 use the following two hooks that are executed right before and right
15103 after \cmd{\chapter}, \cmd{\part}, \cmd{\book}, \cmd{\appendixpage}
15104 writes to the \toc{}. By default they do nothing.\footnote{More hooks
15105 may be added in later releases.}
15106 \begin{syntax}
15107 \cmd{\mempreaddchaptertotochook}\\
15108 \cmd{\mempostaddchaptertotochook}\\
15109 \cmd{\mempreaddparttotochook}\\
15110 \cmd{\mempostaddparttotochook}\\
15111 \cmd{\mempreaddbooktotochook}\\
15112 \cmd{\mempostaddbooktotochook}\\
15113 \cmd{\mempreaddapppagetotochook}\\
15114 \cmd{\mempostaddapppagetotochook}
15115 \end{syntax}
15116 \glossary(mempreaddchaptertotochook)%
15117 {\cs{mempreaddchaptertotochook}}%
15118 {Hook executed right \emph{before} \cs{chapter} writes to the \protect\toc{}}
15119 \glossary(mempostaddchaptertotochook)%
15120 {\cs{mempostaddchaptertotochook}}%
15121 {Hook executed right \emph{after} \cs{chapter} writes to the \protect\toc{}}
15122 \glossary(mempreaddparttotochook)%
15123 {\cs{mempreaddparttotochook}}%
15124 {Hook executed right \emph{before} \cs{part} writes to the \protect\toc{}}
15125 \glossary(mempostaddparttotochook)%
15126 {\cs{mempostaddparttotochook}}%
15127 {Hook executed right \emph{after} \cs{part} writes to the \protect\toc{}}
15128 \glossary(mempreaddbooktotochook)%
15129 {\cs{mempreaddbooktotochook}}%
15130 {Hook executed right \emph{before} \cs{book} writes to the \protect\toc{}}
15131 \glossary(mempostaddbooktotochook)%
15132 {\cs{mempostaddbooktotochook}}%
15133 {Hook executed right \emph{after} \cs{book} writes to the \protect\toc{}}
15134 \glossary(mempreaddapppagetotochook)%
15135 {\cs{mempreaddapppagetotochook}}%
15136 {Hook executed right \emph{before} \cs{appendixpage} writes to the \protect\toc{}}
15137 \glossary(mempostaddapppagetotochook)%
15138 {\cs{mempostaddapppagetotochook}}%
15139 {Hook executed right \emph{after} \cs{appendixpage} writes to the \protect\toc{}}
15140
15141
15142
15143 \LMnote{2010/06/09}{Ineffective to have this seceral places in the manual.}
15144 \subsubsection{Extra chapter material in the ToC}
15145 \label{sec:extra-chapt-mater}
15146
15147 \begin{syntax}
15148 \cmd{\precistoctext}\marg{text} \cmd{\precistocfont} \cmd{\precistocformat}\\
15149 \end{syntax}
15150 The \cmd{\chapterprecistoc} macro puts \cmd{\precistoctext}\marg{text} into
15151 the \pixfile{toc} file. Further information as to the definition of
15152 this macro can be found in \Sref{sec:chapter-precis}.
15153
15154
15155 \LMnote{2012/09/21}{added}
15156 \subsection{About upper or lower casing TOC entries}
15157 \label{sec:about-upper-or}
15158
15159 This is a simple as using one of
15160 \begin{lcode}
15161 \renewcommand\cftKfont{...\MakeUppercase}
15162 \renewcommand\cftKfont{...\MakeLowercase}
15163 \end{lcode}
15164 %
15165 With earlier kernels, the code above would not work with
15166 \Lpack{hyperref} and you'd need to use the method described
15167 below. Using a modern kernel, this is no longer an issue and the
15168 method described below is no longer needed, and will be removed a
15169 later version of the class.
15170
15171
15172
15173
15174 \begin{Changed}[August 2025]
15175 The use of \cs{settocpreprocessor}, see below, is no longer needed
15176 and not recommended.
15177 \end{Changed}
15178
15179 Some designs call for upper (or lower casing) TOC entries. This used
15180 to be a problem when \Lpack{hyperref} was used as it would complain
15181 about \cs{MakeUppercase} etc. With \Lpack{hyperref} the possibilities
15182 were limited. Explanation: The upper/lower casing macros were not that
15183 robust, and need the content to be simple.\footnote{For some
15184 definition of simple.} When \Lpack{hyperref} was used, the hyperlink
15185 is wrapped around the entry before \cs{cftKfont} gains access to it,
15186 and it was thus generally too complicated for, say, \cs{MakeUppercase}
15187 to handle. The following workaround drew inspiration from
15188 \url{http://tex.stackexchange.com/q/11892/3929}.
15189 \begin{syntax}
15190 \cmd{\settocpreprocessor}\marg{type}\marg{code}
15191 \end{syntax}
15192 \glossary(settocpreprocessor)%
15193 {\cs{settocpreprocessor}\marg{type}\marg{code}}
15194 {Provide a method for preprocessing certain TOC entries before they
15195 are written to the \texttt{.toc} file.}
15196 Here \meta{type} is one of \texttt{chapter}, \texttt{part} or
15197 \texttt{book}.\footnote{If needed we will attempt to add a similar
15198 feature to the rest of the sectional types, please write the
15199 maintainer.} And \meta{code} can be something like this example:
15200 \begin{verbatim}
15201 \makeatletter
15202 \settocpreprocessor{chapter}{%
15203 \let\tempf@rtoc\f@rtoc%
15204 \def\f@rtoc{%
15205 \texorpdfstring{\MakeUppercase{\tempf@rtoc}}{\tempf@rtoc}}%
15206 }
15207 \makeatother
15208 \end{verbatim}
15209 Where \cs{f@rtoc} is a placeholder inside \cmd{\chapter}, \cmd{\part}
15210 and \cmd{\book}, holding the material to be written to the actual TOC
15211 file before \Lpack{hyperref} accesses it. This way the upper casing is
15212 sneaked into the TOC file, and the bookmark part of \Lpack{hyperref}
15213 will not complain about the \cmd{\MakeUppercase} in the data. Of
15214 course, you will not have upper cased titles in the bookmark list.
15215
15216 But as mentioned above, the kernel \cs{MakeUppercase} and
15217 \cs{MakeLowercase} work works fine with \Lpack{hyperref}.
15218
15219
15220
15221 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
15222
15223
15224 \subsection{Example: No section number}
15225
15226 There are at least two ways of listing section titles in the \toc\
15227 without displaying their numbers and both involve the \cmd{\numberline}
15228 command which typesets the number in a box.
15229
15230
15231 The first method redefines \cmd{\numberline} so it throws away the
15232 argument. We do this by modifying the \cmd{\cftKfont} macro which is called
15233 before \cmd{\numberline} and the \cmd{\cftKafterpnum} which is called after
15234 the page number has been typeset.
15235 \begin{lcode}
15236 \let\oldcftsf\cftsectionfont% save definition of \cftsectionfont
15237 \let\oldcftspn\cftsectionafterpnum% and of \cftsectionafterpnum
15238 \renewcommand*{\cftsectionfont}{%
15239 \let\oldnl\numberline% save definition of \numberline
15240 \renewcommand*{\numberline}[1]{}% change it
15241 \oldcftsf} % use original \cftsectionfont
15242 \renewcommand*{\cftsectionafterpnum}{%
15243 \let\numberline\oldnl% % restore orginal \numberline
15244 \oldcftspn} % use original \cftsectionafterpnum
15245 \end{lcode}
15246
15247 Probing a little deeper, the \cmd{\numberline} macro is called to
15248 typeset section numbers and is defined as:
15249 \begin{lcode}
15250 \renewcommand*{\numberline}[1]{%
15251 \hb@xt@\@tempdima{\@cftbsnum #1\@cftasnum\hfil}\@cftasnumb}
15252 \end{lcode}
15253 Each
15254 kind of heading \cmd{\let}s the \cmd{\@cftbsnum} macro to \cmd{\cftKpresnum},
15255 and the \cmd{\@cftasnum} macro to \cmd{\cftKaftersnum}, and the
15256 \cmd{\@cftasnumb} macro to \cmd{\cftKaftersnumb} as appropriate for the
15257 heading. The second method for killing the number uses a \tx\ method
15258 for defining a macro with
15259 a delimited argument.
15260 \begin{lcode}
15261 \def\cftsectionpresnum #1\@cftasnum{}
15262 \end{lcode}
15263 The interpretation of this is left as an exercise for anyone who might
15264 be interested.
15265
15266 \subsection{Example: Multicolumn entries}
15267
15268 If the subsection entries, say, in the \toc\ are going to be very
15269 short it might be worth setting them in multiple columns. Here is one way
15270 of doing that which depends on using the \Lpack{multicol}
15271 package~\cite{MULTICOL}. This assumes that subsections will be the lowest
15272 heading in the \toc.
15273 \begin{lcode}
15274 \newcounter{toccols}
15275 \setcounter{toccols}{3}
15276 \newenvironment{mysection}[1]{%
15277 \section{#1}%
15278 \addtocontents{toc}{\protect\begin{multicols}{\value{toccols}}}}%
15279 {\addtocontents{toc}{\protect\end{multocols}}}
15280 \end{lcode}
15281
15282 The counter \texttt{toccols} controls the number of columns to be used.
15283 For each section where you want subsections to be typeset in multiple columns
15284 in the \toc, use the \texttt{mysection} environment instead of \cmd{\section},
15285 like:
15286 \begin{lcode}
15287 \begin{mysection}{Columns}
15288 ...
15289 \subsection{Fat}
15290 ...
15291 \subsection{Thin}
15292 ...
15293 \end{mysection}
15294 \end{lcode}
15295
15296 Any \toc\ entries generated from within the environment will be enclosed
15297 in a \Ie{multicols} environment in the \toc. The \cmd{\protect}s have to be
15298 used because environment \cmd{\begin} and \cmd{\end} commands are
15299 fragile\index{fragile}.
15300
15301
15302 \subsection{Example: Multiple contents}
15303
15304 \PWnote{2009/03/17}{Added bit about simple short \& long ToC.}
15305 It is easy to have two \toc s, one short and one long, when they are
15306 of the same style, like this:
15307 \begin{lcode}
15308 ...
15309 \renewcommand*{\contentsname}{Short contents}
15310 \setcounter{tocdepth}{0}% chapters and above
15311 \tableofcontents
15312 % \clearpage
15313 \renewcommand*{\contentsname}{Contents}
15314 \setcounter{tocdepth}{2}% subsections and above
15315 \tableofcontents
15316 \end{lcode}
15317 (Note that you can't use \cmd{\settocdepth} in this case as that writes the
15318 change into the \toc, so that the second use would override the first.)
15319
15320
15321 This book has both a short and a long \toc, neither of which look like
15322 those typically associated with \ltx. This is how they were done.
15323
15324 The general style for the \toc, etc., is specified in the \Lpack{memsty}
15325 package file.
15326
15327 \begin{lcode}
15328 %%% need more space for ToC page numbers
15329 \setpnumwidth{2.55em}
15330 \setrmarg{3.55em}
15331 %%% need more space for ToC section numbers
15332 \cftsetindents{section}{1.5em}{3.0em}
15333 \cftsetindents{subsection}{4.5em}{3.9em}
15334 \cftsetindents{subsubsection}{8.4em}{4.8em}
15335 \cftsetindents{paragraph}{10.7em}{5.7em}
15336 \cftsetindents{subparagraph}{12.7em}{6.7em}
15337 %%% need more space for LoF & LoT numbers
15338 \cftsetindents{figure}{0em}{3.0em}
15339 \cftsetindents{table}{0em}{3.0em}
15340 %%% remove the dotted leaders
15341 \renewcommand{\cftsectiondotsep}{\cftnodots}
15342 \renewcommand{\cftsubsectiondotsep}{\cftnodots}
15343 \renewcommand{\cftsubsubsectiondotsep}{\cftnodots}
15344 \renewcommand{\cftparagraphdotsep}{\cftnodots}
15345 \renewcommand{\cftsubparagraphdotsep}{\cftnodots}
15346 \renewcommand{\cftfiguredotsep}{\cftnodots}
15347 \renewcommand{\cfttabledotsep}{\cftnodots}
15348 \end{lcode}
15349
15350 Three macros are defined to control the appearance of the short and
15351 the long \toc. First, the macro \cmd{\setupshorttoc} for the short
15352 version.
15353 The first few lines ensure that only chapter or part titles will be set,
15354 and any chapter precis text or \Icn{tocdepth} changes will be ignored.
15355 The rest of the code specifies how the chapter titles are to be typeset,
15356 and finally the part and book titles.
15357 \begin{lcode}
15358 \newcommand*{\setupshorttoc}{%
15359 \renewcommand*{\contentsname}{Short contents}
15360 \let\oldchangetocdepth\changetocdepth
15361 \renewcommand*{\changetocdepth}[1]{}
15362 \let\oldprecistoctext\precistoctext
15363 \renewcommand{\precistoctext}[1]{}
15364 \let\oldcftchapterfillnum\cftchapterfillnum
15365 \setcounter{tocdepth}{0}% chapters and above
15366 \renewcommand*{\cftchapterfont}{\hfill\sffamily}
15367 \renewcommand*{\cftchapterleader}{ \textperiodcentered\space}
15368 \renewcommand*{\cftchapterafterpnum}{\cftparfillskip}
15369 %% \setpnumwidth{0em}
15370 %% \setpnumwidth{1.5em}
15371 \renewcommand*{\cftchapterfillnum}[1]{%
15372 {\cftchapterleader}\nobreak
15373 \hbox to 1.5em{\cftchapterpagefont ##1\hfil}\cftchapterafterpnum\par}
15374 \setrmarg{0.3\textwidth}
15375 \setlength{\unitlength}{\@tocrmarg}
15376 \addtolength{\unitlength}{1.5em}
15377 \let\oldcftpartformatpnum\cftpartformatpnum
15378 \renewcommand*{\cftpartformatpnum}[1]{%
15379 \hbox to\unitlength{{\cftpartpagefont ##1}}}}
15380 \let\oldcftbookformatpnum\cftbookformatpnum
15381 \renewcommand*{\cftbookformatpnum}[1]{%
15382 \hbox to\unitlength{{\cftbookpagefont ##1}}}}
15383 \end{lcode}
15384
15385 You can do many things using the \cs{cft...} macros to change the
15386 appearance of a \toc\ but they can't be entirely coerced into specifying
15387 the paragraphing of the \cmd{\subsection} titles. The
15388 \cmd{\setupparasubsecs} also went in the preamble.
15389 \begin{lcode}
15390 \newcommand*{\setupparasubsecs}{%
15391 \let\oldnumberline\numberline
15392 \renewcommand*{\cftsubsectionfont}{\itshape}
15393 \renewcommand*{\cftsubsectionpagefont}{\itshape}
15394 \renewcommand{\l@subsection}[2]{%
15395 \def\numberline####1{\textit{####1}~}%
15396 \leftskip=\cftsubsectionindent
15397 \rightskip=\@tocrmarg
15398 %% \advance\rightskip 0pt plus \hsize % uncomment this for raggedright
15399 %% \advance\rightskip 0pt plus 2em % uncomment this for semi-raggedright
15400 \parfillskip=\fill
15401 \ifhmode ,\ \else\noindent\fi
15402 \ignorespaces
15403 {\cftsubsectionfont ##1}~{\cftsubsectionpagefont##2}%
15404 \let\numberline\oldnumberline\ignorespaces}
15405 }
15406 \AtEndDocument{\addtocontents{toc}{\par}
15407 \end{lcode}
15408 The above code changes the appearance of subsection titles in the \toc,
15409 setting each group as a single paragraph (each is normally set with
15410 a paragraph to itself). By uncommenting or commenting the noted lines
15411 in the code you can change the layout a little.
15412
15413
15414 \begin{caveat}
15415 We have an interesting caveat regarding \cmd{\setupparasubsecs} if
15416 you are using \Lpack{hyperref} \emph{and} you have subsubsections,
15417 that are not shown in the ToC. You may see some inline subsection
15418 entries showing up as `\dots\ text~15 ,\dots', that is a strange
15419 space appears before the comma.
15420
15421 This is an artifact due to the way \Lpack{hyperref} wraps itself
15422 around the ToC entries, even the ones that are not typeset, and thus
15423 an end of line space survives. We fix it using \cmd{\endlinechar}:
15424 \begin{lcode}
15425 \begingroup
15426 \endlinechar=-1
15427 \tableofcontents
15428 \endgroup
15429 \end{lcode}
15430 Note again that it only happen if you have subsubsections with an
15431 inline subsection entry list, \emph{and} you are using
15432 \Lpack{hyperref}.
15433 \end{caveat}
15434
15435
15436
15437
15438 Normally, section titles (and below) are set as individual
15439 paragraphs. Effectively the first thing that is done is to end any
15440 previous paragraph, and also the last thing is to end the current
15441 paragraph. Notice that the main code above neither starts nor finishes
15442 a paragraph. If the group of subsections is followed by a section title,
15443 that supplies the paragraph end. The last line above ensures that
15444 the last entry in the \file{toc} file is \piif{par} as this might be
15445 needed to finish off a group of subsections if these are the last
15446 entries.
15447
15448 And thirdly for the main \toc, the macro \cmd{\setupmaintoc} reverts
15449 everything back to normal.
15450 \begin{lcode}
15451 \newcommand*{\setupmaintoc}{%
15452 \renewcommand{\contentsname}{Contents}
15453 \let\changetocdepth\oldchangetocdepth
15454 \let\precistoctext\oldprecistoctext
15455 \let\cftchapterfillnum\oldcftchapterfillnum
15456 \addtodef{\cftchapterbreak}{\par}{}
15457 \renewcommand*{\cftchapterfont}{\normalfont\sffamily}
15458 \renewcommand*{\cftchapterleader}{%
15459 \sffamily\cftdotfill{\cftchapterdotsep}}
15460 \renewcommand*{\cftchapterafterpnum}{}
15461 \renewcommand{\cftchapterbreak}{\par\addpenalty{-\@highpenalty}}
15462 \setpnumwidth{2.55em}
15463 \setrmarg{3.55em}
15464 \setcounter{tocdepth}{2}
15465 \let\cftpartformatpnum\oldcftpartformatpnum
15466 \addtodef{\cftpartbreak}{\par}{}
15467 \let\cftbookformatpnum\oldcftbookformatpnum
15468 \addtodef{\cftbookbreak}{\par}{}
15469 }
15470 \end{lcode}
15471 The first few lines restore some macros to their original definitions.
15472 \begin{lcode}
15473 \addtodef{\cftchapterbreak}{\par}{}
15474 \end{lcode}
15475 ensures that a chapter entry starts off with a \piif{par}; this is needed
15476 when the previous entry is a group of subsections and their paragraph
15477 has to be ended. The remaining code lines simply set the appearance of
15478 the chapter titles and restore that for parts and books, as well as ensuring
15479 that they start off new paragraphs.
15480
15481 In the document itself, \cmd{\tableofcontents} was called twice,
15482 after the appropriate setups:
15483 \begin{lcode}
15484 ...
15485 \setupshorttoc
15486 \tableofcontents
15487 \clearpage
15488 \setupparasubsecs
15489 \setupmaintoc
15490 \tableofcontents
15491 \setlength{\unitlength}{1pt}
15492 ...
15493 \end{lcode}
15494 After all this note that I ensured that \lnc{\unitlength} was set
15495 to its default value (it had been used as a scratch length in the
15496 code for \cmd{\setupparasubsecs}).
15497
15498
15499 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
15500
15501
15502
15503 \section{New \listofx\ and entries}
15504
15505 \index{list!new list of|(}
15506
15507 \begin{syntax}
15508 \cmd{\newlistof}\marg{listofcom}\marg{ext}\marg{listofname} \\
15509 \end{syntax}
15510 \glossary(newlistof)%
15511 {\cs{newlistof}\marg{listofcom}\marg{ext}\marg{listofname}}%
15512 {Creates two new List of \ldots commands, \cs{listofcom}
15513 and \cs{listofcom*}, which use
15514 a file with extension \meta{ext} and \meta{listofname} for the
15515 title.}
15516 The command \cmd{\newlistof}
15517 creates a new \listofx, and assorted commands to go along with it.
15518 The first argument, \meta{listofcom} is used to define a new
15519 command called \verb?\listofcom? which can then be used like
15520 \verb?\listoffigures?
15521 to typeset the \listofx. The \meta{ext} argument is the file
15522 extension to
15523 be used for the new listing. The last argument, \meta{listofname} is
15524 the title for the \listofx. Unstarred and starred versions of
15525 \verb?\listofcom? are created. The unstarred version, \verb?\listofcom?,
15526 will add \meta{listofname} to the \toc, while the starred version,
15527 \verb?\listofcom*?, makes no entry in the \toc.
15528
15529 As an example:
15530 \begin{lcode}
15531 \newcommand{\listanswername}{List of Answers}
15532 \newlistof{listofanswers}{ans}{\listanswername}
15533 \end{lcode}
15534 will create a new \cmd{\listofanswers} command that can be used
15535 to typeset a listing of answers under the
15536 title \cmd{\listanswername}, where the answer titles are in an \file{ans}
15537 file.
15538 It is up to the author of the document to specify the `answer' code
15539 for the answers in the document. For example:
15540 \begin{lcode}
15541 \newcounter{answer}[chapter]
15542 \renewcommand{\theanswer}{\arabic{answer}}
15543 \newcommand{\answer}[1]{
15544 \refstepcounter{answer}
15545 \par\noindent\textbf{Answer \theanswer. #1}
15546 \addcontentsline{ans}{answer}{\protect\numberline{\theanswer}#1}\par}
15547 \end{lcode}
15548 which, when used like:
15549 \begin{lcode}
15550 \answer{Hard} The \ldots
15551 \end{lcode}
15552 will print as:
15553 \begin{syntax}
15554 \textbf{Answer 1. Hard} \\
15555 \hspace*{2em} The \ldots \\
15556 \end{syntax}
15557
15558 As mentioned above, the \cmd{\newlistof} command creates several
15559 new commands in addition to \verb?\listofcom?, most of which you should
15560 now be familiar with. For convenience,
15561 assume that \verb?\newlistof{...}{X}{...}? has been issued so that
15562 \texttt{X} is the new file extension and corresponds to the \texttt{X} in
15563 \Sref{sec:titles}. Then in addition to \verb?\listofcom? the following
15564 new commands will be made available.
15565
15566 The four commands, \verb?\Xmark?, \verb?\Xheadstart?,
15567 \verb?\printXtitle?, and \verb?\afterXtitle?, are analagous to the
15568 commands of the same names described in \Sref{sec:titles} (internally
15569 the class uses the \cmd{\newlistof} macro to define the \toc, \lof\
15570 and \lot). In particular the default definition of \verb?\Xmark? is
15571 equivalent to:
15572 \begin{lcode}
15573 \newcommand{\Xmark}{\markboth{listofname}{listofname}}
15574 \end{lcode}
15575 However, this may well be altered by the particular \cmd{\pagestyle} in
15576 use.
15577
15578 \begin{syntax}
15579 \verb?Xdepth? \\
15580 \end{syntax}
15581 The counter \verb?Xdepth? is analagous to the standard
15582 \Icn{tocdepth} counter, in that it specifies that entries
15583 in the new listing should not be typeset if their numbering level
15584 is greater
15585 than \verb?Xdepth?. The default definition is equivalent to
15586 \begin{lcode}
15587 \setcounter{Xdepth}{1}
15588 \end{lcode}
15589
15590 \begin{syntax}
15591 \cmd{\insertchapterspace} \\
15592 \cmd{\addtodef}\marg{macro}\marg{prepend}\marg{append} \\
15593 \end{syntax}
15594 Remember that the \cmd{\chapter} command uses \cmd{\insertchapterspace}
15595 to insert vertical spaces into the \lof{} and \lot. If you want similar
15596 spaces added to your new listing then you have to modify
15597 \cmd{\insertchapterspace}. The easiest way to do this is via
15598 the \cmd{\addtodef} macro, like:
15599 \begin{lcode}
15600 \addtodef{\insertchapterspace}{}%
15601 {\addtocontents{ans}{\protect\addvspace{10pt}}}
15602 \end{lcode}
15603 The \cmd{\addtodef} macro is described later in \Sref{sec:addtodef}.
15604
15605 The other part of creating a new \listofx, is to specify the
15606 formatting of the entries, i.e., define an appropriate \verb?\l@kind?
15607 macro.
15608
15609 \begin{syntax}
15610 \cmd{\newlistentry}\oarg{within}\marg{cntr}\marg{ext}\marg{level-1} \\
15611 \end{syntax}
15612 \glossary(newlistentry)%
15613 {\cs{newlistentry}\oarg{within}\marg{cntr}\marg{ext}\marg{level-1}}%
15614 {Creates the commands for typesetting an entry in a \listofx.
15615 \meta{cntr} is the new counter for the entry, which may be reset
15616 by the \meta{within} counter. \meta{ext} is the file extension
15617 and \meta{level-1} is one less than the entry's level.}
15618
15619 The command \cmd{\newlistentry} creates the commands necessary for
15620 typesetting an entry in a \listofx.
15621 The first required argument, \meta{cntr} is used to define a new
15622 counter called \texttt{cntr}, unless \texttt{cntr} is already defined.
15623 The optional \meta{within} argument can be used so that \texttt{cntr}
15624 gets reset to one every time the counter called \texttt{within} is changed.
15625 That is, the first two arguments when \texttt{cntr} is not
15626 already defined, are equivalent to calling
15627 \cmd{\newcounter}\marg{cntr}\oarg{within}. If \texttt{cntr} is already
15628 defined, \cmd{\newcounter} is not called. \texttt{cntr} is used for the
15629 number that goes along with the title of the entry.
15630
15631 The second required argument, \meta{ext}, is the file extension for
15632 the entry listing. The last argument, \meta{level-1}, is a number
15633 specifying the numbering level minus one, of the entry in a listing.
15634
15635
15636 Calling \cmd{\newlistentry} creates several new commands used to
15637 configure the entry. So in order to configure the list look of our
15638 previous answer example we would add
15639 \begin{lcode}
15640 \newlistentry{answer}{ans}{0}
15641 \end{lcode}
15642
15643 Assuming that \verb?\newlistentry? is called as
15644 \verb?\newlistentry[within]{K}{X}{N}?, where \texttt{K} and
15645 \texttt{X} are similar to the previous uses of them (e.g., \texttt{K}
15646 is the kind of entry \texttt{X} is the file extension), and
15647 \texttt{N} is an integer number, then the following commands are made
15648 available.
15649
15650
15651 The set of commands \verb?\cftbeforeKskip?,
15652 \verb?\cftKfont?,
15653 \verb?\cftKpresnum?,
15654 \verb?\cftKaftersnum?,
15655 \verb?\cftKaftersnumb?,
15656 \verb?\cftKleader?,
15657 \verb?\cftKdotsep?,
15658 \verb?\cftKpagefont?, and
15659 \verb?\cftKafterpnum?,
15660 are analagous to the commands of the same names
15661 described in \Sref{sec:entries}. Their default values are also
15662 as described earlier.
15663
15664 The default values of \verb?\cftKindent? and \verb?\cftKnumwidth? are
15665 set according to the value of the \meta{level-1} argument
15666 (i.e., \texttt{N} in this example). For \verb?N=0? the settings
15667 correspond to those for figures\index{figure} and tables\index{table},
15668 as listed in \tref{tab:indents} for the \Lclass{memoir} class.
15669 For \verb?N=1? the settings correspond to subfigures\index{figure!sub-},
15670 and so on. For values of \verb?N? less than zero or greater than four,
15671 or for non-default values, use the \cmd{\cftsetindents} command to
15672 set the values.
15673
15674 \verb?\l@K? is an internal command that typesets an entry in the list,
15675 and is defined in terms of the above \verb?\cft*K*? commands. It will
15676 not typeset an entry if \verb?Xdepth? is \texttt{N} or less, where
15677 \texttt{X} is the listing's file extension.
15678
15679 The command \verb?\theK? prints the value of the \texttt{K} counter.
15680 It is initially defined so that it prints arabic numerals. If the
15681 optional \meta{within} argument is used, \verb?\theK? is defined as
15682 \begin{lcode}
15683 \renewcommand{\theK}{\thewithin.\arabic{K}}
15684 \end{lcode}
15685 otherwise as
15686 \begin{lcode}
15687 \renewcommand{\theK}{\arabic{K}}
15688 \end{lcode}
15689
15690 As an example of the independent use of \cmd{\newlistentry}, the
15691 following will set up for sub-answers.
15692 \begin{lcode}
15693 \newlistentry[answer]{subanswer}{ans}{1}
15694 \renewcommand{\thesubanswer}{\theanswer.\alph{subanswer}}
15695 \newcommand{\subanswer}[1]{
15696 \refstepcounter{subanswer}
15697 \par\textbf{\thesubanswer) #1}
15698 \addcontentsline{ans}{subanswer}{\protect\numberline{\thesubanswer}#1}
15699 \setcounter{ansdepth}{2}
15700 \end{lcode}
15701 And then:
15702 \begin{lcode}
15703 \answer{Harder} The \ldots
15704 \subanswer{Reformulate the problem} It assists \ldots
15705 \end{lcode}
15706 will be typeset as:
15707 \begin{syntax}
15708 \textbf{Answer 2. Harder} \\
15709 \hspace*{2em} The \ldots \\
15710 \hspace*{2em} \textbf{2.a) Reformulate the problem} It assists \ldots \\
15711 \end{syntax}
15712
15713 By default the answer entries will appear in the List of Answers
15714 listing (typeset by the \cs{listofanswers} command).
15715 In order to get the subanswers to appear,
15716 the \verb?\setcounter{ansdepth}{2}? command was used above.
15717
15718 To turn off page numbering for the subanswers, do
15719 \begin{lcode}
15720 \cftpagenumbersoff{subanswer}
15721 \end{lcode}
15722
15723 As another example of \cmd{\newlistentry}, suppose that an extra
15724 sectioning division below \texttt{subparagraph} is required,
15725 called \texttt{subsubpara}. The \verb?\subsubpara? command itself can
15726 be defined via the \ltx\ kernel \cmd{\@startsection} command.
15727 Also it is necessary to define a \verb?\subsubparamark? macro,
15728 a new \texttt{subsubpara} counter, a \verb?\thesubsubpara? macro and a
15729 \verb?\l@subsubpara? macro. Using \cmd{\newlistentry} takes care of
15730 most of these as shown below; remember the caveats about commands
15731 with \idxatincode\texttt{@} signs in them (\seeatincode).
15732 \begin{lcode}
15733 \newcommand{\subsubpara}{\@startsection{subpara}
15734 {6} % level
15735 {\parindent} % indent from left margin
15736 {3.25ex \@plus1ex \@minus .2ex} % skip above heading
15737 {-1em} run-in heading with % 1em between title & text
15738 {\normalfont\normalsize\itshape} % italic number and title
15739 }
15740 \newlistentry[subparagraph]{subsubpara}{toc}{5}
15741 \cftsetindents{subsubpara}{14.0em}{7.0em}
15742 \newcommand*{\subsubparamark}[1]{} % gobble heading mark
15743 \end{lcode}
15744
15745 Each \listofx\ uses a file to store the list entries, and these
15746 files must remain open for writing throughout the document processing.
15747 \tx\ has only a limited number of files that it can keep open, and this
15748 puts a limit on the number of listings that can be used. For a document
15749 that includes a \toc\ but no other extra ancilliary files (e.g., no
15750 index\index{index} or bibliography\index{bibliography} output files)
15751 the maximum number of LoX's, including a \lof\ and \lot, is no more
15752 than about eleven. If you try and create too many new listings \ltx\
15753 will respond with the error message:
15754 \begin{center}
15755 \texttt{No room for a new write}
15756 \end{center}
15757 If you get such a message the only recourse is to redesign your
15758 document.
15759
15760 \subsection{Example: plates}
15761
15762 As has been mentioned earlier, some illustrations\index{illustration}
15763 may be tipped in\index{tip in} to a book. Often, these are called
15764 \emph{plates}\index{plates} if they are on glossy paper\index{paper}
15765 and the rest of the book is on ordinary paper\index{paper}.
15766 We can define a new kind of Listing for these.
15767
15768 \begin{lcode}
15769 \newcommand{\listplatename}{Plates}
15770 \newlistof{listofplates}{lop}{\listplatename}
15771 \newlistentry{plate}{lop}{0}
15772 \cftpagenumbersoff{plate}
15773 \end{lcode}
15774 This code defines the \cmd{\listofplates} command to start the listing
15775 which will be titled `Plates' from the \cmd{\listplatename} macro.
15776 The entry name is \texttt{plate} and the file extension is \texttt{lop}.
15777 As plate pages typically do not have printed folios\index{folio},
15778 the \cmd{\cftpagenumbersoff} command has been used to prohibit page
15779 number printing in the listing.
15780
15781 If pages are tipped in, then they are put between a verso and
15782 a recto page. The \Lpack{afterpage} package~\cite{AFTERPAGE} lets
15783 you specify something that should happen after the current page
15784 is finished. The next piece of code uses the package and its
15785 \cmd{\afterpage} macro to define two macros which let you specify
15786 something that is to be done after the next verso (\cmd{\afternextverso})
15787 or recto (\cmd{\afternextrecto}) page has been completed.
15788 \begin{lcode}
15789 \newcommand{\afternextverso}[1]{%
15790 \afterpage{\ifodd\c@page #1\else\afterpage{#1}\fi}}
15791 \newcommand{\afternextrecto}[1]{%
15792 \afterpage{\ifodd\c@page\afterpage{#1}\else #1\fi}}
15793 \end{lcode}
15794
15795
15796 The \cmd{\pageref}\marg{labelid} command typesets the page number
15797 corresponding to the location in the document where
15798 \cmd{\label}\marg{labelid} is specified. The following code defines
15799 two macros\footnote{These only work for arabic page numbers.}
15800 that print the page number before (\cmd{\priorpageref}) or after
15801 (\cmd{\nextpageref}) that given by \cmd{\pageref}.
15802 \begin{lcode}
15803 \newcounter{mempref}
15804 \newcommand{\priorpageref}[1]{%
15805 \setcounter{mempref}{\pageref{#1}}\addtocounter{mempref}{-1}\themempref}
15806 \newcommand{\nextpageref}[1]{%
15807 \setcounter{mempref}{\pageref{#1}}\addtocounter{mempref}{1}\themempref}
15808 \end{lcode}
15809
15810 With these preliminaries out of the way, we can use code like the
15811 following for handling a set of physically tipped in plates.
15812 \begin{lcode}
15813 \afternextverso{\label{tip}
15814 \addtocontents{lop}{%
15815 Between pages \priorpageref{tip} and \pageref{tip}
15816 \par\vspace*{\baselineskip}}
15817 \addcontentsline{lop}{plate}{First plate}
15818 \addcontentsline{lop}{plate}{Second plate}
15819 ...
15820 \addcontentsline{lop}{plate}{Nth plate}
15821 }
15822 \end{lcode}
15823 This starts off by waiting until the next recto page is started, which
15824 will be the page immediately after the plates, and then inserts the
15825 label \texttt{tip}. The \cmd{\addtocontents} macro puts its argument
15826 into the plate list \texttt{lop} file, indicating the page numbers
15827 before and after the set of plates. With the plates being physically
15828 added to the document it is not possible to use \cmd{\caption},
15829 instead the \cmd{\addcontentsline} macros are used to add the plate
15830 titles to the \texttt{lop} file.
15831
15832 With a few modifications the code above can also form the basis
15833 for listing plates that are electronically tipped in but do not have
15834 printed folios\index{folio} or \cmd{\caption}s.
15835
15836 \index{list!new list of|)}
15837
15838
15839
15840 \LMnote{2010/06/09}{Why do we have this exact section in two different
15841 chapters? No this links to the version i document-divisions.tex }
15842 \section{Chapter precis}
15843
15844 See \Sref{sec:chapter-precis} on page~\pageref{sec:chapter-precis}.
15845
15846
15847 % \index{chapter!precis|(}
15848
15849 % Some old style novels, and even some modern text
15850 % books,\footnote{For example, Robert Sedgewick, \textit{Algorithms},
15851 % Addison-Wesley, 1983.} include a short synopsis of the contents of
15852 % the chapter either immediately
15853 % after the chapter heading\index{heading!chapter} or in the \toc, or in both places.
15854
15855 % \begin{syntax}
15856 % \cmd{\chapterprecis}\marg{text} \\
15857 % \end{syntax}
15858 % The command \cmd{\chapterprecis} prints its argument
15859 % both at the
15860 % point in the document where it is called, and also adds it to the \file{.toc}
15861 % file. For example:
15862 % \begin{lcode}
15863 % ...
15864 % \chapter{} first chapter
15865 % \chapterprecis{Our hero is introduced; family tree; early days.}
15866 % ...
15867 % \end{lcode}
15868
15869 % \begin{syntax}
15870 % \cmd{\chapterprecishere}\marg{text} \\
15871 % \cmd{\chapterprecistoc}\marg{text} \\
15872 % \end{syntax}
15873 % The \cmd{\chapterprecis} command calls these two commands to print the
15874 % \meta{text} in the document (the \cmd{\chapterprecishere} command)
15875 % and to put it into the \toc{} (the \cmd{\chapterprecistoc} command).
15876 % These can be used individually if required.
15877
15878 % \begin{syntax}
15879 % \cmd{\prechapterprecis} \cmd{\postchapterprecis} \\
15880 % \end{syntax}
15881 % The \cmd{\chapterprecishere} macro is intended for use immediately after
15882 % a \cmd{\chapter}. The \meta{text} argument is typeset in
15883 % italics in a \Ie{quote} environment. The macro's definition is:
15884 % \begin{lcode}
15885 % \newcommand{\chapterprecishere}[1]{%
15886 % \prechapterprecis #1\postchapterprecis}
15887 % \end{lcode}
15888 % where \cmd{\prechapterprecis} and \cmd{\postchapterprecis} are defined
15889 % as:
15890 % \begin{lcode}
15891 % \newcommand{\prechapterprecis}{%
15892 % \vspace*{\prechapterprecisshift}%
15893 % \begin{quote}\normalfont\itshape}
15894 % \newcommand{\postchapterprecis}{\end{quote}}
15895 % \end{lcode}
15896 % The \cmd{\prechapterprecis} and \cmd{\postchapterprecis} macros can be
15897 % changed if another style of typesetting is required.
15898
15899 % \begin{syntax}
15900 % \cmd{\precistoctext}\marg{text} \cmd{\precistocfont} \\
15901 % \end{syntax}
15902 % The \cmd{\chapterprecistoc} macro puts the macro \cmd{\precistoctext} into
15903 % the \pixfile{toc} file. The default definition is
15904 % \begin{lcode}
15905 % \DeclareRobustCommand{\precistoctext}[1]{%
15906 % {\leftskip \cftchapterindent\relax
15907 % \advance\leftskip \cftchapternumwidth\relax
15908 % \rightskip \@tocrmarg\relax
15909 % \precistocfont #1\par}}
15910 % \end{lcode}
15911 % Effectively, in the \toc{} \cmd{\precistoctext} typesets its argument like
15912 % a chapter title using the \cmd{\precistocfont} (default \cmd{\itshape}).
15913
15914 % \index{chapter!precis|)}
15915
15916
15917 \section{Contents lists and bookmarks}
15918 \label{sec:cont-lists-bookm}
15919
15920 \LMnote{2009/06/29}{Added section about contents lists and bookmarks}
15921
15922 With the \Lpack{hyperref} package, the table of contents is often
15923 added as a list of bookmarks thus providing a nice navigation for the
15924 user. There is one slight problem though: when using, say, parts in
15925 the document, all chapters in that part ends up as a child of this
15926 part bookmark---including the index and bibliography. A simple fix to
15927 this is to add
15928 \begin{lcode}
15929 \makeatletter
15930 \renewcommand*{\toclevel@chapter}{-1}
15931 \makeatother
15932 \end{lcode}
15933 just before the material you would like to pull out of the part tree.
15934
15935 \LMnote{2010/06/09}{Heikos own recommendation}
15936 A better solution is the \Lpack{bookmark} package, add it to the
15937 preamble, and add
15938 \begin{lcode}
15939 \bookmarksetup{startatroot}
15940 \end{lcode}
15941 before the stuff you want to have moved out of, say, a part.
15942
15943
15944 %#% extend
15945 %#% extstart include flosts-and-captions.tex
15946
15947 \svnidlong
15948 {$Ignore: $}
15949 {$LastChangedDate: 2025-09-24 16:31:58 +0200 (Wed, 24 Sep 2025) $}
15950 {$LastChangedRevision: 877 $}
15951 {$LastChangedBy: [email protected] $}
15952
15953
15954 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
15955 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
15956 %%\chapterstyle{hangnum}
15957 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
15958 \chapter{Floats and captions} \label{chap:captions}
15959
15960
15961 A float\index{float} environment is a particular kind of
15962 box\index{box} --- one that \ltx\ decides where it should go although
15963 you can provide hints as to where it should be placed;
15964 all other boxes are put at the point where they are defined.
15965 Within reason you can put what you like within a float but it is
15966 unreasonable, for example, to put a float inside
15967 another float. The standard classes provide two kinds of float
15968 environments, namely \Ie{figure} and \Ie{table}. The only difference
15969 between these is the naming and numbering of any caption\index{caption}
15970 within the environments --- a \cmd{\caption} in a \Ie{figure}
15971 environment uses \cmd{\figurename} while a \cmd{\caption} in a
15972 \Ie{table} environment uses \cmd{\tablename}. Figures and tables are
15973 numbered sequentially but the two numbering schemes are independent
15974 of each other.
15975
15976 The class provides means of defining new kinds of floats. It also
15977 provides additional forms of captions for use both within and outside
15978 float environments together with handles for changing the style
15979 of captions.
15980
15981 \section{New float environments} \label{sec:newfloat}
15982
15983 It is often forgotten that the \ltx\ float environments come
15984 in both starred and unstarred forms. The unstarred form typesets the
15985 float contents\index{float!single column} in one column, which is
15986 the most usual form for a book. The starred form typesets the contents
15987 of the float across the top of both columns\index{float!double column}
15988 in a \Lopt{twocolumn} document. In a \Lopt{onecolumn} document there
15989 is no difference between the starred and unstarred forms.
15990
15991 \index{float!new|(} %)| emacs
15992
15993 \begin{syntax}
15994 \cmd{\newfloat}\oarg{within}\marg{fenv}\marg{ext}\marg{capname} \\
15995 \end{syntax}
15996 \glossary(newfloat)%
15997 {\cs{newfloat}\oarg{within}\marg{fenv}\marg{ext}\marg{capname}}%
15998 {Creates new float environments, \texttt{fenv} and \texttt{fenv*},
15999 using counter \texttt{fenv}, which may be restarted by the
16000 \meta{within} counter, putting captioning information into the
16001 file with extension \meta{ext}, and using \meta{capname} as the
16002 name for a caption.}
16003 The \cmd{\newfloat} command creates two new floating environments
16004 called \meta{fenv} and \meta{fenv*}. If there
16005 is not already a counter\index{counter} defined for \meta{fenv} a new
16006 one will be created to be restarted by the counter \meta{within},
16007 if that is specified. A caption\index{caption} within the environment
16008 will be written out to a file with extension \meta{ext}.
16009 The caption, if present, will start with \meta{capname}. For example,
16010 the \texttt{figure} float\index{figure!float definition} for the class
16011 is defined as:
16012 \begin{lcode}
16013 \newfloat[chapter]{figure}{lof}{\figurename}
16014 \renewcommand{\thefigure}{%
16015 \ifnum\c@chapter>\z@ \thechapter.\fi \@arabic\c@figure}
16016 \end{lcode}
16017 The last bit of the definition is internal code to make sure that if a
16018 figure\index{figure} is in the document before chapter numbering starts,
16019 then the figure\index{figure} number will not be preceeded by a
16020 non-existent chapter number.
16021
16022 The captioning style\index{caption!style} for floats defined
16023 with \cmd{\newfloat} is the same as
16024 for the figures\index{figure} and tables\index{table}.
16025
16026 The \cmd{\newfloat} command generates several new commands, some of
16027 which are internal \ltx\ commands. For convenience, assume that the
16028 command was called as
16029 \begin{lcode}
16030 \newfloat{F}{X}{capname}
16031 \end{lcode}
16032 so \texttt{F} is the name of the float environment and also the name of
16033 the counter for the caption, and \texttt{X} is the file extension.
16034 The following float environment and related commands are then created.
16035
16036 \begin{syntax}
16037 \senv{F} float material \eenv{F} \\
16038 \senv{F*} float material \eenv{F*} \\
16039 \end{syntax}
16040 The new float environment is called \texttt{F}, and can be used as
16041 either \senv{F} or \senv{F*}, with the matching \eenv{F} or \eenv{F*}.
16042 It is given the standard default position\index{float!position}
16043 specification of
16044 [\textsf{t}\ixposarg{t}\textsf{b}\ixposarg{b}\textsf{p}\ixposarg{p}].
16045
16046 \begin{syntax}
16047 \Icn{Xdepth} \\
16048 \end{syntax}
16049 The \Icn{Xdepth} counter is analogous to the standard \Icn{tocdepth}
16050 counter in that it specifies that entries in a listing should not be
16051 typeset\index{ToC!controlling entries} if their numbering level is
16052 greater than \Icn{Xdepth}. The default definition is
16053 \begin{lcode}
16054 \setcounter{Xdepth}{1}
16055 \end{lcode}
16056 To have a subfloat of \texttt{X} appear in the listing do
16057 \begin{lcode}
16058 \setcounter{Xdepth}{2}
16059 \end{lcode}
16060
16061
16062 As an example, suppose you wanted both figures\index{figure}
16063 (which come with the class), and diagrams\index{float!new diagram}.
16064 You could then do something
16065 like the following.
16066 \begin{lcode}
16067 \newcommand{\diagramname}{Diagram}
16068 \newcommand{\listdiagramname}{List of Diagrams}
16069 \newlistof{listofdiagrams}{dgm}{\listdiagramname}
16070 \newfloat{diagram}{dgm}{\diagramname}
16071 \newlistentry{diagram}{dgm}{0}
16072 \begin{document}
16073 ...
16074 \listoffigures
16075 \listfofdiagrams
16076 ...
16077 \begin{diagram}
16078 \caption{A diagram} \label{diag1}
16079 ...
16080 \end{diagram}
16081 As diagram~\ref{diag1} shows ...
16082 \end{lcode}
16083
16084
16085 \begin{syntax}
16086 \cmd{\setfloatadjustment}\marg{floatname}\marg{code}
16087 \end{syntax}
16088 \glossary(setfloatadjustment)%
16089 {\cs{setfloatadjustment}\marg{floatname}\marg{code}}%
16090 {Add global internal adjustment to a given type of float. Empty by
16091 default, but can easily be used to make all floats centered or all
16092 tables in a smaller font size.}
16093 Often it is useful to add some global configuration to a given type of
16094 float such that one will not have to add this to each and every
16095 float. For example to have all (floating) figures and tables automatically
16096 centered plus have all (floating) tables typeset in \cmd{\small} use
16097 \begin{lcode}
16098 \setfloatadjustment{figure}{\centering}
16099 \setfloatadjustment{table}{\small\centering}
16100 \end{lcode}
16101 \LMnote{2011/02/18}{I've removed the figure*adjustment feature, so
16102 there is no differenting between starred and non starred floats when
16103 it comes to inner adjustment}
16104
16105
16106 \subsection{Margin floats}
16107 \label{sec:margin-floats}
16108
16109 We also provide two environments to insert an image or table into the
16110 margin (using \cmd{\marginpar}). The construction is inspired by the
16111 Tufte \LaTeX\ collection.
16112 \begin{syntax}
16113 \senv{marginfigure}\oarg{len} float material \eenv{marginfigure} \\
16114 \senv{margintable}\oarg{len} float material \eenv{margintable} \\
16115 \end{syntax}
16116 \glossary(marginfigure)%
16117 {\senv{marginfigure}\oarg{length}}%
16118 {Environment which inserts its contents into the margin, and enables
16119 figure captions. The optional argument should be a length and is
16120 used to perform manual up/down adjustments to the placement.}
16121 \glossary(margintable)%
16122 {\senv{margintable}\oarg{length}}%
16123 {Environment which inserts its contents into the margin, and enables
16124 figure captions.The optional argument should be a length and is used
16125 to perform manual up/down adjustments to the placement.} Because
16126 this is inserted differently than the ordinary \Ie{figure} or
16127 \Ie{table} floats, one might get into the situation where a figure
16128 float inserted before a margin float, might float \emph{past} the
16129 margin float and thus have different caption numbering. For this
16130 reason the margin float contain a float blocking device such that any
16131 unplaced floats are forced to be placed before we start typesetting a
16132 margin figure.
16133
16134 Additionally, note that the term ``float'' is used very lightly
16135 here. As things are placed using \cmd{\marginpar}, margin floats only
16136 ``float'' on the page it self, they never float on to the next page.
16137
16138 \fancybreak{}
16139
16140 The \Ie{marginfigure} and \Ie{margintable} environments can of course
16141 be adjusted using \cmd{\setfloatadjustment}, default
16142 \begin{lcode}
16143 \setfloatadjustment{marginfigure}{\centering}
16144 \setfloatadjustment{margintable}{\centering}
16145 \end{lcode}
16146 It may be useful to adjust the captioning separately, for this we have
16147 added
16148 \begin{syntax}
16149 \cmd{\setmarginfloatcaptionadjustment}\marg{float}\marg{code}
16150 \end{syntax}
16151 where \meta{float} is \verb?figure? or \verb?table?. The intent is to
16152 enable the user to choose a different captioning style (or similar)
16153 within a margin float, for example typesetting the caption ragged
16154 left/right depending on the page.
16155
16156 This \emph{left/right depending on the page} is a little hard to do,
16157 so for the \cmd{\marginpar} (which the margin float use internally) we
16158 provide the following two macros
16159 \begin{syntax}
16160 \cmd{\setmpjustification}\marg{at left of textblock}\marg{at right
16161 of textblock}\\
16162 \cmd{\mpjustification}
16163 \end{syntax}
16164 \glossary(setmpjustification)%
16165 {\cs{setmpjustification}\marg{at left of textblock}\marg{at right
16166 of textblock}}%
16167 {Loads the \cs{mpjustification} command to execute the left part
16168 when placed at the left of the text block and vice versa.}%
16169 \glossary(mpjustification)%
16170 {\cs{mpjustification}}%
16171 {Specialized macro to be used within \cs{marginpar}s}
16172 Basically \cmd{\mpjustification} execute \meta{at left of textblock}
16173 when it is executed at the left of the text block and vice versa. For
16174 it to work the margin into which the \cmd{marginpar} should do,
16175 \emph{has} to be specified using \cmd{marginparmargin}. The default is
16176 \begin{lcode}
16177 \setmpjustification{\raggedleft}{\raggedright}
16178 \end{lcode}
16179 To have both a margin figure and its caption typeset ragged against
16180 the text block, use
16181 \begin{lcode}
16182 \setfloatadjustment{marginfigure}{\mpjustification}
16183 \setmarginfloatcaptionadjustment{figure}{\captionstyle{\mpjustification}}
16184 \end{lcode}
16185 It may be useful to allow hyphenation within the raggedness, which can
16186 be done using the \Lpack{ragged2e} package and
16187 \begin{lcode}
16188 \setmpjustification{\RaggedLeft}{\RaggedRight}
16189 \end{lcode}
16190
16191
16192
16193
16194
16195
16196
16197 \index{float!new|)} %|
16198
16199 \section{Setting off a float} \label{sec:floatsetoff}
16200
16201 \index{float!set off|(} %|
16202
16203 Sometimes it is desireable to set off a float, more probably
16204 an illustration than a tabular, from its surroundings. The \Ie{framed}
16205 environment, described later in \Cref{chap:bvf}, might come in handy
16206 for this.
16207
16208 The following code produces the example\indextwo{framed}{float}
16209 \figurerefname s~\ref{fig:framef} and~\ref{fig:framefcap}.
16210
16211 \begin{lcode}
16212 \begin{figure}
16213 \centering
16214 \begin{framed}\centering
16215 FRAMED FIGURE
16216 \end{framed}
16217 \caption{Example framed figure}\label{fig:framef}
16218 \end{figure}
16219
16220 \begin{figure}
16221 \begin{framed}\centering
16222 FRAMED FIGURE AND CAPTION
16223 \caption{Example framed figure and caption}\label{fig:framefcap}
16224 \end{framed}
16225 \end{figure}
16226 \end{lcode}
16227
16228 \begin{figure}
16229 %\begin{shadefigure}
16230 \centering
16231 \begin{framed}\centering
16232 FRAMED FIGURE
16233 \end{framed}
16234 \caption{Example framed figure}\label{fig:framef}
16235 %\end{shadefigure}
16236 \end{figure}
16237
16238 \begin{figure}
16239 \begin{framed}\centering
16240 FRAMED FIGURE AND CAPTION
16241 \caption{Example framed figure and caption}\label{fig:framefcap}
16242 \end{framed}
16243 \end{figure}
16244
16245 If framing seems overkill then you can use
16246 rules\indextwo{ruled}{float} instead, as in the example code below
16247 which produces
16248 \figurerefname s~\ref{fig:rulef} and~\ref{fig:rulefcap}.
16249
16250 \begin{lcode}
16251 \begin{figure}
16252 \centering
16253 \hrule\vspace{\onelineskip}
16254 RULED FIGURE
16255 \vspace{\onelineskip}\hrule
16256 \vspace{\onelineskip}
16257 \caption{Example ruled figure}\label{fig:rulef}
16258 \end{figure}
16259
16260 \begin{figure}
16261 \centering
16262 \hrule\vspace{\onelineskip}
16263 RULED FIGURE AND CAPTION
16264 \vspace{\onelineskip}\hrule
16265 \vspace{0.2pt}\hrule
16266 \vspace{\onelineskip}
16267 \caption{Example ruled figure and caption}\label{fig:rulefcap}
16268 \hrule
16269 \end{figure}
16270 \end{lcode}
16271
16272 \begin{shadefigure}
16273 %\centering
16274 %\definecolor{shadecolor}{gray}{0.75}
16275 %\begin{shaded}
16276 \hrule\vspace{\onelineskip}
16277 RULED FIGURE
16278 \vspace{\onelineskip}\hrule
16279 \vspace{\onelineskip}
16280 \caption{Example ruled figure}\label{fig:rulef}
16281 %\end{shaded}
16282 \end{shadefigure}
16283
16284 \begin{shadefigure}
16285 %\centering
16286 %\definecolor{shadecolor}{gray}{0.75}
16287 %\begin{shaded}
16288 \hrule\vspace{\onelineskip}
16289 RULED FIGURE AND CAPTION
16290 \vspace{\onelineskip}\hrule
16291 \vspace{0.2pt}\hrule
16292 \vspace{\onelineskip}
16293 \caption{Example ruled figure and caption}\label{fig:rulefcap}
16294 \hrule
16295 %\end{shaded}
16296 \end{shadefigure}
16297
16298 \index{float!set off|)}%|
16299
16300 \section{Multiple floats} \label{sec:multfloats}
16301
16302 \index{float!multiple|(}%|
16303
16304 You can effectively put what you like inside a float box. Normally there
16305 is just a single picture or tabular in a float but you can include
16306 as many of these as will fit inside the box.
16307
16308 % \begin{figure}
16309 \begin{shadefigure}
16310 \centering
16311 \hspace*{\fill}
16312 {ILLUSTRATION 1} \hfill {ILLUSTRATION 2}
16313 \hspace*{\fill}
16314 \caption{Example float with two illustrations} \label{fig:mult1}
16315 \end{shadefigure}
16316 % \end{figure}
16317
16318 Three typical cases of multiple figures\index{figure}/tables\index{table}
16319 in a single float come to mind:
16320 \begin{itemize}
16321 \item Multiple illustrations\index{illustration}/tabulars with a single
16322 caption.
16323 \item Multiple illustrations\index{illustration}/tabulars each
16324 individually captioned.
16325 \item Multiple illustrations\index{illustration}/tabulars with one
16326 main caption and individual subcaptions.
16327 \end{itemize}
16328
16329 \fref{fig:mult1} is an example of multiple
16330 illustrations\index{illustration!multiple} in a single float
16331 with a single caption. The figure was produced by the following code.
16332 \begin{lcode}
16333 \begin{figure}
16334 \centering
16335 \hspace*{\fill}
16336 {ILLUSTRATION 1} \hfill {ILLUSTRATION 2}
16337 \hspace*{\fill}
16338 \caption{Example float with two illustrations} \label{fig:mult1}
16339 \end{figure}
16340 \end{lcode}
16341 The \verb?\hspace*{\fill}? and \cmd{\hfill} commands were used to
16342 space the two illustrations\index{illustration} equally. Of course
16343 \cmd{\includegraphics}
16344 or \Ie{tabular} environments could just as well be used instead of the
16345 \verb?{ILLUSTRATION N}? text.
16346
16347 The following code produces \figurerefname s~\ref{fig:mult2}
16348 and~\ref{fig:mult3} which are examples of two separately
16349 captioned\index{caption!multiple}
16350 illustrations\index{illustration} in one float.
16351 \begin{lcode}
16352 \begin{figure}
16353 \centering
16354 \begin{minipage}{0.4\textwidth}
16355 \centering
16356 GRAPHIC 1
16357 \caption{Graphic 1 in a float} \label{fig:mult2}
16358 \end{minipage}
16359 \hfill
16360 \begin{minipage}{0.4\textwidth}
16361 \centering
16362 GRAPHIC 2
16363 \caption{Graphic 2 in same float} \label{fig:mult3}
16364 \end{minipage}
16365 \end{figure}
16366 \end{lcode}
16367 In this case the illustrations\index{illustration} (or graphics or
16368 tabulars) are put into separate \Ie{minipage}
16369 environments\index{minipage!in float} within the float,
16370 and the captions are also put within the \Ie{minipage}s. Note that
16371 any required \cmd{\label} must also be inside the \Ie{minipage}.
16372 If you wished, you could add yet another (main) caption after the end
16373 of the two \Ie{minipage}s.
16374
16375 %\begin{figure}
16376 \begin{shadefigure}
16377 \centering
16378 \begin{minipage}{0.4\textwidth}
16379 \centering
16380 GRAPHIC 1
16381 \caption{Graphic 1 in a float} \label{fig:mult2}
16382 \end{minipage}
16383 \hfill
16384 \begin{minipage}{0.4\textwidth}
16385 \centering
16386 GRAPHIC 2
16387 \caption{Graphic 2 in same float} \label{fig:mult3}
16388 \end{minipage}
16389 \end{shadefigure}
16390 % \end{figure}
16391
16392 It is slightly more complex if you want to put, say, both a
16393 tabulation captioned as a table and a graph, captioned as a figure,
16394 which illustrates the tabulation, as a
16395 float\index{float!multiple!table and figure}
16396 only permits one kind of caption. The class solves this problem by
16397 letting you define `fixed' captions\index{caption!fixed} which are
16398 independent of the particular kind of the float. These are described in
16399 detail later.
16400
16401 Things do get a little trickier, though, if the bodies and/or the
16402 captions in a float are different heights (as in
16403 figures~\ref{fig:mult2} and~\ref{fig:mult3}) and you want to align
16404 them horizontally. Here are some examples.
16405
16406
16407 This code produces figures~\ref{fig:left1} and~\ref{fig:right1}. The
16408 new \cmd{\hhrule} macro produces a rule twice as thick as \cmd{\hrule}
16409 does.
16410 \begin{lcode}
16411 \newcommand*{\hhrule}{\hrule height 0.8pt}% double thickness
16412
16413 \begin{figure}
16414 \hhrule \vspace{\onelineskip}
16415 \null\hfill\parbox{0.45\linewidth}{%
16416 \centering
16417 Aligned to the center of the right figure
16418 }\hfill
16419 \parbox{0.45\linewidth}{%
16420 \centering
16421 This is the right figure which is taller
16422 than the first one (the one at the left)
16423 }\hfill\null
16424 \vspace{\onelineskip}\hrule
16425 \null\hfill\parbox[t]{0.4\linewidth}{%
16426 \caption{Left figure}\label{fig:left1}%
16427 }\hfill
16428 \parbox[t]{0.4\linewidth}{%
16429 \caption{Right figure. This has more text than the adjacent
16430 caption (\ref{fig:left1}) so the heights are unequal}%
16431 \label{fig:right1}%
16432 }\hfill\null
16433 \hhrule
16434 \end{figure}
16435 \end{lcode}
16436
16437 \newcommand*{\hhrule}{\hrule height 0.8pt}% double thickness
16438
16439 %\begin{figure}
16440 \begin{shadefigure}
16441 \hhrule \vspace{\onelineskip}
16442 \null\hfill\parbox{0.45\linewidth}{%
16443 \centering
16444 Aligned to the center of the right figure
16445 }\hfill
16446 \parbox{0.45\linewidth}{%
16447 \centering
16448 This is the right figure which is taller
16449 than the first one (the one at the left)
16450 }\hfill\null
16451 \vspace{\onelineskip}\hrule
16452 \null\hfill\parbox[t]{0.4\linewidth}{%
16453 \caption{Left center aligned}\label{fig:left1}%
16454 }\hfill
16455 \parbox[t]{0.4\linewidth}{%
16456 \caption{Right figure. This has more text than the adjacent
16457 caption (\ref{fig:left1}) so the heights are unequal}%
16458 \label{fig:right1}%
16459 }\hfill\null
16460 \hhrule
16461 \end{shadefigure}
16462 %\end{figure}
16463
16464
16465 The following code produces \figurerefname s~\ref{fig:left2}
16466 and~\ref{fig:right2}.
16467 \begin{lcode}
16468 \begin{figure}
16469 \hhrule \vspace{0.5\onelineskip}
16470 \null\hfill\parbox[t]{0.45\linewidth}{%
16471 \centering
16472 Aligned to the top of the right figure
16473 }\hfill
16474 \parbox[t]{0.45\linewidth}{%
16475 \centering
16476 This is the right figure which is taller
16477 than the first one (the one at the left)
16478 }\hfill\null
16479 \vspace{0.5\onelineskip}\hrule
16480 \null\hfill\parbox[t]{0.4\linewidth}{%
16481 \caption{Left top aligned}\label{fig:left2}%
16482 }\hfill
16483 \parbox[t]{0.4\linewidth}{%
16484 \caption{Right figure. This has more text than the adjacent
16485 caption (\ref{fig:left2}) so the heights are unequal}%
16486 \label{fig:right2}%
16487 }\hfill\null
16488 \hhrule
16489 \end{figure}
16490 \end{lcode}
16491
16492 %\begin{figure}
16493 \begin{shadefigure}
16494 \hhrule \vspace{0.5\onelineskip}
16495 \null\hfill\parbox[t]{0.45\linewidth}{%
16496 \centering
16497 Aligned to the top of the right figure
16498 }\hfill
16499 \parbox[t]{0.45\linewidth}{%
16500 \centering
16501 This is the right figure which is taller
16502 than the first one (the one at the left)
16503 }\hfill\null
16504 \vspace{0.5\onelineskip}\hrule
16505 \null\hfill\parbox[t]{0.4\linewidth}{%
16506 \caption{Left top aligned}\label{fig:left2}%
16507 }\hfill
16508 \parbox[t]{0.4\linewidth}{%
16509 \caption{Right figure. This has more text than the adjacent
16510 caption (\ref{fig:left2}) so the heights are unequal}%
16511 \label{fig:right2}%
16512 }\hfill\null
16513 \hhrule
16514 \end{shadefigure}
16515 %\end{figure}
16516
16517 The next code produces \figurerefname s~\ref{fig:left3}
16518 and~\ref{fig:right3}.
16519 \begin{lcode}
16520 \begin{figure}
16521 \hhrule \vspace{0.5\onelineskip}
16522 \null\hfill\parbox[b]{0.45\linewidth}{%
16523 \centering
16524 Aligned to the bottom of the right figure
16525 }\hfill
16526 \parbox[b]{0.45\linewidth}{%
16527 \centering
16528 This is the right figure which is taller
16529 than the first one (the one at the left)
16530 }\hfill\null
16531 \vspace{0.5\onelineskip}\hrule
16532 \null\hfill\parbox[t]{0.4\linewidth}{%
16533 \caption{Left bottom aligned}\label{fig:left3}%
16534 }\hfill
16535 \parbox[t]{0.4\linewidth}{%
16536 \caption{Right figure. This has more text than the adjacent
16537 caption (\ref{fig:left3}) so the heights are unequal}%
16538 \label{fig:right3}%
16539 }\hfill\null
16540 \hhrule
16541 \end{figure}
16542 \end{lcode}
16543
16544 %\begin{figure}
16545 \begin{shadefigure}
16546 \hhrule \vspace{0.5\onelineskip}
16547 \null\hfill\parbox[b]{0.45\linewidth}{%
16548 \centering
16549 Aligned to the bottom of the right figure
16550 }\hfill
16551 \parbox[b]{0.45\linewidth}{%
16552 \centering
16553 This is the right figure which is taller
16554 than the first one (the one at the left)
16555 }\hfill\null
16556 \vspace{0.5\onelineskip}\hrule
16557 \null\hfill\parbox[t]{0.4\linewidth}{%
16558 \caption{Left bottom aligned}\label{fig:left3}%
16559 }\hfill
16560 \parbox[t]{0.4\linewidth}{%
16561 \caption{Right figure. This has more text than the adjacent
16562 caption (\ref{fig:left3}) so the heights are unequal}%
16563 \label{fig:right3}%
16564 }\hfill\null
16565 \hhrule
16566 \end{shadefigure}
16567 %\end{figure}
16568
16569
16570 \begin{syntax}
16571 \cmd{\newsubfloat}\marg{float} \\
16572 \end{syntax}
16573 \glossary(newsubfloat)%
16574 {\cs{newsubfloat}\marg{float}}%
16575 {Creates subcaptions for use in the \meta{float} float.}
16576 The \cmd{\newsubfloat} command\index{float!new subfloat}
16577 creates subcaptions\index{caption!new subcaption}
16578 (\cmd{\subcaption}, \cmd{\subtop} and \cmd{\subbottom})
16579 for use within the float environment \meta{fenv} previously
16580 defined via \cmd{\newfloat}\oarg{...}\marg{fenv}\marg{...}.
16581 Subcaptions are discussed below in \Sref{sec:subcaps}.
16582 \PWnote{2009/08/23}{Improved cross references between \cs{newsubfloat}
16583 and \cs{subcaption}.}
16584
16585 \index{float!multiple|)}%|
16586
16587 \section{Where \ltx\ puts floats} \label{sec:floatplace}
16588
16589 \index{float!placement|(}%|
16590
16591 Note that this section is not just relevant to the class, but for
16592 \ltx\ in general. The main difference for placement between the class
16593 and, say, the \Lclass{book} class are the default values of some
16594 settings.
16595
16596
16597
16598 The general format for a float environment is: \\
16599 \senv{float}\oarg{loc} ... \eenv{float}
16600 or for double column\index{float!double column} floats: \\
16601 \senv{float*}\oarg{loc} ... \eenv{float*} \\
16602 where the optional argument \meta{loc}, consisting of one or more characters,
16603 specifies a location where the float may be placed. Note that the
16604 \Lpack{multicol}\index{column!multiple} package only supports the
16605 starred floats and it will not let you have a single
16606 column\index{float!single column} float. The possible \meta{loc} values
16607 are one or more of the following:
16608 \begin{itemize}
16609 \item[\textsf{b}\ixposarg{b}] \emph{bottom}: at the bottom\index{float!bottom}
16610 of a page.
16611 This does not apply to double column\index{float!double column} floats
16612 as they may only be placed at the top of a page.
16613 \item[\textsf{h}\ixposarg{h}] \emph{here}: if possible exactly where
16614 the float\index{float!here} environment is defined.
16615 It does not apply to double
16616 column\index{float!double column} floats.
16617 \item[\textsf{p}\ixposarg{p}] \emph{page}: on a separate page
16618 containing only floats\index{float!page} (no text); this is called
16619 a \emph{float page}.
16620 \item[\textsf{t}\ixposarg{t}] \emph{top}: at the top\index{float!top}
16621 of a page.
16622 \item[\textsf{!}] make an extra effort to place the float at the
16623 earliest place specified by the rest of the argument.
16624 \end{itemize}
16625 The default for \meta{loc} is \textsf{t}\textsf{b}\textsf{p},
16626 so the float may be placed at the top, or bottom, or on a
16627 float\index{float!page} page; the default works well 95\% of the time.
16628 Floats of the same kind are output in
16629 definition order, except that a double column\index{float!double column} float
16630 may be output before
16631 a later single column\index{float!single column} float of the same kind, or
16632 \textit{vice-versa}\footnote{As of 2015 this has been fixed in the
16633 \LaTeX{} kernel.}.
16634 A float is never put on an earlier page than its definition but may be
16635 put on the same or later page of its definition. If a float cannot be
16636 placed, all suceeding floats will be held up, and \ltx\ can store no
16637 more than 16 held up floats. A float cannot be placed if it would cause
16638 an overfull page, or it otherwise cannot be fitted according the
16639 float placement parameters.
16640 A \cmd{\clearpage} or \cmd{\cleardoublepage} or \eenv{document}
16641 flushes\index{float!flush}
16642 out all unprocessed floats, irrespective of the \meta{loc} and float
16643 parameters, putting them on float-only\index{float!page} pages.
16644
16645 \begin{syntax}
16646 \cmd{\setfloatlocations}\marg{float}\marg{locs} \\
16647 \end{syntax}
16648 \glossary(setfloatlocations)%
16649 {\cs{setfloatlocations}\marg{float}\marg{locs}}%
16650 {Sets the default location for the \meta{float} (e.g., \Pe{table})
16651 to \meta{locs} (default \texttt{tbp}).}
16652 You can set the location for all floats of type \meta{float} to
16653 \meta{locs} with the \cs{setfloatlocations} declaration. The class
16654 initialises these using:
16655 \begin{lcode}
16656 \setfloatlocations{figure}{tbp}
16657 \setfloatlocations{table}{tbp}
16658 \end{lcode}
16659
16660 \begin{syntax}
16661 \cmd{\suppressfloats}\oarg{pos} \\
16662 \end{syntax}
16663 \glossary(suppressfloats)%
16664 {\cs{suppressfloats}\oarg{pos}}%
16665 {Suppresses any floats on the current page at the given \meta{pos} placement.}
16666 You can use the command \cmd{\suppressfloats} to
16667 suppress\index{float!suppress} floats
16668 at a given \meta{pos} on the current page.
16669 \cmd{\suppressfloats}\verb?[t]?
16670 prevents any floats at the top\index{float!suppress top} of the page and
16671 \cmd{\suppressfloats}\verb?[b]?
16672 prevents any floats at the bottom\index{float!suppress bottom} of the page.
16673 The simple \cmd{\suppressfloats} prevents both top and bottom floats.
16674
16675 \begin{syntax}
16676 \cmd{\FloatBlock}\\
16677 \cmd{\FloatBlockAllowAbove}\\
16678 \cmd{\FloatBlockAllowBelow}
16679 \end{syntax}
16680 \glossary(FloatBlock)%
16681 {\cs{FloatBlock}}%
16682 {Force \LaTeX\ to place all unplaced floats before proceeding this point.}
16683 \glossary(FloatBlockAllowAbove)%
16684 {\cs{FloatBlockAllowAbove}}%
16685 {Lessens the restriction by \cs{FloatBlock} such that a float
16686 inserted \emph{after} a \cs{FloatBlock} can appear at the top of
16687 the same page as \cs{FloatBlock}.}
16688 \glossary(FloatBlockAllowBelow)%
16689 {\cs{FloatBlockAllowBelow}}%
16690 {Lessens the restriction by \cs{FloatBlock} such that a float
16691 inserted \emph{before} a \cs{FloatBlock} can appear at the bottom of
16692 the same page as \cs{FloatBlock}.}
16693 Contrary to \cmd{\suppressfloats} \cmd{\FloatBlock}\footnote{Yes, it
16694 \emph{is} the same as \cs{FloatBarrier} from the
16695 \Lpack{placeins} package, kudos to Donald Arseneau. For various
16696 reasons we cannot emulate the \Lpack{placeins} package and its
16697 options, thus we have verbatimly copied and renamed it instead.} will block
16698 floats from passing this point, i.e.\ it demands \LaTeX\ to place any
16699 unprocessed floats before proceeding. It is similar to
16700 \cmd{\clearpage} but it does not necessarily introduce a page break
16701 before proceeding.
16702
16703 \cmd{\FloatBlockAllowAbove} lessens the restriction a little, in a
16704 situation like this
16705 \begin{lcode}
16706 \FloatBlock
16707 some float here
16708 \end{lcode}
16709 \cmd{\FloatBlockAllowAbove} will allow the float to be placed at the
16710 top of the same page as \cmd{\FloatBlock}. \cmd{\FloatBlockAllowBelow}
16711 is the reverse situation.
16712
16713 It may be beneficial to be able to add \cmd{\FloatBlock} to sectional
16714 commands. This can be done via
16715 \begin{syntax}
16716 \cmd{\setFloatBlockFor}\marg{sectional name}
16717 \end{syntax}
16718 \glossary(setFloatBlockFor)%
16719 {\cs{setFloatBLockFor}\marg{sectional name}}%
16720 {Adds \cs{FloatBlock} within the \cs{\meta{section name}} macro.}
16721 where \meta{sectional name} is \emph{without} the \cs{}, i.e.\
16722 \begin{lcode}
16723 \setFloatBlockFor{section}
16724 \end{lcode}
16725
16726
16727
16728
16729 \fancybreak{}
16730
16731 The \Lpack{flafter} package, which should have come with your \ltx\
16732 distribution, provides a means of preventing floats from moving
16733 backwards from their definition position in the text. This can be useful to
16734 ensure, for example, that a float early in a \verb?\section{...}? is not
16735 typeset before the section heading\index{heading}.
16736
16737 \begin{figure}
16738 \centering
16739 \drawparameterstrue
16740 \drawfloatpage
16741 \caption{Float and text page parameters}\label{fig:fpp}
16742 \end{figure}
16743
16744 \begin{figure}
16745 \centering
16746 \drawparameterstrue
16747 \setlayoutscale{0.9}
16748 \drawfloat
16749 \caption{Float parameters}\label{fig:flp}
16750 \end{figure}
16751
16752 \begin{table}
16753 \begin{adjustwidth}{-3cm}{-3cm}
16754 \centering
16755 %% \captionnamefont{\small\sffamily}
16756 %% \captiontitlefont{\small\sffamily}
16757 \setlength{\belowcaptionskip}{10pt}
16758 \caption{Float placement parameters}\label{tab:fpp}
16759 \begin{tabular}{lp{0.5\textwidth}r} \toprule
16760 Parameter & Controls & Default \\ \midrule
16761 \multicolumn{3}{c}{Counters --- change with \cs{setcounter} } \\ \midrule
16762 \Icn{topnumber} & max number of floats at top of a page & 2 \\
16763 \Icn{bottomnumber} & max number of floats at bottom of a page & 1 \\
16764 \Icn{totalnumber} & max number of floats on a text page & 3 \\
16765 \Icn{dbltopnumber} & like \Icn{topnumber} for double column
16766 floats\index{float!double column} & 2 \\ \midrule
16767 \multicolumn{3}{c}{Commands --- change with \cs{renewcommand} } \\ \midrule
16768 \cmd{\topfraction} & max fraction of page reserved for top
16769 floats\index{float!top} & 0.7 \\
16770 \cmd{\bottomfraction} & max fraction of page reserved for bottom
16771 floats\index{float!bottom} & 0.3 \\
16772 \cmd{\textfraction} & min fraction of page that must have text & 0.2 \\
16773 \cmd{\dbltopfraction} & like \cmd{\topfraction} for double column
16774 floats\index{float!double column} floats & 0.7 \\
16775 \cmd{\floatpagefraction} & min fraction of a float page that must have float(s) & 0.5 \\
16776 \cmd{\dblfloatpagefraction} & like \cmd{\floatpagefraction} for double column
16777 floats\index{float!double column} & 0.5 \\ \bottomrule
16778 \end{tabular}
16779 \end{adjustwidth}
16780 \end{table}
16781
16782
16783 \begin{table}
16784 \begin{adjustwidth}{-3cm}{-3cm}
16785 \centering
16786 %% \captionnamefont{\small\sffamily}
16787 %% \captiontitlefont{\small\sffamily}
16788 \setlength{\belowcaptionskip}{10pt}
16789 \caption{Float spacing parameters}\label{tab:fsp}
16790 \begin{tabular}{lp{0.5\textwidth}r} \toprule
16791 Parameter & Controls & Default \\ \midrule
16792 \multicolumn{3}{c}{Text page lengths --- change with \cs{setlength} } \\ \midrule
16793 \lnc{\floatsep} & vertical space between floats & 12pt \\
16794 \lnc{\textfloatsep} & vertical space between a top (bottom) float and
16795 suceeding (preceeding) text & 20pt \\
16796 \lnc{\intextsep} & vertical space above and below an \texttt{h}
16797 float\index{float!here} & 12pt \\
16798 \lnc{\dblfloatsep} & like \lnc{\floatsep} for double column
16799 floats\index{float!double column} & 12pt \\
16800 \lnc{\dbltextfloatsep} & like \lnc{\textfloatsep} for double column
16801 floats\index{float!double column} & 20pt \\ \midrule
16802 \multicolumn{3}{c}{Float page lengths --- change with \cs{setlength} } \\ \midrule
16803 \lnc{\@fptop} & space at the top of the page & \verb?0pt plus 1fil? \\
16804 \lnc{\@fpsep} & space between floats & \verb?8pt plus 2fil? \\
16805 \lnc{\@fpbot} & space at the bottom of the page & \verb?0pt plus 1fil? \\
16806 \lnc{\@dblfptop} & like \lnc{\@fptop} for double column
16807 floats\index{float!double column} & \verb?0pt plus 1fil? \\
16808 \lnc{\@dblfpsep} & like \lnc{\@fpsep} for double column
16809 floats\index{float!double column} & \verb?8pt plus 2fil? \\
16810 \lnc{\@dblfpbot} & like \lnc{\@fpbot} for double column
16811 floats\index{float!double column} & \verb?0pt plus 1fil? \\
16812 \bottomrule
16813 \end{tabular}
16814 \end{adjustwidth}
16815 \end{table}
16816
16817 Figures~\ref{fig:fpp} and~\ref{fig:flp} illustrate the many float
16818 parameters\index{float!parameters}
16819 and \tref{tab:fpp} lists the float parameters and the typical
16820 standard default values. The lengths controlling the spaces surroundind
16821 floats are listed
16822 in \tref{tab:fsp}; typical values are shown as they depend on both
16823 the class and the size option.
16824
16825 Given the displayed defaults, the height of a top float must be
16826 less than 70\% of the textheight and there can be no more than 2 top
16827 floats\index{float!top}
16828 on a text page. Similarly, the height of a bottom float must not
16829 exceed 30\% of the textheight and there can be no more than 1 bottom
16830 float\index{float!bottom} on a text page. There can be no more than
16831 3 floats (top, bottom and here\index{float!here})
16832 on the page. At least 20\% of a text page with floats must be text.
16833 On a float page\index{float!page} (one that has no text, only floats)
16834 the sum of the heights
16835 of the floats must be at least 50\% of the textheight. The floats on a float
16836 page should be vertically centered.
16837
16838 Under certain extreme and unlikely conditions and with the defaults
16839 \ltx\ might have trouble finding a place for a float.
16840 Consider what will happen if a float is specified as a bottom float and
16841 its height is 40\% of the textheight and this is followed by a float whose
16842 height is 90\% of the textheight. The first is too large to actually
16843 go at the bottom of a text page but too small to go on a float page by
16844 itself. The second has to go on a float page but it is too large to share
16845 the float page with the first float. \ltx\ is stuck!
16846
16847 At this point it is worthwhile to be precise about the effect of a
16848 one character \meta{loc} argument:
16849 \begin{itemize}
16850 \item[\textsf{b}\ixposarg{b}] means:
16851 `put the float at the bottom of a page with some
16852 text above it, and nowhere else'.
16853 The float must fit into the \cmd{\bottomfraction} space
16854 otherwise it and subsequent floats will be held up.
16855 \item[\textsf{h}\ixposarg{h}] means:
16856 `put the float at this point and nowhere else'.
16857 The float must fit into the space left on the page
16858 otherwise it and subsequent floats will be held up.
16859 \item[\textsf{p}\ixposarg{p}] means:
16860 `put the float on a page that has no text but may
16861 have other floats on it'.
16862 There must be at least `\cmd{\floatpagefraction}' worth of
16863 floats to go on a float only page before the float will be output.
16864 \item[\textsf{t}\ixposarg{t}] means:
16865 `put the float at the top of a page with some
16866 text below it, and nowhere else'.
16867 The float must fit into the \cmd{\topfraction} space
16868 otherwise it and subsequent floats will be held up.
16869 \item[\textsf{!...}] means:
16870 `ignore the \cs{...fraction} values for this float'.
16871 \end{itemize}
16872
16873 You must try and pick a combination from these that will let \ltx\ find
16874 a place to put your floats. However, you can
16875 also change the float parameters to make it easier to find places
16876 to put floats. Some examples are:
16877 \begin{itemize}
16878 \item Decrease \cmd{\textfraction} to get more `float' on a text page,
16879 but the sum of \cmd{\textfraction} and \cmd{\topfraction} and the sum
16880 of \cmd{\textfraction} and \cmd{\bottomfraction} should not exceed 1.0,
16881 otherwise the placement algorithm falls apart. A minimum value for
16882 \cmd{\textfraction} is about 0.10 --- a page with less than 10\% text
16883 looks better with no text at all, just floats.
16884
16885 \item Both \cmd{\topfraction} and \cmd{\bottomfraction} can be increased,
16886 and it does not matter if their sum exceeds 1.0. A good typographic
16887 style is that floats are encouraged to go at the top of a page, and
16888 a better balance is achieved if the float space on a page is larger
16889 at the top than the bottom.
16890
16891 \item Making \cmd{\floatpagefraction} too small might have the effect of a
16892 float page just having one small float. However, to make sure that a float
16893 page never has more than one float on it, do:
16894 \begin{lcode}
16895 \renewcommand{\floatpagefraction}{0.01}
16896 \setlength{\@fpsep}{\textheight}
16897 \end{lcode}
16898
16899 \item Setting \lnc{\@fptop} and \lnc{\@dblftop} to \texttt{0pt},
16900 \lnc{\@fpsep} to \texttt{8pt},
16901 and \lnc{\@fpbot} and \lnc{\@dblfpbot} to \texttt{0pt plus 1fil}
16902 will force floats on
16903 a float page to start at the top of the page.
16904
16905
16906 \item Setting \lnc{\@fpbot} and \lnc{\@dblfpbot} to \texttt{0pt},
16907 \lnc{\@fpsep} to \texttt{8pt},
16908 and \lnc{\@fptop} and \lnc{\@dblfptop} to \texttt{0pt plus 1fil}
16909 will force floats on
16910 a float page to the bottom of the page.
16911 \end{itemize}
16912
16913 If you are experimenting, a reasonable starting position is:
16914 \begin{lcode}
16915 \setcounter{topnumber}{3}
16916 \setcounter{bottomnumber}{2}
16917 \setcounter{totalnumber}{4}
16918 \renewcommand{\topfraction}{0.85}
16919 \renewcommand{\bottomfraction}{0.5}
16920 \renewcommand{\textfraction}{0.15}
16921 \renewcommand{\floatpagefraction}{0.7}
16922 \end{lcode}
16923 and similarly for double column\index{float!double column} floats if you will
16924 have any. Actually, there is no need
16925 to try these settings as they are the default for this class.
16926
16927 One of \ltx's little quirks is that on a text page, the `height' of
16928 a float is its actual height plus \lnc{\textfloatsep} or \lnc{\floatsep},
16929 while on a float page the `height' is the actual height. This means that
16930 when using the default \meta{loc} of \verb?[tbp]? at least one of the text
16931 page float fractions (\cmd{\topfraction} and/or \cmd{\bottomfraction})
16932 must be larger than the \cmd{\floatpagefraction} by an amount sufficient
16933 to take account of the maximum text page separation value.
16934
16935
16936 \index{float!placement|)} % |
16937
16938 \section{Captions}
16939
16940 \index{caption|(} %)|
16941
16942 Some publishers require, and some authors prefer, captioning styles
16943 other than the one style provided by standard \ltx.
16944 Further, some demand that documents that include multi-part
16945 tables\index{table} use a \textit{continuation caption} on all but the first
16946 part of the multi-part table\index{table}. For the times where such
16947 a table\index{table} is specified by the author as a set of
16948 tables\index{table}, the class provides a simple `continuation'
16949 caption\index{caption!continuation} command to meet this
16950 requirement. It also provides a facility for an `anonymous'
16951 caption\index{caption!anonymous}
16952 which can be used in any float\index{float} environment.
16953 Captions can be defined that are suitable for use in non-float
16954 environments, such as placing a picture in a minipage and captioning
16955 it just as though it had been put into a normal
16956 figure\index{figure} environment.
16957
16958 The commands described below are very similar to
16959 those supplied by the \Lpack{ccaption} package~\cite{CCAPTION}.
16960
16961 \begin{recommended}
16962 As an alternative to the styling features in the class we recommend
16963 the \Lpack{caption} package by Axel Sommerfeldt (which provides many
16964 more features compared to the class).
16965
16966 As of late 2020, Axel was kind enough to add a feature to the
16967 \Lpack{caption} package such that if loaded with \theclass\ then
16968 most of the styling commands presented in the next section will be
16969 mapped onto the equivalent settings used by the \Lpack{caption}
16970 package. Just make sure your settings are set \emph{after} loading
16971 \Lpack{caption}.\footnotemark
16972 \end{recommended}
16973 \footnotetext{Be aware that other packages may auto load the \Lpack{caption} package.}
16974
16975
16976 \section{Caption styling}
16977
16978 \index{caption!style|(} %)|
16979
16980 Just as a reminder, the default appearance of a caption for, say,
16981 a table looks like this:
16982 \begin{center}
16983 Table 11.7: Title for the table
16984 \end{center}
16985 That is, it is typeset in the normal body font, with a colon after
16986 the number.
16987
16988 The class uses the following to specify the standard \ltx\ caption
16989 style:
16990 \begin{lcode}
16991 \captionnamefont{}
16992 \captiontitlefont{}
16993 \captionstyle{}
16994 \captionwidth{\linewidth}
16995 \normalcaptionwidth
16996 \normalcaption
16997 \captiondelim{: }
16998 \end{lcode}
16999 These macros are explained in detail below.
17000
17001 \begin{syntax}
17002 \cmd{\captiondelim}\marg{delim} \\
17003 \end{syntax}
17004 \glossary(captiondelim)%
17005 {\cs{captiondelim}\marg{delim}}%
17006 {Specifies \meta{delim} to be the delimeter between the number and title in a caption.}
17007 The default captioning style is to put a delimeter\index{caption!delimeter}
17008 in the form of a colon between the caption
17009 number and the caption title. The command \cmd{\captiondelim}
17010 can be used to change the delimeter. For example, to have an en-dash instead
17011 of the colon, \verb?\captiondelim{-- }? will do the trick.
17012 Notice that no space is put between the delimeter and the title unless
17013 it is specified in the \meta{delim} parameter.
17014 The class initially specifies \verb?\captiondelim{: }? to give the normal
17015 delimeter.
17016 % \begin{syntax}
17017 % \cmd{\captiondelimnocap}\marg{code}
17018 % \end{syntax}
17019 % \glossary(captiondelimnocap)%
17020 % {\cs{captiondelimnocap}\marg{code}}%
17021 % {Used as the delimiter after the caption number when the caption is
17022 % empty. Empty by default.}
17023 % Whenever the caption text is empty, it looks a little strange to have
17024 % \texttt{Figure 2.3:} and nothing else. Instead, in this case we replace
17025 % \cmd{\captiondelim} by \cmd{\captiondelimnocap}, which is empty by
17026 % default, i.e., we end up with \texttt{Figure 2.3} instead.
17027
17028
17029
17030 \begin{syntax}
17031 \cmd{\captionnamefont}\marg{fontspec} \\
17032 \end{syntax}
17033 \glossary(captionnamefont)%
17034 {\cs{captionnamefont}\marg{fontspec}}%
17035 {Set the font for the first part (name and number) of a caption, upto and including
17036 the delimeter.}
17037 The \meta{fontspec} specified by \cmd{\captionnamefont} is used
17038 for typesetting the caption\index{caption!font} name;
17039 that is, the first part of the caption
17040 up to and including the delimeter (e.g., the portion `Table 3:').
17041 \meta{fontspec} can be any kind of font specification and/or command and/or
17042 text. This first part of the caption is treated like:
17043 \begin{lcode}
17044 {\captionnamefont Table 3: }
17045 \end{lcode}
17046 so font declarations, not font text-style commands, are needed for
17047 \meta{fontspec}. For instance,
17048 \begin{lcode}
17049 \captionnamefont{\Large\sffamily}
17050 \end{lcode}
17051 to specify a large sans-serif font. The class initially specifies
17052 \verb?\captionnamefont{}? to give the normal font.
17053
17054
17055 \begin{syntax}
17056 \cmd{\captiontitlefont}\marg{fontspec} \\
17057 \end{syntax}
17058 \glossary(captiontitlefont)%
17059 {\cs{captiontitlefont}\marg{fontspec}}%
17060 {Set the font for the caption title text.}
17061 Similarly, the \meta{fontspec} specified by \cmd{\captiontitlefont}
17062 is used for typesetting the title text\index{caption!font} of a caption.
17063 For example,
17064 \verb?\captiontitlefont{\itshape}? for an italic title text.
17065 The class initially specifies \verb?\captiontitlefont{}?
17066 to give the normal font.
17067
17068 \begin{syntax}
17069 \cmd{\captionstyle}\oarg{short}\marg{style} \\
17070 \cmd{\raggedleft} \cmd{\centering} \cmd{\raggedright} \cmd{\centerlastline} \\
17071 \end{syntax}
17072 \glossary(captionstyle)%
17073 {\cs{captionstyle}\oarg{short}\marg{style}}%
17074 {Set the paragraph style for the caption. The optional \meta{short} is
17075 the style for captions shorter than a full line.}
17076 By default the name and title of a caption are typeset as a block
17077 (non-indented) paragraph\index{paragraph!block}.
17078 \cmd{\captionstyle} can be used to alter this.
17079 Sensible values for \meta{style} are: \cmd{\centering}, \cmd{\raggedleft} or
17080 \cmd{\raggedright} for styles\index{caption!paragraph style}
17081 corresponding to these declarations.
17082 The \cmd{\centerlastline} style gives a block paragraph\index{paragraph!block}
17083 but with the last line centered.
17084 The class initially specifies \verb?\captionstyle{}?
17085 to give the normal block paragraph style.
17086
17087 If a caption is less than one line in length it may look odd if the
17088 \meta{style} is \cmd{\raggedright}, say, as it will be left justified.
17089 The optional \meta{short} argument to \cmd{\captionstyle} can be used to
17090 specify the style\index{caption!short style} for such short captions
17091 if it should differ from that for multiline\index{caption!multiline}
17092 captions. For example, I think that short captions look better
17093 centered:
17094 \begin{lcode}
17095 \captionstyle[\centering]{\raggedright}
17096 \end{lcode}
17097
17098 \begin{syntax}
17099 \cmd{\hangcaption} \\
17100 \cmd{\indentcaption}\marg{length} \\
17101 \cmd{\normalcaption} \\
17102 \end{syntax}
17103 \glossary(hangcaption)%
17104 {\cs{hangcaption}}%
17105 {Multiline captions will be typeset as a hanging paragraph.}
17106 \glossary(indentcaption)%
17107 {\cs{indentcaption}\marg{length}}%
17108 {Multiline captions will be typeset as a hanging paragraph hung by \meta{length}.}
17109 \glossary(normalcaption)%
17110 {\cs{normalcaption}}%
17111 {Multiline captions will be typeset as a block paragraph.}
17112 \PWnote{2009/06/25}{Hang/indent no longer affects short captions}
17113 The declaration \cmd{\hangcaption} causes captions to be typeset with
17114 the second and later lines of a multiline\index{caption!multiline}
17115 caption title indented by
17116 the width of the caption name.
17117 The declaration \cmd{\indentcaption} will indent title lines after
17118 the first by \meta{length}. These commands are independent of
17119 the \cmd{\captionstyle}\verb?{...}? and have no effect on short captions.
17120 Note that a caption will not
17121 be simultaneously hung and indented. The \cmd{\normalcaption} declaration
17122 undoes any previous \cmd{\hangcaption} or \cmd{\indentcaption} declaration.
17123 The class initially specifies \cmd{\normalcaption} to give the normal
17124 non-indented paragraph\index{paragraph!indentation} style.
17125
17126 \begin{syntax}
17127 \cmd{\changecaptionwidth} \\
17128 \cmd{\captionwidth}\marg{length} \\
17129 \cmd{\normalcaptionwidth} \\
17130 \end{syntax}
17131 \glossary(changecaptionwidth)%
17132 {\cs{changecaptionwidth}}%
17133 {Captions will be set within the width specified by \cs{captionwidth}.}
17134 \glossary(captionwidth)%
17135 {\cs{captionwidth}\marg{length}}%
17136 {Set the caption width to \meta{length}.}
17137 \glossary(normalcaptionwidth)%
17138 {\cs{normalcaptionwidth}}%
17139 {Captions will be set to the full width.}
17140 Issuing the declaration \cmd{\changecaptionwidth} causes the captions to
17141 be typeset within a total width\index{caption!width} \meta{length}
17142 as specified by \cmd{\captionwidth}.
17143 Issuing the declaration \cmd{\normalcaptionwidth}
17144 causes captions to be typeset as normal full width captions.
17145 The class initially specifies
17146 \begin{lcode}
17147 \normalcaptionwidth
17148 \captionwidth{\linewidth}
17149 \end{lcode}
17150 to give the normal width. If a caption is being set within the
17151 side captioned\index{caption!side caption} environments from
17152 the \Lpack{sidecap} package~\cite{SIDECAP}
17153 then it must be a \cmd{\normalcaptionwidth} caption.
17154
17155 \begin{syntax}
17156 \cmd{\precaption}\marg{pretext} \\
17157 \cmd{\captiontitlefinal}\marg{text} \\
17158 \cmd{\postcaption}\marg{posttext} \\
17159 \end{syntax}
17160 \glossary(precaption)%
17161 {\cs{precaption}\marg{pretext}}%
17162 {\meta{pretext} will be processed at the start of a caption.}
17163 \glossary(captiontitlefinal)%
17164 {\cs{captiontitlefinal}\marg{text}}%
17165 {\meta{text} will be put immediately at the end of a caption title,
17166 but will not appear in a \listofx.}
17167 \glossary(postcaption)%
17168 {\cs{postcaption}\marg{posttext}}%
17169 {\meta{posttext} will be processed at the end of a caption.}
17170
17171 The commands \cmd{\precaption} and \cmd{\postcaption}
17172 specify \meta{pretext} and \meta{posttext} that will be processed at the
17173 start and end of a caption. For example
17174 \begin{lcode}
17175 \precaption{\rule{\linewidth}{0.4pt}\par}
17176 \postcaption{\rule{\linewidth}{0.4pt}}
17177 \end{lcode}
17178 will draw a horizontal line\index{caption!ruled} above and below
17179 the captions.
17180 The class initially specifies
17181 \begin{lcode}
17182 \precaption{}
17183 \postcaption{}
17184 \end{lcode}
17185 to give the normal appearance.
17186
17187 The argument to \cmd{\captiontitlefinal} is put immediately after the
17188 title text but will not appear in the LoF or LoT. The default is
17189 \begin{lcode}
17190 \captiontitlefinal{}
17191 \end{lcode}
17192 but it could be used instead as, say
17193 \begin{lcode}
17194 \captiontitlefinal{.}
17195 \end{lcode}
17196 to put a period (full stop) after the title.
17197
17198 If any of the above commands are used in a float\index{float},
17199 or other, environment their effect is limited to the environment.
17200 If they are used in the preamble\index{preamble}
17201 or the main text, their effect persists until replaced by a similar
17202 command with a different parameter value. The commands do not affect the
17203 appearance of the title in any \listofx.
17204
17205 \begin{syntax}
17206 \cmd{\\}\oarg{length} \\
17207 \cmd{\\*}\oarg{length} \\
17208 \end{syntax}
17209 The normal \ltx\ command \cmd{\\} can be used within the
17210 caption text to start a new line. Remember that \cmd{\\} is a fragile
17211 command, so if it is used within text that will be added to a \listofx\
17212 it must be protected.
17213 As examples:
17214 \begin{lcode}
17215 \caption{Title with a \protect\\ new line in
17216 both the body and List of}
17217 \caption[List of entry with no new line]%
17218 {Title with a \\ new line}
17219 \caption[List of entry with a \protect\\ new line]%
17220 {Title text}
17221 \end{lcode}
17222
17223 Effectively, a caption is typeset as though it were:
17224 \begin{lcode}
17225 \precaption
17226 {\captionnamefont NAME NUMBER\captiondelim}
17227 {\captionstyle\captiontitlefont THE TITLE\captiontitlefinal}
17228 \postcaption
17229 \end{lcode}
17230 Replacing the above commands by their defaults leads to the simple
17231 format: \\
17232 \verb?{NAME NUMBER: }{THE TITLE}?
17233
17234 As well as using the styling commands to make simple changes to the
17235 captioning style, more noticeable modifications can also be made.
17236 To change the captioning style so that the name and title are typeset in
17237 a sans font\index{caption!font} it is sufficient to do:
17238 \begin{lcode}
17239 \captionnamefont{\sffamily}
17240 \captiontitlefont{\sffamily}
17241 \end{lcode}
17242
17243 \begin{shadetable}
17244 % \centering
17245 \captionnamefont{\sffamily}
17246 \captiondelim{}
17247 \captionstyle{\\}
17248 \captiontitlefont{\scshape}
17249 \setlength{\belowcaptionskip}{10pt}
17250 \caption{Redesigned table caption style} \label{tab:style}
17251 \begin{tabular}{lr} \toprule
17252 three & III \\
17253 five & V \\
17254 eight & VIII \\ \bottomrule
17255 \end{tabular}
17256 \end{shadetable}
17257
17258 A more obvious change in styling is shown in \tref{tab:style},
17259 which was coded as:
17260 \begin{lcode}
17261 \begin{table}
17262 \centering
17263 \captionnamefont{\sffamily}
17264 \captiondelim{}
17265 \captionstyle{\\}
17266 \captiontitlefont{\scshape}
17267 \setlength{\belowcaptionskip}{10pt}
17268 \caption{Redesigned table caption style} \label{tab:style}
17269 \begin{tabular}{lr} \toprule
17270 ...
17271 \end{table}
17272 \end{lcode}
17273 This leads to the approximate caption format
17274 (processed within \cmd{\centering}):
17275 \begin{lcode}
17276 {\sffamily NAME NUMBER}{\\ \scshape THE TITLE}
17277 \end{lcode}
17278 Note that the newline command (\cmd{\\}) cannot be put in the first part
17279 of the format (i.e., the \verb?{\sffamily NAME NUMBER}?); it has to go into
17280 the second part, which is why it is specified via \verb?\captionstyle{\\}?
17281 and not \verb?\captiondelim{\\}?.
17282
17283 If a mixture of captioning styles will be used you may want to
17284 define a special caption command for each non-standard style. For
17285 example for the style of the caption in \tref{tab:style}:
17286 \begin{lcode}
17287 \newcommand{\mycaption}[2][\@empty]{
17288 \captionnamefont{\sffamily\hfill}
17289 \captiondelim{\hfill}
17290 \captionstyle{\centerlastline\\}
17291 \captiontitlefont{\scshape}
17292 \setlength{\belowcaptionskip}{10pt}
17293 \ifx \@empty#1 \caption{#2}\else \caption[#1]{#2}\fi}
17294 \end{lcode}
17295 Remember that any code that involves the \idxatincode\texttt{@} sign must
17296 be either in
17297 a package (\file{sty}) file or enclosed between a \cmd{\makeatletter} \ldots
17298 \cmd{\makeatother} pairing (\seeatincode).
17299
17300 The code for the \tref{tab:style} example can now be written as:
17301 \begin{lcode}
17302 \begin{table}
17303 \centering
17304 \mycaption{Redesigned table caption style} \label{tab:style}
17305 \begin{tabular}{lr} \toprule
17306 ...
17307 \end{table}
17308 \end{lcode}
17309 Note that in the code for \cs{mycaption} I have added two
17310 \cmd{\hfill} commands and \cmd{\centerlastline} compared with the original
17311 specification.
17312 It turned out that the original definitions
17313 worked for a single line caption but not for a
17314 multiline\index{caption!multiline} caption.
17315 The additional commands makes it work in both cases, forcing the
17316 name to be centered as well as the last line of a multiline title,
17317 thus giving a balanced appearence.
17318
17319 \index{caption!style|)}%|
17320
17321
17322 \section{Continuation captions and legends}
17323
17324 \index{caption!continued|(}%|
17325
17326 \begin{syntax}
17327 \cmd{\contcaption}\marg{text} \\
17328 \end{syntax}
17329 \glossary(contcaption)%
17330 {\cs{contcaption}\marg{text}}%
17331 {A continued caption, replacing the original title with \meta{text}.}
17332 The \cmd{\contcaption} command can be used to put
17333 a `continued' or `concluded'
17334 caption into a float\index{float} environment. It neither increments the
17335 float number nor makes any entry into a float listing, but it
17336 does repeat the numbering of the previous \cmd{\caption} command.
17337
17338
17339 \tref{tab:m} illustrates the use of the \cmd{\contcaption}
17340 command. The table\index{table} was produced from the following code.
17341 \begin{lcode}
17342 \begin{table}
17343 \centering
17344 \caption{A multi-part table} \label{tab:m}
17345 \begin{tabular}{lc} \toprule
17346 just a single line & 1 \\ \bottomrule
17347 \end{tabular}
17348 \end{table}
17349
17350 \begin{table}
17351 \centering
17352 \contcaption{Continued}
17353 \begin{tabular}{lc} \toprule
17354 just a single line & 2 \\ \bottomrule
17355 \end{tabular}
17356 \end{table}
17357
17358 \begin{table}
17359 \centering
17360 \contcaption{Concluded}
17361 \begin{tabular}{lc} \toprule
17362 just a single line & 3 \\ \bottomrule
17363 \end{tabular}
17364 \end{table}
17365 \end{lcode}
17366
17367 \begin{shadetable}
17368 % \centering
17369 \caption{A multi-part table} \label{tab:m}
17370 \begin{tabular}{lc} \toprule
17371 just a single line & 1 \\ \bottomrule
17372 \end{tabular}
17373 \end{shadetable}
17374
17375 \begin{shadetable}
17376 % \centering
17377 \contcaption{Continued}
17378 \begin{tabular}{lc} \toprule
17379 just a single line & 2 \\ \bottomrule
17380 \end{tabular}
17381 \end{shadetable}
17382
17383 \begin{shadetable}
17384 % \centering
17385 \contcaption{Concluded}
17386 \begin{tabular}{lc} \toprule
17387 just a single line & 3 \\ \bottomrule
17388 \end{tabular}
17389 \end{shadetable}
17390
17391 \index{caption!continued|)}%|
17392
17393 \index{legend}
17394 \index{caption!anonymous|(}%|
17395
17396 \begin{syntax}
17397 \cmd{\legend}\marg{text} \\
17398 \end{syntax}
17399 \glossary(legend)%
17400 {\cs{legend}\marg{text}}%
17401 {A legend (an anonymous caption).}
17402 The \cmd{\legend} command is intended to be used to put an
17403 anonymous caption, or legend\index{legend} into a float\index{float}
17404 environment, but may be used anywhere.
17405
17406 \begin{shadetable}
17407 % \centering
17408 \caption{Another table} \label{tab:legend}
17409 \begin{tabular}{lc} \toprule
17410 A legendary table & 5 \\
17411 with two lines & 6 \\ \bottomrule
17412 \end{tabular}
17413 \legend{The legend}
17414 \end{shadetable}
17415
17416 For example, the following code was used to produce the two-line
17417 \tref{tab:legend}. The \cmd{\legend} command can be used within a
17418 float\index{float}
17419 independently of any \cmd{\caption} command.
17420 \begin{lcode}
17421 \begin{table}
17422 \centering
17423 \caption{Another table} \label{tab:legend}
17424 \begin{tabular}{lc} \toprule
17425 A legendary table & 5 \\
17426 with two lines & 6 \\ \bottomrule
17427 \end{tabular}
17428 \legend{The legend}
17429 \end{table}
17430 \end{lcode}
17431
17432 \marginpar{\definecolor{shadecolor}{gray}{0.75}\begin{shaded}\legend{LEGEND}
17433 This is a marginal note with a legend.\end{shaded}}
17434
17435 Captioned floats\index{float} are usually thought of in terms of the
17436 \Ie{table} and \Ie{figure} environments. There can be other kinds of
17437 float\index{float}.
17438 As perhaps a more interesting example, the following code produces
17439 the titled marginal\index{marginalia} note which should be displayed near here.
17440 \begin{lcode}
17441 \marginpar{\legend{LEGEND}
17442 This is a marginal note with a legend.}
17443 \end{lcode}
17444
17445 %You can even \legend{Legend in running text} use the \cmd{\legend}
17446 %command in running text, as has been done in this sentence,
17447 %but I'm not sure why one might want to do that as \ltx\ already
17448 %provides the \Ie{center} environment.
17449
17450 If you want the legend text to be included\index{legend!in list of}
17451 in the \listofx{}
17452 you can do it like this with the \cmd{\addcontentsline} macro.
17453 \begin{lcode}
17454 \legend{Legend title}
17455 % left justified
17456 \addcontentsline{lot}{table}{Legend title} % or
17457 % indented
17458 \addcontentsline{lot}{table}{\protect\numberline{}Legend title}
17459 \end{lcode}
17460 The first of these forms will align the first line of the legend text
17461 under the normal table\index{table} numbers. The second form will align
17462 the first line of the legend text under the normal \Ie{table} titles.
17463 In either case, second and later lines of a multi-line text will be
17464 aligned under the normal title lines.
17465
17466 \begin{shadetable}
17467 % \centering
17468 \captiontitlefont{\sffamily}
17469 \legend{Legendary table}
17470 \addcontentsline{lot}{table}{Legendary table (toc 1)}
17471 \addcontentsline{lot}{table}{\protect\numberline{}
17472 Legendary table (toc 2)}
17473 \begin{tabular}{lc} \toprule
17474 An anonymous table & 5 \\
17475 with two lines & 6 \\ \bottomrule
17476 \end{tabular}
17477 \end{shadetable}
17478
17479 As an example, the \textsf{Legendary table} is produced by the following code:
17480 \begin{lcode}
17481 \begin{table}
17482 \centering
17483 \captiontitlefont{\sffamily}
17484 \legend{Legendary table}
17485 \addcontentsline{lot}{table}{Legendary table (toc 1)}
17486 \addcontentsline{lot}{table}{\protect\numberline{}
17487 Legendary table (toc 2)}
17488 \begin{tabular}{lc} \toprule
17489 An anonymous table & 5 \\
17490 with two lines & 6 \\ \bottomrule
17491 \end{tabular}
17492 \end{table}
17493 \end{lcode}
17494 Look at the List of Tables to see how the two forms of \cmd{\addcontentsline}
17495 are typeset.
17496
17497
17498 \begin{syntax}
17499 \cmd{\namedlegend}\oarg{short-title}\marg{long-title} \\
17500 \end{syntax}
17501 \glossary(namedlegend)%
17502 {\cs{namedlegend}\oarg{short}\marg{long}}%
17503 {Like \cs{caption} but no number and no \listofx\ entry.}
17504 As a convenience, the \cmd{\namedlegend}\index{legend!named}
17505 command is like the \cmd{\caption} command except that it does not number
17506 the caption and, by default, puts no entry into a \listofx{} file. Like
17507 the \cmd{\caption} command, it picks up the name to be prepended to the
17508 title text from the float\index{float} environment in which it is called (e.g.,
17509 it will use \cmd{\tablename} if called within a \Ie{table} environment). The
17510 following code is the source of the \textit{Named legendary table}.
17511 \begin{lcode}
17512 \begin{table}
17513 \centering
17514 \captionnamefont{\sffamily}
17515 \captiontitlefont{\itshape}
17516 \namedlegend{Named legendary table}
17517 \begin{tabular}{lr} \toprule
17518 seven & VII \\
17519 eight & VIII \\ \bottomrule
17520 \end{tabular}
17521 \end{table}
17522 \end{lcode}
17523
17524 \begin{shadetable}
17525 % \centering
17526 \captionnamefont{\sffamily}
17527 \captiontitlefont{\itshape}
17528 \namedlegend{Named legendary table}
17529 \begin{tabular}{lr} \toprule
17530 seven & VII \\
17531 eight & VIII \\ \bottomrule
17532 \end{tabular}
17533 \end{shadetable}
17534
17535 \begin{syntax}
17536 \cmd{\flegfloat}\marg{name} \\
17537 \cmd{\flegtocfloat}\marg{title} \\
17538 \end{syntax}
17539 \glossary(flegfloat)%
17540 {\cs{flegfloat}\marg{name}}%
17541 {Where \texttt{float} is a float type (e.g. \texttt{table}), defines the \meta{name} used by \cs{namedlegend}.}
17542 \glossary(flegtocfloat)%
17543 {\cs{flegtocfloat}\marg{title}}%
17544 {Where \texttt{float} is a float type (e.g., \texttt{figure}), called by
17545 \cs{namedlegend} to add \meta{title} to a \listofx.}
17546 The macro \cmd{\flegfloat}, where \texttt{float} is the name
17547 of a float\index{float} environment
17548 (e.g., \texttt{figure}) is called by the \cmd{\namedlegend} macro.
17549 It is provided as a hook that defines the \meta{name} to be used as
17550 the name in \cmd{\namedlegend}. Two defaults are provided, \cmd{\flegtable}
17551 and \cmd{\flegfigure} defined as:
17552 \begin{lcode}
17553 \newcommand{\flegtable}{\tablename}
17554 \newcommand{\flegfigure}{\figurename}
17555 \end{lcode}
17556 \glossary(flegtable)%
17557 {\cs{flegtable}}%
17558 {The name for a \cs{legend} in a \texttt{table}.}
17559 \glossary(flegfigure)%
17560 {\cs{flegfigure}}%
17561 {The name for a \cs{legend} in a \texttt{figure}.}
17562 which may be altered via \cmd{\renewcommand} if desired.
17563
17564 The macro \cmd{\flegtocfloat}, where again \texttt{float} is the name
17565 of a float\index{float} environment
17566 (e.g., \texttt{table}) is also called by the \cmd{\namedlegend} macro.
17567 It is provided as a hook that can be used to add \meta{title} to the \listofx.
17568 Two examplars are provided, \cmd{\flegtocfigure} and \cmd{\flegtoctable}.
17569 By default they are defined to do nothing, and can be changed via
17570 \cmd{\renewcommand}. For instance, one could be changed for
17571 tables\index{table} as:
17572 \begin{lcode}
17573 \renewcommand{\flegtoctable}[1]{
17574 \addcontentsline{lot}{table}{#1}}
17575 \end{lcode}
17576
17577 \index{caption!anonymous|)}%|
17578 \index{caption!outside a float|(}%|
17579
17580 The \cmd{\legend} command produces a plain, unnumbered heading. It can also
17581 be useful sometimes to have named and numbered captions outside
17582 a floating\index{float} environment, perhaps in a \Ie{minipage},
17583 if you want the table\index{table} or picture\index{illustration}
17584 to appear at a precise location in your document.
17585
17586
17587 \index{caption!fixed|(}%|
17588
17589 \begin{syntax}
17590 \cmd{\newfixedcaption}\oarg{capcommand}\marg{command}\marg{float} \\
17591 \cmd{\renewfixedcaption}\oarg{capcommand}\marg{command}\marg{float} \\
17592 \cmd{\providefixedcaption}\oarg{capcommand}\marg{command}\marg{float} \\
17593 \end{syntax}
17594 \glossary(newfixedcaption)%
17595 {\cs{newfixedcaption}\oarg{capcommand}\marg{command}\marg{float}}%
17596 {Defines a captioning command \cs{command} that may used outside the
17597 \meta{float} float as though it was inside it. The \cs{capcommand}
17598 must have been previously defined as a captioning command for \meta{float}.}
17599 \glossary(renewfixedcaption)%
17600 {\cs{renewfixedcaption}\oarg{capcommand}\marg{command}\marg{float}}%
17601 {A `renew' version of \cs{newfixedcaption}.}
17602 \glossary(providefixedcaption)%
17603 {\cs{providefixedcaption}\oarg{capcommand}\marg{command}\marg{float}}%
17604 {A `provide' version of \cs{newfixedcaption}.}
17605 The \cmd{\newfixedcaption} command, and its friends, can be used
17606 to create or modify a captioning \meta{command} that may be used
17607 outside the float\index{float} environment \meta{float}.
17608 Both the environment \meta{float} and a captioning command,
17609 \meta{capcommand}, for that environment must have been defined before
17610 calling \cmd{\newfixedcaption}. Note that \cmd{\namedlegend} can be used
17611 as \meta{capcommand}.
17612 % The \cmd{\renewfixedcaption} and \cmd{\providefixedcaption} commands
17613 % take the same arguments as \cmd{\newfixedcaption}; the three commands
17614 % are analagous to those in the \cmd{\newcommand} family.
17615
17616 For example, to define a new \cs{figcaption} command for captioning pictures
17617 outside the \Ie{figure} environment, do
17618 \begin{lcode}
17619 \newfixedcaption{\figcaption}{figure}
17620 \end{lcode}
17621 The optional \meta{capcommand} argument is the name of the float\index{float}
17622 captioning command that is being aliased. It defaults to \cmd{\caption}.
17623 As an example of where the optional argument is required, if you
17624 want to create a new continuation\index{caption!continued!outside a float}
17625 caption command for non-floating
17626 tables\index{table}, say \cs{ctabcaption}, then do
17627 \begin{lcode}
17628 \newfixedcaption[\contcaption]{\ctabcaption}{table}
17629 \end{lcode}
17630
17631 Captioning commands created by \cmd{\newfixedcaption} will be named and
17632 numbered in the same style as the original \meta{capcommand}, can
17633 be given a \cmd{\label}, and will appear in the appropriate
17634 \listofx. They can also be used within floating\index{float}
17635 environments, but will not use the environment name as a guide to
17636 the caption name or entry into the \listofx. For
17637 example, using \cs{ctabcaption} in a \Ie{figure} environment will still
17638 produce a \textbf{Table\ldots} named caption.
17639
17640 Sometimes captions are required on the
17641 opposite\index{caption!on opposite page} page to a
17642 figure\index{figure}, and a fixed caption can be useful in this context.
17643 For example, if figure\index{figure} captions should be placed on an
17644 otherwise empty page immediately before the actual figure\index{figure},
17645 then this can be accomplished by the following hack:
17646 \begin{lcode}
17647 \newfixedcaption{\figcaption}{figure}
17648 ...
17649 \afterpage{ % fill current page then flush pending floats
17650 \clearpage
17651 \begin{midpage} % vertically center the caption
17652 \figcaption{The caption} % the caption
17653 \end{midpage}
17654 \clearpage
17655 \begin{figure}THE FIGURE, NO CAPTION HERE\end{figure}
17656 \clearpage
17657 } % end of \afterpage
17658 \end{lcode}
17659 Note that the \Lpack{afterpage} package~\cite{AFTERPAGE} is needed,
17660 which is part of the required tools bundle.
17661 The \Lpack{midpage} package supplies the \verb?midpage?
17662 environment, which can be simply defined as:
17663 \begin{lcode}
17664 \newenvironment{midpage}{\vspace*{\fill}}{\vspace*{\fill}}
17665 \end{lcode}
17666 The code, in particular the use of \cmd{\clearpage}, might need
17667 adjusting\index{start new page} to meet your particular requirements.
17668 \begin{itemize}
17669 \item \cmd{\clearpage} gets you to the next page, which may be odd or even.
17670 \item \cmd{\cleardoublepage} gets you to the next odd-numbered page.
17671 \item \cmd{\cleartoevenpage} ensures that you get to the next
17672 even-numbered page.
17673 \end{itemize}
17674
17675 As a word of warning, if you mix both floats and fixed environments
17676 with the same kind of caption you have to ensure that they get printed
17677 in the correct order in the final document. If you do not do this, then
17678 the \listofx\ captions will come out in the wrong order (the lists are
17679 ordered according the
17680 page number in the typeset document, \emph{not} your source input order).
17681
17682
17683 \index{caption!fixed|)}%|
17684
17685 \index{caption!outside a float|)}%|
17686
17687 \section{Bilingual captions}
17688
17689 \index{caption!bilingual|(}%|
17690 \index{bilingual captions|(}%|
17691
17692 Some documents require bilingual (or more) captions. The class
17693 provides a set of commands for bilingual captions. Extensions to the
17694 set, perhaps to support trilingual captioning, are left as an exercise
17695 for the document author.
17696 Essentially, the bilingual commands call the \cmd{\caption}
17697 command twice, once for each language.
17698
17699 Several commands for bilingual captions are provided. They all produce
17700 the same appearance in the text but differ in what they put into
17701 the \listofx.
17702
17703 \begin{syntax}
17704 \cmd{\bitwonumcaption}\oarg{label}\marg{short1}\marg{long1}\% \\
17705 \marg{NAME}\marg{short2}\marg{long2} \\
17706 \cmd{\bionenumcaption}\oarg{label}\marg{short1}\marg{long1}\% \\
17707 \marg{NAME}\marg{short2}\marg{long2} \\
17708 \end{syntax}
17709 \glossary(bitwonumcaption)%
17710 {\cs{bitwonumcaption}\oarg{label}\marg{short1}\marg{long1}\marg{NAME}\marg{short2}\marg{long2}}%
17711 {A bilingual caption with both captions numbered in the float and in the \listofx.}
17712 \glossary(bionenumcaption)%
17713 {\cs{bionenumcaption}\oarg{label}\marg{short1}\marg{long1}\marg{NAME}\marg{short2}\marg{long2}}%
17714 {A bilingual caption with both captions numbered in the float but only the first in the \listofx.}
17715
17716 Bilingual captions can be typeset by the \cmd{\bitwonumcaption}
17717 command which has six arguments.
17718 The first, optional argument \meta{label}, is the name of a label, if
17719 required.
17720 \meta{short1} and \meta{long1} are the short (i.e., equivalent
17721 to the optional argument
17722 to the \cmd{\caption} command) and long caption texts for
17723 the main language of the document. The value of the \meta{NAME} argument
17724 is used as the caption name for the second language caption, while
17725 \meta{short2} and \meta{long2} are the short and long caption texts
17726 for the second language. For example, if the main and secondary languages
17727 are English and German and a figure\index{figure} is being captioned:
17728 \begin{lcode}
17729 \bitwonumcaption{Short}{Long}{Bild}{Kurz}{Lang}
17730 \end{lcode}
17731 If the short title text(s) is not required, then leave the appropriate
17732 argument(s) either empty or as one or more spaces, like:
17733 \begin{lcode}
17734 \bitwonumcaption[fig:bi1]{}{Long}{Bild}{ }{Lang}
17735 \end{lcode}
17736 Both language texts are entered into the
17737 appropriate\index{caption!bilingual!in list of} \listofx,
17738 and both texts are numbered.
17739
17740 \fref{fig:bi1}, typeset from the following code, is an example.
17741 \begin{lcode}
17742 \begin{figure}
17743 \centering
17744 EXAMPLE FIGURE WITH BITWONUMCAPTION
17745 \bitwonumcaption[fig:bi1]%
17746 {}{Long \cs{bitwonumcaption}}%
17747 {Bild}{ }{Lang \cs{bitwonumcaption}}
17748 \end{figure}
17749 \end{lcode}
17750
17751 \begin{shadefigure}
17752 % \centering
17753 EXAMPLE FIGURE WITH BITWONUMCAPTION
17754 \bitwonumcaption[fig:bi1]{}{Long \cs{bitwonumcaption}}{Bild}{ }{Lang \cs{bitwonumcaption}}
17755 \end{shadefigure}
17756
17757 Both \cmd{\bionenumcaption} and \cmd{\bitwonumcaption} take the same
17758 arguments.
17759 The difference between the two commands is that \cmd{\bionenumcaption} does
17760 not number the second language text in the \listofx.
17761 \fref{fig:bi3}, typeset from the following, is an example of this.
17762 \begin{lcode}
17763 \begin{figure}
17764 \centering
17765 EXAMPLE FIGURE WITH BIONENUMCAPTION
17766 \bionenumcaption[fig:bi3]%
17767 {}{Long English \cs{bionenumcaption}}%
17768 {Bild}{ }{Lang Deutsch \cs{bionenumcaption}}
17769 \end{figure}
17770 \end{lcode}
17771
17772 \begin{shadefigure}
17773 % \centering
17774 EXAMPLE FIGURE WITH BIONENUMCAPTION
17775 \bionenumcaption[fig:bi3]%
17776 {}{Long English \cs{bionenumcaption}}%
17777 {Bild}{ }{Lang Deutsch \cs{bionenumcaption}}
17778 \end{shadefigure}
17779
17780 \begin{syntax}
17781 \cmd{\bicaption}\oarg{label}\marg{short1}\marg{long1}\% \\
17782 \marg{NAME}\marg{long2} \\
17783 \end{syntax}
17784 \glossary(bicaption)%
17785 {\cs{bicaption}\oarg{label}\marg{short1}\marg{long1}\marg{NAME}\marg{long2}}%
17786 {A bilingual caption in a float but only the first added to the \listofx.}
17787
17788 When bilingual captions are typeset via the \cmd{\bicaption}
17789 command the second language text is not put into
17790 the \listofx.
17791 The command takes 5 arguments.
17792 The optional \meta{label} is for a label if required.
17793 \meta{short1} and \meta{long1} are the short and long caption texts for
17794 the main language of the document. The value of the \meta{NAME} argument
17795 is used as the caption name for the second language caption. The last
17796 argument, \meta{long2}, is the caption text
17797 for the second language (which is not put into the \listofx).
17798
17799 For example, if the main and secondary languages are English and German:
17800 \begin{lcode}
17801 \bicaption{Short}{Long}{Bild}{Langlauf}
17802 \end{lcode}
17803 If the short title text is not required, then leave the appropriate
17804 argument either empty or as one or more spaces.
17805
17806 \fref{fig:bi2} is an example of using \cmd{\bicaption} and was
17807 produced by the following code:
17808 \begin{lcode}
17809 \begin{figure}
17810 \centering
17811 EXAMPLE FIGURE WITH A RULED BICAPTION
17812 \precaption{\rule{\linewidth}{0.4pt}\par}
17813 \midbicaption{\precaption{}%
17814 \postcaption{\rule{\linewidth}{0.4pt}}}
17815 \bicaption[fig:bi2]%
17816 {Short English \cs{bicaption}}{Longingly}%
17817 {Bild}{Langlauf}
17818 \end{figure}
17819 \end{lcode}
17820
17821 \begin{shadefigure}
17822 % \centering
17823 EXAMPLE FIGURE WITH A RULED BICAPTION
17824 \precaption{\rule{\linewidth}{0.4pt}\par}
17825 \midbicaption{\precaption{}%
17826 \postcaption{\rule{\linewidth}{0.4pt}}}
17827 \bicaption[fig:bi2]{Short English \cs{bicaption}}{Longingly}%
17828 {Bild}{Langlauf}
17829 \end{shadefigure}
17830
17831 \begin{syntax}
17832 \cmd{\bicontcaption}\marg{long1}\% \\
17833 \marg{NAME}\marg{long2} \\
17834 \end{syntax}
17835 \glossary(bicontcaption)%
17836 {\cs{bicontcaption}\marg{long1}\marg{NAME}\marg{long2}}%
17837 {A continued bilingual caption.}
17838 Bilingual continuation captions can be typeset via the \cmd{\bicontcaption}
17839 command. In this case, neither language text is put into the \listofx.
17840 The command takes 3 arguments.
17841 \meta{long1} is the caption text for
17842 the main language of the document. The value of the \meta{NAME} argument
17843 is used as the caption name for the second language caption. The last
17844 argument, \meta{long2}, is the caption text
17845 for the second language.
17846 For example, if the main and secondary languages
17847 are again English and German:
17848 \begin{lcode}
17849 \bicontcaption{Continued}{Bild}{Fortgefahren}
17850 \end{lcode}
17851
17852 \begin{syntax}
17853 \cmd{\midbicaption}\marg{text} \\
17854 \end{syntax}
17855 \glossary(midbicaption)%
17856 {\cs{midbicaption}\marg{text}}%
17857 {In bilingual captions, \meta{text} is inserted after the first \cs{caption}
17858 and immediately before the second \cs{caption}.}
17859 The bilingual captions are implemented by calling \cmd{\caption} twice,
17860 once for each language. The command \cmd{\midbicaption},
17861 which is similar to the \cmd{\precaption} and \cmd{\postcaption} commands,
17862 is executed
17863 just before calling the second \cmd{\caption}. Among other things,
17864 this can be used to
17865 modify the style\index{caption!bilingual!styling} of the second
17866 caption with respect to the first.
17867 For example, if there is a line above and below normal
17868 captions, it is probably undesirable to have a double line in the
17869 middle of a bilingual caption. So, for bilingual captions the
17870 following may be done within the float\index{float} before the caption:
17871 \begin{lcode}
17872 \precaption{\rule{\linewidth}{0.4pt}\par}
17873 \postcaption{}
17874 \midbicaption{\precaption{}%
17875 \postcaption{\rule{\linewidth}{0.4pt}}}
17876 \end{lcode}
17877 This sets a line before the first of the two captions, then the
17878 \cmd{\midbicaption}\verb?{...}? nulls the pre-caption line and adds
17879 a post-caption line for the second caption. The class initially specifies
17880 \verb?\midbicaption{}?.
17881
17882 \index{bilingual captions|)}%|
17883 \index{caption!bilingual|)}%|
17884
17885 \section{Subcaptions} \label{sec:subcaps}
17886
17887 \index{caption!subcaption|(}%|
17888 \index{figure!subfigure|(}%|
17889 \index{table!subtable|(}%|
17890 \index{float!subfloat|(}%|
17891
17892
17893 %\fxnote[author=dlf,vadj=0em]{This needs to be rewritten as \protect\Lpack{subfigure} is now seen as obsolete, \protect\Lpack{subcaption} is better}
17894
17895 The \Lpack{subcaption} package enables the captioning of sub-figures
17896 within a larger figure\index{figure}, and similarly for
17897 tables\index{table}.\footnote{It works nicely with the \Lpack{caption}
17898 package.} The \Lpack{subcaption} package may be used with the class,
17899 or you can use the class commands described below.
17900
17901 \fancybreak{}
17902
17903 The class commands can only be used inside a float environment for
17904 which a subfloat\footnote{See \Sref{sec:multfloats}.} has been
17905 specified via \cmd{\newsubfloat}.
17906
17907 \begin{syntax}
17908 \cmd{\subcaption}\oarg{list-entry}\marg{subtitle} \\
17909 \end{syntax}
17910 \glossary(subcaption)%
17911 {\cs{subcaption}\oarg{list-entry}\marg{subtitle}}%
17912 {Analagous to \cs{caption} but for an identified subcaption within a float.}
17913 The \cmd{\subcaption} command is similar to the \cmd{\caption} command
17914 and can only be used inside a float environment.
17915 It typesets an identified \meta{subtitle}, where the identification
17916 is an alphabetic character enclosed in parentheses. If the optional
17917 \meta{list-entry} argument is present, \meta{list-entry} is added to
17918 the caption listings for the float. If it is not present, then
17919 \meta{subtitle} is added to the listing.
17920
17921 \begin{caveat}
17922 For technical reasons the \cs{label} has to be placed \emph{inside}
17923 \meta{subtitle}.
17924 \end{caveat}
17925
17926
17927
17928 The \meta{subtitle} is typeset within a box which is the width of
17929 the surrounding environment, so \cmd{\subcaption} should only be used
17930 within a fixed width box of some kind, for example a \Ie{minipage} as shown
17931 below.
17932 \begin{lcode}
17933 \begin{figure}
17934 \centering
17935 \begin{minipage}{0.3\textwidth}
17936 \verb?Some verbatim text?
17937 \subcaption{First text\label{first}}
17938 \end{minipage}
17939 \hfill
17940 \begin{minipage}{0.3\textwidth}
17941 \verb?More verbatim text?
17942 \subcaption{Second text}
17943 \end{minipage}
17944 \caption{Verbatim texts}
17945 \end{figure}
17946 \end{lcode}
17947 As the example code shows, the \cmd{\subcaption} command provides a
17948 means of putting verbatim elements into subfigures.
17949
17950 \begin{syntax}
17951 \cmd{\subtop}\oarg{list-entry}\oarg{subtitle}\marg{contents} \\
17952 \cmd{\subbottom}\oarg{list-entry}\oarg{subtitle}\marg{contents} \\
17953 \end{syntax}
17954 \glossary(subtop)%
17955 {\cs{subtop}\oarg{list-entry}\oarg{subtitle}\marg{contents}}%
17956 {Puts a subcaption identifier, and optionally \meta{subtitle}, on top of \meta{text}.}
17957 \glossary(subbottom)%
17958 {\cs{subbottom}\oarg{list-entry}\oarg{subtitle}\marg{contents}}%
17959 {Puts a subcaption identifier, and optionally \meta{subtitle}, below \meta{text}.}
17960 The command \cmd{\subtop} puts a subcaption identifier on top of
17961 \meta{contents}. If both optional arguments are present, \meta{list-entry}
17962 will be added to the appropriate\index{caption!subcaption!in list of}
17963 listing, and \meta{subtitle} is
17964 placed above the \meta{text} with the identifier. If only one optional
17965 argument is present this is treated as being \meta{subtitle}; the
17966 identifier and \meta{subtitle} are placed above the \meta{text}
17967 and \meta{subtitle} is added to the listing. Regardless of the optional
17968 arguments the identifier is always added to the listing and placed above
17969 the \meta{text}.
17970
17971 The \cmd{\subbottom} command is identical to \cmd{\subtop} except
17972 that the identifier, and potentially the \meta{subtitle}, is placed
17973 below the \meta{text}. Note that verbatim text cannot be used
17974 in the \meta{text} argument to \cmd{\subbottom} or \cmd{\subtop}.
17975
17976 \begin{Changed}[2025/09/24]
17977 The \cs{label} needs to be placed either in \meta{subtitle}, or from
17978 Summer 2025 as part of \meta{contents}.
17979 \end{Changed}
17980
17981 The main caption can be at either the top or the bottom of the float.
17982 The positioning of the main and subcaptions are independent.
17983 For example
17984 \begin{lcode}
17985 \begin{figure}
17986 \subbottom{...} % captioned as (a) below
17987 \subtop{...} % captioned as (b) above
17988 \caption{...}
17989 \end{figure}
17990 \end{lcode}
17991
17992
17993 If a figure that\index{figure} includes subfigures
17994 is itself continued then it may be desirable to
17995 continue the captioning of the subfigures. For example, if Figure~3
17996 has three subfigures, say A, B and C, and Figure~3 is continued then
17997 the subfigures in the continuation should be D, E, etc.
17998 \begin{syntax}
17999 \cmd{\contsubcaption}\oarg{list-entry}\marg{subtitle} \\
18000 \cmd{\contsubtop}\oarg{list-entry}\oarg{subtitle}\marg{text} \\
18001 \cmd{\contsubbottom}\oarg{list-entry}\oarg{subtitle}\marg{text} \\
18002 \cmd{\subconcluded} \\
18003 \end{syntax}
18004 \glossary(contsubcaption)%
18005 {\cs{contsubcaption}\oarg{list-entry}\marg{subtitle}}%
18006 { A continued \cs{subcaption}.}
18007 \glossary(contsubtop)%
18008 {\cs{contsubtop}\oarg{list-entry}\oarg{subtitle}\marg{text}}%
18009 { A continued \cs{subtop}.}
18010 \glossary(contsubbottom)%
18011 {\cs{contsubbottom}\oarg{list-entry}\oarg{subtitle}\marg{text}}%
18012 { A continued \cs{subbottom}.}
18013 \glossary(subconcluded)%
18014 {\cs{subconcluded}}
18015 {Indicates (to \ltx) that a continued subfloat is finished.}
18016
18017 The \cmd{\contsubcaption}, \cmd{\contsuptop} and \cmd{\contsubbottom}
18018 commands are the continued\index{caption!subcaption!continued}
18019 versions of the respective subcaptioning
18020 commands. These continue the subcaption numbering scheme across
18021 (continued) floats. In any event, the main caption can
18022 be at the top or bottom of the float\index{float}.
18023 The \cmd{\subconcluded} command is used to indicate that the continued
18024 (sub) float has been concluded and the numbering
18025 scheme is reinitialized. The command should be placed immediately
18026 before the end of the last continued environment.
18027
18028 \begin{note}
18029 They have the same rules about the placement of \cs{label} as their
18030 normal counterparts.
18031 \end{note}
18032
18033 \goodbreak
18034
18035 For example:
18036 \begin{lcode}
18037 \begin{figure}
18038 \subbottom{...} captioned as (a) below
18039 \subbottom{...} captioned as (b) below
18040 \caption{...}
18041 \end{figure}
18042 \begin{figure}
18043 \contsubtop{...} captioned as (c) above
18044 \contsubtop{...} captioned as (d) above
18045 \contcaption{Concluded}
18046 \subconcluded
18047 \end{figure}
18048 ...
18049 \begin{table}
18050 \caption{...}
18051 \subtop{...} captioned as (a) above
18052 \subbottom{...} captioned as (b) below
18053 \end{table}
18054 \end{lcode}
18055
18056
18057 \begin{syntax}
18058 \cmd{\label}\marg{labstr} \\
18059 \cmd{\subcaptionref}\marg{labstr} \\
18060 \end{syntax}
18061 % \glossary(label)%
18062 % {\cs{label}\parg{bookmark}\marg{labstr}}%
18063 % {Associates \meta{labstr} with the current (section, caption, etc.)
18064 % number and page number. If used inside a subfloat and with the
18065 % \Ppack{hyperref} package the optional \meta{bookmark} (note the parentheses
18066 % not square brackets) is available to specify a hyperref bookmark.}
18067 \glossary(subcaptionref)%
18068 {\cs{subcaptionref}\marg{labstr}}%
18069 {Print the subcaption identifer for a \meta{labstr} labelled subcaption.}
18070 A \cmd{\label} command may be included in the \meta{subtitle} argument
18071 of the subcaptioning\index{caption!subcaption!referencing} commands.
18072 Using the normal \cmd{\ref} macro to
18073 refer to the label will typeset the number of the float (obtained
18074 from a \cmd{\label}ed main \cmd{\caption}) and the subcaption
18075 identifier. If the \cmd{\subcaptionref} macro is used instead of
18076 \cmd{\ref} then only the subcaption identifier is printed.
18077 \begin{Changed}[2025/09/23]
18078 Earlier versions allowed the syntax of
18079 \cs{label}\parg{bookmark}\marg{labstr}, as this is non-standard
18080 syntax regarding labels, this syntax has been removed.
18081 \end{Changed}
18082
18083
18084 % In cases where the \Lpack{hyperref} package is used, the \cmd{\label}
18085 % command when used inside the \meta{subtitle} argument can take an optional
18086 % \meta{bookmark} argument,
18087 % \emph{enclosed in parenthese \emph{not} square brackets},
18088 % which will create a bookmark field of the form `Subfigure 4.7(d)'.
18089
18090 As an example to show the difference between \cmd{\subcaptionref} and
18091 \cmd{\ref}, \fref{fig:twosubfig} and the paragraph immediately
18092 following this one were produced by the code shown below.
18093
18094 Figure \ref{fig:twosubfig} has two subfigures,
18095 namely \ref{sf:1} and \subcaptionref{sf:2}.
18096 \begin{shadefigure}
18097 %\centering
18098 \subbottom[Subfigure 1\label{sf:1}]{\fbox{SUBFIGURE ONE}}
18099 \hfill
18100 \subbottom[Subfigure 2\label{sf:2}]{\fbox{SUBFIGURE TWO}}
18101 \caption{Figure with two subfigures} \label{fig:twosubfig}
18102 \end{shadefigure}
18103 \begin{lcode}
18104 Figure \ref{fig:twosubfig} has two subfigures,
18105 namely \ref{sf:1} and \subcaptionref{sf:2}.
18106 \begin{figure}
18107 \centering
18108 \subbottom[Subfigure 1\label{sf:1}]{\fbox{SUBFIGURE ONE}}
18109 \hfill
18110 \subbottom[Subfigure 2\label{sf:2}]{\fbox{SUBFIGURE TWO}}
18111 \caption{Figure with two subfigures} \label{fig:twosubfig}
18112 \end{figure}
18113 \end{lcode}
18114
18115 \begin{syntax}
18116 \cmd{\tightsubcaptions} \cmd{\loosesubcaptions} \\
18117 \end{syntax}
18118 \glossary(tightsubcaptions)%
18119 {\cs{tightsubcaptions}}%
18120 {Specifies the default vertical space around subcaptions.}
18121 \glossary(loosesubcaptions)%
18122 {\cs{loosesubcaptions}}%
18123 {Specifies extra vertical space around subcaptions.}
18124 As with many other aspects of typesetting the style of
18125 subcaptions\index{caption!subcaption!styling} may
18126 be specified. There is a small amount of vertical space
18127 surrounding a subcaption. More space is used after the \cmd{\loosesubcaptions}
18128 declaration compared to that produced after the default
18129 \cmd{\tightsubcaptions} declaration.
18130
18131 \begin{syntax}
18132 \cmd{\subcaptionsize}\marg{size} \\
18133 \cmd{\subcaptionlabelfont}\marg{fontspec} \\
18134 \cmd{\subcaptionfont}\marg{fontspec} \\
18135 \end{syntax}
18136 \glossary(subcaptionsize)%
18137 {\cs{subcaptionsize}\marg{size}}%
18138 {Font size for subcaptions.}
18139 \glossary(subcaptionlabelfont)%
18140 {\cs{subcaptionlabelfont}\marg{fontspec}}%
18141 {Font for subcaption identifiers.}
18142 \glossary(subcaptionfont)%
18143 {\cs{subcaptionfont}\marg{fontspec}}%
18144 {Font for subcaption titles.}
18145
18146 The size of the font used for subcaptions is specified by
18147 \cmd{\subcaptionsize}, and the fonts for the identifier and text
18148 are specified by \cmd{\subcaptionlabelfont} for the identifier and by
18149 \cmd{\subcaptionfont} for the title text. The defaults are:
18150 \begin{lcode}
18151 \subcaptionsize{\footnotesize}
18152 \subcaptionlabelfont{\normalfont}
18153 \subcaptionfont{\normalfont}
18154 \end{lcode}
18155
18156 \begin{syntax}
18157 \cmd{\subcaptionstyle}\marg{style} \\
18158 \cmd{\raggedleft} \cmd{\centering} \cmd{\raggedright} \cmd{\centerlastline} \\
18159 \end{syntax}
18160 \glossary(subcaptionstyle)%
18161 {\cs{subcaptionstyle}\marg{style}}%
18162 {Paragraph \meta{style} for subcaptions.}
18163 The identifier and title of a subcaption is typeset as a block (i.e.,
18164 non-indented) paragraph by specifying
18165 \begin{lcode}
18166 \subcaptionstyle{}
18167 \end{lcode}
18168 Other styles are available by calling \cmd{\subcaptionstyle}
18169 with a styling \meta{cmd}. Values that you might use are:
18170 \cmd{\centering} for a centered paragraph, \cmd{\raggedleft} or
18171 \cmd{\raggedright} for ragged left or right paragraphs, or
18172 \cmd{\centerlastline} which calls for a block paragraph with the last
18173 line centered.
18174
18175 \begin{syntax}
18176 \cmd{\hangsubcaption} \\
18177 \cmd{\shortsubcaption} \\
18178 \cmd{\normalsubcaption} \\
18179 \end{syntax}
18180 \glossary(hangsubcaption)%
18181 {\cs{hangsubcaption}}%
18182 {The subcaption version of \cs{hangcaption}.}
18183 \glossary(shortsubcaption)%
18184 {\cs{shortsubcaption}}%
18185 {The subcaption version of \cs{shortcaption}.}
18186 \glossary(normalsubcaption)%
18187 {\cs{normalsubcaption}}%
18188 {The subcaption version of \cs{normalcaption}.}
18189 The \cmd{\hangsubcaption} declaration causes subcaptions to be typeset
18190 with the identifier above the title. Following the \cmd{\shortsubcaption}
18191 declaration subcaptions that are less than a full line in length are
18192 typeset left justified instead of centered. The \cmd{\normalsubcaption}
18193 declaration, which is the default, undoes any previous \cmd{\hangsubcaption}
18194 or \cmd{\shortsubcaption} declaration, so that subcaptions are normally
18195 centered.
18196
18197 \index{float!subfloat|)}%|
18198 \index{table!subtable|)}%|
18199 \index{figure!subfigure|)}%|
18200 \index{caption!subcaption|)}%|
18201
18202 \section{Side captions}
18203
18204 \index{caption!side|(}%|
18205
18206 Typically captions are put either above or below the element they
18207 are describing. Sometimes it is desireable to put a caption at the
18208 side of the element instead.
18209
18210
18211 \begin{syntax}
18212 \senv{sidecaption}\oarg{fortoc}\marg{title}\oarg{label} \\
18213 the body of the float \\
18214 \eenv{sidecaption} \\
18215 \end{syntax}
18216 \glossary(sidecaption)%
18217 {\senv{sidecaption}\oarg{fortoc}\marg{title}\oarg{label}}%
18218 {Environment for setting a sidecaption.}%
18219 The \Ie{sidecaption} environment is used for a sidecaption rather than a
18220 macro. The body of the float is put inside the environment. For example:
18221 \begin{lcode}
18222 \begin{figure}
18223 \begin{sidecaption}{An illustration}[fig:ill]
18224 \centering
18225 \includegraphics{...}
18226 \end{sidecaption}
18227 \end{figure}
18228 \end{lcode}
18229 whereby the caption, `Figure N: An illustration', will be placed in the
18230 margin alongside the graphic, and for reference purposes will be given
18231 given the \cs{label} \texttt{fig:ill}.
18232
18233 \begin{syntax}
18234 \lnc{\sidecapwidth} \lnc{\sidecapsep} \\
18235 \cmd{\setsidecaps}\marg{sep}\marg{width} \\
18236 \end{syntax}
18237 \glossary(sidecapwidth)%
18238 {\cs{sidecapwidth}}%
18239 {Length specifying the maximum width of a sidecaption.}%
18240 \glossary(sidecapsep)%
18241 {\cs{sidecapsep}}%
18242 {Length specifying the horizontal separation between a sidecaption and the float.}%
18243 \glossary(setsidecaps)%
18244 {\cs{setsidecaps}\marg{sep}\marg{width}}%
18245 {Sets the lengths \cs{sidecapsep} and \cs{sidcapwidth} to the given
18246 values.}%
18247
18248 The caption is set in a box \lnc{\sidecapwidth} wide (the default is
18249 \lnc{\marginparwidth}) offset \lnc{\sidecapsep} (default \lnc{\marginparsep})
18250 into the margin.
18251 The command \cmd{\setsidcaps} sets the \lnc{\sidecapsep} and
18252 \lnc{\sidecapwidth} to the given values. Changing the marginpar parameters,
18253 for example with \cmd{\setmarginnotes}, will not change the side caption
18254 settings. Note also that \cmd{\checkandfixthelayout}
18255 neither checks nor fixes the side caption parameters.
18256
18257 \begin{syntax}
18258 \cmd{\sidecapmargin}\marg{margin} \\
18259 \piif{ifscapmargleft} \piif{scapmarglefttrue} \piif{scapmargleftfalse} \\
18260 \end{syntax}
18261 \glossary(sidecapmargin)%
18262 {\cs{sidecapmargin}\marg{margin}}%
18263 {Sets the margin for sidecaptions.}%
18264 \glossary(ifsidecapleft)%
18265 {\cs{ifsidecapleft}}%
18266 {\ptrue\ if sidecaptions will be set in the left margin,
18267 otherwise they will be set in the right margin.}%
18268
18269 If the float is a single column float in a twocolumn document then
18270 the caption is
18271 always\footnote{Well, nearly always. See the \cs{overridescapmargin} command
18272 later.}
18273 placed in the adjacent margin, otherwise the \cmd{\sidecapmargin} command
18274 controls the margin where the sidecaption will be placed.
18275 The possible values for \meta{margin} are one of:
18276 \texttt{left},
18277 \texttt{right},
18278 \texttt{inner}, or
18279 \texttt{outer}.
18280 If \texttt{left} or \texttt{right} is specified the caption will go into
18281 the left or right margin. If \texttt{inner} or \texttt{outer} is specified
18282 then in a two sided document the caption will be on different sides of the
18283 typeblock according to whether it is a recto or verso page; in a one sided
18284 document the caption margin is fixed. The left margin is the default.
18285
18286 When the caption is to be set in the left margin, \piif{ifscapmargleft} is
18287 set \ptrue, and for a right margin it is set \pfalse.
18288
18289 \begin{syntax}
18290 \cmd{\setsidecappos}\marg{pos} \\
18291 \end{syntax}
18292 \glossary(setsidcappos)%
18293 {\cs{setsidcappos}\marg{pos}}%
18294 {Declaration of the vertical position of a sidecaption with respect
18295 to the float.}%
18296 By default a sidecaption is vertically centered with respect to the float
18297 it is captioning. This can be altered by using the \cmd{\setsidecappos}
18298 declaration. The allowed values for \meta{pos} are:
18299 \begin{description}
18300 \item[\texttt{t}] --- the top of the caption is aligned
18301 with the top of the float
18302 \item[\texttt{c}] --- (the default) the center of the caption is aligned
18303 with the center of the float
18304 \item[\texttt{b}] --- the bottom of the caption is aligned
18305 with the bottom of the float
18306 \end{description}
18307
18308 The other kinds of simple captions can also be put at the side
18309 of a float. The positioning and styling commands for these are exactly
18310 those for \Ie{sidecaption}.
18311 Bilingual captions, which are not considered to be simple, can only be
18312 placed above or below a float;
18313 no facilities are provided for setting them at the side..
18314
18315 \begin{syntax}
18316 \senv{sidecontcaption}\marg{title}\oarg{label} \\
18317 the body of the float \\
18318 \eenv{sidecontcaption} \\
18319 \end{syntax}
18320 \glossary(sidecontcaption)%
18321 {\senv{sidecontcaption}\marg{title}\oarg{label}}%
18322 {Environment for setting a continued sidecaption.}%
18323 Sidecaptions may be continued with the \Ie{sidecontcaption} environment.
18324
18325 \begin{syntax}
18326 \senv{sidenamedlegend}\oarg{fortoc}\marg{title} \\
18327 the body of the float \\
18328 \eenv{sidenamedlegend} \\
18329 \end{syntax}
18330 \glossary(sidenamedlegend)%
18331 {\senv{sidenamedlegend}\marg{title}\oarg{label}}%
18332 {Environment for setting a named legend kind of sidecaption.}%
18333 Named legends may be set at the side with the \Ie{sidenamedlegend} environment.
18334
18335 \begin{syntax}
18336 \senv{sidelegend}\marg{title} \\
18337 the body of the float \\
18338 \eenv{sidelegend} \\
18339 \end{syntax}
18340 \glossary(sidelegend)%
18341 {\senv{sidelegend}\marg{title}\oarg{label}}%
18342 {Environment for setting a legend kind of sidecaption.}%
18343 Legends may be set at the side with the \Ie{sidelegend} environment.
18344
18345 \fancybreak{}
18346
18347 \textbf{Caveat}: Note that the \texttt{side...} envs expect the body
18348 of the float to be \emph{taller} than the typeset caption/legend. In
18349 case you write a long caption/legend for a short float, you may want
18350 to visit this answer:
18351 \url{http://tex.stackexchange.com/a/228412/3929}.
18352
18353
18354 \subsection{Tweaks}
18355
18356 \begin{syntax}
18357 \cmd{\sidecapstyle} \\
18358 \end{syntax}
18359 \glossary(sidecapstyle)%
18360 {\cs{sidecapstyle}}%
18361 {Style settings for a sidecaption.}%
18362 Just before the caption is set, the \cmd{\sidecapstyle} command is called.
18363 This may be used to set the styling for the particular caption. By default
18364 it sets captions that are in the left margin raggedleft, and those
18365 that are in the right margin are set raggedright. The default definition
18366 is:
18367 %\begin{lcode}
18368 \begin{shadecode}
18369 \newcommand*{\sidecapstyle}{%
18370 %% \captionnamefont{\bfseries}
18371 \ifscapmargleft
18372 \captionstyle{\raggedleft}%
18373 \else
18374 \captionstyle{\raggedright}%
18375 \fi}
18376 \end{shadecode}
18377 %\end{lcode}
18378 You can change the command to suit your purposes; for example, uncommenting
18379 the \cmd{\captionnamefont} line would result in the caption's float name being
18380 set in a bold font.
18381
18382 \begin{syntax}
18383 \cmd{\overridescapmargin}\marg{margin} \\
18384 \lnc{\sidecapraise} \\
18385 \end{syntax}
18386 \glossary(overridescapmargin)%
18387 {\cs{overridescapmargin}\marg{margin}}%
18388 {A one-time override of \cs{sidecapmargin}.}%
18389 \glossary(sidecapraise)%
18390 {\cs{sidecapraise}}%
18391 {Vertical distance added to the default vertical placement of a sidecaption.}%
18392 Sometimes the caption may not be placed exactly where you want it --- it
18393 may be in the wrong margin or at the wrong height.
18394
18395 The command \cmd{\overridescapmargin} will force the following caption into
18396 the \meta{margin} you specify which can only be \texttt{left} or
18397 \texttt{right}. In a twosided document where \cmd{\sidecapmargin}
18398 is \texttt{inner} or \texttt{outer} and the caption goes in the wrong margin,
18399 it is likely that the declaration \piif{strictpagecheck} will solve
18400 the problem. The wrong margin might be chosen in a twocolumn document
18401 where the float is in the second column; use
18402 \begin{lcode}
18403 \overridescapmargin{right}
18404 \end{lcode}
18405 to fix this.
18406
18407 The caption may not be at quite the height you want with respect to the
18408 float. The caption will be raised by the length \lnc{\sidecapraise}
18409 in addition to the calculated movement (or lowered if \lnc{\sidecapraise}
18410 is negative).
18411
18412 \begin{syntax}
18413 \cmd{\sidecapfloatwidth}\marg{length} \\
18414 \end{syntax}
18415 \glossary(sidecapfloatwidth)%
18416 {\cs{sidecapfloatwidth}\marg{length}}%
18417 {Macro holding the width of a float with a sidecaption.}%
18418
18419 The float is set in a \Ie{minipage} with width \cmd{sidecapfloatwidth},
18420 whose default definition is
18421 \begin{lcode}
18422 \newcommand*{\sidecapfloatwidth}{\linewidth}
18423 \end{lcode}
18424 That is, the normal width is the same as the current \lnc{\linewidth}.
18425 For a narrow table, say, you may want to reduce this, for example to
18426 half by
18427 \begin{lcode}
18428 \renewcommand*{\sidecapfloatwidth}{0.5\linewidth}
18429 \end{lcode}
18430 Note that \cmd{\sidecapfloatwidth} is a macro, not a length,
18431 so it must be altered by using a \cmd{\renewcommand*},
18432 \emph{not} by \cmd{\setlength}.
18433
18434 If you do reduce the \cmd{\sidecapfloatwidth} you may notice that the
18435 sidecaption is actually placed a distance \lnc{\sidecapsep} with respect
18436 to the float's \Ie{minipage}, not with respect to the text block.
18437
18438 \newlength{\mylength}
18439 \setlength{\mylength}{\linewidth}
18440 \addtolength{\mylength}{-\sidecapsep}
18441 \addtolength{\mylength}{-\sidecapwidth}
18442 \begin{shadetable}
18443 \sidecapmargin{left}%
18444 \renewcommand*{\sidecapfloatwidth}{\mylength}%
18445 \raggedleft
18446 \begin{sidecaption}{%
18447 Permitted arguments for some sidecaption related commands}[scap:one]
18448 \centering
18449 % \begin{tabular}{ccc} \toprule
18450 % \cs{setsidecappos} & \cs{sidecapmargin} & \cs{overridescapmargin} \\ \midrule
18451 % \texttt{t} & \texttt{left} & \texttt{left} \\
18452 % \texttt{c} & \texttt{right} & \texttt{right} \\
18453 % \texttt{b} & \texttt{inner} & \\
18454 % & \texttt{outer} & \\ \bottomrule
18455 % \end{tabular}
18456 \begin{tabular}{cc} \toprule
18457 \cs{sidecapmargin} & \cs{overridescapmargin} \\ \midrule
18458 \texttt{left} & \texttt{left} \\
18459 \texttt{right} & \texttt{right} \\
18460 \texttt{inner} & \\
18461 \texttt{outer} & \\ \bottomrule
18462 \end{tabular}
18463 \end{sidecaption}
18464 \end{shadetable}
18465
18466 \tref{scap:one} was created by the following code.
18467 %\begin{lcode}
18468 \begin{shadecode}
18469 \newlength{\mylength}
18470 \setlength{\mylength}{\linewidth}
18471 \addtolength{\mylength}{-\sidecapsep}
18472 \addtolength{\mylength}{-\sidecapwidth}
18473 \begin{table}
18474 \sidecapmargin{left}%
18475 \renewcommand*{\sidecapfloatwidth}{\mylength}%
18476 \raggedleft
18477 \begin{sidecaption}{%
18478 Permitted arguments for some sidecaption related commands}[scap:one]
18479 \centering
18480 \begin{tabular}{cc} \toprule
18481 \cs{sidecapmargin} & \cs{overridescapmargin} \\ \midrule
18482 \texttt{left} & \texttt{left} \\
18483 \texttt{right} & \texttt{right} \\
18484 \texttt{inner} & \\
18485 \texttt{outer} & \\ \bottomrule
18486 \end{tabular}
18487 \end{sidecaption}
18488 \end{table}
18489 \end{shadecode}
18490 %\end{lcode}
18491
18492 The calculations on the \cs{mylength} length are so that the sidecaption
18493 and float will just fit inside the typeblock.
18494
18495 Note that the \cmd{\raggedleft} command before the \Ie{sidecaption} environment
18496 makes the float's \Ie{minipage} be placed raggedleft (i.e., moved across to
18497 the right hand edge of the typeblock) while the \cmd{\centering} centers
18498 the \Ie{tabular} within the minipage. You can get a variety of horizontal
18499 placements by judicious use of \cmd{\raggedright}, \cmd{\centering}
18500 and \cmd{\raggedleft} commands. If you do move the float sideways to leave
18501 space for the caption make sure that the caption will go to the side you
18502 want. In the example code I `moved' the float to the right so I made
18503 sure that the caption would go on the left by explicitly setting
18504 \begin{lcode}
18505 \sidecapmargin{left}
18506 \end{lcode}
18507
18508 As far as \tx\ is concerned a sidecaption takes no horizontal space. If
18509 you use a sidecaption in a wrapped float from, say, the \Lpack{wrapfig}
18510 package, make sure that the sidecaption gets placed where it won't be
18511 overlaid by the main text.
18512
18513 \index{caption!side|)}%|
18514
18515 \section{How \ltx\ makes captions} \label{sec:ltx}%|
18516
18517 \index{caption!\ltx\ methods|(}%|
18518
18519 This section provides an overview of how \ltx\ creates captions and
18520 gives some examples of how to change the captioning style directly.
18521 The section need not be looked at more than once unless you like
18522 reading \ltx\ code
18523 or you want to make changes to \ltx's style of captioning not supported
18524 by the class.
18525
18526 The \ltx\ kernel provides tools to help in the definition of captions,
18527 but it is the particular class that decides on their format.
18528
18529 \begin{syntax}
18530 \cmd{\caption}\oarg{short}\marg{long} \\
18531 \end{syntax}
18532 \glossary(caption)%
18533 {\cs{caption}\oarg{short}\marg{long}}%
18534 {Typeset a caption with title \meta{long}, and add it, or \meta{short}
18535 instead if given, to a \listofx.}
18536 The kernel (in \file{ltfloat.dtx}) defines the caption command via
18537 \begin{lcode}
18538 \def\caption{%
18539 \refstepcounter\@captype \@dblarg{\@caption\@captype}}
18540 \end{lcode}
18541
18542 \begin{syntax}
18543 \cmd{\@captype} \\
18544 \end{syntax}
18545 \cmd{\@captype} is defined by the code that creates a new float\index{float}
18546 environment and is set to the environment's name (see the code for
18547 \cmd{\@xfloat} in \file{ltfloat.dtx}). For a \Ie{figure} environment,
18548 there is an equivalent to
18549 \begin{lcode}
18550 \def\@captype{figure}
18551 \end{lcode}
18552
18553 \begin{syntax}
18554 \cmd{\@caption}\marg{type}\oarg{short}\marg{long} \\
18555 \end{syntax}
18556 The kernel also provides the \cmd{\@caption} macro as:
18557 \begin{lcode}
18558 \long\def\@caption#1[#2]#3{\par
18559 \addcontentsline{\csname ext@#1\endcsname}{#1}% <-
18560 {\protect\numberline{\csname the#1\endcsname}%
18561 {\ignorespaces #2}}
18562 \begingroup
18563 \@parboxrestore
18564 \if@minipage
18565 \@setminipage
18566 \fi
18567 \normalsize
18568 \@makecaption{\csname fnum@#1\endcsname}% <-
18569 {\ignorespaces #3}\par
18570 \endgroup}
18571 \end{lcode}
18572 where \meta{type} is the name of the environment in which the caption
18573 will be used. Putting these three commands together results in the user's
18574 view of the caption command as \cmd{\caption}\oarg{short}\marg{long}.
18575
18576 It is the responsibilty of the class (or package) which defines
18577 floats\index{float} to provide definitions for \cmd{\ext@type},
18578 \cmd{\fnum@type} and \cmd{\@makecaption} which appear in the
18579 definition of \cmd{\@caption} (in the lines marked \verb?<-? above).
18580
18581 \begin{syntax}
18582 \cmd{\ext@type} \\
18583 \end{syntax}
18584 This macro holds the name of the extension for a \listofx{} file.
18585 For example for the \Ie{figure} float\index{float} environment there is the
18586 definition equivalent to
18587 \begin{lcode}
18588 \newcommand{\ext@figure}{lof}
18589 \end{lcode}
18590
18591 \begin{syntax}
18592 \cmd{\fnum@type} \\
18593 \end{syntax}
18594 This macro is responsible for typesetting the caption number. For example,
18595 for the \Ie{figure} environment there is the definition equivalent to
18596 \begin{lcode}
18597 \newcommand{\fnum@figure}{\figurename~\thefigure}
18598 \end{lcode}
18599
18600 \begin{syntax}
18601 \cmd{\@makecaption}\marg{number}\marg{text} \\
18602 \end{syntax}
18603 The \cmd{\@makecaption} macro, where \meta{number}
18604 is a string such as `Table~5.3' and \meta{text} is the caption text,
18605 performs the typesetting of the caption, and
18606 is defined in the standard classes (in \file{classes.dtx}) as the
18607 equivalent of:
18608 \begin{lcode}
18609 \newcommand{\@makecaption}[2]{
18610 \vskip\abovecaptionskip <- 1
18611 \sbox\@tempboxa{#1: #2} <- 2
18612 \ifdim \wd\@tempboxa >\hsize
18613 #1: #2\par <- 3
18614 \else
18615 \global \@minipagefalse
18616 \hb@xt@\hsize{\hfil\box\@tempboxa\hfil}
18617 \fi
18618 \vskip\belowcaptionskip} <- 4
18619 \end{lcode}
18620
18621 \begin{syntax}
18622 \lnc{\abovecaptionskip}
18623 \lnc{\belowcaptionskip} \\
18624 \end{syntax}
18625 \glossary(abovecaptionskip)%
18626 {\cs{abovecaptionskip}}%
18627 {Vertical space above a caption.}
18628 \glossary(belowcaptionskip)%
18629 {\cs{belowcaptionskip}}%
18630 {Vertical space below a caption.}
18631 Vertical space is added before and after a caption (lines marked 1 and 4
18632 in the code for \cmd{\@makecaption} above) and the amount of space is given
18633 by the lengths \lnc{\abovecaptionskip}\index{caption!space above}
18634 and \lnc{\belowcaptionskip}. The
18635 standard classes set these to 10pt and 0pt respectively. If you want
18636 to change the space before or after a caption, use \cmd{\setlength} to change
18637 the values. In figures\index{figure}, the caption is usually placed below the
18638 illustration\index{illustration}. The actual space between the bottom
18639 of the illustration\index{illustration} and the baseline of the first
18640 line of the caption\index{caption!space above} is
18641 the \lnc{\abovecaptionskip} plus the
18642 \lnc{\parskip} plus the \lnc{\baselineskip}.
18643 If the illustration\index{illustration} is in a \Ie{center} environment
18644 then additional space will be added by the \eenv{center}; it is usually
18645 better to use the \cmd{\centering} command rather than the
18646 \Ie{center} environment.
18647
18648 The actual typesetting of a caption is effectively performed by the code
18649 in lines marked 2 and 3 in the code for \cmd{\@makecaption}; note that
18650 these are where the colon that is typeset after the number is specified.
18651 If you want to
18652 make complex changes to the default captioning style you may have to
18653 create your own version of \cmd{\@caption} using
18654 \cmd{\renewcommand}. On the other hand, many such changes can be achieved
18655 by changing the definition of the
18656 the appropriate \cmd{\fnum@type} command(s). For example, to make the
18657 figure\index{figure} name and number\index{caption!font} bold:
18658 \begin{lcode}
18659 \renewcommand{\fnum@figure}{\textbf{\figurename~\thefigure}}
18660 \end{lcode}
18661
18662 REMEMBER: If you are doing anything involving commands that include
18663 the \idxatincode\texttt{@} character, and it's not in a class or package
18664 file, you have
18665 to do it within a \cmd{\makeatletter} and \cmd{\makeatother} pairing
18666 (\seeatincode).
18667 So,
18668 if you modify the \cmd{\fnum@figure} command anywhere in your document
18669 it has to be done as:
18670 \begin{lcode}
18671 \makeatletter
18672 \renewcommand{\fnum@figure}{......}
18673 \makeatother
18674 \end{lcode}
18675
18676 \makeatletter
18677 \let\oldfnum@figure\fnum@figure
18678 \renewcommand{\fnum@figure}{\textsc{\figurename~\thefigure}}
18679 \makeatother
18680 \begin{shadefigure}
18681 \centering
18682 A THOUSAND WORDS\ldots
18683 \caption{A picture is worth a thousand words}\label{fig:sc}
18684 \end{shadefigure}
18685
18686 As an example, \fref{fig:sc} was created by the following code:
18687 \begin{lcode}
18688 \makeatletter
18689 \renewcommand{\fnum@figure}{\textsc{\figurename~\thefigure}}
18690 \makeatother
18691 \begin{figure}
18692 \centering
18693 A THOUSAND WORDS\ldots
18694 \caption{A picture is worth a thousand words}\label{fig:sc}
18695 \end{figure}
18696 \end{lcode}
18697
18698 As another example, suppose that you needed to typeset the \cmd{\figurename}
18699 and its number in a bold font, replace the
18700 colon\index{caption!delimeter} that normally appears
18701 after the number by a long dash, and typeset the actual title
18702 text\index{caption!font} in
18703 a sans-serif font, as is illustrated by the caption for
18704 \fref{fig:sf}. The following code does this.
18705
18706 \makeatletter
18707 \renewcommand{\fnum@figure}[1]{\textbf{\figurename~\thefigure} --- \sffamily}
18708 \makeatother
18709 \begin{shadefigure}
18710 \centering
18711 ANOTHER THOUSAND WORDS\ldots
18712 \caption{A different kind of figure caption}\label{fig:sf}
18713 \end{shadefigure}
18714
18715 \begin{lcode}
18716 \makeatletter
18717 \renewcommand{\fnum@figure}[1]{\textbf{\figurename~\thefigure}
18718 --- \sffamily}
18719 \makeatother
18720 \begin{figure}
18721 \centering
18722 ANOTHER THOUSAND WORDS\ldots
18723 \caption{A different kind of figure caption}\label{fig:sf}
18724 \end{figure}
18725 \end{lcode}
18726 Perhaps a little description of how this works is in order.
18727 Doing a little bit of \tx's macro processing by hand, the typesetting
18728 lines in \cmd{\@makecaption} (lines 2 and 3) get instantiated like:
18729 \begin{lcode}
18730 \fnum@figure{\figurename~\thefigure}: text
18731 \end{lcode}
18732 Redefining \cmd{\fnum@figure} to take one argument and then not using the
18733 value of the argument essentially gobbles up the colon. Using
18734 \begin{lcode}
18735 \textbf{\figurename~\thefigure}
18736 \end{lcode}
18737 in the definition causes \cmd{\figurename} and the number to be typeset in
18738 a bold font. After this comes the long dash. Finally, putting \cmd{\sffamily}
18739 at the end of the redefinition causes any following text (i.e., the actual
18740 title) to be typeset using the sans-serif font.
18741
18742 If you do modify \cmd{\@makecaption}, then spaces in the definition may be
18743 important; also you must use the comment (\%) character in the same
18744 places as I have done above. Hopefully, though, the class provides the
18745 tools that you need to make most, if not all, of any likely caption styles.
18746
18747 \makeatletter
18748 \let\fnum@figure\oldfnum@figure
18749 \makeatother
18750
18751 \index{caption!\ltx\ methods|)}%|
18752
18753
18754 \section{Footnotes in captions}
18755
18756 \index{caption!footnote|(}%|
18757 \index{footnote!in caption|(}%|
18758
18759 If you want to have a caption with a footnote, think long and hard
18760 as to whether this is really essential. It is not normally considered
18761 to be good typographic practice, and to rub the point in \ltx\ does not
18762 make it necessarily easy to do. However, if you (or your publisher)
18763 insists, read on.
18764
18765 If it is present, the optional argument to \cmd{\caption} is put into
18766 the \listofx\ as appropriate. If the argument is not present, then the
18767 text of the required argument is put into the \listofx. In the first case,
18768 the optional argument is moving, and in the second case the required
18769 argument is moving. The \cmd{\footnote} command\index{footnote!fragile}
18770 is fragile and must be
18771 \cmd{\protect}ed (i.e., \verb?\protect\footnote{}?) if it is used in a moving
18772 argument. If you don't want the footnote to appear in
18773 the \listofx, use a
18774 footnoteless optional argument and a footnoted required argument.
18775
18776 You will probably be surprised if you just do, for example:
18777 \begin{lcode}
18778 \begin{figure}
18779 ...
18780 \caption[For LoF]{For figure\footnote{The footnote}}
18781 \end{figure}
18782 \end{lcode}
18783 because (a) the footnote number may be greater than you thought, and (b)
18784 the footnote text has vanished. This latter is because \ltx\ won't typeset
18785 footnotes\index{footnote!in float} from a float\index{float}.
18786 To get an actual footnote within the float you have to use a minipage,
18787 like:
18788 \begin{lcode}
18789 \begin{figure}
18790 \begin{minipage}{\linewidth}
18791 ...
18792 \caption[For LoF]{For figure\footnote{The footnote}}
18793 \end{minipage}
18794 \end{figure}
18795 \end{lcode}
18796 If you are using the standard classes you may now find that you get two
18797 footnotes for the price of one. Fortunately this will not occur with this
18798 class, nor will an unexpected increase of the footnote number.
18799
18800 When using a minipage as above, the footnote text is typeset at the
18801 bottom of the minipage (i.e., within the float\index{float}).
18802 If you want the footnote text typeset at the bottom of the page,
18803 then you have to use the
18804 \cmd{\footnotemark} and \cmd{\footnotetext} commands like:
18805 \begin{lcode}
18806 \begin{figure}
18807 ...
18808 \caption[For LoF]{For figure\footnotemark}
18809 \end{figure}
18810 \footnotetext{The footnote}
18811 \end{lcode}
18812 This will typeset the argument of the \cmd{\footnotetext} command at the
18813 bottom of the page where you called the command.
18814 Of course, the figure\index{figure} might have floated\index{float} to a
18815 later page, and then it's a matter of some manual fiddling to get everything
18816 on the same page, and possibly to get the footnote
18817 marks\index{footnote!mark} to match correctly with the
18818 footnote\index{footnote!text} text.
18819
18820 At this point, you are on your own.
18821 \index{footnote!in caption|)}%|
18822 \index{caption!footnote|)}%|
18823
18824
18825 % \section{The class versus the caption package (and its friends)}
18826 % \label{sec:class-versus-caption}
18827
18828 % For some, the configurations for captions provided by the class, are
18829 % either a bit too complicated or not complicated enough.
18830
18831 % The \Lpack{caption} package by Alex Sommerfeldt may provide a simpler
18832 % and much more extensive configuration interface for captions. The
18833 % package can be used with the class, but there are a few caveats:
18834 % \begin{enumerate}[(a)]
18835 % \item All of the special configuration macros provided by the class
18836 % will no longer have any effect (\Lpack{caption} overwrites the core,
18837 % and thus our interfaces will have no effect),
18838 % \item \cmd{\abovecaptionskip} will be reset to 10\,pt, and
18839 % \cmd{\belowcaptionskip} to zero. (The class would set both to
18840 % 0.5\cmd{\onelineskip}, so if you need to change these, move the
18841 % change until after \Lpack{caption} has been loaded)
18842 % \end{enumerate}
18843
18844
18845
18846
18847
18848
18849
18850
18851 \index{caption|)}%|
18852
18853
18854 %#% extend
18855 %#% extstart include rows-and-columns.tex
18856
18857 \svnidlong
18858 {$Ignore: $}
18859 {$LastChangedDate: 2025-09-19 16:06:27 +0200 (Fri, 19 Sep 2025) $}
18860 {$LastChangedRevision: 873 $}
18861 {$LastChangedBy: [email protected] $}
18862
18863
18864 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
18865 %%%%%%%%%%%% Original memman
18866
18867 %%%%%%%%%%%%%%% end original memman
18868 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
18869
18870 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
18871 %%%%\DeleteShortVerb{\|}
18872 %%%%\MakeShortVerb{\=}
18873 %%%%\input{tabmanbody} %% rows & columns
18874 %%%% tabmanbody.tex
18875
18876 \chapter{Rows and columns}
18877
18878 The class provides extensions to the standard \Ie{array} and \Ie{tabular}
18879 environments. These are based partly on a merging of the
18880 \Lpack{array}~\cite{ARRAY},
18881 \Lpack{dcolumn}~\cite{DCOLUMN},
18882 \Lpack{delarray}~\cite{DELARRAY},
18883 \Lpack{tabularx}~\cite{TABULARX}, and
18884 \Lpack{booktabs}~\cite{BOOKTABS}
18885 packages.
18886 Much of the material in this chapter strongly reflects the
18887 documentation of these packages.
18888
18889 \begin{note}
18890 As of September 2018: The \Lpack{array}, \Lpack{delarray},
18891 \Lpack{tabularx} and \Lpack{dcolumn} packages are no longer embedded
18892 into the class, but rather being autoloaded from the \LaTeX\
18893 installation.\footnote{As the embedded versions were more or less
18894 carbon copies, it makes much more sense to let the \LaTeX-team
18895 maintain them, than us having to replace the embedded copy each
18896 time they are updated or bug fixed.} As the embededed versions
18897 were just carbon copies,\footnote{With edited error messages.} we
18898 get the same result but just loading the packages, with less
18899 maintenance. Plus these packages are part of the \LaTeX{} core
18900 packages and thus is available in all \LaTeX{} installations.
18901
18902 We have kept the documentation we had written for the manual (and
18903 updated it slightly), but refer to \cite{ARRAY}, \cite{DELARRAY}, \cite{TABULARX} and
18904 \cite{DCOLUMN} for the 100\% up to date documentation.
18905
18906 As of Summer 2023: The \Lpack{booktabs} package is now loaded
18907 instead of embedded. The code was an exact copy.
18908 \end{note}
18909
18910
18911
18912
18913 \fancybreak{}
18914
18915
18916 Additionally, new kinds of tabular environments are also provided.
18917
18918
18919 \section{General}
18920
18921 \begin{syntax}
18922 \cmd{\[} \senv{array}\oarg{pos}\marg{preamble} rows \eenv{array} \cmd{\]} \\
18923 \senv{tabular}\oarg{pos}\marg{preamble} rows \eenv{tabular} \\
18924 \senv{tabular*}\marg{width}\oarg{pos}\marg{preamble} rows \eenv{tabular*} \\
18925 \senv{tabularx}\marg{width}\oarg{pos}\marg{preamble} rows \eenv{tabularx} \\
18926 \end{syntax}
18927 \glossary(array)%
18928 {\senv{array}\oarg{pos}\marg{preamble}}%
18929 {Environment for setting math elements in an array form.}
18930 \glossary(tabular)%
18931 {\senv{tabular}\oarg{pos}\marg{preamble}}%
18932 {Environment for setting text elements in a tabular form.}
18933 \glossary(tabular*)%
18934 {\senv{tabular*}\marg{width}\oarg{pos}\marg{preamble}}%
18935 {Environment for setting text elements in a tabular form within an overall
18936 \meta{width}; intercolumn spacing is adjusted to suit.}
18937 \glossary(tabularx)%
18938 {\senv{tabularx}\marg{width}\oarg{pos}\marg{preamble}}%
18939 {Environment for setting text elements in a tabular form within an overall
18940 \meta{width}; column widths are adjusted to suit.}
18941 The \Ie{array} and \Ie{tabular} environments are traditional and the others
18942 are extensions. The \Ie{array} is for typesetting
18943 math and has to be within a math environment of some kind. The \Ie{tabular}
18944 series are for typesetting ordinary text.
18945
18946 The optional \meta{pos} argument can be one of \texttt{t}, \texttt{c},
18947 or \texttt{b} (the default is \texttt{c}), and controls the vertical position
18948 of the array or tabular; either the \texttt{t}op or the \texttt{c}enter,
18949 or the \texttt{b}ottom is aligned with the baseline.
18950 Each row consists of elements separated by
18951 \&, and finished with \cmd{\\}. There may be as many rows as desired.
18952 The number and style of the columns is specified by the \meta{preamble}.
18953 The width of each column is wide enough to contain its longest entry and
18954 the overall width of the \Ie{array} or \Ie{tabular} is sufficient to contain
18955 all the columns. However, the \Ie{tabular*} and \Ie{tabularx} environments
18956 provide more control over the width through their \meta{width} argument.
18957
18958 \section{The preamble}
18959
18960 You use the \meta{preamble} argument to the array and tabular
18961 environments to specify the number of columns and how you want column
18962 entries to appear. The preamble consists of a sequence of options, which
18963 are listed in \tref{tab:tabpream}.
18964
18965 \begin{table}
18966 \begin{adjustwidth}{-5mm}{-5mm}
18967 %\begin{center}
18968 \centering
18969 \caption{The array and tabular preamble options.} \label{tab:tabpream}
18970 \setlength{\extrarowheight}{1pt}
18971 \begin{tabular}{lp{9cm}} \toprule \texttt{l} & Left adjusted
18972 column.
18973 \\
18974 \texttt{c} & Centered adjusted column.
18975 \\
18976 \texttt{r} & Right adjusted column.
18977 \\
18978 \texttt{p}\marg{width} & Equivalent to
18979 \verb?\parbox[t]?\marg{width}.
18980 \\
18981 \texttt{m}\marg{width} & Defines a column of width \meta{width}.
18982 Every entry will be centered in proportion to the rest of the
18983 line. It is somewhat like \cmd{\parbox}\marg{width}.
18984 \\
18985 \texttt{b}\marg{width} & Coincides with
18986 \verb?\parbox[b]?\marg{width}.
18987 \\
18988 \texttt{>}\marg{decl} & Can be used before an \texttt{l},
18989 \texttt{r}, \texttt{c}, \texttt{p}, \texttt{m} or a \texttt{b}
18990 option. It inserts \meta{decl} directly in front of the entry of
18991 the column.
18992 \\
18993 \texttt{<}\marg{decl} & Can be used after an \texttt{l},
18994 \texttt{r}, \texttt{c}, \verb?p{..}?, \verb?m{..}? or a
18995 \verb?b{..}? option. It inserts \meta{decl} right after the
18996 entry of the column.
18997 \\
18998 \texttt{|} & Inserts a vertical line. The distance between two
18999 columns will be enlarged by the width of the line.
19000 \\
19001 \texttt{@}\marg{decl} & Suppresses inter-column space and
19002 inserts \meta{decl} instead.
19003 \\
19004 \texttt{!}\marg{decl} & Can be used anywhere and corresponds
19005 with the \texttt{|} option. The difference is that \meta{decl}
19006 is inserted instead of a vertical line, so this option doesn't
19007 suppress the normally inserted space between columns in contrast
19008 to \verb?@{...}?.
19009 \\
19010 \texttt{*}\marg{num}\marg{opts} & Equivalent to \meta{num}
19011 copies of \meta{opts}
19012 \\
19013 \texttt{w}\marg{align}\marg{width} & \raggedright\arraybackslash
19014 Here \meta{align} is
19015 one of \texttt{l}, \texttt{c} or \texttt{r}. The construction
19016 corresponds to every cell in the column being formated as
19017 \verb|\makebox|\oarg{width}\oarg{align}\marg{cell}. It will
19018 silently overprint if the contents are wider than \meta{width}.
19019 \\
19020
19021 \texttt{W}\marg{align}\marg{width} & Similar to \texttt{w}, but issues an overfull warning if
19022 the contents is too wide.
19023 \\
19024 \texttt{D}\marg{ssep}\marg{osep}\marg{places} & Column entries aligned
19025 on a `decimal point'
19026 \\
19027 \bottomrule
19028 \end{tabular}
19029 % \end{center}
19030 \end{adjustwidth}
19031 \end{table}
19032
19033 Examples of the options include:
19034 \begin{itemize}
19035 \item A flush left column with bold font can be specified
19036 with \verb?>{\bfseries}l?.
19037 %% Companion, page 106.
19038 %\begin{egsource}{eg:tabcols}
19039 \begin{lcode}
19040 \begin{center}
19041 \begin{tabular}{>{\large}c >{\large\bfseries}l >{\large\itshape}c}
19042 \toprule
19043 A & B & C \\
19044 100 & 10 & 1 \\ \bottomrule
19045 \end{tabular}
19046 \end{center}
19047 \end{lcode}
19048 %\end{egsource}
19049
19050 %\begin{egresult}[Different column styles in a \Pe{tabular}]{eg:tabcols}
19051 \begin{center}
19052 \begin{tabular}{>{\large}c >{\large\bfseries}l >{\large\itshape}c}
19053 \toprule
19054 A & B & C \\
19055 100 & 10 & 1 \\ \bottomrule
19056 \end{tabular}
19057 \end{center}
19058 %\end{egresult}
19059
19060 \item
19061 In columns which have been generated with \texttt{p}, \texttt{m}
19062 or \texttt{b}, the default value of \lnc{\parindent} is
19063 0pt.
19064
19065 %Companion, page 106.
19066
19067 \begin{lcode}
19068 \begin{center}
19069 \begin{tabular}{m{1cm}m{1cm}m{1cm}} \toprule
19070 1 1 1 1 1 1 1 1 1 1 1 1 &
19071 2 2 2 2 2 2 2 2 &
19072 3 3 3 3 \\ \bottomrule
19073 \end{tabular}
19074 \end{center}
19075 \end{lcode}
19076
19077 \begin{center}
19078 \begin{tabular}{m{1cm}m{1cm}m{1cm}} \toprule
19079 1 1 1 1 1 1 1 1 1 1 1 1 &
19080 2 2 2 2 2 2 2 2 &
19081 3 3 3 3 \\ \bottomrule
19082 \end{tabular}
19083 \end{center}
19084
19085 The \lnc{\parindent} for a particular column can be changed with,
19086 for example
19087 \begin{lcode}
19088 >{\setlength{\parindent}{1cm}}p
19089 \end{lcode}
19090
19091 %%Companion, page 107.
19092
19093 \begin{lcode}
19094 \begin{center}
19095 \begin{tabular}{>{\setlength{\parindent}{5mm}}p{2cm} p{2cm}} \toprule
19096 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 &
19097 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 \\ \bottomrule
19098 \end{tabular}
19099 \end{center}
19100 \end{lcode}
19101
19102 \begin{center}
19103 \begin{tabular}{>{\setlength{\parindent}{5mm}}p{2cm} p{2cm}} \toprule
19104 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 &
19105 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 \\ \bottomrule
19106 \end{tabular}
19107 \end{center}
19108
19109 \item
19110 The specification \verb?>{$}c<{$}? generates a column in math
19111 mode in a \Ie{tabular} environment. When used in an \Ie{array}
19112 environment the column is in LR mode (because the additional
19113 \$'s cancel the existing \$'s).
19114 \item
19115 Using \verb?c!{\hspace{1cm}}c? you get space between two
19116 columns which is enlarged by one centimeter, while
19117 \verb?c@\hspace{1cm}}c? gives you exactly one centimeter
19118 space between two columns.
19119 \item Elsewhere reasons are given why you should not use vertical
19120 lines (e.g., the \texttt{|} option) in tables. Any examples
19121 that use vertical lines are for illustrative purposes only where
19122 it is advantageous to denote column boundaries, for example
19123 to show different spacing effects.
19124 \end{itemize}
19125
19126 \newpage
19127
19128 \subsection{D column specifiers} \label{sec:dcolumns}
19129
19130 \begin{recommended}
19131 As an alternative to the \texttt{D} column (through using the
19132 \Lpack{dcolumn} package), you can use the \Lpack{siunitx} package
19133 which have the added bonus of many more configuration and
19134 formatting features. See \cite{SIUNITX} for details.
19135 \end{recommended}
19136
19137
19138
19139 In financial tables dealing with pounds
19140 and pence or dollars and cents, column entries
19141 should be aligned on the separator between the numbers. The \texttt{D}
19142 column specifier is provided for columns which are to be aligned on
19143 a `decimal point'. The specifier takes three arguments.
19144 \begin{syntax}
19145 \texttt{D}\marg{ssep}\marg{osep}\marg{places} \\
19146 \end{syntax}
19147 \begin{itemize}
19148 \item[\meta{ssep}] is the single character which is used as the
19149 separator in the source \texttt{.tex} file. Thus it will usually
19150 be `\texttt{.}' or `\texttt{,}'.
19151
19152 \item[\meta{osep}] is the separator in the output, this may
19153 be the same as the first argument, but may be any math-mode
19154 expression, such as \cmd{\cdot}. A \texttt{D} column
19155 always uses math mode for the digits as well as the separator.
19156
19157 \item[\meta{places}] should be the maximum number of decimal places
19158 in the column (but see below for more on this).
19159 If this is negative, any number of decimal places can
19160 be used in the column, and all entries will be centred on
19161 (the leading edge of) the
19162 separator. Note that this can cause a column to be too wide; for instance,
19163 compare the first two columns in the example below.
19164 \end{itemize}
19165
19166 Here are some example specifications which, for convenience, employ
19167 the \cmd{\newcolumntype} macro described later.
19168
19169 \begin{lcode}
19170 \newcolumntype{d}[1]{D{.}{\cdot}{#1}}
19171 \end{lcode}
19172 This defines \texttt{d} to be a column specifier taking a single argument
19173 specifying the number of decimal places,
19174 and the \file{.tex} file should use `\texttt{.}' as the separator, with
19175 \cmd{\cdot} ($\cdot$) being used in the output.
19176
19177 \begin{lcode}
19178 \newcolumntype{.}{D{.}{.}{-1}}
19179 \end{lcode}
19180 The result of this is that `\texttt{.}' specifies a column of entries to
19181 be centered on the~`$.$'.
19182
19183 \begin{lcode}
19184 \newcolumntype{,}{D{,}{,}{2}}
19185 \end{lcode}
19186 And the result of this is that `\texttt{,}' specifies a column of
19187 entries with at most two decimal places after a~`$,$'.
19188
19189 \newcolumntype{d}[1]{D{.}{\cdot}{#1}}
19190 \newcolumntype{.}{D{.}{.}{-1}}
19191 \newcolumntype{,}{D{,}{,}{2}}
19192
19193 The following table is typeset from this code:
19194 \begin{lcode}
19195 \begin{center}
19196 \begin{tabular}{|d{-1}|d{2}|.|,|}
19197 1.2 & 1.2 &1.2 &1,2 \\
19198 1.23 & 1.23 &12.5 &300,2 \\
19199 1121.2& 1121.2&861.20 &674,29 \\
19200 184 & 184 &10 &69 \\
19201 .4 & .4 & &,4 \\
19202 & &.4 &
19203 \end{tabular}
19204 \end{center}
19205 \end{lcode}
19206
19207 \begin{center}
19208 \begin{tabular}{|d{-1}|d{2}|.|,|}
19209 1.2 & 1.2 &1.2 &1,2 \\
19210 1.23 & 1.23 &12.5 &300,2 \\
19211 1121.2& 1121.2&861.20 &674,29 \\
19212 184 & 184 &10 &69 \\
19213 .4 & .4 & &,4 \\
19214 & &.4 &
19215 \end{tabular}
19216 \end{center}
19217
19218 Note that the first column, which had a negative \meta{places}
19219 argument is wider than the second column, so that the decimal point
19220 appears in the middle of the column.
19221
19222 The third
19223 \meta{places} argument may specify \emph{both} the number of
19224 digits to the left and to the right of the decimal place. The third
19225 column in the next table below is set with \verb?D{.}{.}{5.1}? and in the
19226 second table, \verb?D{.}{.}{1.1}?, to specify
19227 `five places to the left and one to the right' and `one place to the
19228 left and one to the right' respectively. (You may use `,' or other
19229 characters, not necessarily `.' in this argument.) The column of figures
19230 is then positioned such that a number with the specified numbers of
19231 digits is centred in the column.
19232
19233 Be careful if you have table headings inserted, say, with
19234 \begin{lcode}
19235 \multicolumn{1}{c}{...}
19236 \end{lcode}
19237 to over-ride the \texttt{D} column type, as the overall result may not look
19238 quite as good as you might expect. In the next pair of tabulars the first
19239 column is set with
19240 \begin{lcode}
19241 D{.}{.}{-1}
19242 \end{lcode}
19243 to produce a column centered on the `.', and the second column is set with
19244 \begin{lcode}
19245 D{.}{.}{1}
19246 \end{lcode}
19247 to produce a right aligned column.
19248
19249 %\begin{lcode}
19250 \begin{egsource}{eg:tabwidehead}
19251 \begin{center}\small
19252 \begin{tabular}[t]{|D..{-1}|D..{1}|D..{5.1}|}
19253 \multicolumn{1}{|c|}{head} &
19254 \multicolumn{1}{c|}{head} &
19255 \multicolumn{1}{c|}{head} \\[3pt]
19256 1 & 2 & 3 \\
19257 1.2 & 1.2 & 1.2 \\
19258 11212.2 & 11212.2 & 11212.2 \\
19259 .4 & .4 & .4
19260 \end{tabular}
19261 \hfill
19262 \begin{tabular}[t]{|D..{-1}|D..{1}|D..{1.1}|}
19263 \multicolumn{1}{|c|}{wide heading} &
19264 \multicolumn{1}{c|}{wide heading} &
19265 \multicolumn{1}{c|}{wide heading} \\[3pt]
19266 1 & 2 & 3 \\
19267 1.2 & 1.2 & 1.2 \\
19268 .4 & .4 & .4
19269 \end{tabular}
19270 \end{center}
19271 \end{egsource}
19272 %\end{lcode}
19273
19274 \begin{egresultplain}[Tabular with narrow and wide headings]{eg:tabwidehead}
19275 \begin{center}\small
19276 \begin{tabular}[t]{|D..{-1}|D..{1}|D..{5.1}|}
19277 \multicolumn{1}{|c|}{head}&
19278 \multicolumn{1}{c|}{head}&
19279 \multicolumn{1}{c|}{head}\\[3pt]
19280 1 & 2 & 3 \\
19281 1.2 & 1.2 &1.2 \\
19282 11212.2 & 11212.2 &11212.2 \\
19283 .4 & .4 &.4
19284 \end{tabular}
19285 \hfill
19286 \begin{tabular}[t]{|D..{-1}|D..{1}|D..{1.1}|}
19287 \multicolumn{1}{|c|}{wide heading}&
19288 \multicolumn{1}{c|}{wide heading}&
19289 \multicolumn{1}{c|}{wide heading}\\[3pt]
19290 1 & 2 & 3 \\
19291 1.2 & 1.2 & 1.2 \\
19292 .4 & .4 & .4
19293 \end{tabular}
19294 \end{center}
19295 \end{egresultplain}
19296
19297 In both of these tables the first column is set with \verb?D{.}{.}{-1}?
19298 to produce a column centered on the `\texttt{.}', and the second column is
19299 set with \verb?D{.}{.}{1}? to produce a right aligned column.
19300
19301 The centered (first) column produces columns that are wider than necessary
19302 to fit in the numbers under a heading as it has to ensure that the
19303 decimal point is centered. The right aligned (second) column does not have
19304 this drawback, but under a wide heading a column of small right
19305 aligned figures is somewhat disconcerting.
19306
19307 The notation for the \meta{places} argument also enables columns that
19308 are centred on the mid-point
19309 of the separator, rather than its leading edge; for example
19310 \begin{lcode}
19311 D{+}{\,\pm\,}{3,3}
19312 \end{lcode}
19313 will give a symmetric layout of up to three
19314 digits on either side of a $\pm$ sign.
19315
19316 \subsection{Defining new column specifiers}
19317
19318 You can easily type
19319 \begin{quote}
19320 \verb?>{?\meta{some declarations}\verb?}{c}<{?\meta{some more
19321 declarations}\verb?}?
19322 \end{quote}
19323 when you have a one-off column in a table, but it gets tedious
19324 if you often use columns of this form.
19325 The \cmd{\newcolumntype} lets you define a new column option like, say
19326 \begin{quote}
19327 \verb?\newcolumntype{x}{>{?\meta{some declarations}\verb?}{c}<{?\meta{some
19328 more declarations}\verb?}}?\hspace*{-3cm}
19329 \end{quote}
19330 and you can then use the \texttt{x} column specifier in the preamble wherever
19331 you want a column of this kind.
19332
19333 \begin{syntax}
19334 \cmd{\newcolumntype}\marg{char}\oarg{nargs}\marg{spec} \\
19335 \end{syntax}
19336 \glossary(newcolumntype)
19337 {\cs{newcolumntype}\marg{char}\oarg{nargs}\marg{spec}}%
19338 {Creates a new column type \meta{char} according to \meta{spec} (which has
19339 \meta{nargs} number of arguments).}
19340 The \meta{char} argument is the character that identifies the option
19341 and \meta{spec}
19342 is its specification in terms of the regular preamble options.
19343 The \cmd{\newcolumntype} command is similar to \cmd{\newcommand} ---
19344 \meta{spec} itself can take arguments with the optional \meta{nargs}
19345 argument declaring their number.
19346
19347 For example, it is commonly required to have both math-mode and text
19348 columns in the same alignment. Defining:
19349 \begin{lcode}
19350 \newcolumntype{C}{>{$}c<{$}}
19351 \newcolumntype{L}{>{$}l<{$}}
19352 \newcolumntype{R}{>{$}r<{$}}
19353 \end{lcode}
19354 Then \texttt{C} can be used to get centred text in an
19355 \Ie{array}, or centred math-mode in a \Ie{tabular}. Similarly
19356 \texttt{L} and \texttt{R} are for left- and right-aligned columns.
19357
19358 The \meta{spec} in a \cmd{\newcolumntype} command may refer to any of
19359 the primitive column specifiers (see \tref{tab:tabpream} on
19360 \tref{tab:tabpream}), or to any new letters defined in other
19361 \cmd{\newcolumntype} commands. There is also the \Lpack{collcell}
19362 package, that can pick up the cell contents and send it to a macro. We
19363 refer to the package manual for details.
19364
19365 \begin{syntax}
19366 \cmd{\showcols} \\
19367 \end{syntax}
19368 \glossary(showcols)%
19369 {\cs{showcols}}%
19370 {Writes a list of all \cs{newcolumntype}s to the terminal and log file.}
19371 A list of all the currently active
19372 \cmd{\newcolumntype} definitions is sent to the terminal and log file if
19373 the \cmd{\showcols} command is given.
19374
19375 \subsection{Surprises}
19376
19377 \begin{itemize}
19378 \item A preamble of the form \verb?{wx*{0}{abc}yz}? is treated as \verb?{wxyz}?
19379
19380 \item An incorrect positional argument, such as \texttt{[Q]},
19381 is treated as \texttt{[t]}.
19382
19383 \item A preamble such as \verb?{cc*{2}}? with an error in
19384 a $*$-form will generate an error message
19385 that is not particularly helpful.
19386
19387 \item Error messages generated when parsing the column specification
19388 refer to the preamble argument \emph{after} it has been re-written
19389 by the \cmd{\newcolumntype} system, not to the preamble entered by the
19390 user.
19391
19392 \item Repeated \texttt{<} or \texttt{>} constructions
19393 are allowed. \texttt{>}\marg{decs1}\texttt{>}\marg{decs2}
19394 is treated the same as \texttt{>}\marg{decs2}\marg{decs1}.
19395
19396 The treatment of multiple \texttt{<} or \texttt{>}
19397 declarations may seem strange. Using the obvious ordering
19398 of \texttt{>}\marg{decs1}\marg{decs2} has the disadvantage
19399 of not allowing the settings of a \cmd{\newcolumntype}
19400 defined using these declarations to be overriden.
19401
19402 \item The \cmd{\extracolsep} command may be used in \texttt{@}-expressions
19403 as in standard \ltx, and also in \texttt{!}-expressions.
19404
19405 The use of \cmd{\extracolsep} is subject to the following
19406 two restrictions. There must be at most one \cmd{\extracolsep}
19407 command per \texttt{@}, or \texttt{!} expression and the command must be
19408 directly entered into the \texttt{@} expression, not as part of a macro
19409 definition. Thus
19410 \begin{lcode}
19411 \newcommand{\ef}{\extracolsep{\fill}} ... @{\ef}
19412 \end{lcode}
19413 does not work. However you can use
19414 something like
19415 \begin{lcode}
19416 \newcolumntype{e}{@{\extracolsep{\fill}}
19417 \end{lcode}
19418 instead.
19419
19420 \item As noted by the \ltx\ book~\cite{LAMPORT94}, a
19421 \cmd{\multicolumn}, with the exception of the first column,
19422 consists of the entry and the \emph{following} inter-column
19423 material. This means that in a tabular with the preamble
19424 \verb?|l|l|l|l|? input such as \verb?\multicolumn{2}{|c|}? in
19425 anything other than the first column is incorrect.
19426
19427 In the standard array/tabular implementation this error is not
19428 noticeable as a \verb?|? takes no horizontal space. But in the class the
19429 vertical lines take up their natural width and you will see two lines if
19430 two are specified --- another reason to avoid using \verb?|?.
19431
19432 \end{itemize}
19433
19434 \section{The array environment}
19435
19436 Mathematical arrays are usually produced using the \Ie{array} environment.
19437
19438 \begin{syntax}
19439 \cmd{\[} \senv{array}\oarg{pos}\marg{preamble} rows \eenv{array} \cmd{\]} \\
19440 \cmd{\[} \senv{array}\oarg{pos}\meta{left}\marg{preamble}\meta{right} rows \eenv{array} \cmd{\]} \\
19441 \end{syntax}
19442 Math formula are usually centered in the columns, but a column of
19443 numbers often looks best flush right, or aligned on some distinctive
19444 feature. In the latter case the \texttt{D} column scheme is very handy.
19445 \begin{lcode}
19446 \[ \begin{array}{lcr}
19447 a +b +c & d - e - f & 123 \\
19448 g-h & j k & 45 \\
19449 l & m & 6
19450 \end{array} \]
19451 \end{lcode}
19452
19453 \[ \begin{array}{lcr}
19454 a +b +c & d - e - f & 123 \\
19455 g-h & j k & 45 \\
19456 l & m & 6
19457 \end{array} \]
19458
19459 Arrays are often enclosed in brackets or vertical lines or brackets
19460 or other symbols to
19461 denote math constructs like matrices. The delimeters are often large and have
19462 to be indicated using \cmd{\left} and \cmd{\right} commands.
19463 \begin{lcode}
19464 \[ \left[ \begin{array}{cc}
19465 x_{1} & x_{2} \\
19466 x_{3} & x_{4}
19467 \end{array} \right] \]
19468 \end{lcode}
19469
19470 \[ \left[ \begin{array}{cc}
19471 x_{1} & x_{2} \\
19472 x_{3} & x_{4}
19473 \end{array} \right] \]
19474
19475
19476 The class's \Ie{array} environment is an extension of the standard
19477 environment in that it provides a system of implicit \cmd{\left} \cmd{\right}
19478 pairs. If you want an array surrounded by parentheses, you can enter:
19479 \begin{lcode}
19480 \[ \begin{array}({cc})a&b\\c&d\end{array} \]
19481 \end{lcode}
19482
19483 \[ \begin{array}({cc})a&b\\c&d\end{array} \]
19484
19485 Or, a litle more complex
19486 \begin{lcode}
19487 \[ \begin{array}({c})
19488 \begin{array}|{cc}|
19489 x_{1} & x_{2} \\
19490 x_{3} & x_{4}
19491 \end{array} \\
19492 y \\
19493 z
19494 \end{array} \]
19495 \end{lcode}
19496
19497 \[ \begin{array}({c})
19498 \begin{array}|{cc}|
19499 x_{1} & x_{2} \\
19500 x_{3} & x_{4}
19501 \end{array} \\
19502 y \\
19503 z
19504 \end{array} \]
19505
19506 And you can do things like this:
19507 \begin{lcode}
19508 \[ a = {\begin{array}|{*{20}{c}}|
19509 x-\lambda & 1 & 0 \\
19510 0 & x-\lambda & 1 \\
19511 0 & & x-\lambda \\
19512 \end{array}
19513 }^{2} \]
19514 \end{lcode}
19515
19516 \[ a = {\begin{array}|{*{20}{c}}|
19517 x-\lambda & 1 & 0 \\
19518 0 & x-\lambda & 1 \\
19519 0 & & x-\lambda \\
19520 \end{array}
19521 }^{2} \]
19522
19523
19524
19525 As another example, a construct equivalent to plain \tx's \cmd{\cases}
19526 could be defined by:\\
19527 \begin{lcode}
19528 \[ f(x)=\begin{array}\{{lL}.
19529 0 & if $x=0$\\
19530 \sin(x)/x & otherwise
19531 \end{array} \]
19532 \end{lcode}
19533
19534 \newcolumntype{L}{>{$}l<{$}}
19535 \[ f(x)=\begin{array}\{{lL}.
19536 0 & if $x=0$\\
19537 \sin(x)/x & otherwise
19538 \end{array} \]
19539
19540 Here \texttt{L} denotes a column of left aligned L-R text, as described
19541 earlier.
19542 Note that as the delimiters must always be used in pairs, the `\texttt{.}'
19543 must be used to denote a `null delimiter'.
19544
19545 This feature is especially useful if the \verb?[t]? or \verb?[b]?
19546 arguments are also used. In these cases the result is not equivalent
19547 to surrounding the environment by \cmd{\left}\ldots\cmd{\right}, as
19548 can be seen from the following example:
19549 \begin{lcode}
19550 \begin{array}[t]({c}) 1\\2\\3 \end{array}
19551 \begin{array}[c]({c}) 1\\2\\3 \end{array}
19552 \begin{array}[b]({c}) 1\\2\\3 \end{array}
19553 \quad\mbox{not}\quad
19554 \left(\begin{array}[t]{c} 1\\2\\3 \end{array}\right)
19555 \left(\begin{array}[c]{c} 1\\2\\3 \end{array}\right)
19556 \left(\begin{array}[b]{c} 1\\2\\3 \end{array}\right)
19557 \end{lcode}
19558
19559
19560 \[
19561 \begin{array}[t]({c}) 1\\2\\3 \end{array}
19562 \begin{array}[c]({c}) 1\\2\\3 \end{array}
19563 \begin{array}[b]({c}) 1\\2\\3 \end{array}
19564 \quad\mbox{not}\quad
19565 \left(\begin{array}[t]{c} 1\\2\\3 \end{array}\right)
19566 \left(\begin{array}[c]{c} 1\\2\\3 \end{array}\right)
19567 \left(\begin{array}[b]{c} 1\\2\\3 \end{array}\right)
19568 \]
19569
19570
19571
19572 \section{Tables}
19573
19574 A table is one way of presenting a large amount of information
19575 in a limited space. Even a simple table can presents facts that could
19576 require several wordy paragraphs --- it is not only a picture that is worth
19577 a thousand words.
19578
19579 A table should have at least two columns, otherwise it is really a list,
19580 and many times has more. The leftmost column is often called the
19581 \emph{stub}\index{table!column!stub}
19582 and it typically contains a vertical listing of the information categories
19583 in the other columns. The columns\index{table!column!head}
19584 have \emph{heads} (or \emph{headings}) at
19585 the top indicating the nature of the entries in the column, although
19586 it is not always necessary to provide a head for the stub if the
19587 heading is obvious from the table's caption. Column heads
19588 may include subheadings, often to specify the unit of measurement for numeric
19589 data.
19590
19591 A less simple table may need two or more levels of headings, in which
19592 case \emph{decked heads} are used.
19593 A decked head\index{table!column!decked head} consists of a
19594 \emph{spanner head}\index{table!column!spanner head} and the two or
19595 more column heads it applies to. A horizontal
19596 \emph{spanner rule}\index{table!column!spanner rule} is set between the
19597 spanner and column heads to
19598 show which columns belong to the spanner.
19599
19600 Double decking, and certainly triple decking or more, should be avoided
19601 as it can make it difficult following them down the table. It may be possible
19602 to use a \emph{cut-in head}\index{table!column!cut-in head} instead of
19603 double decking. A cut-in head is
19604 one that cuts across the columns of the table and applies to all the
19605 matter below it. To try and clarify, the parts of a table
19606 are shown diagrammatically in \tref{tab:tabparts}.
19607
19608 \begin{table}
19609 \centering
19610 \caption{Demonstrating the parts of a table} \label{tab:tabparts}
19611 \begin{tabular}{lcccc} \toprule
19612 & & \multicolumn{2}{c}{spanner} & \\ \cmidrule{3-4}
19613 & head & head & head & head \\
19614 stub & subhead & subhead & & \\ \midrule
19615 A & a & b & c & d \\
19616 B & e & f & g & h \\ \cmidrule{2-5}
19617 & \multicolumn{4}{c}{cut-in head} \\ \cmidrule{2-5}
19618 C & i & j & k & l \\
19619 D & m & n & o & p \\ \bottomrule
19620 \end{tabular}
19621 \end{table}
19622
19623 No mention has been made of vertical\index{table!rule!vertical}
19624 rules in a table, and this is
19625 deliberate. There should be no vertical rules in a table. Rules,
19626 if used at all, should be horizontal\index{table!rule!horizontal} only,
19627 and these should be single,
19628 not double or triple. It's not that ink is expensive, or that practically
19629 no typesetting is done by hand any more, it is simply that the visual
19630 clutter should be eliminated.
19631
19632 For example, in \tref{tab:twoviews} which was produced from the code below,
19633 \tref{tab:before} is from the \ltx\ book and
19634 \tref{tab:after} is how Simon Fear~\cite{BOOKTABS} suggests it
19635 should be cleaned up. Notice how both the revised code and the table
19636 are generally simpler than the originals.
19637
19638 \begin{table}
19639 \centering
19640 \caption{Two views of one table} \label{tab:twoviews}
19641 \subtop[Before]{\label{tab:before}%
19642 \begin{tabular}{||l|lr||} \hline
19643 gnats & gram & \$13.65 \\ \cline{2-3}
19644 & each & .01 \\ \hline
19645 gnu & stuffed & 92.50 \\ \cline{1-1} \cline{3-3}
19646 emu & & 33.33 \\ \hline
19647 armadillo & frozen & 8.99 \\ \hline
19648 \end{tabular}}
19649 \hfill
19650 \subtop[After]{\label{tab:after}%
19651 \begin{tabular}{@{}llr@{}} \toprule
19652 \multicolumn{2}{c}{Item} \\ \cmidrule(r){1-2}
19653 Animal & Description & Price (\$)\\ \midrule
19654 Gnat & per gram & 13.65 \\
19655 & each & 0.01 \\
19656 Gnu & stuffed & 92.50 \\
19657 Emu & stuffed & 33.33 \\
19658 Armadillo & frozen & 8.99 \\ \bottomrule
19659 \end{tabular}
19660 }
19661 \end{table}
19662
19663 \begin{lcode}
19664 \begin{table}
19665 \centering
19666 \caption{Two views of one table} \label{tab:twoviews}
19667 \subtop[Before]{\label{tab:before}%
19668 \begin{tabular}{||l|lr||} \hline
19669 gnats & gram & \$13.65 \\ \cline{2-3}
19670 & each & .01 \\ \hline
19671 gnu & stuffed & 92.50 \\ \cline{1-1} \cline{3-3}
19672 emu & & 33.33 \\ \hline
19673 armadillo & frozen & 8.99 \\ \hline
19674 \end{tabular}}
19675 \hfill
19676 \subtop[After]{\label{tab:after}%
19677 \begin{tabular}{@{}llr@{}} \toprule
19678 \multicolumn{2}{c}{Item} \\ \cmidrule(r){1-2}
19679 Animal & Description & Price (\$)\\ \midrule
19680 Gnat & per gram & 13.65 \\
19681 & each & 0.01 \\
19682 Gnu & stuffed & 92.50 \\
19683 Emu & stuffed & 33.33 \\
19684 Armadillo & frozen & 8.99 \\ \bottomrule
19685 \end{tabular}
19686 }
19687 \end{table}
19688 \end{lcode}
19689
19690
19691 Columns of numbers often end with a line giving the total or result.
19692 A horizontal rule\index{table!rule} may be drawn to separate the result
19693 from the rest but
19694 a small amount of white space may do just as well, as in \tref{tab:micawber}.
19695
19696 Some other points are:
19697 \begin{itemize}
19698 \item Put the units in the column heading (not in the body of
19699 the table).
19700 \item Always precede a decimal point by a digit; thus 0.1
19701 \emph{not} just .1.
19702 \item Do not use `ditto' signs or any other such convention to
19703 repeat a previous value. In many circumstances a blank
19704 will serve just as well. If it won't, then repeat the value.
19705 \end{itemize}
19706
19707 Not every table requires all the elements mentioned above.
19708 For instance, in Charles Dicken's \emph{David Copperfield} (1849--1850)
19709 Mr Wilkins Micawber states:
19710 \begin{quote}
19711 `Annual income twenty pounds, annual expenditure nineteen six,
19712 result hapiness.
19713 Annual income twenty pounds, annual expenditure twenty pounds ought and six,
19714 result misery.'
19715 \end{quote}
19716 This can also be represented in tabular
19717 form\footnote{%
19718 But putting Josh Billings' (Henry Wheeler Shaw) corollary:
19719 `Live within your income, even if you have to borrow to do it.'
19720 into tabular form would not work.}
19721 as in \tref{tab:micawber}.
19722
19723 \begin{table}
19724 \centering
19725 \caption{Micawber's law} \label{tab:micawber}
19726 \begin{tabular}{lrr} \toprule
19727 Income & \pounds{20-0-0} & \pounds{20-0-0} \\
19728 Expenditure & \pounds{19-0-6} & \pounds{20-0-6} \\ \addlinespace
19729 Result & happiness & misery \\ \bottomrule
19730 \end{tabular}
19731 \end{table}
19732
19733 Long narrow tables do not look well on the page. In such cases
19734 the table\index{table!half and half} could be set half and half
19735 instead, as in \tref{tab:halfhalf}.
19736
19737 \settowidth{\versewidth}{Relative contents of odd isotopes for heavy elements}
19738 \addtolength{\versewidth}{2mm}
19739 \begin{table}
19740 \begin{adjustwidth}{-5mm}{-5mm}
19741 \centering \addtolength{\cmidrulekern}{0.25em}
19742 \caption{A narrow table split half and half} \label{tab:halfhalf}
19743 \begin{tabularx}{\versewidth}{lclXlcl@{}}
19744 \multicolumn{7}{c}{Relative contents of odd isotopes for heavy elements}\\ \toprule
19745 Element & Z & \multicolumn{1}{c}{$\gamma$} & &
19746 Element & Z & \multicolumn{1}{c}{$\gamma$} \\ \cmidrule{1-3}\cmidrule(r){5-7}
19747 Sm & 62 & 1.480 & & W & 74 & 0.505 \\
19748 Gd & 64 & 0.691 & & Os & 76 & 0.811 \\
19749 Dy & 66 & 0.930 & & Pt & 78 & 1.160 \\
19750 \ldots & & & & \ldots & & \\ \bottomrule
19751 \end{tabularx}
19752 \end{adjustwidth}
19753 \end{table}
19754
19755 \section{Fear's rules}
19756
19757 Simon Fear disapproves of the default \ltx\ table\index{table!rule}
19758 rules and
19759 wrote the \Lpack{booktabs} package~\cite{BOOKTABS} to provide
19760 better horizontal rules. Like many typographers, he abhors vertical rules.
19761 The following is taken almost verbatim from the \Lpack{booktabs}
19762 package which as of Summer 2023 is automatically loaded (was embedded).
19763
19764 \index{table!rule|(}
19765
19766 In the simplest of cases a table begins with a top rule, has
19767 a single row of column headings, then a dividing rule,
19768 and after the columns of data it is finished
19769 off with a final rule. The top and bottom rules are normally
19770 set heavier (i.e., thicker or darker) than any intermediate rules.
19771
19772
19773 \begin{syntax}
19774 \cmd{\toprule}\oarg{width}
19775 \cmd{\bottomrule}\oarg{width}
19776 \lnc{\heavyrulewidth} \\
19777 \cmd{\midrule}\oarg{width}
19778 \lnc{\lightrulewidth} \\
19779 \lnc{\aboverulesep} \lnc{\belowrulesep} \lnc{\doublerulesep} \\
19780 \end{syntax}
19781 \glossary(toprule)%
19782 {\cs{toprule}\oarg{width}}%
19783 {Draws a rule across a tabular, default width \cs{heavyrulewidth}.}
19784 \glossary(bottomrule)%
19785 {\cs{bottomrule}\oarg{width}}%
19786 {Draws a rule across a tabular, default width \cs{heavyrulewidth}.}
19787 \glossary(midrule)%
19788 {\cs{midrule}\oarg{width}}%
19789 {Draws a rule across a tabular, default width \cs{lightrulewidth}.}
19790 \glossary(heavyrulewidth)%
19791 {\cs{heavyrulewidth}}%
19792 {Default width for a heavy tabular rule.}
19793 \glossary(lightrulewidth)%
19794 {\cs{lightrulewidth}}%
19795 {Default width for a light tabular rule.}
19796 \glossary(aboverulesep)%
19797 {\cs{aboverulesep}}%
19798 {Space above a tabular rule.}
19799 \glossary(belowrulesep)%
19800 {\cs{belowrulesep}}%
19801 {Space below a tabular rule.}
19802 \glossary(doublerulesep)%
19803 {\cs{doublerulesep}}%
19804 {Space between adjacent rules in a tabular, or an array.}
19805 All the rule commands here go immediately after the closing
19806 \cmd{\\} of the preceding row (except of course \cmd{\toprule}, which
19807 comes right after the start of the environment). Each rule has an optional
19808 length argument, \meta{width}, which you can use to locally change the default
19809 width of the rule.
19810
19811 \cmd{\toprule} draws a rule (with a default width of \lnc{\heavyrulewidth}),
19812 and \lnc{\belowrulesep} vertical space inserted below it.
19813
19814 \cmd{\midrule} draws a rule (default \lnc{\lightrulewidth} width)
19815 with \lnc{\aboverulesep} space above it and \lnc{\belowrulesep}
19816 below it.
19817
19818
19819 \cmd{\bottomrule} draws a rule with a default width of \lnc{\heavyrulewidth}.
19820 There is \lnc{\aboverulesep} space above it and \lnc{\belowrulesep} space
19821 below it.
19822
19823 If a rule immediately follows another the space between them is
19824 \lnc{\doublerulesep}, but as you are not going to use double rules you
19825 won't be concerned about this.
19826
19827 \begin{syntax}
19828 \cmd{\cmidrule}\oarg{width}\parg{trim}\marg{m--n} \\
19829 \lnc{\cmidrulewidth} \lnc{\cmidrulekern} \\
19830 \end{syntax}
19831 \glossary(cmidrule)%
19832 {\cs{cmidrule}\oarg{width}\parg{trim}\marg{m--n}}%
19833 {Draws a rule, default thickness \cs{cmidrulewidth}, across tabular
19834 columns \meta{m} to \meta{n}; the ends may be \meta{trim}ed by
19835 \cs{cmidrulekern}.}
19836 \glossary(cmidrulewidth)%
19837 {\cs{cmidrulewidth}}%
19838 {Default width for a \cs{cmidrule} tabular rule.}
19839 \glossary(cmidrulekern)
19840 {\cs{cmidrulekern}}
19841 {Trim amount for \cs{cmidrule}.}
19842 Spanner rules do not extend the full width of the table, and the
19843 \cmd{\cmidrule} is provided for that purpose. This draws a rule,
19844 default thickness \lnc{\cmidrulewidth}, across columns \meta{m}
19845 to \meta{n} inclusive (where \meta{m} and \meta{n} are column numbers,
19846 with \meta{m} not greater than \meta{n}).
19847
19848 Generally, this rule
19849 should not come to the full width of the end columns, and this
19850 is especially the case if you have to begin a \cmd{\cmidrule}
19851 straight after the end of another one. You can use the
19852 optional trimming argument commands, which are \verb?(r)?, \verb?(l)? and \verb?(rl)?
19853 or \verb?(lr)?, indicated whether the right and/or left ends of the
19854 rule should be trimmed. Note the exceptional use of parentheses
19855 instead of brackets for this optional argument.
19856
19857
19858 \cmd{\cmidrule} draws a rule from column $m$ to $n$ with a default
19859 thickness of \lnc{\cmidrulewidth}. Adjacent \cmd{\cmidrule}s,
19860 for example
19861 \begin{lcode}
19862 ... \\ \cmidrule{2-3}\cmidrule{5-7}
19863 \end{lcode}
19864 have the same vertical alignment. It is best not to leave any space between
19865 these commands. The space above and below
19866 is normally \lnc{\aboverulesep} and \lnc{\belowrulesep}.
19867
19868 If you are forced into having double spanner rules then you will
19869 reluctantly have
19870 to insert the command \cmd{\morecmidrules} between the commands for
19871 the upper and lower rules. For example:
19872 \begin{lcode}
19873 ... \\ \cmidrule{2-3}\cmidrule{5-7}\morecmidrules\cmidrule{2-3}
19874 \end{lcode}
19875 will draw double rules across columns 2 and 3. You must finish off
19876 the rules for one row before starting the lower set of rules. There
19877 must not be any space surrounding the \cmd{\morecmidrules} macro.
19878 The upper and lower rules are separated by \lnc{\cmidrulesep}.
19879
19880
19881 \begin{syntax}
19882 \cmd{\addlinespace}\oarg{width}
19883 \lnc{\defaultaddspace} \\
19884 \end{syntax}
19885 \glossary(addlinespace)%
19886 {\cs{addlinespace}\marg{width}}%
19887 {Puts extra space, default \cs{defaultaddspace}, between a pair of tabular
19888 rows.}
19889 \glossary(defaultaddspace)%
19890 {\cs{defaultaddspace}}%
19891 {Default space for \cs{addlinespace}.}
19892
19893
19894 Occasionally extra space between certain rows of a table may be helpful;
19895 for example, before the last row if this is a total.
19896 This is simply a matter of inserting \cmd{\addlinespace}
19897 after the \cmd{\\} alignment marker.
19898 You can think
19899 of \cmd{\addlinespace} as being a white rule of width \meta{width}.
19900 The default space is \cmd{\defaultaddspace} which gives rather
19901 less than a whole line space. If another rule follows
19902 the amount of whitespace is increased by \lnc{\doublerulesep}.
19903
19904 \begin{syntax}
19905 \cmd{\specialrule}\marg{width}\marg{abovespace}\marg{belowspace} \\
19906 \end{syntax}
19907 \glossary(specialrule)%
19908 {\cs{specialrule}\marg{width}\marg{abovespace}\marg{belowspace}}%
19909 {Draws a rule with the given parameters across a tabular.}
19910 You can, but should not, generate peculiar spacing between
19911 rules by using \cmd{\specialrule}. The three required arguments are the
19912 width, \meta{width}, of the rule and the spaces above (\meta{abovespace})
19913 and below (\meta{belowspace}). \cmd{\specialrule} ignores a preceding rule
19914 but if there is a following one then \meta{belowspace}
19915 will be increased by \lnc{\doublerulesep}.
19916
19917 The default dimensions are
19918 \begin{quote}
19919 \lnc{\heavyrulewidth} = 0.08em \\
19920 \lnc{\lightrulewidth} = 0.05em \\
19921 \lnc{\cmidrulewidth} = 0.03em \\
19922 \lnc{\belowrulesep} = 0.65ex \\
19923 \lnc{\aboverulesep} = 0.4ex \\
19924 \lnc{\defaultaddspace} = 0.5em \\
19925 \lnc{\cmidrulekern} = 0.25em
19926 \end{quote}
19927 The last of these, \lnc{\cmidrulekern}, is the amount by which a
19928 \cmd{\cmidrule} is trimmed at the ends indicated in the \verb?()?
19929 option. In the construction
19930 \begin{quote}
19931 \verb?\cmidrule(r){1-2}\cmidrule(l){3-4}?
19932 \end{quote}
19933 there is a total of 0.5em separating the two rules. Currently
19934 the only way to get special effects is to reset \lnc{\cmidrulekern}
19935 as appropriate; the amount of trimming is not available as an
19936 argument in the current implementation of \cmd{\cmidrule}.
19937
19938
19939 An example of the commands in use was given by the code to
19940 produce \tref{tab:after} on \pref{tab:after}:
19941 \begin{lcode}
19942 \begin{tabular}{@{}llr@{}} \toprule
19943 \multicolumn{2}{c}{Item} \\ \cmidrule(r){1-2}
19944 Animal & Description & Price (\$)\\ \midrule
19945 Gnat & per gram & 13.65 \\
19946 & each & 0.01 \\
19947 Gnu & stuffed & 92.50 \\
19948 Emu & stuffed & 33.33 \\
19949 Armadillo & frozen & 8.99 \\ \bottomrule
19950 \end{tabular}
19951 \end{lcode}
19952
19953 \index{table!rule|)}
19954
19955 \subsection{Fills}
19956
19957 \index{table!row fill|(}
19958 \index{array!row fill|(}
19959
19960 The rules described previously go between rows. Sometimes it may be
19961 desirable to to put a rule or something similar within a
19962 row.
19963
19964 \begin{syntax}
19965 \cmd{\downbracefill} \cmd{\hrulefill} \cmd{\upbracefill} \\
19966 \end{syntax}
19967 \glossary(downbracefill)%
19968 {\cs{downbracefill}}%
19969 {Fills a tabular column with a down brace.}
19970 \glossary(hrulefill)%
19971 {\cs{hrulefill}}%
19972 {Fills a tabular column with a rule.}
19973 \glossary(upbracefill)%
19974 {\cs{upbracefill}}%
19975 {Fills a tabular column with an up brace.}
19976
19977 Examples of \cmd{\downbracefill}, \cmd{\hrulefill}, and \cmd{\upbracefill}
19978 are illustrated in \tref{tab:fills}, typeset from the code below.
19979 Surprisingly these are
19980 ordinary text commands, not math mode commands.
19981
19982
19983 \begin{lcode}
19984 \begin{table}
19985 \centering
19986 \caption{Example table with fills} \label{tab:fills}
19987 \begin{tabular}{rrrrr}
19988 1 & 2 & 3 & 4 & 5 \\
19989 Q & & fgh & jklm & qwerty \\
19990 v & as & x & y & z \\
19991 g & nnn & \multicolumn{3}{c}{\upbracefill} \\
19992 \multicolumn{3}{c}{\downbracefill} & pq & dgh \\
19993 k & j & t & co & ytrewq \\
19994 1 & 2 & 3 & \multicolumn{2}{c}{\hrulefill}
19995 \end{tabular}
19996 \end{table}
19997 \end{lcode}
19998
19999 \begin{table}
20000 \centering
20001 \caption{Example table with fills} \label{tab:fills}
20002 \begin{tabular}{rrrrr}
20003 1 & 2 & 3 & 4 & 5 \\
20004 Q & & fgh & jklm & qwerty \\
20005 v & as & x & y & z \\
20006 g & nnn & \multicolumn{3}{c}{\upbracefill} \\
20007 \multicolumn{3}{c}{\downbracefill} & pq & dgh \\
20008 k & j & t & co & ytrewq \\
20009 1 & 2 & 3 & \multicolumn{2}{c}{\hrulefill}
20010 \end{tabular}
20011 \end{table}
20012
20013 Here are the same fills, but this time in an \Ie{array} environment.
20014 are shown afterwards. Notice the \texttt{\$}s in the array surrounding
20015 the fills. Normally \verb?$...$? is used to typeset a small
20016 amount of math mode material
20017 in the middle of text. In this case, as the \Ie{array} is already in math mode
20018 the \verb?$...$? are used to typeset a small amount of text material
20019 within math mode.
20020
20021 \begin{lcode}
20022 \begin{displaymath}
20023 \begin{array}{rrrrr}
20024 1 & 2 & 3 & 4 & 5 \\
20025 Q & & fgh & jklm & qwerty \\
20026 v & as & x & y & z \\
20027 g & nnn & \multicolumn{3}{c}{$\upbracefill$} \\
20028 \multicolumn{3}{c}{$\downbracefill$} & pq & dgh \\
20029 k & j & t & co & ytrewq \\
20030 1 & 2 & 3 & \multicolumn{2}{c}{\hrulefill}
20031 \end{array}
20032 \end{displaymath}
20033 \end{lcode}
20034
20035 \begin{displaymath}
20036 \begin{array}{rrrrr}
20037 1 & 2 & 3 & 4 & 5 \\
20038 Q & & fgh & jklm & qwerty \\
20039 v & as & x & y & z \\
20040 g & nnn & \multicolumn{3}{c}{$\upbracefill$} \\
20041 \multicolumn{3}{c}{$\downbracefill$} & pq & dgh \\
20042 k & j & t & co & ytrewq \\
20043 1 & 2 & 3 & \multicolumn{2}{c}{\hrulefill}
20044 \end{array}
20045 \end{displaymath}
20046
20047 You can define your own `fill'. For example:
20048 \begin{lcode}
20049 \newcommand*{\upbracketfill}{%
20050 \vrule height 4pt depth 0pt\hrulefill%
20051 \vrule height 4pt depth 0pt}
20052 \end{lcode}
20053 is a fill that has the appearance of a (horizontal) bracket. It can
20054 be used like this:
20055 \begin{lcode}
20056 \begin{displaymath}
20057 \begin{array}{cccc}
20058 1 & 2 & 3 & 4 \\
20059 a & \multicolumn{2}{c}{\upbracketfill} & d \\
20060 A & B & C & D
20061 \end{array}
20062 \end{displaymath}
20063 \end{lcode}
20064
20065 \newcommand*{\upbracketfill}{%
20066 \vrule height 4pt depth 0pt\hrulefill\vrule height 4pt depth 0pt}
20067
20068 \begin{displaymath}
20069 \begin{array}{cccc}
20070 1 & 2 & 3 & 4 \\
20071 a & \multicolumn{2}{c}{\upbracketfill} & d \\
20072 A & B & C & D
20073 \end{array}
20074 \end{displaymath}
20075
20076 \index{array!row fill|)}
20077 \index{table!row fill|)}
20078
20079 \section{Tabular environments}
20080
20081 \index{tabular|(}
20082
20083 \begin{syntax}
20084 \senv{tabular}\oarg{pos}\marg{format} rows \eenv{tabular} \\
20085 \senv{tabular*}\marg{width}\oarg{pos}\marg{format} rows \eenv{tabular*} \\
20086 \senv{tabularx}\marg{width}\oarg{pos}\marg{format} rows \eenv{tabularx} \\
20087 \end{syntax}
20088
20089 A table created using the \Ie{tabular} environment comes out as
20090 wide as it has to be to accomodate the entries. On the other hand,
20091 both the \Ie{tabular*} and \Ie{tabularx} environments let you specify
20092 the overall width\index{tabular!controlling width}
20093 of the table via the additional \meta{width} atrgument.
20094
20095 The \Ie{tabular*} environment makes any necessary adjustment by altering
20096 the intercolumn\index{tabular!intercolumn space} spaces while the
20097 \Ie{tabularx} environment alters
20098 the column\index{tabular!column width} widths. Those columns that can
20099 be adjusted are noted by
20100 using the letter \texttt{X}\index{tabular!X column} as the column
20101 specifier in the \meta{format}.
20102 Once the correct column widths have been calculated the \texttt{X}
20103 columns are converted to \texttt{p} columns.
20104
20105 \subsection{Examples}
20106
20107 The following code is used for a regular \Ie{tabular}.
20108 \begin{lcode}
20109 \begin{figure}
20110 \centering
20111 \caption{Example of a regular \texttt{tabular}}
20112 \begin{tabular}{|c|p{5.5pc}|c|p{5.5pc}|} \hline
20113 \multicolumn{2}{|c|}{Multicolumn entry!} & THREE & FOUR \\ \hline
20114 one &
20115 \raggedright\arraybackslash The width of this column is fixed
20116 (5.5pc). & three &
20117 \raggedright\arraybackslash Column four will act in the same
20118 way as column two, with the same width.\\
20119 \hline
20120 \end{tabular}
20121 \end{figure}
20122 \end{lcode}
20123
20124 \begin{figure}
20125 \centering
20126 \caption{Example of a regular \texttt{tabular}}
20127 \begin{tabular}{|c|p{5.5pc}|c|p{5.5pc}|} \hline
20128 \multicolumn{2}{|c|}{Multicolumn entry!} & THREE & FOUR \\ \hline
20129 one &
20130 \raggedright\arraybackslash The width of this column is fixed (5.5pc). &
20131 three &
20132 \raggedright\arraybackslash Column four will act in the same way as
20133 column two, with the same width.\\
20134 \hline
20135 \end{tabular}
20136 \end{figure}
20137
20138
20139 The following examples use virtually the same contents, the major
20140 differences are the specifications of the environment.
20141
20142
20143 \begin{figure}
20144 \centering
20145 \caption{Example \texttt{tabularx} and \texttt{tabular*} with widths of 250pt}
20146 \verb?\begin{tabularx}{250pt}{|c|X|c|X|}?
20147
20148 \begin{tabularx}{250pt}{|c|X|c|X|}
20149 \hline
20150 \multicolumn{2}{|c|}{Multicolumn entry!}&
20151 THREE&
20152 FOUR\\
20153 \hline
20154 one&
20155 \raggedright\arraybackslash The width of this column depends on the
20156 width of the table.\footnote{You can use footnotes in a \texttt{tabularx}!}
20157 &
20158 three&
20159 \raggedright\arraybackslash Column four will act in the same way as
20160 column two, with the same width.\\
20161 \hline
20162 \end{tabularx}
20163 \vspace{\onelineskip}
20164
20165 \verb? \begin{tabular*}{250pt}{|c|p{5.5pc}|c|p{5.5pc}|}?
20166
20167 \begin{tabular*}{250pt}{|c|p{5.5pc}|c|p{5.5pc}|}
20168 \hline
20169 \multicolumn{2}{|c|}{Multicolumn entry!}&
20170 THREE&
20171 FOUR\\
20172 \hline
20173 one&
20174 \raggedright\arraybackslash The width of this column is fixed (5.5pc). &
20175 three &
20176 \raggedright\arraybackslash Column four will act in the same way as
20177 column two, with the same width.\\
20178 \hline
20179 \end{tabular*}
20180 \end{figure}
20181
20182 Note that the horizontal rules\index{tabular!rule} extend beyond the
20183 last column.
20184 There are no \texttt{X} columns and the total width required to set
20185 the \Ie{tabular*} is less than the 250pt specified for the width.
20186
20187
20188 Compare the previous narrow \Ie{tabular*} with the next one which is set with
20189 \begin{lcode}
20190 \begin{tabular*}{300pt}%
20191 {|@{\extracolsep{\fill}}c|p{5.5pc}|c|p{5.5pc}|}
20192 \end{lcode}
20193
20194 \begin{figure}
20195 \centering
20196 \caption{Example \texttt{tabularx} and \texttt{tabular*} with widths of 300pt}
20197 \verb?\begin{tabularx}{300pt}{|c|X|c|X|}?
20198
20199 \begin{tabularx}{300pt}{|c|X|c|X|}
20200 \hline
20201 \multicolumn{2}{|c|}{Multicolumn entry!}&
20202 THREE&
20203 FOUR\\
20204 \hline
20205 one&
20206 \raggedright\arraybackslash The width of this column depends on the
20207 width of the table.&
20208 three&
20209 \raggedright\arraybackslash Column four will act in the same way as
20210 column two, with the same width.\\
20211 \hline
20212 \end{tabularx}
20213
20214 \vspace{\onelineskip}
20215 \verb?\begin{tabular*}{300pt}%? \\
20216 \verb? {|@{\extracolsep{\fill}}c|p{5.5pc}|c|p{5.5pc}|}?
20217
20218 \begin{tabular*}{300pt}{|@{\extracolsep{\fill}}c|p{5.5pc}|c|p{5.5pc}|}
20219 \hline
20220 \multicolumn{2}{|c|}{Multicolumn entry!}&
20221 THREE&
20222 FOUR\\
20223 \hline
20224 one&
20225 \raggedright\arraybackslash The width of this column's text is fixed (5.5pc). &
20226 three &
20227 \raggedright\arraybackslash Column four will act in the same way as
20228 column two, with the same width.\\
20229 \hline
20230 \end{tabular*}
20231 \end{figure}
20232
20233
20234
20235 The main differences between the \Ie{tabularx} and \Ie{tabular*}
20236 environments are:
20237 \begin{itemize}
20238 \item \Ie{tabularx} modifies the widths\index{tabular!column width}
20239 of the \emph{columns},
20240 whereas \Ie{tabular*} modifies the widths of the
20241 intercolumn\index{tabular!intercolumn space} \emph{spaces}.
20242 \item \Ie{tabular} and \Ie{tabular*} environments may be
20243 nested with no restriction, however if one \Ie{tabularx}
20244 environment occurs inside another, then the inner one \emph{must} be
20245 enclosed by \verb?{ }?.
20246 \item The body of the \Ie{tabularx} environment is in fact the
20247 argument to a command, and so certain constructions which are not
20248 allowed in command arguments (like \cmd{\verb}) may not be used.\footnote
20249 {Actually, \cs{verb} and \cs{verb*} may be used, but they may
20250 treat spaces incorrectly, and the
20251 argument can not contain an unmatched {\ttfamily\char`\{} or
20252 {\ttfamily\char`\}}, or a {\ttfamily\char`\%} character.}
20253 \item \Ie{tabular*} uses a primitive capability of \tx\ to
20254 modify the inter column space of an alignment. \Ie{tabularx}
20255 has to set the table several times as it searches for the best column
20256 widths, and is therefore much slower. Also the fact that the body is
20257 expanded several times may break certain \tx\ constructs.
20258 \end{itemize}
20259
20260 \begin{syntax}
20261 \cmd{\tracingtabularx} \\
20262 \end{syntax}
20263 \glossary(tracingtabularx)%
20264 {\cs{tracingtabularx}}%
20265 {Writes information about the changing column widths while setting
20266 a \texttt{tabularx}.}
20267 Following the \cmd{\tracingtabularx} declaration all
20268 later \Ie{tabularx} environments will print information
20269 about column widths as they repeatedly re-set the tables to find the
20270 correct widths.
20271
20272
20273 By default the \texttt{X} specification is turned into
20274 \verb?p?\marg{some value}. Such narrow columns often
20275 require a special format, which can be achieved by using the \verb?>? syntax.
20276 For example, \verb?>{\small}X?. Another format which is useful in narrow
20277 columns is raggedright\index{tabular!raggedright},
20278 however \ltx's \cmd{\raggedright} macro redefines
20279 \cmd{\\} in a way which conflicts with its use in \Ie{tabular} or
20280 \Ie{array} environments.
20281
20282 \begin{syntax}
20283 \cmd{\arraybackslash} \\
20284 \end{syntax}
20285 \glossary(arraybackslash)%
20286 {\cs{arraybackslash}}%
20287 {Use instead of \Vprint{\\} in a tabular column.}
20288 For this reason the command \cmd{\arraybackslash} is provided;
20289 this may be used after a \cmd{\raggedright}, \cmd{\raggedleft} or
20290 \cmd{\centering} declaration. Thus a \Ie{tabularx} format may include
20291 \begin{lcode}
20292 >{\raggedright\arraybackslash}X
20293 \end{lcode}
20294 These format specifications may of course be saved using the
20295 command, \cmd{\newcolumntype}\index{tabular!new column type}.
20296 After specifying, say,
20297 \begin{lcode}
20298 \newcolumntype{Y}{>{\small\raggedright\arraybackslash}X}
20299 \end{lcode}
20300 then \texttt{Y} could be used in the \Ie{tabularx} format
20301 argument.
20302
20303
20304 \begin{syntax}
20305 \cmd{\tabularxcolumn} \\
20306 \end{syntax}
20307 \glossary(tabularxcolumn)%
20308 {\cs{tabularxcolumn}}%
20309 {Column type for an \texttt{X} column in a \texttt{tabularx}.}
20310 The \texttt{X} columns are set using the \texttt{p} column, which
20311 corresponds to \cmd{\parbox}\verb?[t]?. You may want them set using, say, the
20312 \texttt{m} column, which corresponds to \cmd{\parbox}\verb?[c]?. It is not
20313 possible to change the column type using the \texttt{>} syntax, so another
20314 system is provided. \cmd{\tabularxcolumn} should be defined to be a macro
20315 with one argument, which expands to the \Ie{tabular} format
20316 specification that you want to correspond to \texttt{X}. The
20317 argument will be replaced by the calculated width of a column.
20318
20319 The default definition is
20320 \begin{lcode}
20321 \newcommand{\tabularxcolumn}[1]{p{#1}}
20322 \end{lcode}
20323 This may be changed, for instance
20324 \begin{lcode}
20325 \renewcommand{\tabularxcolumn}[1]{>{\small}m{#1}}
20326 \end{lcode}
20327 so that \texttt{X} columns will be typeset as \texttt{m} columns using
20328 the \cmd{\small} font.
20329
20330 Normally all \texttt{X} columns\index{tabular!X column}
20331 in a single table are set to the
20332 same width, however it is possible to make \Ie{tabularx} set
20333 them to different widths.
20334 A format argument of
20335 \begin{lcode}
20336 {>{\hsize=.5\hsize}X>{\hsize=1.5\hsize}X}
20337 \end{lcode}
20338 specifies two columns, where the second will be three times as wide as the
20339 first. If you think you need to do things like this try and redesign
20340 your table. However, if you must you should follow these two rules.
20341 \begin{itemize}
20342 \item Make sure that the sum of the widths of all the \texttt{X}
20343 columns is unchanged. (In the above example, the new widths still add
20344 up to twice the default width, the same as two standard \texttt{X}
20345 columns.)
20346 \item Do not use \cmd{\multicolumn} entries which cross any \texttt{X}
20347 column.
20348 \end{itemize}
20349
20350
20351 \Ie{tabularx} will not set \texttt{X} columns to a negative width.
20352 If the widths of the `normal' columns of the table already total more
20353 than the requested total width you will get the warning
20354 `\texttt{X columns too narrow (table too wide)}'.\index{X columns too narrow (table too wide)}
20355 The \texttt{X} columns will be set to a width of 1em
20356 and so the table itself will be wider than the requested total width
20357 given in the argument to the environment.
20358 % This behaviour of the package can be customised slightly
20359 % as noted in the documentation of the code section.
20360
20361 The standard \cmd{\verb} macro does not work inside a \Ie{tabularx},
20362 just as it does not work in the argument to any macro.
20363
20364 \begin{syntax}
20365 \cmd{\TX@verb} \\
20366 \end{syntax}
20367 \glossary(TX@verb)%
20368 {\cs{TX@verb}}%
20369 {A poor man's \cs{verb} for use in a \texttt{tabularx}.}
20370 The `poor man's \cmd{\verb}' (and
20371 \cmd{\verb*}) defined here is based on page 382 of the \btitle{\tx book}. As
20372 explained there, doing verbatim this way means that spaces are not
20373 treated correctly, and so \cmd{\verb*} may well be useless.
20374 The mechanism is quite general, and any macro which wants to allow a
20375 form of \cmd{\verb} to be used within its argument may
20376 \begin{lcode}
20377 \let\verb=\TX@verb
20378 \end{lcode}
20379 It must ensure that the real definition is restored afterwards.
20380
20381 This version of \cmd{\verb} and \cmd{\verb*} are subject to the
20382 following restictions:
20383 \begin{enumerate}
20384 \item Spaces in the argument are not read verbatim, but may be skipped
20385 according to \tx's usual rules.
20386 \item Spaces will be added to the output after control words, even if
20387 they were not present in the input.
20388 \item Unless the argument is a single space, any trailing space,
20389 whether in the original argument, or added as in (2),
20390 will be omitted.
20391 \item The argument must not end with \verb?\?, so \verb?\verb|\|? is not
20392 allowed, however, because of (3), \verb?\verb|\ |? produces
20393 \verb?\?.
20394 \item The argument must be balanced with respect to \verb?{? and \verb?}?. So
20395 \verb?\verb|{|? is not allowed.
20396 \item A comment character like \verb?%? will not appear verbatim. It will
20397 act as usual, commenting out the rest of the input line!
20398 \item The combinations \verb=?`= and \verb?!`? will appear as
20399 {\ttfamily?`} and {\ttfamily!`} if the Computer Typewriter\index{Typewriter}
20400 font is being used.
20401 \end{enumerate}
20402
20403
20404 \index{tabular|)}
20405
20406 \section{Spaces and rules}
20407
20408 \subsection{Spacing}
20409
20410 Sometimes tabular rows appear vertically challenged.
20411
20412 \begin{syntax}
20413 \cmd{\arraystretch} \\
20414 \end{syntax}
20415 \glossary(arraystretch)%
20416 {\cs{arraystretch}}%
20417 {Multiplication factor for the normal row spacing in tabulars and arrays.}
20418 The macro \cmd{\arraystretch} controls the spacing between
20419 rows.\index{array!row spacing}\index{tabular!row spacing} The normal
20420 space is multiplied by the value of \cmd{\arraystretch}, whose default
20421 definition is
20422 \begin{lcode}
20423 \newcommand{\arraystretch}{1.0}
20424 \end{lcode}
20425 If this is changed to 1.25, for example, the row spacing is increased by 25\%.
20426
20427 \begin{syntax}
20428 \lnc{\extrarowheight} \\
20429 \end{syntax}
20430 \glossary(extrarowheight)%
20431 {\cs{extrarowheight}}%
20432 {Length added to the normal row height in tabulars and arrays.}
20433 If the length \lnc{\extrarowheight} is positive, its value is added
20434 to the normal height of every row of the array or table, while
20435 the depth will remain the same. This is important for tables
20436 with horizontal lines because those lines normally touch the
20437 capital letters. For example
20438 \begin{lcode}
20439 \begin{table}
20440 \centering
20441 \caption{The array and tabular format options.}%
20442 \label{tab:tabpream}
20443 \setlength{\extrarowheight}{1pt}
20444 \begin{tabular}{cp{9cm}} \toprule
20445 ...
20446 \end{lcode}
20447 was used for \tref{tab:tabpream}.
20448
20449 \begin{syntax}
20450 \lnc{\arraycolsep} \lnc{\tabcolsep} \\
20451 \end{syntax}
20452 \glossary(arraycolsep)%
20453 {\cs{arraycolsep}}%
20454 {Half the space between columns in an array.}
20455 \glossary(tabcolsep)%
20456 {\cs{tabcolsep}}%
20457 {Half the space between columns in a tabular.}
20458 The length \lnc{\arraycolsep} is half the width of the horizontal space
20459 between columns\index{array!intercolumn space} in an \Ie{array} environment
20460 and similarly the length
20461 \lnc{\tabcolsep} is half the space between
20462 columns\index{tabular!intercolumn space} in an \Ie{tabular}
20463 or \Ie{tabular*} environment.
20464
20465 \begin{syntax}
20466 \lnc{\arrayrulewidth} \lnc{\doublerulesep} \\
20467 \end{syntax}
20468 \glossary(arrayrulewidth)%
20469 {\cs{arrayrulewidth}}%
20470 {Width of lines (e.g., \cs{hline}, \cs{vline}, etc.) in an array or tabular.}
20471 The length \lnc{\arrayrulewidth} is the width of the line created by
20472 a \verb?|? in the format, or by an \cmd{\hline}, \cmd{\cline} or
20473 \cmd{\vline} command. The length \lnc{\doublerulesep} is the space
20474 between lines created by two successive \verb?|? options in the format
20475 or by successive \cmd{\hline} commands.
20476
20477
20478 \subsection{Special variations on horizontal lines}
20479
20480 The family of \texttt{tabular} environments allows
20481 vertical positioning\index{tabular!vertical position}
20482 with respect to the baseline of
20483 the text in which the environment appears. By default the
20484 environment appears centered, but this can be changed to
20485 align with the first or last line in the environment by
20486 supplying a \texttt{t} or \texttt{b} value to the
20487 optional position argument. However, this does not work
20488 when the first or last element in the environment is a
20489 \cmd{\hline} command --- in that case the environment is
20490 aligned at the horizontal rule.
20491
20492 \pagebreak[3]
20493
20494 Here is an example:
20495 \begin{center}
20496 \begin{minipage}[t]{.4\linewidth}
20497 Tables
20498 \begin{tabular}[t]{l}
20499 with no\\ hline\\ commands
20500 \end{tabular} versus \\ tables
20501 \begin{tabular}[t]{|l|}
20502 \hline
20503 with some\\ hline\\ commands\\
20504 \hline
20505 \end{tabular} used.
20506 \end{minipage}
20507 \begin{minipage}[t]{.52\linewidth}
20508 \begin{verbatim}
20509 Tables
20510 \begin{tabular}[t]{l}
20511 with no\\ hline\\ commands
20512 \end{tabular} versus tables
20513 \begin{tabular}[t]{|l|}
20514 \hline
20515 with some\\ hline\\ commands\\
20516 \hline
20517 \end{tabular} used.
20518 \end{verbatim}
20519 \end{minipage}
20520 \end{center}
20521
20522 \begin{syntax}
20523 \cmd{\firsthline} \cmd{\lasthline} \\
20524 \lnc{\extratabsurround} \\
20525 \end{syntax}
20526 \glossary(firsthline)%
20527 {\cs{firsthline}}%
20528 {An \cs{hline} (the first) that does not effect vertical alignment of an
20529 array or tabular.}
20530 \glossary(lasthline)%
20531 {\cs{lasthline}}%
20532 {An \cs{hline} (the last) that does not effect vertical alignment of an
20533 array or tabular.}
20534 \glossary(extratabsurround)%
20535 {\cs{extratabsurround}}
20536 {Adds additional space for \cs{firsthline} and \cs{lasthline}.}
20537
20538 Using \cmd{\firsthline} and \cmd{\lasthline} will
20539 cure the problem, and the tables will align properly as long
20540 as their first or last line does not contain extremely large
20541 objects.
20542 \begin{center}
20543 \begin{minipage}[t]{.4\linewidth}
20544 Tables
20545 \begin{tabular}[t]{l}
20546 with no\\ line \\ commands
20547 \end{tabular} versus \\ tables
20548 \begin{tabular}[t]{|l|}
20549 \firsthline
20550 with some\\ line \\ commands \\
20551 \lasthline
20552 \end{tabular} used.
20553 \end{minipage}
20554 \begin{minipage}[t]{.52\linewidth}
20555 \begin{verbatim}
20556 Tables
20557 \begin{tabular}[t]{l}
20558 with no\\ line\\ commands
20559 \end{tabular} versus tables
20560 \begin{tabular}[t]{|l|}
20561 \firsthline
20562 with some\\ line\\ commands\\
20563 \lasthline
20564 \end{tabular} used.
20565 \end{verbatim}
20566 \end{minipage}
20567 \end{center}
20568
20569 The implementation of these two commands contains an extra
20570 dimension, which is called \cmd{\extratabsurround}, to add some
20571 additional space at the top and the bottom of such an environment.
20572 This is useful if such tables are nested.
20573
20574 \subsection{Handling of rules}
20575
20576 There are two possible approaches to the handling of horizontal and
20577 vertical rules in tables:
20578 \begin{enumerate}
20579 \item rules can be placed into the available space without
20580 enlarging the table, or
20581 \item rules can be placed between columns or rows thereby enlarging
20582 the table.
20583 \end{enumerate}
20584 The class implements the second possibility while the
20585 default implementation in the \ltx\ kernel implements the first
20586 concept.
20587
20588 With standard \ltx\ adding rules to a table will not affect the
20589 width or height of the table (unless double rules are used), e.g.,
20590 changing a format from \verb?lll? to \verb?l|l|l? does not
20591 affect the document other than adding rules to the table. In
20592 contrast, with the class a table that just fits the
20593 \lnc{\textwidth} might now produce an overfull box.
20594 (But you shouldn't have vertical rules in the first place.)
20595
20596
20597 \section{Free tabulars}
20598
20599 \index{tabular!free|(}
20600
20601 All the tabular environments described so far put the table
20602 into a box\index{box}, which \ltx\ treats like a large complex
20603 character, and characters are not broken across\index{page!break} pages.
20604 If you
20605 have a long table\index{table!long} that runs off the bottom of
20606 the page you can turn
20607 to, say, the \Lpack{longtable}~\cite{LONGTABLE} or \Lpack{xtab}~\cite{XTAB}
20608 packages which will automatically break tables across page boundaries.
20609 These have various bells and whistles, such as automatically putting
20610 a caption at the top of each page, repeating the column heads, and
20611 so forth.
20612
20613 \subsection{Continuous tabulars}
20614
20615 \index{tabular!continuous}
20616
20617 \begin{recommended}
20618 The construction below is not recommended for data tables that span
20619 across a page break as it has no feature to repeat the headers. In
20620 that case a better solution would be the \Lpack{longtable}
20621 package. There are also other similar newer packages.
20622 \end{recommended}
20623
20624 \bigskip
20625
20626 \begin{syntax}
20627 \senv{ctabular}\oarg{pos}\marg{format} rows \eenv{ctabular} \\
20628 \end{syntax}
20629 \glossary(ctabular)%
20630 {\senv{ctabular}\oarg{pos}\marg{format}}%
20631 {Like \texttt{tabular} except that it will continue over a page break.}
20632 The \Ie{ctabular} environment is similar to \Ie{tabular}, but with a
20633 couple of differences, the main one
20634 being that the table will merrily continue across page\index{page!break}
20635 breaks.
20636 The \meta{format} argument is the same as for the previous \Ie{array}
20637 and \Ie{tabular} environments, but the optional \meta{pos} argument
20638 controls the horizontal position\index{tabular!continuous!position}
20639 of the table, not the vertical. The
20640 possible argument value is one of the following characters:
20641 \begin{itemize}
20642 \item[\pixposarg{l}] left justified,
20643 \item[\pixposarg{c}] centered, or
20644 \item[\pixposarg{r}] right justified;
20645 \end{itemize}
20646 the default is \pixposarg{c}.
20647
20648 \begin{lcode}
20649 \begin{ctabular}{lcr} \toprule
20650 LEFT & CENTER & RIGHT \\ \midrule
20651 l & c & r \\
20652 l & c & r \\
20653 l & c & r \\
20654 l & c & r \\ \bottomrule
20655 \end{ctabular}
20656 \end{lcode}
20657
20658 \begin{ctabular}[c]{lcr} \toprule
20659 LEFT & CENTER & RIGHT \\ \midrule
20660 l & c & r \\
20661 l & c & r \\
20662 l & c & r \\
20663 l & c & r \\ \bottomrule
20664 \end{ctabular}
20665
20666 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
20667 % \begin{comment}
20668 % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
20669 % The \Ie{ctabular*} has an extra \meta{width} argument. The table will be
20670 % placed within \meta{width} from the lefthand margin. Essentially
20671 % the following are equivalent:
20672 % \begin{lcode}
20673 % \begin{ctabular}[c]{...}
20674 % \begin{ctabular*}[c]{\textwidth}{...}
20675 % \end{lcode}
20676 % but \ldots
20677 % \begin{lcode}
20678 % \begin{ctabular*}[c]{0.5\textwidth}{lcr} \toprule
20679 % LEFT & CENTER & RIGHT \\ \midrule
20680 % l & c & r \\
20681 % l & c & r \\
20682 % l & c & r \\
20683 % l & c & r \\ \bottomrule
20684 % \end{ctabular*}
20685 % \end{lcode}
20686
20687 % \begin{ctabular*}[c]{0.5\textwidth}{lcr} \toprule
20688 % LEFT & CENTER & RIGHT \\ \midrule
20689 % l & c & r \\
20690 % l & c & r \\
20691 % l & c & r \\
20692 % l & c & r \\ \bottomrule
20693 % \end{ctabular*}
20694 % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
20695 % \end{comment}
20696 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
20697
20698 An example use is for setting two texts\index{parallel texts} in parallel,
20699 for instance a
20700 poem and it's translation, without having to be concerned about page
20701 breaks.
20702
20703 \begin{ctabular}{lcl}
20704 Je suis Fran\c{c}oys, dont il me pois, &
20705 \index[lines]{Je suis Fran\c{c}oys, dont il me pois}%
20706 \index[lines]{I am Fran\c{c}ois, which is unfortunate}&
20707 I am Fran\c{c}ois, which is unfortunate, \\
20708 N\'{e} de Paris empr\`{e}s Pointoise, & & born in Paris near Pointoise, \\
20709 Et de la corde d'une toise & & and with a six-foot stretch of rope, \\
20710 S\c{c}aura mon col que mon cul poise. & & my neck will know my arse's weight. \\
20711 \multicolumn{3}{r}{Fran\c{c}ois Villon, 1431--1463?}
20712 \end{ctabular}
20713
20714 The \Ie{ctabular} environment will probably not be used within
20715 a \Ie{table} environment (which defeats the possibility of the table
20716 crossing page boundaries). To caption a \Ie{ctabular} you can define a
20717 fixed\index{tabular!free!caption} caption\index{caption!fixed}.
20718 For example:
20719 \begin{lcode}
20720 \newfixedcaption{\freetabcaption}{table}
20721 \end{lcode}
20722 And then \cmd{\freetabcaption} can be used like the normal \cmd{\caption}
20723 within a \Ie{table} float.
20724 \newfixedcaption{\freetabcaption}{table}
20725
20726
20727 \subsection{Automatic tabulars}
20728
20729 A tabular format may be used just to list things, for example the
20730 names of the members of a particular organisation, or the names of
20731 \ltx\ environments.
20732
20733 \index{tabular!automatic|(}
20734
20735 Especially when drafting a document, or when the number of entries
20736 is likely to change, it is convenient to be able to tabulate a list
20737 of items without having to explicitly mark the end of each row.
20738
20739 \index{tabular!automatic!by row}
20740 \begin{syntax}
20741 \cmd{\autorows}\oarg{width}\marg{pos}\marg{num}\marg{style}\marg{entries} \\
20742 \end{syntax}
20743 \glossary(autorows)%
20744 {\cs{autorows}\oarg{width}\marg{pos}\marg{num}\marg{style}\marg{entries}}%
20745 {Lists the \meta{entries} in rows across \meta{num} columns in a tabular
20746 fashion.}
20747 The \cmd{\autorows} macro lists the \meta{entries} in rows; that is,
20748 the entries are typeset left to right and top to bottom. The
20749 \meta{num} argument is the number of columns.
20750 The \meta{entries} argument is a comma-separated list of the names to be
20751 tabulated; there must be no comma after the last of the names before the
20752 closing brace.
20753 \tref{tab:autorows} was set by \cmd{\autorows} using:
20754 \begin{lcode}
20755 \begin{figure}
20756 \freetabcaption{Example automatic row ordered table}
20757 \label{tab:autorows}
20758 \autorows{c}{5}{c}{one, two, three, four, five,
20759 six, seven, eight, nine, ten,
20760 eleven, twelve, thirteen, fourteen }
20761 \end{figure}
20762 \end{lcode}
20763
20764 \begin{figure}
20765 \freetabcaption{Example automatic row ordered table} \label{tab:autorows}
20766 \autorows{c}{5}{c}{one, two, three, four, five,
20767 six, seven, eight, nine, ten,
20768 eleven, twelve, thirteen, fourteen }
20769 \end{figure}
20770
20771 The \meta{pos} argument controls the horizontal
20772 position\index{tabular!automatic!position} of the
20773 tabular and the \meta{style} argument specifies the location of the
20774 entries in the columns; each column\index{tabular!automatic!column style}
20775 is treated identically. The value
20776 of a \meta{pos} or \meta{style} argument is one of the following
20777 characters:
20778 \begin{itemize}
20779 \item[\pixposarg{l}] left justified,
20780 \item[\pixposarg{c}] centered, or
20781 \item[\pixposarg{r}] right justified.
20782 \end{itemize}
20783
20784 Each column is normally the same
20785 width,\index{tabular!automatic!column width}\index{tabular!automatic!table width}
20786 which is large enough to accomodate
20787 the widest entry in the list.
20788 A positive \meta{width} (e.g., \verb?{0.8\textwidth}?), defines the overall
20789 width of the table, and the column width is calculated by dividing \meta{width}
20790 by the number of columns. Any negative value for the \meta{width} width lets
20791 each column be wide enough for the widest entry in that column;
20792 the column width is no longer a constant.
20793
20794 The examples in \fref{fig:arw} illustrate the effect of the \meta{width}
20795 argument (the default value is 0pt). The principal elements of the code
20796 for the \figurerefname{} are:
20797 \begin{lcode}
20798 \begin{figure}
20799 ...
20800 \autorows[-1pt]{c}{5}{c}{one, two, three, four, five,
20801 six, seven, eight, nine, ten,
20802 eleven, twelve, thirteen, fourteen }
20803 ...
20804 \autorows[0pt]{c}{5}{c}{one, two, three,
20805 ... fourteen }
20806 ...
20807 \autorows[0.9\textwidth]{c}{5}{c}{one, two, three,
20808 ... fourteen }
20809 \caption{Changing the width of a row ordered table}
20810 \label{fig:arw}
20811 \end{figure}
20812 \end{lcode}
20813
20814 \begin{figure}
20815 \centering
20816 \meta{width} = \verb?-1pt?
20817 \autorows[-1pt]{c}{5}{c}{one, two, three, four, five,
20818 six, seven, eight, nine, ten,
20819 eleven, twelve, thirteen, fourteen }
20820
20821 \meta{width} = \verb?0pt? (the default)
20822 \autorows[0pt]{c}{5}{c}{one, two, three, four, five,
20823 six, seven, eight, nine, ten,
20824 eleven, twelve, thirteen, fourteen }
20825
20826 \meta{width} = \verb?0.9\textwidth?
20827 \autorows[0.9\textwidth]{c}{5}{c}{one, two, three, four, five,
20828 six, seven, eight, nine, ten,
20829 eleven, twelve, thirteen, fourteen }
20830 \caption{Changing the width of a row ordered table} \label{fig:arw}
20831 \end{figure}
20832
20833
20834 \begin{syntax}
20835 \cmd{\autocols}\oarg{width}\marg{pos}\marg{num}\marg{style}\marg{entries} \\
20836 \end{syntax}
20837 \glossary(autocols)%
20838 {\cs{autocols}\oarg{width}\marg{pos}\marg{num}\marg{style}\marg{entries}}%
20839 {Lists the \meta{entries} down \meta{num} columns in a tabular
20840 fashion.}
20841 The \cmd{\autocols} macro lists its \meta{entries} in
20842 columns,\index{tabular!automatic!by column} proceeding
20843 top to bottom and left to right. The arguments,
20844 are the same as for \cmd{\autorows}, except that a negative
20845 \meta{width} is treated as if it were zero. The column
20846 width\index{tabular!automatic!column width}\index{tabular!automatic!table width}
20847 is always constant
20848 throughout the table and is normally sufficient for the
20849 widest entry. A positive or zero \meta{width} has the same effect as for
20850 \cmd{\autorows}.
20851
20852 If you need to include a comma within one of the entries in the list
20853 for either \cmd{\autorows} or \cmd{\autocols} you have to use a macro.
20854 For instance:
20855 \begin{lcode}
20856 \newcommand*{\comma}{,}
20857 \end{lcode}
20858 \newcommand*{\comma}{,}
20859
20860 The examples in \fref{fig:acw}, from the following code elements,
20861 illustrate these points.
20862
20863 \begin{lcode}
20864 \begin{figure}
20865 ...
20866 \autocols{c}{5}{c}{one\comma{} two, three, four, five,
20867 six, seven, eight, nine, ten,
20868 eleven, twelve, thirteen, fourteen }
20869 ...
20870 \autocols[0.9\textwidth]{c}{5}{c}{one\comma{} two, three,
20871 ... fourteen }
20872 \caption{Changing the width of a column ordered table}
20873 \label{fig:acw}
20874 \end{figure}
20875 \end{lcode}
20876
20877 \begin{figure}
20878 \begin{adjustwidth}{-10mm}{-10mm}
20879 \centering
20880 \meta{width} = \verb?0pt? (the default)
20881 \autocols{c}{5}{c}{one\comma{} two, three, four, five,
20882 six, seven, eight, nine, ten,
20883 eleven, twelve, thirteen, fourteen }
20884
20885 \meta{width} = \verb?0.9\textwidth?
20886 \autocols[0.9\textwidth]{c}{5}{c}{one\comma{} two, three, four, five,
20887 six, seven, eight, nine, ten,
20888 eleven, twelve, thirteen, fourteen }
20889 \caption{Changing the width of a column ordered table} \label{fig:acw}
20890 \end{adjustwidth}
20891 \end{figure}
20892
20893 \index{tabular!automatic|)}
20894 \index{tabular!free|)}
20895
20896 %#% extend
20897 %#% extstart include page-notes.tex
20898
20899 \svnidlong
20900 {$Ignore: $}
20901 {$LastChangedDate: 2025-07-30 17:12:49 +0200 (Wed, 30 Jul 2025) $}
20902 {$LastChangedRevision: 853 $}
20903 {$LastChangedBy: [email protected] $}
20904
20905 \chapter{Page notes} \label{chap:mnotes}
20906
20907 The standard classes provide the \cmd{\footnote} command for notes
20908 at the bottom of the page. The class provides several styles of footnotes
20909 and you can also have several series of footnotes for when the material
20910 gets complicated. The normal \cmd{\marginpar} command puts notes into
20911 the margin, which may float around a little if there are other
20912 \cmd{\marginpar}s on the page. The class additionally supplies commands
20913 for fixed marginal notes and sidebars.
20914
20915
20916 \section{Footnotes}
20917 \index{footnote|(}
20918
20919
20920 A footnote can be considered to be a special kind of float\index{float}
20921 that is put at the bottom of a page.
20922
20923 \begin{syntax}
20924 \cmd{\footnote}\oarg{num}\marg{text} \\
20925 \end{syntax}
20926 \glossary(footnote)
20927 {\cs{footnote}\oarg{num}\marg{text}}%
20928 {Put \meta{text} as a footnote.}
20929 In the main text, the \cmd{\footnote} command puts a marker at the
20930 point where it is called, and puts the \meta{text}, preceded by the same
20931 mark, at the bottom of the page. If the optional \meta{num} is used
20932 then its value is used for the mark, otherwise the \Icn{footnote}
20933 counter is stepped and provides the mark's value. The \cmd{\footnote}
20934 command should be used in paragraph mode where it puts the note at the
20935 bottom of the page, or in a \Ie{minipage} where it puts the note
20936 at the end of the \Ie{minipage}. Results are likely to be peculiar if
20937 it is used anywhere else (like in a \Ie{tabular}).
20938
20939
20940
20941 \begin{syntax}
20942 \cmd{\footnotemark}\oarg{num} \\
20943 \cmd{\footnotetext}\oarg{num}\marg{text} \\
20944 \end{syntax}
20945 \glossary(footnotemark)%
20946 {\cs{footnotemark}\oarg{num}}%
20947 {Typesets a footnote mark.}
20948 \glossary(footnotetext)%
20949 {\cs{footnotetext}\oarg{num}\marg{text}}%
20950 {Typesets \meta{text} as a footnote at the bottom of the page but does
20951 not put a mark in the main text.}
20952 You can use \cmd{\footnotemark} to put a marker in the main text; the value
20953 is determined just like that for \cmd{\footnote}. Footnote text can be put
20954 at the bottom of the page via \cmd{\footnotetext}; if the optional \meta{num}
20955 is given it is used as the mark's value, otherwise the value of the
20956 \Icn{footnote} counter is used.
20957 It may be helpful, but completely untrue, to think of \cmd{\footnote} being
20958 defined like:
20959 \begin{lcode}
20960 \newcommand{\footnote}[1]{\footnotemark\footnotetext{#1}}
20961 \end{lcode}
20962 In any event, you can use a combination of \cmd{\footnotemark} and
20963 \cmd{\footnotetext} to do footnoting where \ltx\ would normally get upset.
20964
20965
20966
20967 \begin{syntax}
20968 \cmd{\footref}\marg{label} \\
20969 \end{syntax}
20970 \glossary(footref)%
20971 {\cs{footref}{labstr}}%
20972 {Reference a labelled footnote.}
20973 On occasions it may be desireable to make more than one reference
20974 to the text of a footnote\index{footnote!reference}. This can be done by
20975 putting a \cmd{\label} in the footnote and then using \cmd{\footref} to refer
20976 to the label; this prints the footnote mark. For example:
20977 % \begin{comment}
20978 % %%% in memdesign, not memman
20979 % \begin{lcode}
20980 % ...\footnote{... adults or babies.\label{fn:rabbits}}
20981 % ...
20982 % ... The footnote\footref{fn:rabbits} on \pref{fn:rabbits} ...
20983 % \end{lcode}
20984 % In this manual, the last line above prints:
20985 % \begin{syntax}
20986 % ... The footnote\footref{fn:rabbits} on \pref{fn:rabbits} ... \\
20987 % \end{syntax}
20988 % \end{comment}
20989 \begin{lcode}
20990 ...\footnote{...values for the kerning.\label{fn:kerning}} ...
20991 ...
20992 ... The footnote\footref{fn:kerning} on \pref{fn:kerning} ... \\
20993 \end{lcode}
20994 In this manual, the last line above prints:
20995 \begin{syntax}
20996 ...
20997 The footnote\footref{fn:kerning}
20998 % on \pref{fn:kerning} ...
20999 \end{syntax}
21000
21001
21002
21003
21004 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
21005 %%%% from membook
21006
21007 \begin{syntax}
21008 \cmd{\multfootsep} \\
21009 \end{syntax}
21010 \glossary(multfootsep)%
21011 {\cs{multfootsep}}%
21012 {Separator between adjacent footnote marks.}
21013 In the standard classes if two or more footnotes are applied
21014 sequentially\footnote{One footnote}\footnote{Immediately followed by another}
21015 then the markers in the text are just run together. The class, like the
21016 \Lpack{footmisc}~\cite{FOOTMISC} and \Lpack{ledmac} packages, inserts a
21017 separator\index{footnote!marker separator}
21018 between the marks. In the class the macro \cmd{\multfootsep} is used as
21019 the separator. Its default definition is:
21020 \begin{lcode}
21021 \newcommand*{\multfootsep}{\textsuperscript{\normalfont,}}
21022 \end{lcode}
21023
21024 \begin{syntax}
21025 \cmd{\feetabovefloat} \\
21026 \cmd{\feetbelowfloat} \\
21027 \end{syntax}
21028 \label{interest:feetbelowfloat}
21029 \glossary(feetabovefloat)%
21030 {\cs{feetabovefloat}}%
21031 {Typeset footnotes above bottom floats (the default).}
21032 \glossary(feetbelowfloat)%
21033 {\cs{feetbelowfloat}}%
21034 {Typeset footnotes below bottom floats.}
21035 In the standard classes, footnotes on a page that has a float at the
21036 bottom are typeset before the float. I think that this looks
21037 peculiar. Following the \cmd{\feetbelowfloat} declaration footnotes
21038 will be typeset at the bottom of the page below any bottom
21039 floats;\index{footnote!bottom float}
21040 they will also be typeset at the bottom of \cmd{\raggedbottom} pages
21041 as opposed to being
21042 put just after the bottom line of text. The standard positioning is
21043 used following the \cmd{\feetabovefloat} declaration, which is the default.
21044
21045
21046
21047 \LMnote{2018/09/19}{Removed \cs{feetatbottom} from the manual. It does not
21048 actually do anything. The footnotes are always at the bottom}
21049 % \begin{syntax}
21050 % \cmd{\feetatbottom} \\
21051 % \end{syntax}
21052 % \glossary(feetatbottom)%
21053 % {\cs{feetatbottom}}%
21054 % {Place footnotes at the very bottom of the text block whenever we
21055 % are in a non \cs{flushbottom} context.}
21056 % Then\Added{2015/04/22} we use \cs{raggedbottom} or similar, \LaTeX{}
21057 % will by default attach the footnotes just below the text. In many
21058 % cases it may look better if the footnotes are being build from the
21059 % bottom of the texst block up. Issuing \cs{feetatbottom} does
21060 % this. Please note that \cs{feetatbottom} has no effect whenever
21061 % \cs{flushbottom} is active.
21062
21063
21064
21065 \subsection{A variety of footnotes}
21066
21067 \begin{syntax}
21068 \cmd{\verbfootnote}\oarg{num}\marg{text} \\
21069 \end{syntax}
21070 \glossary(verbfootnote)%
21071 {\cs{verbfootnote}\oarg{num}\marg{text}}%
21072 {Like \cs{footnote} except that \meta{text} can contain verbatim material.}
21073 The macro \cmd{\verbfootnote} is like the normal \cmd{\footnote}
21074 except that its \meta{text} agument\index{footnote!verbatim text}
21075 can contain verbatim material.
21076 For example, the next two paragraphs are typeset by this code:
21077 \begin{lcode}
21078 Below, footnote~\ref{fn1} is a \verb?\footnote? while
21079 footnote~\ref{fn2} is a \verb?\verbfootnote?.
21080
21081 The \verb?\verbfootnote? command should
21082 appear\footnote{There may be some problems if color is
21083 used.\label{fn1}}
21084 to give identical results as the normal \verb?\footnote?,
21085 but it can include some verbatim
21086 text\verbfootnote{The \verb?\footnote? macro, like all
21087 other macros except for \verb?\verbfootnote?,
21088 can not contain verbatim text in its
21089 argument.\label{fn2}}
21090 in the \meta{text} argument.
21091 \end{lcode}
21092
21093 Below, footnote~\ref{fn1} is a \verb?\footnote? while
21094 footnote~\ref{fn2} is a \verb?\verbfootnote?.
21095
21096 The \verb?\verbfootnote? command should
21097 appear\footnote{There may be some problems if color is
21098 used.\label{fn1}}
21099 to give identical results as the normal \verb?\footnote?, but it
21100 can include some verbatim
21101 text\verbfootnote{The \verb?\footnote? macro, like all other macros
21102 except for \verb?\verbfootnote?, can not contain
21103 verbatim text in its argument.\label{fn2}}
21104 in the \meta{text} argument.
21105
21106
21107
21108 \begin{syntax}
21109 \cmd{\plainfootnotes} \\
21110 \cmd{\twocolumnfootnotes} \\
21111 \cmd{\threecolumnfootnotes} \\
21112 \cmd{\paragraphfootnotes} \\
21113 \end{syntax}
21114 \glossary(plainfootnotes)%
21115 {\cs{plainfootnotes}}%
21116 {Typeset footnotes as separate marked paragraphs (the default).}
21117 \glossary(twocolumnfootnotes)%
21118 {\cs{twocolumnfootnotes}}%
21119 {Typeset footnotes in two columns.}
21120 \glossary(threecolumnfootnotes)%
21121 {\cs{threecolumnfootnotes}}%
21122 {Typeset footnotes in three columns.}
21123 \glossary(paragraphfootnotes)%
21124 {\cs{paragraphfootnotes}}%
21125 {Typeset footnotes as a single paragraph.}
21126
21127 Normally, each footnote\index{footnotes!as paragraphs}
21128 starts a new paragraph. The class provides three
21129 other\index{footnote!styles} styles, making four in all.
21130 Following the \cmd{\twocolumnfootnotes}\index{footnotes!as two columns}
21131 declaration footnotes will be typeset in two columns, and similarly
21132 they are typeset in three columns\index{footnotes!as three columns}
21133 after the \cmd{\threecolumnfootnotes}
21134 declaration. Footnotes are run together as a single
21135 paragraph\index{footnotes!as a paragraph} after the
21136 \cmd{\paragraphfootnotes} declaration. The default style is used after
21137 the \cmd{\plainfootnotes} declaration.
21138
21139 \begin{caveat}
21140 Following \cmd{\paragraphfootnotes} the footnotes should only be a
21141 single paragraph each.
21142 \end{caveat}
21143
21144
21145 The style can be changed at any
21146 time but there may be odd effects if the change is made in the middle of
21147 a page when there are footnotes before and after the declaration. You may
21148 find it interesting to try changing styles in an article type document
21149 that uses \cmd{\maketitle} and \cmd{\thanks}, and some footnotes on the
21150 page with the title:
21151 \begin{lcode}
21152 \title{...\thanks{...}}
21153 \author{...\thanks{...}...}
21154 ...
21155 \begin{document}
21156 \paragraphfootnotes
21157 \maketitle
21158 \plainfootnotes
21159 ...
21160 \end{lcode}
21161
21162 \begin{syntax}
21163 \cmd{\footfudgefiddle} \\
21164 \end{syntax}
21165 \glossary(footfudgefiddle)%
21166 {\cs{footfudgefiddle}}%
21167 {Integer number (default 64) to help when typesetting \cs{paragraphfootnotes}.}
21168 Paragraphed footnotes may overflow\index{footnote!too long}
21169 the bottom of a page. \tx\ has
21170 to estimate the amount of space that the paragraph will require once
21171 all the footnotes are assembled into it. It then chops off the main text
21172 to leave the requisite space at the bottom of the page, following which
21173 it assembles and typesets the paragraph. If it underestimated the size
21174 then the footnotes will run down the page too far. If this happens then
21175 you can change \cmd{\footfudgefiddle} to make \tx\ be more generous in
21176 its estimation. The default is 64 and a value about 10\% higher should
21177 fix most overruns.
21178 \begin{lcode}
21179 \renewcommand*{\footfudgefiddle}{70}
21180 \end{lcode}
21181 You must use an integer in the redefinition as the command is going to be
21182 used in a place where \tx\ expects an integer.
21183
21184 \LMnote{2010/09/17}{removed the text below, I see no reason for adding
21185 this to memoir, so it is now removed from the manual}
21186 % \begin{syntax}
21187 % \cmd{\footnoteA}\marg{text} \\
21188 % \cmd{\footnoteB}\marg{text} \\
21189 % \cmd{\footnoteC}\marg{text} \\
21190 % \end{syntax}
21191 % \glossary(footnoteA)%
21192 % {\cs{footnoteA}\marg{text}}%
21193 % {A series A footnote.}
21194 % \glossary(footnoteB)%
21195 % {\cs{footnoteB}\marg{text}}%
21196 % {A series B footnote.}
21197 % \glossary(footnotec)%
21198 % {\cs{footnoteC}\marg{text}}%
21199 % {A series C footnote.}
21200 %
21201 % In addition to the regular \cmd{\footnote} the class provides
21202 % three further\index{footnote!series} series
21203 % of footnotes, namely the `A', `B', and `C' series which are
21204 % distinguished by appending the series' uppercase letter at the end of
21205 % the command, like \cmd{\footnoteB} for the `B' series.
21206 % Perhaps the normal footnotes are required,
21207 % marked\index{footnote!marker} flagged with arabic numerals, and another
21208 % kind of footnote flagged with roman numerals. Each series has its own
21209 % \cmd{\footnotemarkB}, \cmd{\footnotetextB} and so on matching the regular
21210 % commands.
21211
21212
21213 \begin{syntax}
21214 \cmd{\newfootnoteseries}\marg{series} \\
21215 \cmd{\plainfootstyle}\marg{series} \\
21216 \cmd{\twocolumnfootstyle}\marg{series} \\
21217 \cmd{\threecolumnfootstyle}\marg{series} \\
21218 \cmd{\paragraphfootstyle}\marg{series} \\
21219 \end{syntax}
21220 \glossary(newfootnoteseries)%
21221 {\cs{newfootnoteseries}\marg{series}}%
21222 {Create a new footnote \meta{series}.}
21223 \glossary(plainfootstyle)%
21224 {\cs{plainfootstyle}\marg{series}}%
21225 {Set the \meta{series} footnotes to be typeset plain style.}
21226 \glossary(twocolumnfootstyle)%
21227 {\cs{twocolumnfootstyle}\marg{series}}%
21228 {Set the \meta{series} footnotes to be typeset in two column style.}
21229 \glossary(threecolumnfootstyle)%
21230 {\cs{threecolumnfootstyle}\marg{series}}%
21231 {Set the \meta{series} footnotes to be typeset in three column style.}
21232 \glossary(paragraphfootstyle)%
21233 {\cs{paragraphfootstyle}\marg{style}}%
21234 {Set the \meta{series} footnotes to be typeset in single paragraph style.}
21235
21236 If you need further series you can create you own.
21237 A new footnote series\index{footnote!new series} is
21238 created by the \cmd{\newfootseries} macro, where \meta{series} is an
21239 alphabetic identifier for the series. This is most conveniently a
21240 single (upper case) letter, for example \texttt{P}.
21241
21242 Calling, say, \verb?\newfootnoteseries{Q}? creates a set of macros
21243 equivalent to those for the normal \cmd{\footnote} but with the \meta{series}
21244 appended. These include \cs{footnoteQ}, \cs{footnotemarkQ},
21245 \cs{footnotetextQ} and so on. These are used just like the normal
21246 \cmd{\footnote} and companions.
21247
21248 By default, a series is set to typeset using the normal style
21249 of a paragraph per note. The series' style can be changed by using one
21250 of the \cs{...footstyle} commands.\index{footnote!style}
21251
21252 For example, to have a `P' (for paragraph) series using roman numerals
21253 as markers which, in the main text are superscript with a closing parenthesis
21254 and at the foot are on the baseline followed by an endash, and the text is
21255 set in italics at the normal footnote size:
21256 \begin{lcode}
21257 \newfootnoteseries{P}
21258 \paragraphfootstyle{P}
21259 \renewcommand{\thefootnoteP}{\roman{footnoteP}}
21260 \footmarkstyleP{#1--}
21261 \renewcommand{\@makefnmarkP}{%
21262 \hbox{\textsuperscript{\@thefnmarkP)}}}
21263 \renewcommand{\foottextfontP}{\itshape\footnotesize}
21264 \end{lcode}
21265 This can then be used like:
21266 \begin{lcode}
21267 .... this sentence\footnoteP{A `p' footnote\label{fnp}}
21268 includes footnote~\footrefP{fnp}.
21269 \end{lcode}
21270
21271 The \cmd{\newfootnoteseries} macro does not create series versions
21272 of the footnote-related length commands, such as \lnc{\footmarkwidth}
21273 and \lnc{\footmarksep}, nor does it create versions of \cmd{\footnoterule}.
21274
21275 At the foot of the page footnotes are grouped according to their series;
21276 all ordinary footnotes are typeset, then all the first series footnotes
21277 (if any), then the second series, and so on. The ordering corresponds to
21278 the order of \cmd{\newfootnoteseries} commands.
21279
21280 If you can't specify a particular footnote style using the
21281 class facilities the \Lpack{footmisc}
21282 package~\cite{FOOTMISC} provides a range of styles.
21283 A variety of styles also comes with the \Lpack{ledmac} package~\cite{LEDMAC}
21284 which additionally provides several classes of footnotes that can be mixed
21285 on a page.
21286
21287
21288
21289 \subsection{Styling}
21290
21291 \index{footnote!styling|(}
21292 The parameters controlling the vertical spacing of footnotes are
21293 illustrated in \fref{fig:fn}.
21294
21295 \begin{figure}
21296 \centering
21297 \drawparameterstrue
21298 \setlayoutscale{0.4}
21299 \drawfootnote
21300 \caption{Footnote layout parameters}\label{fig:fn}
21301 \end{figure}
21302
21303 There is a discussion in \Sref{sec:thanks} starting on
21304 \pref{sec:thanks} about how to style the \cmd{\thanks} command; footnotes
21305 can be similarly styled.
21306
21307 The \cmd{\footnote} macro (and its relations) essentially does three
21308 things:
21309 \begin{itemize}
21310 \item Typesets a marker\index{footnote!marker} at the point where
21311 \cmd{\footnote} is called;
21312 \item Typesets a marker\index{footnote!marker} at the bottom of the page
21313 on which \cmd{\footnote} is called;
21314 \item Following the marker at the bottom of the page, typesets the
21315 text \index{footnote!text} of the footnote.
21316 \end{itemize}
21317
21318 \begin{syntax}
21319 \cmd{\@makefnmark} \\
21320 \cmd{\@thefnmark} \\
21321 \end{syntax}
21322 \glossary(@makefnmark)%
21323 {\cs{@makefnmark}}%
21324 {Typesets the footnote marker where \cs{footnote} is called.}
21325 \glossary(@thefnmark)%
21326 {\cs{@thefnmark}}%
21327 {Value of the footnote marker.}
21328
21329 The \cmd{\footnote} macro calls the kernel command \cmd{\@makefnmark} to
21330 typeset the footnote marker at the point where \cmd{\footnote} is called
21331 (the value of the marker is kept in the macro \cmd{\@thefnmark}
21332 which is defined by the \cmd{\footnote} or \cmd{\footnotemark} macros).
21333 The default definition typesets the mark\index{footnote!marker!styling}
21334 as a superscript and is effectively
21335 \LMnote{2014/05/07}{\cs{@makefnmark} does not take arguments}
21336 \begin{lcode}
21337 \newcommand*{\@makefnmark}{\hbox{\textsuperscript{\@thefnmark}}}
21338 \end{lcode}
21339 You can change this if, for example,
21340 you wanted the marks to be in parentheses at the baseline.
21341 \LMnote{2014/05/07}{\cs{@makefnmark} does not take arguments}
21342 \begin{lcode}
21343 \renewcommand*{\@makefnmark}{{\footnotesize (\@thefnmark)}}
21344 \end{lcode}
21345 or, somewhat better to take account of the size of the surrounding text
21346 \LMnote{2014/05/07}{\cs{@makefnmark} does not take arguments}
21347 \begin{lcode}
21348 \renewcommand*{\@makefnmark}{\slashfracstyle{(\@thefnmark)}}
21349 \end{lcode}
21350
21351
21352
21353 \begin{syntax}
21354 \cmd{\footfootmark} \\
21355 \cmd{\footmarkstyle}\marg{arg} \\
21356 \end{syntax}
21357 \glossary(footfootmark)%
21358 {\cs{footfootmark}}%
21359 {Typsets the footnote mark at the bottom of the page.}
21360 \glossary(footmarkstyle)%
21361 {\cs{footmarkstyle}\marg{style}}%
21362 {Style of the footnote mark at the bottom of the page.}
21363 The class macro for typesetting the marker at the foot of the page is
21364 \cmd{\footfootmark}. The appearance of the mark is controlled by
21365 \cmd{\footmarkstyle}. The default specification is
21366 \begin{lcode}
21367 \footmarkstyle{\textsuperscript{#1}}
21368 \end{lcode}
21369 where the \verb?#1? indicates the position of \cmd{\@thefnmark} in the style.
21370 The default results in the mark being set as a superscript.
21371 For example, to have the marker set on the baseline
21372 and followed by a right parenthesis, do
21373 \begin{lcode}
21374 \footmarkstyle{#1) }
21375 \end{lcode}
21376
21377 \begin{syntax}
21378 \lnc{\footmarkwidth} \lnc{\footmarksep} \lnc{\footparindent} \\
21379 \end{syntax}
21380 \glossary(footmarkwidth)%
21381 {\cs{footmarkwidth}}%
21382 {Width of footnote mark box.}
21383 \glossary(footmarksep)%
21384 {\cs{footmarksep}}%
21385 {Offset from the footnote mark box for lines after the first.}
21386 \glossary(footparindent)%
21387 {\cs{footparindent}}%
21388 {Paragraph indent for multiparagraph footnote text.}
21389 The mark is typeset in a box of width \lnc{\footmarkwidth}
21390 If this is negative, the mark is outdented
21391 into the margin, if zero the mark is flush left, and when positive
21392 the mark is indented. The mark is followed by the
21393 text\index{footnote!text} of the footnote. Second and later lines of the
21394 text are offset by the length \lnc{\footmarksep} from the end of the box.
21395 The first line of a paragraph within a footnote is indented by
21396 \lnc{\footparindent}.
21397 The default values for these lengths are:
21398 \begin{lcode}
21399 \setlength{\footmarkwidth}{1.8em}
21400 \setlength{\footmarksep}{-\footmarkwidth}
21401 \setlength{\footparindent}{1em}
21402 \end{lcode}
21403
21404
21405 \begin{syntax}
21406 \cmd{\foottextfont} \\
21407 \end{syntax}
21408 \glossary(foottextfont)%
21409 {\cs{foottextfont}}%
21410 {Font for footnote text.}
21411 The text in the footnote\index{footnote!text!font} is typeset using
21412 the \cmd{\foottextfont} font. The default is \cmd{\footnotesize}.
21413
21414 \leavevmode\Added{Summer 2023} In case you wanted the footnotes to be
21415 typeset ragged right you can use
21416 \begin{lcode}
21417 \renewcommand\foottextfont{\footnotesize\raggedright}
21418 \end{lcode}
21419 Just be aware that (1) \cmd{\raggedright} has an effect on paragraph
21420 settings, so things like \cmd{\parindent} might need to be reset to
21421 \cmd{\footparindent} after \cmd{\raggedright}. (2) Column footnotes
21422 are already in ragged right. (3) \cmd{\raggedright} should never be
21423 used with paragraph footnotes.
21424
21425
21426
21427 Altogether, the class specifies
21428 \begin{lcode}
21429 \footmarkstyle{\textsuperscript{#1}}
21430 \setlength{\footmarkwidth}{1.8em}
21431 \setlength{\footmarksep}{-1.8em}
21432 \setlength{\footparindent}{1em}
21433 \newcommand{\foottextfont}{\footnotesize}
21434 \end{lcode}
21435 to replicate the standard footnote layout.
21436
21437 You might like to try the
21438 combinations of \lnc{\footmarkwidth} and \lnc{\footmarksep} listed
21439 in \tref{tab:fnstyle} to see which you might prefer.
21440 Not listed in the \tablerefname, to get the marker flushleft and then
21441 the text set as a block paragraph you can try:
21442 \begin{lcode}
21443 \setlength{\footmarkwidth}{1.8em}
21444 \setlength{\footmarksep}{0em}
21445 \footmarkstyle{#1\hfill}
21446 \end{lcode}
21447
21448 \begin{table}
21449 \begin{adjustwidth}{-5mm}{-5mm}
21450 \centering
21451 \caption{Some footnote text styles}\label{tab:fnstyle}
21452 \begin{tabular}{cc>{\raggedright\arraybackslash}p{0.5\textwidth}} \toprule
21453 \lnc{\footmarkwidth} & \lnc{\footmarksep} & Comment \\ \midrule
21454 1.8em & -1.8em & Flushleft, regular indented paragraph (the default) \\
21455 1.8em & 0em & Indented, block paragraph hung on the mark \\
21456 %1.8em & 1.8em & Indented, outdented paragraph \\
21457 %0em & -1.8em & Regular indented paragraph, first line flushleft \\
21458 0em & 0em & Flushleft, block paragraph \\
21459 %0em & 1.8em & Outdented paragraph, first line flushleft \\
21460 %-1.8em & -1.8em & Regular indented paragraph, starting in the margin \\
21461 %-1.8em & 0em & \\
21462 -1.8em & 1.8em & Block paragraph, flushleft, mark in the margin \\
21463 \LMnote{2010/02/05}{added -1sp trick}
21464 -1sp & 0em & Block paragraph, flushleft, mark in the margin but
21465 flush against the text
21466 \\
21467 \bottomrule
21468 \end{tabular}
21469 \end{adjustwidth}
21470 \end{table}
21471
21472 As an example of a rather different scheme, in at least one discipline
21473 the footnoted text in the main body has a
21474 marker\index{footnote!marker!multiple} at each end. It is possible
21475 to define a macro to do this:
21476 \begin{lcode}
21477 \newcommand{\wrapfootnote}[1]{\stepcounter\@mpfn%
21478 % marks in the text
21479 \protected@xdef\@thefnmark{\thempfn}%
21480 \@footnotemark #1\@footnotemark%
21481 % marks at the bottom
21482 \protected@xdef\@thefnmark{\thempfn--\thempfn}%
21483 \@footnotetext}
21484 \end{lcode}
21485 \makeatletter
21486 \newcommand{\wrapfootnote}[1]{\stepcounter\@mpfn%
21487 % marks in the text
21488 \protected@xdef\@thefnmark{\thempfn}%
21489 \@footnotemark #1\@footnotemark%
21490 % marks at the bottom
21491 \protected@xdef\@thefnmark{\thempfn--\thempfn}%
21492 \@footnotetext}
21493 \makeatother
21494 The macro is based on a posting to \ctt{} by Donald
21495 Arseneau\index{Arseneau, Donald} in November 2003,
21496 and is used like this:
21497 \begin{lcode}
21498 Some
21499 \wrapfootnote{disciplines}{For example, Celtic studies.}
21500 require double marks in the text.
21501 \end{lcode}
21502 Some
21503 \wrapfootnote{disciplines}{For example, Celtic studies.}
21504 require double marks in the text.
21505
21506
21507 \begin{syntax}
21508 \cmd{\fnsymbol}\marg{counter} \\
21509 \cmd{\@fnsymbol}\marg{num} \\
21510 \end{syntax}
21511 \glossary(fnsymbol)%
21512 {\cs{fnsymbol}\marg{counter}}%
21513 {Typesets the representation of the footnote marker.}
21514 \glossary(@fnsymbol)%
21515 {\cs{@fnsymbol}\marg{num}}%
21516 {Converts \meta{num} to the footnote marker representation.}
21517
21518 Any footnotes after this point will be set according to:
21519 \begin{lcode}
21520 \setlength{\footmarkwidth}{-1.0em}
21521 \setlength{\footmarksep}{-\footmarkwidth}
21522 \footmarkstyle{#1}
21523 \end{lcode}
21524 \setlength{\footmarkwidth}{-1.0em}
21525 \setlength{\footmarksep}{-\footmarkwidth}
21526 \footmarkstyle{#1}
21527
21528 The \cmd{\fnsymbol} macro typesets the representation of the
21529 counter \meta{counter} like a footnote\index{footnote!symbol} symbol.
21530 Internally it uses the kernel \cmd{\@fnsymbol} macro which converts
21531 a positive integer \meta{num} to a symbol. If you are not fond of
21532 the standard ordering\index{footnote!symbol!order} of the footnote
21533 symbols, this is the macro to change. Its
21534 original definition is:
21535 \begin{lcode}
21536 \def\@fnsymbol#1{\ensuremath{%
21537 \ifcase#1\or *\or \dagger\or \ddagger\or
21538 \mathsection\or \mathparagraph\or \|\or **\or
21539 \dagger\dagger \or \ddagger\ddagger \else\@ctrerr\fi}}
21540 \end{lcode}
21541 \makeatletter
21542 \let\m@mold@fnsymbol\@fnsymbol
21543 \def\@fnsymbol#1{\ensuremath{%
21544 \ifcase#1\or *\or \dagger\or \ddagger\or
21545 \mathsection\or \mathparagraph\or \|\or **\or
21546 \dagger\dagger \or \ddagger\ddagger \else\@ctrerr\fi}}
21547 \makeatother
21548 This, as shown by \verb?\@fnsymbol{1},...\@fnsymbol{9}? produces the series:
21549 \begin{center}
21550 \makeatletter
21551 \@fnsymbol{1},
21552 \@fnsymbol{2},
21553 \@fnsymbol{3},
21554 \@fnsymbol{4},
21555 \@fnsymbol{5},
21556 \@fnsymbol{6},
21557 \@fnsymbol{7},
21558 \@fnsymbol{8}, and
21559 \@fnsymbol{9}.
21560 %\@fnsymbol{10} % out of bounds
21561 \makeatother
21562 \end{center}
21563
21564 \makeatletter
21565 \renewcommand*{\@fnsymbol}[1]{\ensuremath{%
21566 \ifcase#1\or *\or \dagger\or \ddagger\or
21567 \mathsection\or \|\or \mathparagraph\or **\or \dagger\dagger
21568 \or \ddagger\ddagger \else\@ctrerr\fi}}
21569 \makeatother
21570 Robert Bringhurst quotes the following as the traditional
21571 ordering\index{footnote!symbol!order} (at least up
21572 to \makeatletter\@fnsymbol{6}\makeatother):
21573 \begin{center}
21574 \makeatletter
21575 \@fnsymbol{1},
21576 \@fnsymbol{2},
21577 \@fnsymbol{3},
21578 \@fnsymbol{4},
21579 \@fnsymbol{5},
21580 \@fnsymbol{6},
21581 \@fnsymbol{7},
21582 \@fnsymbol{8}, and
21583 \@fnsymbol{9}.
21584 \makeatother
21585 \end{center}
21586 You can obtain this sequence by redefining \cmd{\@fnsymbol} as:
21587 \begin{lcode}
21588 \renewcommand*{\@fnsymbol}[1]{\ensuremath{%
21589 \ifcase#1\or *\or \dagger\or \ddagger\or
21590 \mathsection\or \|\or \mathparagraph\or **\or \dagger\dagger
21591 \or \ddagger\ddagger \else\@ctrerr\fi}}
21592 \end{lcode}
21593 not forgetting judicious use of \cmd{\makeatletter} and \cmd{\makeatother}
21594 if you do this in the preamble\index{preamble}. Other authorities or publishers
21595 may prefer other sequences and symbols.
21596 \makeatletter\let\@fnsymbol\m@mold@fnsymbol\makeatother
21597
21598 To get the footnote reference marks\index{reference mark} set with
21599 symbols use:
21600 \begin{lcode}
21601 \renewcommand*{\thefootnote}{\fnsymbol{footnote}}
21602 \end{lcode}
21603 or to use roman numerals instead of the regular arabic numbers:
21604 \begin{lcode}
21605 \renewcommand*{\thefootnote}{\roman{footnote}}
21606 \end{lcode}
21607
21608 \begin{syntax}
21609 \cmd{\footnoterule} \\
21610 \end{syntax}
21611 \glossary(footnoterule)%
21612 {\cs{footnoterule}}%
21613 {Rule separating footnotes from the main text.}
21614
21615 The rule separating footnotes from the main text is specified
21616 by \cmd{\footnoterule}:
21617 \begin{lcode}
21618 \newcommand*{\footnoterule}{%
21619 \kern-3pt%
21620 \hrule width 0.4\columnwidth
21621 \kern 2.6pt}
21622 \end{lcode}
21623 If you don't want a rule (but you might later), then the easiest method is:
21624 \begin{lcode}
21625 \let\oldfootnoterule\footnoterule
21626 \renewcommand*{\footnoterule}{}
21627 \end{lcode}
21628 and if you later want rules you can write:
21629 \begin{lcode}
21630 \let\footnoterule\oldfootnoterule
21631 \end{lcode}
21632
21633
21634 \fancybreak{}
21635
21636
21637 In \fref{fig:fn} we see that the footnotes are separated from the text
21638 by \cs{skip}\cs{footins}. We provide a special interface to set this
21639 skip:
21640 \begin{syntax}
21641 \cmd{\setfootins}\marg{length for normal}\marg{length for minipage} \\
21642 \end{syntax}
21643 \glossary(setfootins)%
21644 {\cs{setfootins}\marg{length for normal}\marg{length for minipage}}%
21645 {Sets \cs{skip}\cs{footins} and its minipage counterpart.}
21646 The default is similar to
21647 \begin{lcode}
21648 \setfootins{\bigskipamount}{\bigskipamount}
21649 \end{lcode}
21650 Internally \cmd{\setfootins} also sets the skips being used by
21651 \cmd{\twocolumnfootnotes} and friends.
21652
21653
21654
21655 \index{footnote!styling|)}
21656
21657 \index{footnote|)}
21658
21659 \section{Marginal notes}
21660
21661
21662
21663 \LMnote{2010/01/**}{added a reference back to \cs{setmarginnotes}}
21664 Some marginalia can also be considered to be kinds of floats. The
21665 class provides the standard margin notes\index{margin note} via
21666 \cmd{\marginpar}. Remember that the width of the margin note, the
21667 separation from the text, and the separation from one \cmd{\marginpar}
21668 to another is controlled by \cmd{\setmarginnotes}, see
21669 \Sref{sec:head-foot-marg} on \pref{sec:head-foot-marg}.
21670
21671 \begin{syntax}
21672 \cmd{\marginpar}\oarg{left-text}\marg{text} \\
21673 \cmd{\marginparmargin}\marg{placement}\\
21674 \cmd{\reversemarginpar} \\
21675 \cmd{\normalmarginpar} \\
21676 \end{syntax}
21677 \glossary(marginpar)%
21678 {\cs{marginpar}\oarg{left-text}\marg{text}}%
21679 {Puts \meta{text} into the margin; if given, \meta{left-text} will be
21680 used instead of \meta{text} for the left margin.}
21681 \glossary(marginparmargin)%
21682 {\cs{marginparmargin}\marg{placement}}%
21683 {Provides a more textual
21684 interface for the user to specify in which margin the margin note
21685 should be placed.}
21686 \glossary(reversemarginpar)%
21687 {\cs{reversemarginpar}}%
21688 {Reverses the normal margins used by \cs{marginpar}.}
21689 \glossary(normalmarginpar)%
21690 {\cs{normalmarginpar}}%
21691 {Sets the normal margins used by \cs{marginpar}(the default).}
21692 Just as a reminder, the \cmd{\marginpar} macro puts \meta{text} into
21693 the margin alongside the typeblock --- the particular margin depends
21694 on the document style and the particular page.
21695
21696 \LMnote{2010/01/**}{explained why the need for the
21697 \cs{marginparmargin} macro}
21698 The interface for specifying which margin \cmd{\marginpar} (and
21699 friends) write to, have long been quite cluttered, so we have in 2010
21700 adopted a more textual and natural interface. For \cmd{\marginpar} the
21701 macro is named \cmd{\marginparmargin}\marg{placement} with possible
21702 placements: \emph{left}, \emph{right}, \emph{outer}, and
21703 \emph{inner}. The interpretation of which is explained in \fref{fig:xmargin}.
21704 The default corresponds to \verb?\marginparmargin{outer}?.
21705
21706
21707 \LMnote{2010/01/**}{instead of explaining the algorithm, each time the
21708 algorithm is explaine donce and for all in a figure, then we can
21709 simply refer to it}
21710 \begin{figure}[htbp]
21711 \centering
21712 \begin{minipage}{0.9\linewidth}
21713 \cs{Xmargin}\marg{placement} for possible placements: \emph{left},
21714 \emph{right}, \emph{outer}, and \emph{inner}\\
21715 \renewcommand\descriptionlabel[1]{\hspace\labelsep\normalfont\sffamily\bfseries #1}
21716 \begin{description}
21717 \small
21718 \item[Two column document] If the note is placed in the first
21719 column, to the left, otherwise to the right, irrespective the
21720 document being one- or two-side and of the users choices.
21721 \item[One sided document] If user specified \emph{left}, notes are
21722 placed to the left, otherwise to the right.
21723 \item[Two sided document] depends on whether a recto or verso page:
21724 \begin{description}
21725 \item[Recto (odd) page] note is placed on the right if the user
21726 specified \emph{right} or \emph{outer}, otherwise the note is
21727 placed on the left.
21728 \item[Verso (even) page] note is placed on the left if the user
21729 specified \emph{left} or \emph{outer}, otherwise the note is
21730 placed on the right.
21731 \end{description}
21732 \end{description}
21733 \end{minipage}
21734 \caption{Interpretation of the arguments to the \cs{Xmargin}
21735 commands for specifying the side in which to place side note like
21736 material. \texttt{X} here equals \texttt{marginpar},
21737 \texttt{sidepar}, \texttt{sidebar}, or \texttt{sidefoot}.}
21738 \label{fig:xmargin}
21739 \end{figure}
21740
21741 \fancybreak{}
21742
21743 \LMnote{2010/02/07}{Removed the explanation of the old interface for
21744 specifying the margin the \cs{marginpar} should go to. The original
21745 text is still available via subversion.}
21746 The original convoluted methods of specifying the margin for
21747 \cmd{\marginpar} is deprecated, although still supported; if you need
21748 to know what they are then you can read all about them in \texttt{memoir.dtx}.
21749
21750 Sometimes \ltx\ gets confused near a page break and a note just after
21751 a break may get put into the wrong\index{margin note!wrong margin}
21752 margin (the wrong margin for the current page but the right one if the
21753 note fell on the previous page). If this occurs then inserting the
21754 \cmd{\strictpagecheck} declaration before any \cmd{\marginpar} command
21755 is used will prevent this, at the cost of at least one additional
21756 \ltx\ run.
21757 \begin{caveat}[March 2025]
21758 In two column mode there is a bug in the output routine where the
21759 test for whether you are in the first or the second column may fail.
21760 In this case you can load the \Lpack{mparhack} package and see if
21761 that helps. As the name suggestes it is a bit of a hack and may be
21762 incompatible with other packages.
21763
21764 Earlier the class would autoload \Ppack{mparhack} in two column
21765 mode, but as of March 2025, we no longer do so, as there are
21766 relevant packages known to be incompatible with~it.
21767 \end{caveat}
21768
21769
21770 \section{Side notes}
21771
21772 The vertical position of margin notes\index{margin note!moved}
21773 specified via \cmd{\marginpar}
21774 is flexible so that adjacent notes are prevented from overlapping.
21775
21776 \LMnote{2010/01/**}{side note section extended with \cs{sidenotefont}
21777 and \cs{sidenotemargin}}
21778 \begin{syntax}
21779 \cmd{\sidepar}\oarg{left}\marg{right} \\
21780 \cmd{\sideparmargin}\marg{placement}\\
21781 \cmd{\sideparfont}\\
21782 \cmd{\sideparform}\\
21783 \lnc{\sideparvshift} \\
21784 \end{syntax}
21785 \glossary(sidepar)%
21786 {\cs{sidepar}\oarg{left}\marg{right}}%
21787 {Like \cs{marginpar} except that the note does not move vertically.}
21788 \glossary(sideparvshift)%
21789 {\cs{sideparvshift}}%
21790 {Move a \cs{sidepar} up/down by this amount.}
21791 \glossary(sideparmargin)%
21792 {\cs{sideparmargin}\marg{placement}}%
21793 {Specify into which margin the \cs{sidepar} goes.}
21794 \glossary(sideparfont)%
21795 {\cs{siderparfont}}%
21796 {The font which the \cs{sidepar}s are typeset.}
21797 \glossary(sideparform)
21798 {\cs{sideparform}}%
21799 {Macro holding placement like \cs{raggedright} and such.}
21800
21801 The \cmd{\sidepar} macro is similar to \cmd{\marginpar} except that
21802 it produces side notes\index{side note} that do not float ---
21803 they may overlap.
21804
21805 The same spacing is used for both \cmd{\marginpar} and \cmd{\sidepar},
21806 namely the lengths \lnc{\marginparsep} and \lnc{\marginparwidth}. See
21807 \cmd{\setmarginnotes}, in \Sref{sec:head-foot-marg} on
21808 \pref{sec:head-foot-marg}.
21809
21810 The length
21811 \lnc{\sideparvshift} can be used to make vertical
21812 adjustments\index{side note!adjust position} to the
21813 position of \cmd{\sidepar} notes. By default this is set to a value
21814 of 0pt which should align the top of the note with the text line.
21815
21816 The command \cmd{\sideparfont} is used to specify the font used for
21817 the \cmd{\sidepar}, default is \cmd{\normalfont}\cmd{\normalsize}.
21818
21819 \LMnote{2010/02/05}{added description of \cs{sideparform}}
21820 While \cmd{\sideparfont} holds the font settings for the sidepar, the
21821 local adjustment is kept in \cmd{\sideparform}, the default is
21822 \begin{lcode}
21823 \newcommand*{\sideparform}{%
21824 \ifmemtortm\raggedright\else\raggedleft\fi}
21825 \end{lcode}
21826 Which is a special construction the makes the text go flush against the
21827 text block on side specified via \cmd{\sideparmargin}. Since the
21828 margin par area is usually quite narrow it might be an idea to use a
21829 ragged setup which enables hyphenation. This can be achieved by
21830 \begin{lcode}
21831 \usepackage{ragged2e}
21832 \newcommand*{\sideparform}{%
21833 \ifmemtortm\RaggedRight\else\RaggedLeft\fi}
21834 \end{lcode}
21835
21836
21837 \LMnote{2010/01/**}{Fixed the typo, such that it IS now stated that
21838 the default is left, not right as was earlier stated}
21839 The macro \cmd{\sideparmargin}\marg{placement} can be used to specify
21840 which margin the side note should go to. \meta{placement} should be
21841 one of \emph{left}, \emph{right}, \emph{outer}, or
21842 \emph{inner}. Interpretation of which is explained in
21843 \fref{fig:xmargin}. For some now forgotten reason the default
21844 corresponds to \verb?\sideparmargin{left}?.\footnote{As not to change
21845 existing documents, we have decided to leave it like that.}
21846
21847
21848 By default the \meta{right} argument is put in the
21849 %right
21850 left%
21851 \index{side note!text for particular margin} margin. When
21852 the \Lopt{twoside} option is used the \meta{right} argument is put into
21853 the %left
21854 right
21855 margin on the verso (even numbered) pages; however, for these pages
21856 the optional \meta{left} argument is used instead if it is present. For
21857 two column text the relevent argument is put into the `outer' margin with
21858 respect to the column.
21859
21860 \fancybreak{}
21861
21862 \LMnote{2010/02/07}{Removed the explanation of the old interface for
21863 specifying the margin the \cs{sidepar} should go to. The original
21864 text is still available via subversion.} The original convoluted
21865 methods of specifying the margin for \cmd{\sidepar} is deprecated,
21866 although still supported; if you need to know what they are then you
21867 can read all about them in \texttt{memoir.dtx}.
21868
21869
21870 \begin{syntax}
21871 \cmd{\parnopar} \\
21872 \end{syntax}
21873 \glossary(parnopar)%
21874 {\cs{parnopar}}%
21875 {Forces a new paragraph, but with no apparent break in the text.}
21876 When \ltx\ is deciding where to place the side notes it checks whether
21877 it is on an odd or even page and sometimes TeX doesn't realise that it has just
21878 moved onto the next page. Effectively TeX typesets paragraph by paragraph
21879 (including any side notes) and at the end of each paragraph sees if there
21880 should have been a page break in the middle of the paragraph. If there was
21881 it outputs the first part of the paragraph, inserts the page break, and retains
21882 the second part of the paragraph, without retypesetting it, for eventual
21883 output at the top of the new page. This means that side notes for any given
21884 paragraph are in the same margin, either left or right. A side note at the
21885 end of a paragraph may then end up in the wrong margin. The macro
21886 \cmd{\parnopar} forces a new paragraph\index{paragraph break!invisible}
21887 but without appearing to (the first
21888 line in the following paragraph follows immediately after the last element
21889 in the prior paragraph with no line break). You can use \cmd{\parnopar}
21890 to make TeX to do its page break calculation when you want it to, by splitting
21891 what appears to be one paragraph into two paragraphs.
21892
21893 \LMnote{2010/02/09}{Moved the veelo example to the new sniplet
21894 chapter} Bastiaan Veelo\index{Veelo, Bastiaan} has kindly provided
21895 example code for another form of a side note, the code is shown in
21896 \snipletref{snip:veelo}.
21897
21898 Bastiaan also noted that it provided an example of using the
21899 \lnc{\foremargin} length.
21900 If you want to try it out, either put the code in your preamble,
21901 or put it into a package (i.e., \file{.sty} file) without the
21902 \cs{makeat...} commands.
21903
21904
21905 \section{Sidebars}
21906
21907 Sidebars\index{sidebar} are typeset in the margin and usually
21908 contain material that is ancilliary to the main text. They may be long
21909 and extend for more than one page.\footnote{Donald
21910 Arseneau's\index{Arseneau, Donald} help has been invaluable in getting
21911 the sidebar code to work.}
21912
21913
21914 \begin{syntax}
21915 \cmd{\sidebar}\marg{text} \\
21916 \end{syntax}
21917 \glossary(sidebar)%
21918 {\cs{sidebar}\marg{text}}%
21919 {Typesets \meta{text} in a sidebar.}
21920 The \cmd{\sidebar} command is like \cmd{\marginpar} in that it sets
21921 the \meta{text} in the margin. However, unlike \cmd{\marginpar} the
21922 \meta{text} will start near the top of the page, and may continue onto
21923 later pages if it is too long to go on a single page. If multiple
21924 \cmd{\sidebar} commands are used on a page, the several \meta{text}s
21925 are set one after the other.
21926
21927 \LMnote{2010/02/07}{dropped \cs{ifsidebaroneside} as it is not used anymore}
21928 \begin{syntax}
21929 \cmd{\sidebarmargin}\marg{margin} \\
21930 \end{syntax}
21931 \glossary(sidebarmargin)%
21932 {\cs{sidebarmargin}\marg{margin}}%
21933 {Specifies the \meta{margin}(s) for sidebars.}
21934
21935 \LMnote{2010/02/07}{just adapted the explanation from the other
21936 \cs{Xmargin} macros}
21937 The macro \cmd{\sidebarmargin}\marg{placement} can be used to specify
21938 which margin the side note should go to. \meta{placement} should be
21939 one of \emph{left}, \emph{right}, \emph{outer}, or
21940 \emph{inner}. Interpretation of which is explained in
21941 \fref{fig:xmargin}. The default corresponds to \verb?\sidebarmargin{outer}?.
21942
21943
21944 \begin{syntax}
21945 \cmd{\sidebarfont} \cmd{\sidebarform} \\
21946 \end{syntax}
21947 \glossary(sidebarfont)%
21948 {\cs{sidebarfont}}%
21949 {Font used for sidebars.}
21950 \glossary(sidebarform)%
21951 {\cs{sidebarform}}%
21952 {Form (e.g., \cs{raggedright}) used for sidebars.}
21953 The sidebar \meta{text} is typeset using the \cmd{\sidebarfont}, whose initial
21954 definition is
21955 \begin{lcode}
21956 \newcommand{\sidebarfont}{\normalsize\normalfont}
21957 \end{lcode}
21958 Sidebars\index{sidebar!styling} are normally narrow so the text is
21959 set raggedright\index{raggedright} to
21960 reduce hyphenation\index{hyphenation}
21961 problems and stop items in environments like \Ie{itemize} from overflowing.
21962 \LMnote{2010/02/05}{added description of \cs{sidebarform}}
21963 \LMnote{2010/02/06}{fixed typo}
21964 More accurately, the text is set according to \cmd{\sidebarform} which is
21965 defined as:
21966 \begin{lcode}
21967 \newcommand*{\sidebarform}{%
21968 \ifmemtortm\raggedright\else\raggedleft\fi}
21969 \end{lcode}
21970 Which is a special construction the makes the text go flush against the
21971 text block on side specified via \cmd{\sideparmargin}. Since the
21972 margin par area is usually quite narrow it might be an idea to use a
21973 ragged setup which enables hyphenation. This can be achieved by
21974 \begin{lcode}
21975 \usepackage{ragged2e}
21976 \newcommand*{\sidebarform}{%
21977 \ifmemtortm\RaggedRight\else\RaggedLeft\fi}
21978 \end{lcode}
21979
21980
21981
21982 % which is ragged right but with less raggedness than \cmd{\raggedright}
21983 % would allow. As usual, you can change \cmd{\sidebarform}, for example:
21984 % \begin{lcode}
21985 % \renewcommand{\sidebarform}{} % justified text
21986 % \end{lcode}
21987
21988
21989
21990
21991
21992 You may run into problems if the \cmd{\sidebar} command comes near
21993 a pagebreak, or if the sidebar text gets typeset alongside main text that
21994 has non-uniform line spacing (like around a \cmd{\section}). Further,
21995 the contents of sidebars may not be typeset if they are too near to the
21996 end of the document.
21997
21998 \begin{syntax}
21999 \lnc{\sidebarwidth} \lnc{\sidebarhsep} \lnc{\sidebarvsep} \\
22000 \end{syntax}
22001 \glossary(sidebarwidth)%
22002 {\cs{sidebarwidth}}%
22003 {Width of sidebars.}
22004 \glossary(sidebarhsep)%
22005 {\cs{sidebarhsep}}%
22006 {Space between the edge of the main text and sidebars.}
22007 \glossary(sidebarvsep)%
22008 {\cs{sidebarvsep}}%
22009 {Vertical space between sidebars that fall on the same page.}
22010 The \meta{text} of a \cmd{\sidebar} is typeset in a column of width
22011 \lnc{\sidebarwidth} and there is a horizontal gap of \lnc{\sidebarhsep}
22012 between the main text and the sidebar. The length \lnc{\sidebarvsep}
22013 is the vertical gap between sidebars that fall on the same page; it also
22014 has a role in controlling the start of sidebars with respect to the
22015 top of the page.
22016
22017 \begin{syntax}
22018 \lnc{\sidebartopsep} \\
22019 \cmd{\setsidebarheight}\marg{height} \\
22020 \end{syntax}
22021 \glossary(sidebartopsep)%
22022 {\cs{sidebartopsep}}%
22023 {Controls the vertical position of a sidebar. The default is 0pt which
22024 aligns the tops of the typeblock and the sidebar.}
22025 \glossary(setsidebarheight)%
22026 {\cs{setsidebarheight}\marg{height}}%
22027 {Sets the height of sidebars. The default is \cs{textheight}.}
22028 The length \lnc{\sidebartopsep} controls the vertical position of the top
22029 of a sidebar. The default is 0pt which aligns it with the top of the
22030 typeblock.
22031 The command \cmd{\setsidebarheight} sets the height of sidebars to
22032 \meta{height}, without making any allowance for \lnc{\sidebartopsep}.
22033 The \meta{length} argument should be equivalent to an integral number
22034 of lines. For example:
22035 \begin{lcode}
22036 \setsidebarheight{15\onelineskip}
22037 \end{lcode}
22038 The default is the \lnc{\textheight}.
22039
22040 Perhaps you would like sidebars to start two lines below the top of
22041 the typeblock but still end at the bottom of the typeblock? If so, and
22042 you are using the \Lpack{calc} package~\cite{CALC}, then the following
22043 will do the job:
22044 \begin{lcode}
22045 \setlength{\sidebartopskip}{2\onelineskip}
22046 \setsidebarheight{\textheight-\sidebartopskip}
22047 \end{lcode}
22048
22049
22050 The alignment of the text in a sidebar with the main text may not
22051 be particularly good and you may wish to do some experimentation
22052 (possibly through a combination of \lnc{\sidebarvsep} and
22053 \cmd{\setsidebarheight}) to improve matters.
22054
22055 Although you can set the parameters for your sidebars individually it
22056 is more efficient to use the \cmd{\setsidebars} command; it \emph{must} be
22057 used if you change the font and/or the height.
22058 \begin{syntax}
22059 \cmd{\setsidebars}\marg{hsep}\marg{width}\marg{vsep}\marg{topsep}\marg{font}\marg{height} \\
22060 \end{syntax}
22061 \glossary(setsidebars)%
22062 {\cs{setsidebars}\marg{hsep}\marg{width}\marg{vsep}\marg{topsep}\marg{font}\marg{height}}%
22063 {Sets the several sidebar parameters.}
22064
22065 The \cmd{\setsidebars} command can be used to set the sidebar parameters.
22066 \lnc{\sidebarhsep} is set to \meta{hsep}, \lnc{\sidebarwidth} is set to
22067 \meta{width}, \lnc{\sidebarvsep} is set to \meta{vsep}, \lnc{\sidebartopsep}
22068 is set to \meta{topsep}, \cmd{\sidebarfont} is set to \meta{font},
22069 and finally \cmd{\setsidebarheight} is used to set the height to \meta{height}.
22070 The default is:
22071 \LMnote{2010/02/07}{the default was wrong compared to the class}
22072 \begin{lcode}
22073 \setsidebars{\marginparsep}{\marginparwidth}{\onelineskip}%
22074 {0pt}{\normalsize\normalfont}{\textheight}
22075 \end{lcode}
22076 Any, or all, of the arguments can be a \verb?*?, in which case the parameter
22077 corresponding to that argument is unchanged. Repeating the above example of
22078 changing the topskip and the height, assuming that the other defaults are
22079 satisfactory except that the width should be 3cm and an italic font should
22080 be used:
22081 \begin{lcode}
22082 \setsidebars{*}{3cm}{*}{2\onelineskip}{\itshape}%
22083 {\textheight-\sidebartopsep}
22084 \end{lcode}
22085
22086 Changing the marginpar parameters, for example with \cmd{\setmarginnotes},
22087 will not affect the sidebar parameters.
22088
22089 Note that \cmd{\checkandfixthelayout} neither checks nor fixes any of
22090 the sidebar parameters. This means, for instance, that if you change the
22091 \lnc{\textheight} from its default value and you want sidebars to have
22092 the same height then after changing the \lnc{\textheight} you have to
22093 call \cmd{\checkandfixthelayout} and then call \cmd{\setsidebars} with
22094 the (new) \lnc{\textheight}. For instance:
22095 \begin{lcode}
22096 ...
22097 \settypeblocksize{40\baselineskip}{5in}{*}
22098 ...
22099 \checkandfixthelayout
22100 \setsidebars{...}{...}{...}{...}{...}{\textheight}
22101 \end{lcode}
22102
22103 Unfortunately if a sidebar is on a double column page that either includes
22104 a double column float or starts a new chapter then the top of the sidebar
22105 comes below the float or the chapter title. I have been unable to eliminate
22106 this `feature'.
22107
22108
22109 \section{Side footnotes}
22110 \label{sec:side-footnotes}
22111
22112 Besides three already mentioned macros for writing in the margin
22113 (\cmd{\marginpar}, \cmd{\sidepar}, and \cmd{\sidebar}) \theclass\ also
22114 provide a functionality to add side footnotes. Actually two ways: one
22115 is to internally make \cmd{\footnote} use \cmd{\marginpar} to write
22116 in the margin, the other is to collect all side footnotes bottom up in
22117 the margin.
22118 \begin{syntax}
22119 \cmd{\footnotesatfoot}\\
22120 \cmd{\footnotesinmargin}\\
22121 \end{syntax}
22122 \cmd{\footnotesatfoot} (the default) causes \cmd{\footnote} to place
22123 its text at the bottom of the page. By issuing \cmd{footnotesinmargin}
22124 \cmd{\footnote} (and friends like \cmd{\footnotetext})will internally
22125 use \cmd{\marginpar} to write the footnote to the page.
22126
22127
22128
22129 \subsection{Bottom aligned side footnotes}
22130 \label{sec:bottom-aligned-side}
22131
22132 Bottom aligned footnotes works just like regular footnotes, just with
22133 a separate macro \cmd{\sidefootenote}\marg{text}, and here the side
22134 footnotes are placed at the bottom of the specified margin (more or
22135 like as if one had taken the footnotes from the bottom of the page and
22136 moved it to the margin instead). All the major functionality is the
22137 same as for the normal \cmd{\footnote}
22138 command.\footnote{\cs{sidefootnote} does not make sense inside
22139 minipages\dots}
22140 \begin{syntax}
22141 \cmd{\sidefootnote}\oarg{num}\marg{text}\\
22142 \cmd{\sidefootnotemark}\oarg{num}\\
22143 \cmd{\sidefootnotetext}\oarg{num}\marg{text}\\
22144 \end{syntax}
22145
22146 By default the regular footnotes and the side footnotes use different
22147 counters. If one would like them to use the same counter, issue the
22148 following in the preamble:
22149 \begin{lcode}
22150 \letcountercounter{sidefootnote}{footnote}
22151 \end{lcode}
22152
22153
22154 \subsection{Setting the layout for
22155 \texorpdfstring{\cs{sidefootnote}}{sidefootnote}}
22156 \label{sec:sett-layo-texorpdfst}
22157
22158
22159
22160 There are several possibilities to change the appearance of the
22161 \cmd{\sidefootnote}:
22162
22163 Specifying the margin in which the side footnote should go, is done by
22164 \begin{syntax}
22165 \cmd{\sidefootmargin}\marg{keyword}\\
22166 \end{syntax}
22167 where \meta{keyword} can be \emph{left}, \emph{right}, \emph{outer}, and
22168 \emph{inner}, and their meaning is explained in
22169 \fref{fig:xmargin}. The default is \emph{outer}.
22170
22171 \begin{syntax}
22172 \lnc{\sidefoothsep}\\
22173 \lnc{\sidefootwidth}\\
22174 \lnc{\sidefootvsep}\\
22175 \end{syntax}
22176 \cmd{\sidefoothsep} is a length controlling the separation from the
22177 text to the side footnote column, default
22178 \cmd{\marginparsep}. \cmd{\sidefootwidth} is length controlling the
22179 width of the side footnote column, default \cmd{\marginparwidth}, and
22180 \cmd{\sidefootvsep} is the vertical distance between two side
22181 footnotes, default \cmd{\onelineskip}.
22182
22183 \begin{syntax}
22184 \lnc{\sidefootadjust}\\
22185 \cmd{\setsidefootheight}\marg{height}\\
22186 \cmd{\sidefootfont}\\
22187 \end{syntax}
22188 \cmd{\sidefootadjust} is a length which specifies the placement of the
22189 side footnote column in relation to the bottom of the text block, the
22190 default is 0pt. \cmd{\setsidefootheight} sets the maximal height of
22191 the side footnote column, default \cmd{textwidth}. Lastly
22192 \cmd{\sidefootfont} holds the general font setting for the side
22193 footnote,\footnote{There is a similar macro to control the font of the
22194 text alone.} default \verb?\normalfont\footnotesize?.
22195
22196
22197 The macro
22198 \begin{syntax}
22199 \cmd{\setsidefeet}\marg{hsep}\marg{width}\marg{vsep}\marg{adj}\marg{font}\marg{height}\\
22200 \end{syntax}
22201 sets the specifications all six settings above in one go.. An `*'
22202 means `use the current value'. So \theclass\ internally use the
22203 following default
22204 \begin{lcode}
22205 \setsidefeet{\marginparsep}{\marginparwidth}%
22206 {\onelineskip}{0pt}%
22207 {\normalfont\footnotesize}{\textheight}%
22208 \end{lcode}
22209 It is recommended to use this macro along with the other macros in the
22210 preamble to specify document layout.
22211
22212 \subsection{Styling
22213 \texorpdfstring{\cs{sidefootnote}}{sidefootnote}}
22214
22215
22216 \begin{syntax}
22217 \cmd{\sidefootmarkstyle}\marg{code}\\
22218 \end{syntax}
22219 controls how the side footnote counter is typeset in the side
22220 footnote. The default is
22221 \begin{lcode}
22222 \sidefootmarkstyle{\textsuperscript{#1}}
22223 \end{lcode}
22224
22225 The mark is typeset in a box of width \lnc{\sidefootmarkwidth}
22226 If this is negative, the mark is outdented
22227 into the margin, if zero the mark is flush left, and when positive
22228 the mark is indented. The mark is followed by the
22229 text\index{side footnote!text} of the footnote. Second and later lines of the
22230 text are offset by the length \lnc{\sidefootmarksep} from the end of the box.
22231 The first line of a paragraph within a footnote is indented by
22232 \lnc{\sidefootparindent}. The default values for these lengths are:
22233 \begin{lcode}
22234 \setlength{\sidefootmarkwidth}{0em}
22235 \setlength{\sidefootmarksep}{0em}
22236 \setlength{\sidefootparindent}{1em}
22237 \end{lcode}
22238
22239
22240 \fancybreak{}
22241
22242 Caveat: It is natural to specify a length as \lnc{\sidefootparindent}
22243 as a \LaTeX\ length, but it has a down side. If, as we do here, set
22244 the value to 1em, then since the size of the em unit changes with the
22245 current font size, one will actually end up with an indent
22246 corresponding to the font size being used when the
22247 \begin{lcode}
22248 \setlength{\sidefootparindent}{1em}
22249 \end{lcode}
22250 was issued, not when it has used (where the font size most often will
22251 be \cmd{\footnotesize}).
22252
22253 At this point we consider this to be a \emph{feature} not an
22254 error. One way to get pass this problem it the following
22255 \begin{lcode}
22256 \begingroup% keep font change local
22257 \sidefoottextfont
22258 \global\setlength\sidefootparindent{1em}
22259 \endgroup
22260 \end{lcode}
22261 Then it will store the value of em corresponding to the font being
22262 used.
22263
22264
22265 \LMnote{2010/02/07}{explained the rest, left the side footnote hook
22266 out of it for now}
22267 \begin{syntax}
22268 \cmd{\sidefoottextfont}\\
22269 \end{syntax}
22270 holds the font being used by the side footnote, default
22271 \verb+\normalfont\footnotesize+.
22272 \begin{syntax}
22273 \cmd{\sidefootform}\\
22274 \end{syntax}
22275 is used to specify the raggedness of the text. Default
22276 \begin{lcode}
22277 \newcommand*{\sidefootform}{\rightskip=\z@ \@plus 2em}
22278 \end{lcode}
22279 which is much like \cs{raggedright} but allows some hyphenation. One
22280 might consider using
22281 \begin{lcode}
22282 \usepackage{ragged2e}
22283 \newcommand*{\sidefootform}{\RaggedRight}
22284 \end{lcode}
22285 Which does something similar.
22286
22287
22288
22289
22290
22291 \subsection{Side footnote example}
22292 \label{sec:side-footn-example}
22293
22294
22295
22296 In the margin you will find the result of the following code:
22297 \begin{verbatim}
22298 Testing\sidefootnote{This is test} bottom aligned
22299 footnotes.\sidefootnote{This is another side
22300 footnote, spanning several lines.
22301
22302 And several paragraphs}\sidefootnote{And number three}
22303 \end{verbatim}
22304 Testing\sidefootnote{This is test} bottom aligned
22305 footnotes.\sidefootnote{This is another side
22306 footnote, spanning several lines.
22307
22308 And several paragraphs}\sidefootnote{And number three}
22309
22310
22311 \LMnote{2013/05/02}{Moved here from backmatter.tex}
22312
22313 \section{Endnotes}
22314 \label{sec:endnotes}
22315
22316 \LMnote{2010/10/28}{several \cs{printpagenotes} was spelled wrong}
22317
22318 % \reimplemented{December 2010}{The former implementation had some
22319 % difficulties handling certain types of input. A few of the macros
22320 % used to format the output are no longer supported/used in the new
22321 % implementation.}
22322
22323
22324 Endnotes are often used instead of footnotes so as not to interrupt the
22325 flow of the main text. Although endnotes are normally put at the end of
22326 the document, they may instead be put at the end of each chapter.
22327
22328 The \Lpack{endnotes} package already uses the command \cmd{\endnote} for
22329 an endnote, so the class uses \cmd{\pagenote} for an endnote so as not
22330 to clash if you prefer to use the package.
22331 \LMnote{2011/01/23}{The implementation has nothing to do with the
22332 current pagenote package, thus the remark is removed}
22333 % The following was originally supplied as the \Lpack{pagenote}
22334 % package~\cite{PAGENOTE}.
22335
22336 \begin{syntax}
22337 \cmd{\makepagenote} \\
22338 \cmd{\pagenote}\oarg{id}\marg{text} \\
22339 \cmd{\printpagenotes} \cmd{\printpagenotes*} \\
22340 \end{syntax}
22341 \glossary(makepagenote)%
22342 {\cs{makepagenote}}%
22343 {Preamble command for enabling page/end notes.}%
22344 \glossary(printpagenotes)%
22345 {\cs{printpagenotes}}%
22346 {Input the pagenote \file{ent} file for printing, then close it to any
22347 more notes.}%
22348 \glossary(printpagenotes*)%
22349 {\cs{printpagenotes*}}%
22350 {Input the pagenote \file{ent} file for printing, then empty it ready for
22351 further notes.}%
22352
22353 The general principle is that notes are written out to a file which
22354 is then input at the place where the notes are to be printed. The note
22355 file has an \pixfile{ent} extension, like the table of contents file
22356 has a \pixfile{toc} extension.
22357
22358 You have to put \cmd{\makepagenote} in your preamble if you want
22359 endnotes. This will open the \pixfile{ent} note file which is called
22360 \verb?\jobname.ent?.
22361
22362 In the body of the text use use \cmd{\pagenote} to create an endnote, just
22363 as you would use \cmd{\footnote} to create a footnote. In the books that I have
22364 checked there are two common methods of identifying an endnote:
22365 \begin{enumerate}
22366 \item Like a footnote, put a number in the text at the location
22367 of the note and use the same number to identify the note when it
22368 finally gets printed.\label{pagenote:id1}
22369 \item Put no mark in the text, but when it is finally
22370 printed\pagenote[Put no mark \ldots finally printed]{This manual uses
22371 both footnotes and endnotes. For identifying the endnotes I have used the
22372 `words' method for identifying the parent location of an endnote, so as not
22373 to start confusing the reader with two sets of note marks in the body of the
22374 text. Typically either footnotes or endnotes are used, not both, so the
22375 question of distinguishing them does not normally arise.}
22376 use a few words from the text to identify the origin of the note. The page number
22377 is often used as well with this method.\label{pagenote:id2}
22378 \end{enumerate}
22379 The \meta{text} argument of \cmd{\pagenote} is the contents of the note and
22380 if the optional \meta{id} argument is not used the
22381 result is similar to having used \cmd{\footnote} --- a number in the main text
22382 and the corresponding number in the endnotes listing (as
22383 in \ref{pagenote:id1} above). For the second reference style
22384 (\ref{pagenote:id2} above) use the
22385 optional \meta{id} argument for the `few words', and no mark will be put
22386 into the main text but \meta{id} will be used as the identification in
22387 the listing.
22388
22389 \begin{note}
22390 If you ever look into the \texttt{.ent} file, you'll notice that it
22391 is very long and that every space in the note text has been
22392 converted into line breaks. This is done to get a round an upper
22393 limit as to how long a line of input can be in \TeX. Some users
22394 wrote so long notes that they hit the limit, this is our solution to
22395 the problem.
22396 \end{note}
22397
22398
22399 For one set of endnotes covering the whole document put
22400 \cmd{\printpagenotes} where you want them printed, typically before
22401 any bibliography or index. The \cmd{\printpagenotes} macro inputs the
22402 \pixfile{ent} endnote file for printing and then closes it to any further
22403 notes.
22404
22405 For notes
22406 at the end of each chapter put \cmd{\printpagenotes*}, which inputs
22407 the \pixfile{ent} file for printing then empties it ready for more notes,
22408 at the end of each chapter.
22409
22410 The simple use is like this:
22411 \begin{lcode}
22412 \documentclass[...]{memoir}
22413 ...
22414 \makepagenote
22415 ...
22416 \begin{document}
22417 \chapter{One}
22418 ...\pagenote{An end note.} ...
22419 ...\pagenote{Fascinating information.}
22420 ...
22421 \chapter{Last}% chapter 9
22422 ...\pagenote{Another note.}% 30th note
22423 ...
22424 ...
22425 \printpagenotes
22426 ...
22427 \end{document}
22428 \end{lcode}
22429 This will result in an endnote listing looking like \fref{fig:endnote}.
22430
22431 \begin{figure}
22432 \centering
22433 \begin{minipage}{0.8\textwidth}
22434 \begin{framed}
22435 \noindent{\bfseries\Large Notes}\\[\baselineskip]
22436 {\bfseries Chapter 1 One} \\[\baselineskip]
22437 1. An end note \\
22438 2. Fascinating information. \\
22439 .............. \\[\baselineskip]
22440 {\bfseries Chapter 9 Last} \\[\baselineskip]
22441 1. Another note \\[\baselineskip]
22442 \end{framed}
22443 \end{minipage}
22444 \caption{Example endnote listing}\label{fig:endnote}
22445 \end{figure}
22446
22447 For notes at the end of each chapter:
22448 \begin{lcode}
22449 \documentclass[...]{memoir}
22450 ...
22451 \makepagenote
22452 ...
22453 \begin{document}
22454 \chapter{One}
22455 ...\pagenote{An end note.} ...
22456 ...
22457 \printpagenotes*
22458 \chapter{Last}
22459 ...\pagenote{Another note.} ...
22460 ...
22461 \printpagenotes*
22462 %%% no more chapters
22463 ...
22464 \end{document}
22465 \end{lcode}
22466
22467 \begin{syntax}
22468 \cmd{\continuousnotenums} \\
22469 \cmd{\notepageref} \\
22470 \end{syntax}
22471 \glossary(continuousnotenums)%
22472 {\cs{continuousnotenums}}%
22473 {Declaration to make the numbering of endnotes continuous throughout the
22474 document.}%
22475 \glossary(notepageref)%
22476 {\cs{notepageref}}%
22477 {Declaration that page numbers are available to notes in the endnote listing.}
22478 The \Icn{pagenote} counter is used for the notes. By default the endnotes
22479 are numbered per chapter. If you want the numbering
22480 to be continuous throughout the document use the \cmd{\continuousnotenums}
22481 declaration. Normally the information on which page a note was created is
22482 discarded but will be made available to notes in the endnote listing
22483 following the \cmd{\notepageref} declaration. Both
22484 \cmd{\continuousnotenums} and \cmd{\notepageref} can only be used in
22485 the preamble.
22486
22487 \LMnote{2011/01/23}{Because of the new implementation this is no
22488 longer needed as the writing to file is no longer delayed.}
22489 % Because of how TeX writes information to files, when the
22490 % \cmd{\notepageref} declaration is used there must be no notes on the
22491 % page where \cmd{\printpagenotes} or \cmd{\printpagenotes*} closes the
22492 % \pixfile{ent} file. If necessary, a \cmd{\clearpage} or similar must
22493 % be used before the print command.
22494
22495 \begin{syntax}
22496 \cmd{\notesname} \\
22497 \cmd{\notedivision} \\
22498 \end{syntax}
22499 \glossary(notesname)%
22500 {\cs{notesname}}%
22501 {Name for endnotes, default \texttt{Notes}.}%
22502 \glossary(notedivision)%
22503 {\cs{notedivision}}%
22504 {Heading printed by the \cs{printpagenotes} and \cs{printpagenotes*} macros.}
22505
22506 When \cmd{\printpagenotes} (or \cmd{\printpagenotes*}) is called the
22507 first thing it does is call the macro \cmd{\notedivision}. By
22508 default this is defined as:
22509 \begin{lcode}
22510 \newcommand*{\notedivision}{\chapter{\notesname}}
22511 \end{lcode}
22512 with
22513 \begin{lcode}
22514 \newcommand*{\notesname}{Notes}
22515 \end{lcode}
22516 In other words, it will print out a heading for the notes that will be read
22517 from the \file{ent} file. \verb?\print...? then closes the \pixfile{ent} file
22518 for writing and after this \verb?\input?s it to get and process the notes.
22519
22520
22521 \subsection{Changing the appearance}
22522
22523 \subsubsection{In the text}
22524 \label{sec:in-the-text}
22525
22526
22527 \begin{syntax}
22528 \cmd{\notenumintext}\marg{num} \\
22529 \end{syntax}
22530 \glossary(notenumintext)%
22531 {\cs{notenumintext}\marg{num}}%
22532 {Typesets the number \meta{num} of a page note in the main text.}%
22533 The \Icn{pagenote} counter is used for pagenotes. The macro
22534 \cmd{\notenumintext} is called by \cmd{\pagenote} with the value of the
22535 \Icn{pagenote} counter as the \meta{num} argument to print the
22536 value of the \Icn{pagenote} counter in the main text. By default it is
22537 printed as a
22538 superscript, but this can be changed, or even eliminated.
22539 \begin{lcode}
22540 \newcommand*{\notenumintext}[1]{\textsuperscript{#1}}
22541 \end{lcode}
22542
22543 \subsubsection{In the page note list}
22544 \label{sec:page-note-list}
22545
22546
22547 \LMnote{2011/01/23}{Added to make the formating code easier to understand}
22548
22549 To better understand how a page note entry is formatted in the page
22550 note list, we start with the following pseudo code (it is not exactly
22551 what you will see in the \texttt{.ent} file, but macros will end up
22552 being called in this manner)
22553 \begin{syntax}
22554 \cmd{\prenoteinnotes}\\
22555 \cmd{\noteidinnotes}\marg{notenum}\marg{id}\\
22556 \cmd{\pageinnotes}\marg{auto generated note label key}\\
22557 \cmd{\prenotetext}\\
22558 \quad\meta{Page note text}\\
22559 \cmd{\postnotetext}\\
22560 \cmd{\postnoteinnotes}
22561 \end{syntax}
22562 At the start and end we have the two macros \cmd{\prenoteinnotes} and
22563 \cmd{\postnoteinnotes}, they take care of preparing for and ending an
22564 entry in the list. The list is typeset in a manner where each item is
22565 (at least) a paragraph, so the default definition is
22566 \begin{lcode}
22567 \newcommand{\prenoteinnotes}{\par\noindent}
22568 \newcommand{\postnoteinnotes}{\par}
22569 \end{lcode}
22570 \glossary(prenoteinnotes)%
22571 {\cs{prenoteinnotes}}%
22572 {Called by \cs{noteentry} to initialise the printing of an endnote.}%
22573 \glossary(postnoteinnotes)%
22574 {\cs{postnoteinnotes}}%
22575 {Called by \cs{noteentry} to finish the printing of an endnote.}%
22576 A user could change this to make it look a bit more like a list
22577 construction. For example the following would give a hanging
22578 indentation
22579 \begin{lcode}
22580 \renewcommand{\prenoteinnotes}{\par\noindent\hangindent 2em}
22581 \end{lcode}
22582
22583 \fancybreak{}
22584
22585
22586 The \cmd{\noteidinnotes} calls \cmd{\idtextinnotes} to print the note \meta{id}
22587 if it was given as the optional argument to \cmd{pagenote},
22588 otherwise it calls \cmd{\notenuminnotes} to print the note number.
22589 \begin{syntax}
22590 \cmd{\noteidinnotes}\marg{notenum}\marg{id} \\
22591 \cmd{\idtextinnotes}\marg{id} \\
22592 \cmd{\notenuminnotes}\marg{num} \\
22593 \end{syntax}
22594 \glossary(noteidinnotes)%
22595 {\cs{noteidinnotes}\marg{notenum}\marg{id}}%
22596 {Prints an endnote's number or id in the endnote listing.}%
22597 \glossary(idtextinnotes)%
22598 {\cs{idtextinnotes}\marg{id}}%
22599 {Prints an endnote's \meta{id} text}%
22600 \glossary(notenuminnotes)%
22601 {\cs{notenuminnotes}\marg{num}}%
22602 {Typesets the number \meta{num} of a page note in the note listing.}%
22603 These are defined respectively as:
22604 \begin{lcode}
22605 \newcommand*{\idtextinnotes}[1]{[#1]\space}
22606 \newcommand*{\notenuminnotes}[1]{\normalfont #1.\space}
22607 \end{lcode}
22608
22609 \fancybreak{}
22610
22611 Next we execute \cmd{\pageinnotes}\marg{note label key} which does
22612 nothing by default. But if \cmd{\notepageref} is issued in the
22613 preamble two things happen, (1) each page note issues a label such
22614 that we can refer back to its page, and (2) \cmd{\pageinnotes} calls
22615 \cmd{\printpageinnotes} (or if \Lpack{hyperref} is loaded
22616 \cmd{\printpageinnoteshyperref})
22617 \begin{syntax}
22618 \cmd{\pageinnotes}\marg{auto generated note label key}\\
22619 \cmd{\printpageinnotes}\marg{auto generated note label key}\\
22620 \cmd{\printpageinnoteshyperref}\marg{auto generated note label key}\\
22621 \cmd{\pagerefname}
22622 \end{syntax}
22623 \glossary(pageinnotes)%
22624 {\cs{pageinnotes}\marg{pagenum}}%
22625 {Controls the printing of an endnote's page reference number.}%
22626 \glossary(printpageinnotes)%
22627 {\cs{printpageinnotes}\marg{pagenum}}%
22628 {Prints an endnote's page reference number.}%
22629 \glossary(printpageinnoteshypreref)%
22630 {\cs{printpageinnoteshyperref}\marg{pagenum}}%
22631 {Prints an endnote's page reference number whenever the
22632 \protect\Lpack{hyperref} package is used, it will include a
22633 hyperlink back to the page in question.}%
22634 \glossary(pagerefname)%
22635 {\cs{pagerename}}%
22636 {Holds the name prefix when referring to a page number, defaults to \texttt{page}.}%
22637 Default definitions
22638 \begin{lcode}
22639 \newcommand*{\printpageinnotes}[1]{%
22640 (\pagerefname\ \pageref{#1})\space}
22641 \newcommand\printpageinnoteshyperref[1]{%
22642 (\hyperref[#1]{\pagerefname\ \pageref*{#1}})\space}
22643 \end{lcode}
22644 That is if \Lpack{hyperref} is loaded the entire text \meta{page 3}
22645 will be the text of a hyperlink.
22646
22647 \bigskip
22648
22649 \begin{syntax}
22650 \cmd{\prenotetext}\\
22651 \cmd{\postnotetext}\\
22652 \end{syntax}
22653 \glossary(prenotetext)%
22654 {\cs{prenotetext}}%
22655 {Called within a page note list entry to initialise the printing
22656 of the text part of an endnote.}%
22657 \glossary(postnotetex)%
22658 {\cs{postnotetext}}%
22659 {Called within a page note list entry to finish the printing of an
22660 endnote.}%
22661 The actual text part of the page note is enclosed by
22662 \cmd{\prenotetext} and \cmd{postnotetext}. By default they do nothing,
22663 but could easily be redefined such that (only) the entry text would be
22664 in italic:
22665 \begin{lcode}
22666 \renewcommand\prenotetext{\begingroup\itshape}
22667 \renewcommand\postnotetext{\endgroup}
22668 \end{lcode}
22669
22670
22671
22672 %%%%%%%%%%%
22673
22674
22675 \LMnote{2011/01/25}{Covered above}
22676 % \begin{syntax}
22677 % \cmd{\notenuminnotes}\marg{num} \\
22678 % \end{syntax}
22679 % \glossary(notenuminnotes)%
22680 % {\cs{notenuminnotes}\marg{num}}%
22681 % {Typesets the number \meta{num} of a page note in the note listing.}%
22682 % In the note listing \cmd{\notenuminnotes} is used to print the number
22683 % of a note. The default definitions are:
22684
22685 % \begin{lcode}
22686 % \newcommand*{\notenuminnotes}[1]{\normalfont #1.\space}
22687 % \end{lcode}
22688
22689
22690
22691 \LMnote{2011/01/25}{Covered above, \cmd{\noteentry} is not used anymore}
22692 % \begin{syntax}
22693 % \cmd{\noteentry}\marg{notenum}\marg{id}\marg{text}\marg{pagenum} \\
22694 % \cmd{\prenoteinnotes} \\
22695 % \cmd{\postnoteinnotes} \\
22696 % \end{syntax}
22697 % \glossary(noteentry)%
22698 % {\cs{noteentry}\marg{notenum}\marg{id}\marg{text}\marg{pagenum}}%
22699 % {Typesets a pagenote with number \meta{notenum}, identifier \meta{id},
22700 % contents \meta{text}, created on page \meta{pagenum}.}
22701 % \glossary(prenoteinnotes)%
22702 % {\cs{prenoteinnotes}}%
22703 % {Called by \cs{noteentry} to initialise the printing of an endnote.}
22704 % \glossary(postnoteinnotes)%
22705 % {\cs{postnoteinnotes}}%
22706 % {Called by \cs{noteentry} to finish the printing of an endnote.}
22707 % The \cmd{\pagenote} macro writes \cmd{\noteentry}, with the appropriate
22708 % values for the arguments, to the \pixfile{ent} file,
22709 % where \meta{notenum} is the note number (from the \Icn{pagenote} counter),
22710 % \meta{id} and \meta{text} are as supplied to
22711 % \cmd{\pagenote}, and if the \cmd{\notepageref} declaration option is used,
22712 % \meta{pagenum} is the page number, otherwise it is empty.
22713 % The \cmd{\noteentry} macro controls the typesetting of the note.
22714
22715 % The default definition of \cmd{\noteentry} is
22716 % \begin{lcode}
22717 % \newcommand{\notentry}[4]{%
22718 % \prenoteinnotes
22719 % \noteidinnotes{#1}{#2}\pageinnotes{#4}\noteinnotes{#3}%
22720 % \postnoteinnotes}
22721 % \end{lcode}
22722 % and the definitions of other macros are:
22723 % \begin{lcode}
22724 % \newcommand{\prenoteinnotes}{\par\noindent}
22725 % \newcommand{\postnoteinnotes}{\par}
22726 % \end{lcode}
22727 % so that (the first paragraph of) each note is printed as a non-indented
22728 % paragraph.
22729
22730 % If you would prefer, say, hanging paragraphs try:
22731 % \begin{lcode}
22732 % \renewcommand{\prenoteinnotes}{\par\noindent\hangindent 2em}
22733 % \end{lcode}
22734
22735 % \begin{syntax}
22736 % \cmd{\noteidinnotes}\marg{notenum}\marg{id} \\
22737 % \cmd{\idtextinnotes}\marg{id} \\
22738 % \cmd{\notenuminnotes}\marg{num} \\
22739 % \end{syntax}
22740 % \glossary(noteidinnotes)%
22741 % {\cs{noteidinnotes}\marg{notenum}\marg{id}}%
22742 % {Prints an endnote's number or id in the endnote listing.}%
22743 % \glossary(idtextinnotes)%
22744 % {\cs{idtextinnotes}\marg{id}}%
22745 % {Prints an endnote's \meta{id} text}%
22746 % The \cmd{\noteidinnotes} calls \cmd{\idtextinnotes} to print the note \meta{id}
22747 % if it was given as the optional argument to \cmd{pagenote},
22748 % otherwise it calls \cmd{\notenuminnotes} to print the note number.
22749 % These are defined respectively as:
22750 % \begin{lcode}
22751 % \newcommand*{\idtextinnotes}[1]{[#1]\space}
22752 % \newcommand*{\notenuminnotes}[1]{\normalfont #1.\space}
22753 % \end{lcode}
22754
22755 % \begin{syntax}
22756 % \cmd{\pageinnotes}\marg{pagenum} \\
22757 % \cmd{\printpageinnotes}\marg{pagenum} \\
22758 % \end{syntax}
22759 % \glossary(pageinnotes)%
22760 % {\cs{pageinnotes}\marg{pagenum}}%
22761 % {Controls the printing of an endnote's page reference number.}%
22762 % \glossary(printpageinnotes)%
22763 % {\cs{printpageinnotes}\marg{pagenum}}%
22764 % {Prints an endnote's page reference number.}%
22765 % The macro \cmd{\pageinnotes} controls the printing of a note's page
22766 % reference. If the
22767 % \cmd{\notepageref} declaration has been used it calls
22768 % \cmd{\printpageinnotes} to do the actual printing. Its definition is:
22769 % \begin{lcode}
22770 % \newcommand*{\printpageinnotes}[1]{%
22771 % (\pagerefname\ #1)\space}
22772 % \end{lcode}
22773
22774 % \begin{syntax}
22775 % \cmd{\noteinnotes}\marg{text} \\
22776 % \end{syntax}
22777 % \glossary(noteinnotes)%
22778 % {\cs{noteinnotes}\marg{text}}%
22779 % {Prints the text of an endnote.}%
22780 % The macro \cmd{\noteinnotes}\marg{text} is simply:
22781 % \begin{lcode}
22782 % \newcommand{\noteinnotes}[1]{#1}
22783 % \end{lcode}
22784 % and is used to print the text of a note.
22785
22786
22787
22788
22789 \bigskip
22790
22791
22792
22793 \LMnote{2011/01/25}{rewritten a bit}
22794 \begin{syntax}
22795 \cmd{\addtonotes}\marg{text} \\
22796 \end{syntax}
22797 \glossary(addtonotes)%
22798 {\cs{addtonotes}\marg{text}}%
22799 {Inserts \meta{text} into the endnotes \file{ent} file.}%
22800 The macro \cmd{\addtonotes} inserts \meta{text} into the \pixfile{ent}
22801 file.
22802
22803 \begin{note}
22804 As the argument to \cmd{\pagenote} and \cmd{\addtonotes} is moving
22805 you may have to \cmd{\protect} any fragile commands. If you get
22806 strange error messages, try using \cmd{\protect} and see if they go
22807 away.
22808 \end{note}
22809 \fancybreak{}
22810
22811 Internally in \cmd{\pagenote} \cmd{\addtonotes} is used to provide
22812 chapter devisions into the note list. It will detect both numbered and
22813 unnumbered chapters. The actual text is provided using
22814 \begin{syntax}
22815 \cmd{\pagenotesubhead}\marg{chapapp}\marg{num}\marg{title} \\
22816 \cmd{\pagenotesubheadstarred}\marg{chapapp}\marg{num}\marg{title} \\
22817 \cmd{\pnchap} \cmd{\pnschap} \\
22818 \end{syntax}
22819 \glossary(pagenotesubhead)%
22820 {\cs{pagenotesubhead}\marg{chapapp}\marg{num}\marg{title}}%
22821 {Typesets a subheading for notes from chapter or appendix \meta{chapapp}
22822 \meta{num} called \meta{title}.}%
22823 \glossary(pagenotesubheadstarred)%
22824 {\cs{pagenotesubheadstarred}\marg{chapapp}\marg{num}\marg{title}}%
22825 {Typesets a subheading for notes from unnumbered chapter or appendix
22826 \meta{chapapp} \meta{num} called \meta{title}.}%
22827 \glossary(pnchap)%
22828 {\cs{pnchap}}%
22829 {Chapter title for \cs{pagenotesubhead}. Defaults to the ToC entry.}
22830 \glossary(pnschap)%
22831 {\cs{pnschap}}%
22832 {Starred chapter title for \cs{pagenotesubhead}. Defaults to the regular title.}
22833
22834 The macro \cmd{\pagenotesubhead} typesets the subheadings in an
22835 endnote list. The \meta{chapapp} argument is normally
22836 \cmd{\chaptername} but if the notes are from an appendix then
22837 \cmd{\appendixname} is used instead. \meta{num} is the number of the
22838 chapter, or blank if there is no number. Lastly, \meta{title} is
22839 \cmd{\pnchap} for regular chapters which defaults to the ToC entry, or
22840 \cmd{\pnschap} for starred chapters which defaults to the normal
22841 title. The default definition of \cmd{\pagenotesubhead} is very
22842 simply:
22843 \begin{lcode}
22844 \newcommand*{\pagenotesubhead}[3]{%
22845 \section*{#1 #2 #3}}
22846 \newcommand\pagenotesubheadstarred{\pagenotesubhead} % i.e. the same
22847 \end{lcode}
22848 By default this means that the header for starred chapters will be
22849 something like >>Chapter Title<<, which may look odd. In that case
22850 redefine \cmd{\pagenotesubheadstarred} to something similar to
22851 \begin{lcode}
22852 \renewcommand\pagenotesubheadstarred[3]{\section*{#3}}
22853 \end{lcode}
22854 Just remember that unless you have specified \cmd{\continuousnotenums}
22855 in the preamble the note counter (\Icn{pagenote}) will only be reset
22856 at the start of any numbered chapters (because it is tied to changes
22857 in the chapter counter).
22858
22859 The scheme is set up under the assumption that notes will only be
22860 printed at the end of the document. If you intend to put them at the
22861 end of each chapter, then you will probably want to change the
22862 definitions of the \cmd{\notedivision} and \cmd{\pagenotesubhead}
22863 macros. For example:
22864 \begin{lcode}
22865 \renewcommand*{\notedivision}{\section*{\notesname}}
22866 \renewcommand*{\pagenotesubhead}[3]{}
22867 \end{lcode}
22868 and remember to use \cmd{\printpagenotes*} at each place you want the
22869 current set of notes to be printed.
22870
22871 \fancybreak{}
22872
22873 Say you have written a document with footnotes, but later on decide on
22874 using end notes (page notes) instead. In that case you can use
22875 \cmd{\foottopagenote} to make \cmd{\footnote}, \cmd{\footnotemark} and
22876 \cmd{\footnotetext} works as if it was implemented using end notes. On
22877 the other hand \cmd{\pagetofootnote} makes all page notes into
22878 footnotes (note that this might not work, because there are places
22879 where page notes can be issued but foot notes cannot).
22880
22881 \begin{syntax}
22882 \cmd{\foottopagenote}\\ \cmd{\pagetofootnote} \\
22883 \end{syntax}
22884 \glossary(foottopagenote)%
22885 {\cs{foottopagenote}}%
22886 {Declaration which turns \cs{footnote}s into \cs{pagenote}s.}%
22887 \glossary(pagetofootnote)%
22888 {\cs{pagetofootnote}}%
22889 {Declaration which turns \cs{pagenote}s into \cs{footnote}s.}%
22890 % You can have both footnotes and endnotes in the same
22891 % document. However you may start with all footnotes and later
22892 % decide you would have preferred endnotes instead, or
22893 % \emph{vice-versa}. The \cmd{\foottopagenote} declaration makes
22894 % \cmd{\footnote}s behave as \cmd{\pagenote}s, and
22895 % \cmd{\pagetofootnote} has the opposite effect.
22896 In either conversion the optional argument will be
22897 ignored as for \cmd{\pagenote} it can be arbitrary text whereas for
22898 \cmd{\footnote} it must be a number.
22899
22900
22901
22902
22903
22904
22905 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
22906 %%%% start membook
22907
22908
22909 %#% extend
22910 %#% extstart include decorative-text.tex
22911
22912 \svnidlong
22913 {$Ignore: $}
22914 {$LastChangedDate: 2013-04-24 17:14:15 +0200 (Wed, 24 Apr 2013) $}
22915 {$LastChangedRevision: 442 $}
22916 {$LastChangedBy: daleif $}
22917
22918
22919 %%%%% end membook
22920 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
22921
22922
22923
22924
22925
22926
22927 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
22928 \clearpage
22929 %%%\pagestyle{companion}
22930 %%\chapterstyle{companion}
22931 \defaultsecnum
22932 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
22933 \chapter{Decorative text} \label{chap:signposts}
22934
22935
22936 \newcommand{\tepi}[2]{\epigraph{#1}{#2}}
22937
22938 % \tepi{My soul, seek not the life of immortals; but enjoy to the full
22939 % the resources that are within your reach}
22940 % {\textit{Pythian Odes \\ Pindar}}
22941 \tepi{Too servile a submission to the books and opinions of the ancients
22942 has spoiled many an ingenious man, and plagued the world with an
22943 abundance of pedants and coxcombs.}
22944 {James Puckle (1677?--1724)}
22945
22946
22947 By now we have covered most aspects of typesetting. As far as
22948 the class is concerned this chapter describes the slightly more fun
22949 task of typesetting epigraphs\index{epigraph}.
22950
22951 Some authors like to add an interesting quotation\index{quotation}
22952 at either the start or end of a chapter. The class provides commands
22953 to assist in the typesetting of a single epigraph. Other authors like to
22954 add many such quotations\index{quotation} and the class provides
22955 environments to cater for these as well.
22956 Epigraphs can be typeset at either the left, the center or the right of
22957 the typeblock\index{typeblock}. A few example epigraphs are exhibited here, and
22958 others can be found in an article by
22959 Christina Thiele~\cite{TTC199} where she reviewed the \Lpack{epigraph}
22960 package~\cite{EPIGRAPH} which is included in the class.
22961
22962 \section{Epigraphs}
22963 \index{epigraph|(}
22964
22965 % \tepi{The whole is more than the sum of the parts.}
22966 % {\textit{Metaphysica \\ Aristotle}}
22967
22968 %\subsection{The \texttt{epigraph} command}
22969
22970 The original inspiration for \cmd{\epigraph} was Doug Schenck's
22971 for the epigraphs in our book~\cite{EBOOK}. That was hard wired for
22972 the purpose at hand. The version here provides much more flexibility.
22973
22974
22975 \begin{syntax}
22976 \cmd{\epigraph}\marg{text}\marg{source} \\
22977 \end{syntax}
22978 \glossary(epigraph)%
22979 {\cs{epigraph}\marg{text}\marg{source}}%
22980 {Typesets the \meta{text} and \meta{source} of an epigraph.}
22981 The command \cmd{\epigraph} typesets
22982 an epigraph using \meta{text} as the main text of the epigraph and
22983 \meta{source} being the original author (or book, article, etc.)
22984 of the quoted text. By default the epigraph is placed at the right hand
22985 side of the typeblock\index{typeblock}, and the \meta{source} is typeset at the bottom
22986 right of the \meta{text}.
22987
22988
22989 \begin{syntax}
22990 \senv{epigraphs} \\
22991 \cmd{\qitem}\marg{text}\marg{source} \\
22992 ... \\
22993 \eenv{epigraphs} \\
22994 \end{syntax}
22995 \glossary(epigraphs)%
22996 {\senv{epigraphs}}%
22997 {Environment for several epigraphs.}
22998 \glossary(qitem)%
22999 {\cs{qitem}\marg{text}\marg{source}}%
23000 {Typesets the \meta{text} and \meta{source} of an epigraph in an
23001 \texttt{epigrpahs} environment.}
23002 The \Ie{epigraphs} environment typesets a list of epigraphs, and by default
23003 places them at the right hand side of the typeblock\index{typeblock}.
23004 Each epigraph in an \Ie{epigraphs} environment is specified by a
23005 \cmd{\qitem} (analagous to the \cmd{\item}
23006 command in ordinary list environments).
23007 By default, the \meta{source} is typeset at the bottom right of the
23008 \meta{text}.
23009
23010
23011 \section{General}
23012
23013 \tepi{Example is the school of mankind, and they will learn at no other.}
23014 {\textit{Letters on a Regicide Peace}\\ \textsc{Edmund Burke}}
23015
23016 The commands described in this section apply to both the \cmd{\epigraph}
23017 command and the \Ie{epigraphs} environment. But first of all, note that an
23018 epigraph immediately after a heading\index{heading} will cause the
23019 first paragraph\index{paragraph!indentation}
23020 of the following text to be indented. If you want the initial paragraph
23021 to have no indentation, then start it with the \cmd{\noindent} command.
23022
23023 \begin{syntax}
23024 \lnc{\epigraphwidth} \\
23025 \cmd{\epigraphposition}\marg{flush} \\
23026 \end{syntax}
23027 \glossary(epigraphwidth)%
23028 {\cs{epigraphwidth}}%
23029 {Textwidth for epigraphs.}
23030 \glossary(epigraphposition)%
23031 {\cs{epigraphposition}\marg{flush}}%
23032 {Sets the horizontal placement of epigraphs.}
23033 The epigraphs are typeset in a minipage of width \lnc{\epigraphwidth}.
23034 The default value for this can be changed using the \cmd{\setlength} command.
23035 Typically, epigraphs are typeset in a measure much less than the width of
23036 the typeblock\index{typeblock}. The horizontal position of an epigraph
23037 in relation to the main typeblock is controlled by
23038 the \meta{flush} argument to the \cmd{\epigraphposition} declaration.
23039 The default value is \texttt{flushright}, so that epigraphs are set
23040 at the right hand side of the typeblock. This can be changed
23041 to \texttt{flushleft} for positioning at the left hand side or to
23042 \texttt{center} for positioning at the center of the
23043 typeblock\index{typeblock}.
23044
23045 \begin{syntax}
23046 \cmd{\epigraphtextposition}\marg{flush} \\
23047 \end{syntax}
23048 \glossary(epigraphtextposition)%
23049 {\cs{epigraphtextposition}\marg{flush}}
23050 {Sets the justification for epigraph text.}
23051 In order to avoid bad line breaks, the epigraph \meta{text} is normally
23052 typeset raggedright.
23053 The \meta{flush} argument to the \cmd{\epigraphtextposition}
23054 declaration controls the \meta{text} typesetting style. By default this is
23055 \texttt{flushleft} (which produces raggedright text). The sensible values
23056 are \texttt{center} for centered text, \texttt{flushright} for raggedleft
23057 text, and \texttt{flushleftright} for normal justified text.
23058
23059 If by any chance you want the \meta{text} to be typeset in some
23060 other layout style, the easiest
23061 way to do this is by defining a new environment which sets the paragraphing
23062 parameters to your desired values. For example, as the \meta{text} is
23063 typeset in a minipage, there is no paragraph indentation. If you
23064 want the paragraphs to be indented and justified then define
23065 a new environment like:
23066 \begin{lcode}
23067 \newenvironment{myparastyle}{\setlength{\parindent}{1em}}{}
23068 \end{lcode}
23069 and use it as:
23070 \begin{lcode}
23071 \epigraphtextposition{myparastyle}
23072 \end{lcode}
23073
23074 \begin{syntax}
23075 \cmd{\epigraphsourceposition}\marg{flush} \\
23076 \end{syntax}
23077 \glossary(epigraphsourceposition)%
23078 {\cs{epigraphsourceposition}\marg{flush}}%
23079 {Sets the placement of the source within an epigraph.}
23080 The \meta{flush} argument to the \cmd{\epigraphsourceposition}
23081 declaration controls the position
23082 of the \meta{source}.
23083 The default value is \texttt{flushright}. It can be changed to
23084 \texttt{flushleft}, \texttt{center} or \texttt{flushleftright}.
23085
23086 For example, to have epigraphs centered with the \meta{source} at the left,
23087 add the following to your document.
23088 \begin{lcode}
23089 \epigraphposition{center}
23090 \epigraphsourceposition{flushleft}
23091 \end{lcode}
23092
23093 \begin{syntax}
23094 \cmd{\epigraphfontsize}\marg{fontsize} \\
23095 \end{syntax}
23096 \glossary(epigraphfontsize)%
23097 {\cs{epigraphfontsize}\marg{fontsize}}%
23098 {Font size to be used for epigraphs.}
23099 Epigraphs are often typeset in a smaller font than the main text. The
23100 \meta{fontsize} argument to the \cmd{\epigraphfontsize}
23101 declaration sets the font size to be used.
23102 If you don't like the default value (\cmd{\small}), you can easily change
23103 it to, say \cmd{\footnotesize} by:
23104 \begin{lcode}
23105 \epigraphfontsize{\footnotesize}
23106 \end{lcode}
23107
23108 \begin{syntax}
23109 \lnc{\epigraphrule} \\
23110 \end{syntax}
23111 \glossary(epigraphrule)%
23112 {\cs{epigraphrule}}%
23113 {Thickness of the rule drawn between the text and source of an epigraph.}
23114 By default, a rule is drawn between the \meta{text} and \meta{source},
23115 with the rule thickness being given by the value of \lnc{\epigraphrule}.
23116 The value can be changed by using \cmd{\setlength}.
23117 A value of \texttt{0pt} will eliminate the rule. Personally, I dislike
23118 the rule in the list environments.
23119
23120 \begin{syntax}
23121 \lnc{\beforeepigraphskip} \\
23122 \lnc{\afterepigraphskip} \\
23123 \end{syntax}
23124 \glossary(beforeepigraphskip)%
23125 {\cs{beforeepigraphskip}}%
23126 {Vertical space before an epigraph.}
23127 \glossary(afterepigraphskip)%
23128 {\cs{afterepigraphskip}}%
23129 {Vertical space after an epigraph.}
23130 The two \verb?...skip? commands specify the amount of vertical space inserted
23131 before and after typeset epigraphs. Again, these can be changed by
23132 \cmd{\setlength}. It is desireable that the sum of their values should be an
23133 integer multiple of the \lnc{\baselineskip}.
23134
23135 Note that you can use normal LaTeX commands in the \meta{text} and
23136 \meta{source} arguments. You may wish to use different fonts for the
23137 \meta{text} (say roman) and the \meta{source} (say italic).
23138
23139 The epigraph at the start of this section was specified as:
23140 \begin{lcode}
23141 \epigraph{Example is the school of mankind,
23142 and they will learn at no other.}
23143 {\textit{Letters on a Regicide Peace}\\ \textsc{Edmund Burke}}
23144 \end{lcode}
23145
23146 \section{Epigraphs before chapter headings}
23147
23148 \begingroup
23149 \epigraphsourceposition{flushleft}
23150 \tepi{If all else fails, immortality can always be assured by spectacular
23151 error.}
23152 {\textsf{John Kenneth Galbraith}}
23153 \endgroup
23154
23155 The \cmd{\epigraph} command and the \Ie{epigraphs} environment typeset
23156 an epigraph at the point in the text where they are placed. The
23157 first thing that a \cmd{\chapter} command does is to start off a new page,
23158 so another mechanism is provided for placing an epigraph just before
23159 a chapter heading\index{heading!chapter}.
23160
23161 \begin{syntax}
23162 \cmd{\epigraphhead}\oarg{distance}\marg{text} \\
23163 \end{syntax}
23164 \glossary(epigraphhead)%
23165 {\cs{epigraphhead}\oarg{distance}\marg{text}}%
23166 {Stores \meta{text} for printing at \meta{distance} below the page header.}
23167 The \cmd{\epigraphhead} macro stores \meta{text}
23168 for printing at \meta{distance} below the header\index{header} on a page.
23169 \meta{text} can be ordinary text or, more likely, can be either an
23170 \cmd{\epigraph} command or an \Ie{epigraphs} environment. By default, the
23171 epigraph will be typeset at the righthand margin\index{margin!right}.
23172 If the command is immediately preceded by a \cmd{\chapter} or \cmd{\chapter*}
23173 command, the epigraph is typeset on the chapter title page.
23174
23175 The default value for the optional \meta{distance} argument is set so
23176 that an \cmd{\epigraph} consisting of a single line of
23177 quotation\index{quotation} and a single
23178 line denoting the source is aligned with the bottom of the `Chapter X'
23179 line produced by the \cmd{\chapter} command using the \cstyle{default}
23180 chapterstyle. In other cases you will
23181 have to experiment with the \meta{distance} value. The value for
23182 \meta{distance} can be either a integer or a real number. The units
23183 are in terms of the current value for \lnc{\unitlength}. A typical value
23184 for \meta{distance} for a single line quotation\index{quotation} and
23185 source for a \cmd{\chapter*} might be about 70 (points). A positive value
23186 of \meta{distance} places the epigraph below the page heading and a negative
23187 value will raise it above the page heading.
23188
23189 Here's some example code:
23190 \begin{lcode}
23191 \chapter*{Celestial navigation}
23192 \epigraphhead[70]{\epigraph{Star crossed lovers.}{\textit{The Bard}}}
23193 \end{lcode}
23194 The \meta{text} argument is put into a minipage of width \lnc{\epigraphwidth}.
23195 If you use something other than \cmd{\epigraph} or \Ie{epigraphs} for the
23196 \meta{text} argument, you may have to do some positioning of the text
23197 yourself so that it is properly located in the minipage. For example
23198 \begin{lcode}
23199 \chapter{Short}
23200 \renewcommand{\epigraphflush}{center}
23201 \epigraphhead{\centerline{Short quote}}
23202 \end{lcode}
23203
23204 The \cmd{\epigraphhead} command changes the page style for the page on
23205 which it is specified, so there should be no text between the
23206 \cmd{\chapter} and the \cmd{\epigraphhead} commands. The page style
23207 is identical to the \pstyle{plain} page style except for the inclusion of
23208 the epigraph.
23209 If you want a more fancy style for epigraphed chapters you will have
23210 to do some work yourself.
23211
23212 \begin{syntax}
23213 \cmd{\epigraphforheader}\oarg{distance}\marg{text} \\
23214 \cmd{\epigraphpicture} \\
23215 \end{syntax}
23216 \glossary(epigraphforheader)%
23217 {\cs{epigraphforheader}\oarg{distance}\marg{text}}%
23218 {Puts \meta{text} into a zero-sized picture (\cs{epigraphpicture})
23219 at the coordinate position (0, -meta{distance}).}
23220 \glossary(epigraphpicture)%
23221 {\cs{epigraphpicture}}%
23222 {A zero-sized picture holding the result of \cs{epigraphforheader}.}
23223 The \cmd{\epigraphforheader} macro takes the same arguments as
23224 \cmd{\epigraphhead} but puts \meta{text} into a zero-sized picture at
23225 the coordinate position \verb?(0,-<distance>)?; the macro
23226 \cmd{\epigraphpicture}
23227 holds the resulting picture. This can then be used as part of a
23228 chapter pagestyle, as in
23229 \begin{lcode}
23230 \makepagestyle{mychapterpagestyle}
23231 ...
23232 \makeoddhead{mychapterpagestyle}{}{}{\epigraphpicture}
23233 \end{lcode}
23234 Of course the \meta{text} argument for \cs{epigraphforheader} need not
23235 be an \cs{epigraph}, it can be arbitrary text.
23236
23237 \begin{syntax}
23238 \cmd{\dropchapter}\marg{length} \\
23239 \cmd{\undodrop} \\
23240 \end{syntax}
23241 \glossary(dropchapter)%
23242 {\cs{dropchapter}\marg{length}}%
23243 {Lowers subsequent chapter heads by \meta{length}.}
23244 \glossary(undodrop)%
23245 {\cs{undodrop}}%
23246 {Following a \cs{dropchapter} restores subsequent chapter heads to their
23247 normal position.}
23248 If a long epigraph is placed before a chapter title it is possible that the
23249 bottom of the epigraph may interfere with the chapter title. The command
23250 \cmd{\dropchapter} will lower any subsequent chapter titles by
23251 \meta{length}; a negative \meta{length} will raise the titles.
23252 The command \cmd{\undodrop} restores subsequent chapter titles to their default
23253 positions. For example:
23254 \begin{lcode}
23255 \dropchapter{2in}
23256 \chapter{Title}
23257 \epigraphhead{long epigraph}
23258 \undodrop
23259 \end{lcode}
23260
23261 \index{epigraph|)}
23262
23263 \begin{syntax}
23264 \cmd{\cleartoevenpage}\oarg{text} \\
23265 \end{syntax}
23266 \glossary(cleartoevenpage)%
23267 {\cs{cleartoevenpage}\oarg{text}}%
23268 {Clears the current page and moves to the next verso page; the optional
23269 \meta{text} is put on the skipped page (if there is one).}
23270 On occasions it may be desirable to put something (e.g., an epigraph, a map,
23271 a picture) on the page facing the start
23272 of a chapter, where the something belongs to the chapter that is about to
23273 start rather than the chapter that has just ended. In order to do this
23274 in a document that is going to be printed
23275 doublesided, the chapter must start on an odd numbered page and the
23276 pre-chapter material put on the immediately preceding even numbered page.
23277 The \cmd{\cleartoevenpage} command is like \cmd{\cleardoublepage} except
23278 that the page following the command will be an even numbered page, and the
23279 command takes an optional argument
23280 which is applied to the skipped page (if any).
23281
23282 Here is an example:
23283 \begin{lcode}
23284 ... end previous chapter.
23285 \cleartoevenpage
23286 \begin{center}
23287 \begin{picture}... \end{picture}
23288 \end{center}
23289 \chapter{Next chapter}
23290 \end{lcode}
23291 If the style is such that chapter headings\index{heading!chapter} are put at the top of the pages,
23292 then it would be advisable to include \verb?\thispagestyle{empty}?
23293 (or perhaps \texttt{plain})
23294 immediately after \cmd{\cleartoevenpage} to avoid a heading related to the
23295 previous chapter from appearing on the page.
23296
23297 If the something is like a figure\index{figure} with a numbered caption and the numbering
23298 depends on the chapter numbering, then the numbers have to be hand set (unless
23299 you define a special chapter command for the purpose). For example:
23300 \begin{lcode}
23301 ... end previous chapter.
23302 \cleartoevenpage[\thispagestyle{empty}] % a skipped page to be empty
23303 \thispagestyle{plain}
23304 \addtocounter{chapter}{1} % increment the chapter number
23305 \setcounter{figure}{0} % initialise figure counter
23306 \begin{figure}
23307 ...
23308 \caption{Pre chapter figure}
23309 \end{figure}
23310
23311 \addtocounter{chapter}{-1} % decrement the chapter number
23312 \chapter{Next chapter} % increments chapter & resets figure numbers
23313 \addtocounter{figure}{1} % to account for pre-chapter figure
23314 \end{lcode}
23315
23316
23317 \subsection{Epigraphs on book or part pages}
23318
23319 \index{epigraph|(}
23320
23321 If you wish to put an epigraphs on \cmd{\book} or \cmd{\part}
23322 pages you have to do a little more work than in other cases. This
23323 is because these division commands do some page flipping before and
23324 after typesetting the title.
23325
23326 One method is to put the epigraph into the page header as for epigraphs
23327 before \cmd{\chapter} titles. By suitable adjustments the epigraph can be
23328 placed anywhere on the page, independently of whatever else is on the page.
23329 A similar scheme may be used for epigraphs on other kinds of pages.
23330 The essential
23331 trick is to make sure that the \pstyle{epigraph} pagestyle is used for
23332 the page.
23333 For an epigraphed bibliography\index{bibliography}
23334 or index\index{index}, the macros \cmd{\prebibhook}
23335 or \cmd{\preindexhook} can be appropriately modified to do this.
23336
23337 The other method is to subvert the \cmd{\beforepartskip} command
23338 for epigraphs before the title, or the \cmd{\afterpartskip} command
23339 for epigraphs after the title (or the equivalents for \cmd{\book} pages).
23340
23341 For example:
23342 \begin{lcode}
23343 \let\oldbeforepartskip\beforepartskip % save definition
23344 \renewcommand*{\beforepartskip}{%
23345 \epigraph{...}{...}% an epigraph
23346 \vfil}
23347 \part{An epigraphed part}
23348 ...
23349 \renewcommand*{\beforepartskip}{%
23350 \epigraph{...}{...}% another epigraph
23351 \vfil}
23352 \part{A different epigraphed part}
23353 ...
23354 \let\beforepartskip\oldbeforepartskip % restore definition
23355 \part{An unepigraphed part}
23356 ...
23357 \end{lcode}
23358
23359
23360 \index{epigraph|)}
23361
23362 %#% extend
23363 %#% extstart include poetry.tex
23364
23365 \svnidlong
23366 {$Ignore: $}
23367 {$LastChangedDate: 2024-02-06 16:53:11 +0100 (Tue, 06 Feb 2024) $}
23368 {$LastChangedRevision: 817 $}
23369 {$LastChangedBy: [email protected] $}
23370
23371 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
23372 %\clearpage
23373 %\pagestyle{Ruled}
23374 %%\chapterstyle{demo}
23375 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
23376
23377 \chapter{Poetry} \label{chap:verse}
23378
23379
23380 The typesetting of a poem should ideally be dependent on the
23381 particular poem. Individual problems do not usually admit of a
23382 general solution, so this manual and code should be used more
23383 as a guide towards some solutions rather than providing a ready
23384 made solution for any particular piece of verse.
23385
23386 The doggerel used as illustrative material has been taken
23387 from~\cite{RUMOUR}.
23388
23389 Note that for the examples in this section I have made no attempt
23390 to do other than use the minimal \alltx\ capabilities; in particular
23391 I have made no attempt to do any special page breaking so some stanzas
23392 may cross onto the next page --- most undesireable for publication.
23393
23394 \index{verse|(}
23395 \index{verse!typesetting environments|(}
23396
23397 The standard \ltx\ classes provide the \Ie{verse} environment which
23398 is defined as a particular kind of list. Within the environment you
23399 use \cmd{\\}\index{verse!end a line} to end a line,
23400 and a blank line will end\index{verse!end a stanza}\index{stanza!end} a
23401 stanza. For example, here is the text of a single stanza poem:
23402 \begin{lcode}
23403 \newcommand{\garden}{
23404 I used to love my garden \\
23405 But now my love is dead \\
23406 For I found a bachelor's button \\
23407 In black-eyed Susan's bed.
23408 }
23409 \end{lcode}
23410 \newcommand{\garden}{
23411 I used to love my garden \\
23412 But now my love is dead \\
23413 For I found a bachelor's button \\
23414 In black-eyed Susan's bed.
23415 }
23416 When this is typeset as a normal \ltx\ paragraph\index{paragraph}
23417 (with no paragraph indentation), i.e.,
23418 \begin{lcode}
23419 \noident\garden
23420 \end{lcode}
23421 it looks like: \\[\baselineskip]
23422 \garden{}
23423
23424 \vspace*{\onelineskip}
23425
23426 Typesetting it within the \Ie{verse} environment produces:% \\[\baselineskip]
23427
23428 \begin{verse}\index[lines]{I used to love my garden}
23429 \garden
23430 \end{verse}
23431
23432 %\ablankline
23433
23434 The stanza could also be typeset within the \Ie{alltt} environment, defined
23435 in the standard \Lpack{alltt} package~\cite{ALLTT},
23436 using a normal font and no \cmd{\\} line endings.
23437 \begin{lcode}
23438 \begin{alltt}\normalfont
23439 I used to love my garden
23440 But now my love is dead
23441 For I found a bachelor's button
23442 In black-eyed Susan's bed.
23443 \end{alltt}
23444 \end{lcode}
23445 which produces:
23446
23447 \begin{alltt}\normalfont
23448 I used to love my garden
23449 But now my love is dead
23450 For I found a bachelor's button
23451 In black-eyed Susan's bed.
23452 \end{alltt}
23453
23454 The \Ie{alltt} environment is like the \Ie{verbatim} environment except that
23455 you can use LaTeX macros inside it.
23456 In the \Ie{verse} environment long lines\index{verse!long lines}
23457 will be wrapped and indented
23458 but in the \Ie{alltt} environment there is no indentation.
23459
23460 Some stanzas have certain lines\index{verse!indent line} indented,
23461 often alternate ones. To
23462 typeset stanzas like this you have to add your own spacing. For
23463 instance:
23464 \begin{lcode}
23465 \begin{verse}
23466 There was an old party of Lyme \\
23467 Who married three wives at one time. \\
23468 \hspace{2em} When asked: `Why the third?' \\
23469 \hspace{2em} He replied: `One's absurd, \\
23470 And bigamy, sir, is a crime.'
23471 \end{verse}
23472 \end{lcode}
23473 is typeset as:
23474 \begin{verse}\index[lines]{There was an old party of Lyme}
23475 There was an old party of Lyme \\
23476 Who married three wives at one time. \\
23477 \hspace{2em} When asked: `Why the third?' \\
23478 \hspace{2em} He replied: `One's absurd, \\
23479 And bigamy, sir, is a crime.'
23480 \end{verse}
23481 \vspace{\onelineskip}
23482
23483 Using the \Ie{alltt} environment you can put in the spacing via ordinary
23484 spaces. That is, this:
23485 \begin{lcode}
23486 \begin{alltt}\normalfont
23487 There was an old party of Lyme
23488 Who married three wives at one time.
23489 When asked: `Why the third?'
23490 He replied: `One's absurd,
23491 And bigamy, sir, is a crime.'
23492 \end{alltt}
23493 \end{lcode}
23494 is typeset as
23495
23496 \begin{alltt}
23497 \normalfont
23498 There was an old party of Lyme
23499 Who married three wives at one time.
23500 When asked: `Why the third?'
23501 He replied: `One's absurd,
23502 And bigamy, sir, is a crime.'
23503 \end{alltt}
23504
23505 More exotically you could use the TeX \cmd{\parshape}
23506 command\footnote{See the \btitle{\tx book} for how to use this.}:
23507 \begin{lcode}
23508 \parshape = 5 0pt \linewidth 0pt \linewidth
23509 2em \linewidth 2em \linewidth 0pt \linewidth
23510 \noindent There was an old party of Lyme \\
23511 Who married three wives at one time. \\
23512 When asked: `Why the third?' \\
23513 He replied: `One's absurd, \\
23514 And bigamy, sir, is a crime.' \par
23515 \end{lcode}
23516 which will be typeset as:
23517
23518 \vspace*{\onelineskip}
23519
23520 \parshape = 5 0pt \linewidth 0pt \linewidth
23521 2em \linewidth 2em \linewidth 0pt \linewidth
23522 \noindent There was an old party of Lyme \\
23523 Who married three wives at one time. \\
23524 When asked: `Why the third?' \\
23525 He replied: `One's absurd, \\
23526 And bigamy, sir, is a crime.' \par
23527
23528
23529 \vspace*{\onelineskip}
23530
23531 This is about as much assistance as standard \alltx\ provides, except
23532 to note that in the \Ie{verse} environment the \cmd{\\*} version of \cmd{\\}
23533 will prevent\index{verse!prevent page break} a following page break.
23534 You can also make judicious use
23535 of the \cmd{\needspace} macro to keep things together.
23536
23537 \index{verse!typesetting environments|)}
23538
23539 Some books of poetry, and especially anthologies, have two or more
23540 indexes\index{index}\index{verse!multiple indexes}, one, say for the
23541 poem titles and another for the
23542 first lines, and maybe even a third for the poets' names.
23543 If you are not using \Lclass{memoir} then
23544 the \Lpack{index}~\cite{INDEX} and \Lpack{multind}~\cite{MULTIND}
23545 packages provide support for multiple indexes\index{index!multiple}
23546 in one document.
23547
23548 %\clearpage
23549 \section{Classy verse}
23550
23551 The code provided by the \Lclass{memoir} class is meant to help
23552 with some aspects of typesetting poetry but does not, and cannot,
23553 provide a comprehensive solution to all the requirements that
23554 will arise.
23555
23556 The main aspects of typesetting poetry that differ from typesetting
23557 plain text are:
23558 \begin{itemize}
23559 \item Poems are usually visually centered\index{verse!centering} on the page.
23560 \item Some lines\index{verse!indent line} are indented, and often there
23561 is a pattern\index{verse!indent pattern} to the indentation.
23562 \item When a line is too wide\index{verse!long line} for the page it is
23563 broken and the
23564 remaining portion indented with respect to the original start
23565 of the line.
23566 \end{itemize}
23567 These are the ones that the class attempts to deal with.
23568
23569 \begin{syntax}
23570 \senv{verse}\oarg{length} ... \eenv{verse} \\
23571 \lnc{\versewidth} \\
23572 \end{syntax}
23573 \glossary(verse)%
23574 {\senv{verse}\oarg{length}}%
23575 {Environment for typesetting verse; if given the midpoint of \meta{length}
23576 is placed at the center of the typeblock measure.}
23577 \glossary(versewidth)%
23578 {\cs{versewidth}}%
23579 {Scratch length, typically for use in verse typesetting.}
23580 The \Ie{verse} environment provided by the class is an extension
23581 of the usual LaTeX environment. The environment takes one optional
23582 parameter, which is a length; for example \verb?\begin{verse}[4em]?.
23583 You may have noticed that the earlier verse examples are all
23584 near the left margin\index{margin!left}, whereas verses usually look better
23585 if they
23586 are typeset about the center of the page. The length parameter,
23587 if given, should be about the length of an average line, and then
23588 the entire contents\index{verse!centering} will be typeset with the mid
23589 point of the length centered horizontally on the page.
23590
23591 The length \lnc{\versewidth} is provided as a convenience. It may be used,
23592 for example, to calculate the length of a line of text for use
23593 as the optional argument to the \Ie{verse} environment:
23594 \begin{lcode}
23595 \settowidth{\versewidth}{This is the average line,}
23596 \begin{verse}[\versewidth]
23597 \end{lcode}
23598
23599 \begin{syntax}
23600 \lnc{\vleftmargin} \\
23601 \end{syntax}
23602 \glossary(vleftmargin)%
23603 {\cs{vleftmargin}}%
23604 {General verse indent from the left of the typeblock.}
23605 In the basic \ltx\ \Ie{verse} environment the body of the verse is indented
23606 from the left of the typeblock by an amount \lnc{\leftmargini}, as is the
23607 text in many other environments based on the basic \ltx\ \Ie{list}
23608 environment. For the class's version of \Ie{verse} the default indent
23609 is set by the length \lnc{\vleftmargin} (which is initially set to
23610 \lnc{leftmargini}). For poems with particularly long
23611 lines\index{verse!long line} it could perhaps be
23612 advantageous to eliminate any general indentation by:
23613 \begin{lcode}
23614 \setlength{\vleftmargin}{0em}
23615 \end{lcode}
23616 If necessary the poem could even be moved into the left margin by giving
23617 \lnc{\vleftmargin} a negative length value, such as -1.5em.
23618
23619 \begin{syntax}
23620 \lnc{\stanzaskip} \\
23621 \end{syntax}
23622 \glossary(stanzaskip)%
23623 {\cs{stanzaskip}}%
23624 {Vertical space between verse stanzas.}
23625 The vertical space\index{stanza!space} between stanzas is the
23626 length \lnc{\stanzaskip}. It can be changed by the usual methods.
23627
23628 \begin{syntax}
23629 \cmd{\vin} \\
23630 \lnc{\vgap} \\
23631 \lnc{\vindent} \\
23632 \end{syntax}
23633 The command \cmd{\vin} is shorthand for \verb?\hspace*{\vgap}? for use
23634 at the start of an indented\index{verse!indent space} line of verse.
23635 The length \lnc{\vgap}
23636 (initially 1.5em) can be changed by \cmd{\setlength} or \cmd{\addtolength}.
23637 When a verse line\index{verse!long line} is too long to fit within the
23638 typeblock\index{typeblock} it is wrapped\index{verse!wrapped line indent}
23639 to the next line with an initial indent given by the value of the length
23640 \lnc{vindent}. Its initial value is twice the default value of \lnc{\vgap}.
23641
23642 \begin{syntax}
23643 \cmd{\\}\oarg{length} \\
23644 \cmd{\\*}\oarg{length} \\
23645 \cmdprint{\\!}\oarg{length} \\
23646 \end{syntax}
23647 \glossary(\\)%
23648 {\Vprint{\\}\oarg{length}}%
23649 {Ends a verse line, and adds \meta{length} vertical space.}
23650 \glossary(\\*)%
23651 {\Vprint{\\*}\oarg{length}}%
23652 {Ends a line while preventing a pagebreak, and adds \meta{length} vertical space.}
23653 \glossary(\\!)
23654 {\Vprint{\\!}\oarg{length}}%
23655 {Ends a verse stanza, and adds \meta{length} vertical space.}
23656
23657 Each line in the \Ie{verse} environment, except possibly for the last line
23658 in a stanza\index{stanza!last line},
23659 must be ended by \cmd{\\}, which comes in several variants. In each variant
23660 the optional \meta{length} is the vertical space to be left before the next
23661 line. The \cmd{\\*} form prohibits a page
23662 break\index{stanza!prevent page break} after the line.
23663 The \pixslashbang\ form is to be used only for the last
23664 line\index{stanza!last line!numbering} in a stanza
23665 when the lines are being numbered; this is because the line
23666 numbers\index{line number} are incremented by the \cmd{\\} macro.
23667 It would normally be followed by a blank line.
23668
23669 \begin{syntax}
23670 \cmd{\verselinebreak}\oarg{length} \\
23671 \cmdprint{\\>}\oarg{length} \\
23672 \end{syntax}
23673 \glossary(verselinebreak)
23674 {\cs{verselinebreak}\oarg{length}}%
23675 {Makes a break in a verse line, indenting the next part by twice \cs{vgap},
23676 or by \meta{length} if it is given.}
23677 \glossary(\\>)
23678 {\Vprint{\\>}\oarg{length}}%
23679 {Shorthand for \cs{verselinebreak}.}
23680 Using \cmd{\verselinebreak} will cause later\index{stanza!line break}
23681 text in the line to be typeset
23682 indented\index{stanza!line break!indent} on the following line.
23683 If the optional \meta{length} is not given
23684 the indentation is twice \lnc{\vgap}, otherwise it is \meta{length}.
23685 The broken line will count as a single line as far as the \Ie{altverse}
23686 and \Ie{patverse} environments are concerned. The macro \cmd{\\>} is
23687 shorthand for \cmd{\verselinebreak}, and unlike other members of the \cmd{\\}
23688 family the optional \meta{length} is the indentation of the following
23689 partial\index{stanza!line break!indent} line, not a vertical skip.
23690 Also, the \cmd{\\>} macro does not increment any
23691 line number\index{line number}.
23692
23693 \begin{syntax}
23694 \cmd{\vinphantom}\marg{text} \\
23695 \end{syntax}
23696 \glossary(vinphantom)%
23697 {\cs{vinphantom}\marg{text}}%
23698 {Leaves a space as wide as \meta{text}.}
23699 Verse lines are sometimes indented according to the space taken by
23700 the text on the previous line. The macro \cmd{\vinphantom} can be used
23701 at the start of a line\index{verse!indent space} to give an indentation
23702 as though the
23703 line started with \meta{text}. For example here are a few lines from
23704 the portion of \textit{Fridthjof's Saga} where Fridthjof and Ingeborg part:
23705 \begin{egsource}{eg:fridthjof}
23706 \settowidth{\versewidth}{Nay, nay, I leave thee not,
23707 thou goest too}
23708 \begin{verse}[\versewidth]
23709 \ldots \\*
23710 His judgement rendered, he dissolved the Thing. \\*
23711 \flagverse{Ingeborg} And your decision? \\*
23712 \flagverse{Fridthjof} \vinphantom{And your decision?}
23713 Have I ought to choose? \\*
23714 Is not mine honour bound by his decree? \\*
23715 And that I will redeem through Angantyr \\*
23716 His paltry gold doth hide in Nastrand's flood. \\*
23717 Today will I depart. \\*
23718 \flagverse{Ingeborg} \vinphantom{Today will I depart.}
23719 And Ingeborg leave? \\*
23720 \flagverse{Fridthjof} Nay, nay, I leave thee not,
23721 thou goest too. \\*
23722 \flagverse{Ingeborg} Impossible! \\*
23723 \flagverse{Fridthjof} \vinphantom{Impossible!}
23724 O! hear me, ere thou answerest.
23725 \end{verse}
23726 \end{egsource}
23727
23728 \begin{egresult}[Phantom text in verse]{eg:fridthjof}%
23729 \settowidth{\versewidth}{Nay, nay, I leave thee not,
23730 thou goest too}%
23731 \begin{verse}[\versewidth]
23732 \ldots\index[lines]{His judgement rendered, he dissolved the Thing} \\*
23733 His judgement rendered, he dissolved the Thing. \\*
23734 \flagverse{Ingeborg} And your decision? \\*
23735 \flagverse{Fridthjof} \vinphantom{And your decision?}
23736 Have I ought to choose? \\*
23737 Is not mine honour bound by his decree? \\*
23738 And that I will redeem through Angantyr \\*
23739 His paltry gold doth hide in Nastrand's flood. \\*
23740 Today will I depart. \\*
23741 \flagverse{Ingeborg} \vinphantom{Today will I depart.}
23742 And Ingeborg leave? \\*
23743 \flagverse{Fridthjof} Nay, nay, I leave thee not,
23744 thou goest too. \\*
23745 \flagverse{Ingeborg} Impossible! \\*
23746 \flagverse{Fridthjof} \vinphantom{Impossible!}
23747 O! hear me, ere thou answerest.
23748 \end{verse}
23749 \end{egresult}
23750
23751 Use of \cmd{\vinphantom} is not restricted to the start of verse lines ---
23752 it may be used anywhere in text to leave some some
23753 blank\index{blank space} space.
23754 For example, compare the two lines below, which are produced by this code:
23755 \begin{lcode}
23756 \noindent Come away with me and be my love --- Impossible. \\
23757 Come away with me \vinphantom{and be my love} --- Impossible.
23758 \end{lcode}
23759 \noindent Come away with me and be my love --- Impossible. \\
23760 Come away with me \vinphantom{and be my love} --- Impossible.
23761
23762 \begin{syntax}
23763 \cmd{\vleftofline}\marg{text} \\
23764 \end{syntax}
23765 \glossary(vleftofline)%
23766 {\cs{vleftofline}\marg{text}}%
23767 {`Hanging left' \meta{text} at the start of a verse line.}
23768 A verse line may start with something, for example open quote marks,
23769 where it is desireable that it is ignored as far as the alignment of the
23770 rest of the line is concerned\footnote{Requested by Matthew
23771 Ford\index{Ford, Matthew} who also provided the example text.} --- a sort
23772 of `hanging left punctuation'. When it is put at the start of a line
23773 in the \Ie{verse} environment the \meta{text} is typeset but ignored as
23774 far as horizontal indentation is concerned.
23775 Compare the two examples.
23776
23777 \begin{egsource}{eg.joel1}
23778 \noindent ``No, this is what was spoken by the prophet Joel:
23779 \begin{verse}
23780 ``\,`\,``In the last days,'' God says, \\
23781 ``I will pour out my spirit on all people. \\
23782 Your sons and daughters will prophesy, \\
23783 \ldots \\
23784 And everyone who calls \ldots ''\,'
23785 \end{verse}
23786 \end{egsource}
23787
23788 \begin{egresult}[Verse with regular quote marks]{eg.joel1}
23789 \noindent ``No, this is what was spoken by the prophet Joel:
23790 \begin{verse}
23791 ``\,`\,``In the last days,'' God says, \\
23792 ``I will pour out my spirit on all people. \\
23793 Your sons and daughters will prophesy, \\
23794 \ldots \\
23795 And everyone who calls \ldots ''\,'
23796 \end{verse}
23797 \end{egresult}
23798
23799 \begin{egsource}{eg.joel2}
23800 \noindent ``No, this is what was spoken by the prophet Joel:
23801 \begin{verse}
23802 \vleftofline{``\,`\,``}In the last days,'' God says, \\
23803 \vleftofline{``}I will pour out my spirit on all people. \\
23804 Your sons and daughters will prophesy, \\
23805 \ldots \\
23806 And everyone who calls \ldots ''\,'
23807 \end{verse}
23808 \end{egsource}
23809
23810 \begin{egresult}[Verse with hanging left quote marks]{eg.joel2}
23811 \noindent ``No, this is what was spoken by the prophet Joel:
23812 \begin{verse}
23813 \vleftofline{``\,`\,``}In the last days,'' God says, \\
23814 \vleftofline{``}I will pour out my spirit on all people. \\
23815 Your sons and daughters will prophesy, \\
23816 \ldots \\
23817 And everyone who calls \ldots ''\,'
23818 \end{verse}
23819 \end{egresult}
23820
23821
23822
23823 \subsection{Indented lines}
23824
23825 Within the \Ie{verse} environment stanzas are normally separated by a
23826 blank line in the input.
23827
23828 \begin{syntax}
23829 \senv{altverse} ... \eenv{altverse} \\
23830 \end{syntax}
23831 \glossary(altverse)%
23832 {\senv{altverse}}%
23833 {Alternate lines in the stanza are indented.}
23834 Individual stanzas within \Ie{verse} may, however,
23835 be enclosed in the \Ie{altverse}\index{stanza!indent alternate lines}
23836 environment. This has the effect of
23837 indenting the 2nd, 4th, etc., lines of the stanza by the length \lnc{\vgap}.
23838
23839 \begin{syntax}
23840 \senv{patverse} ... \eenv{patverse} \\
23841 \senv{patverse*} ... \eenv{patverse*} \\
23842 \cmd{\indentpattern}\marg{digits} \\
23843 \end{syntax}
23844 \glossary(patverse)%
23845 {\senv{patverse}}%
23846 {Stanza lines are indented according to the \cs{indentpattern};
23847 lines after the pattern is completed are not indented.}
23848 \glossary(patverse*)%
23849 {\senv{patverse*}}%
23850 {Like \Pe{patverse} except that the pattern will keep repeating.}
23851 \glossary(indentpattern)%
23852 {\cs{indentpattern}\marg{digits}}%
23853 {Stanza lines in \Pe{patverse} environment are indented according to
23854 the \meta{digits} pattern.}
23855 As an alternative to the \Ie{altverse} environment,
23856 individual stanzas within the \Ie{verse} environment may be enclosed
23857 in the \Ie{patverse} environment. Within this environment the indentation
23858 of each line is specified by an indentation\index{stanza!indent pattern}
23859 pattern, which consists
23860 of an array of digits, \(d_{1}\) to \(d_{n}\), and the \(n\)th line is
23861 indented by \(d_{n}\) times \lnc{\vgap}. However, the first line is
23862 not indented, irrespective of the value of \(d_{1}\).
23863
23864 The indentation pattern for a \Ie{patverse} or \Ie{patverse*}
23865 environment is specified
23866 via the \cmd{\indentpattern} command, where \meta{digits} is a string
23867 of digits (e.g., \texttt{3213245281}). With the \Ie{patverse}
23868 environment, if the pattern is
23869 shorter than the number of lines in the stanza, the trailing lines will
23870 not be indented. However, in the \Ie{patverse*} environment the pattern
23871 keeps repeating until the end of the stanza.
23872
23873 \subsection{Numbering}
23874
23875 \begin{syntax}
23876 \cmd{\flagverse}\marg{flag} \\
23877 \lnc{\vleftskip} \\
23878 \end{syntax}
23879 \glossary(flagverse)%
23880 {\cs{flagverse}\marg{flag}}%
23881 {Used at the start of a verse line to put \meta{flag} distance
23882 \cs{vleftskip} before the start of the line.}
23883 \glossary(vleftskip)%
23884 {\cs{vleftskip}}%
23885 {Space between the argument to \cs{flageverse} and \cs{flagverse}.}
23886 Putting \cmd{\flagverse} at the start of a line will typeset \meta{flag},
23887 for example the stanza\index{stanza!number} number,
23888 ending at a distance \lnc{\vleftskip} before the line. The default for
23889 \lnc{\vleftskip} is 3em.
23890
23891 The lines in a poem may be numbered.
23892
23893 \begin{syntax}
23894 \cmd{\linenumberfrequency}\marg{nth} \\
23895 \cmd{\setverselinenums}\marg{first}\marg{startat} \\
23896 \end{syntax}
23897 \glossary(setverselinenums)%
23898 {\cs{setverselinenums}\marg{first}\marg{startat}}%
23899 {The first line of the following verse is number \marg{first} and the
23900 first printed line number should be \meta{startat}.}
23901 The declaration \cmd{\linenumberfrequency}\marg{nth} will cause every
23902 \meta{nth} line\index{line number!frequency}
23903 of succeeding verses to be numbered.
23904 For example,
23905 \verb?\linenumberfrequency{5}?
23906 will number every fifth line. The default is \verb?\linenumberfrequency{0}?
23907 which prevents any numbering.
23908
23909 \begin{Changed}[February 2024]
23910 Verse line numbers are now added at the start of the line via a
23911 paragraph hook.\footnotemark\ This affects how lines with a
23912 automatic line break are numbered. They are now always aligned with the
23913 first line of a broken line.
23914
23915 This change also remove the need to have \bs\bs\ after the last line
23916 of a poem in order to have it numbered.
23917 \end{Changed}
23918 \footnotetext{Internally all the lines of a verse are actually
23919 separate paragraphs. The line numbers are added via a hook into the
23920 start of paragraphs inside verse and friends.}
23921
23922
23923 The \cmd{\setverselinenums} macro can be used to specify that the
23924 number of the first line of the following \Ie{verse} shall be
23925 \meta{first} and the first printed number shall be \meta{startat}.
23926 For example, perhaps you are quoting part of a numbered poem. The
23927 original numbers every tenth line but if your extract starts with line
23928 7, then
23929 \begin{lcode}
23930 \linenumberfrequency{10}
23931 \setverselinenums{7}{10}
23932 \end{lcode}
23933 is what you will need.
23934
23935 \begin{syntax}
23936 \cmd{\thepoemline} \\
23937 \cmd{\linenumberfont}\marg{font-decl} \\
23938 \end{syntax}
23939 \glossary(thepoemline)%
23940 {\cs{thepoemline}}%
23941 {The numeric representation of verse line numbers (default arabic).}
23942 The \Icn{poemline} counter is used in numbering the lines, so the
23943 number representation is \cmd{\thepoemline}, which defaults to
23944 arabic numerals, and they are typeset using the font
23945 specified\index{line number!font}
23946 via \cmd{\linenumberfont}; the default is
23947 \begin{lcode}
23948 \linenumberfont{\small\rmfamily}
23949 \end{lcode}
23950 for small numbers in the roman font.
23951
23952 \begin{syntax}
23953 \cmd{\verselinenumbersright} \\
23954 \cmd{\verselinenumbersleft} \\
23955 \lnc{\vrightskip} \\
23956 \end{syntax}
23957 \glossary(verselinenumbersright)%
23958 {\cs{verselinenumbersright}}%
23959 {Following this declaration verse line numbers are set at the right of the
23960 verse lines.}
23961 \glossary(verselinenumbersleft)%
23962 {\cs{verselinenumbersleft}}%
23963 {Following this declaration verse line numbers are set at the left of the
23964 verse lines.}
23965 \glossary(vrightskip)
23966 {\cs{vrightskip}}%
23967 {Verse line numbers are set distance \cs{vrightskip} into the margin.}
23968 Following the declaration
23969 \cmd{\verselinenumbersright}, which is the default, any verse line numbers
23970 will be set\index{line number!position} in the righthand margin.
23971 The \cmd{\verselinenumbersleft}
23972 declaration will set any subsequent line numbers to the left of the lines.
23973 The numbers are set at a distance
23974 \lnc{\vrightskip} (default 1em) into the margin.
23975
23976
23977 \section{Titles}
23978
23979 The \cmd{\PoemTitle} command is provided for typesetting titles
23980 of poems.
23981
23982 \begin{syntax}
23983 \cmd{\PoemTitle}\oarg{fortoc}\oarg{forhead}\marg{title} \\
23984 \cmd{\NumberPoemTitle} \\
23985 \cmd{\PlainPoemTitle} \\
23986 \cmd{\thepoem} \\
23987 \end{syntax}
23988 \glossary(PoemTitle)%
23989 {\cs{PoemTitle}\oarg{fortoc}\oarg{forhead}\marg{title}}%
23990 {Typesets the title for a poem and puts it into the ToC.}
23991 \glossary(NumberPoemTitle)%
23992 {\cs{NumberPoemTitle}}%
23993 {Declaration for \cs{PoemTitle} to be numbered.}
23994 \glossary(PlainPoemTitle)%
23995 {\cs{PlainPoemTitle}}%
23996 {Declaration for \cs{PoemTitle} to be unnumbered.}
23997 \glossary(thepoem)%
23998 {\cs{thepoem}}%
23999 {Typeset the current Poem Title number}%
24000 The \cmd{\PoemTitle} command takes the same arguments as the
24001 \cmd{\chapter} command; it typesets the title for a poem\index{poem title}
24002 and adds it to the ToC\index{poem title!in ToC}.
24003 Following the declaration \cmd{\NumberPoemTitle}
24004 the title is numbered but there is no numbering after the
24005 \cmd{\PlainPoemTitle} declaration.
24006
24007 \begin{syntax}
24008 \cmd{\poemtoc}\marg{sec} \\
24009 \end{syntax}
24010 \glossary(poemtoc)%
24011 {\cs{poemtoc}}%
24012 {Kind of entry for a \cs{PoemTitle} in the ToC.}
24013 The kind of entry made in the \toc\ by\index{poem title!in ToC}
24014 \cmd{\PoemTitle} is defined by \cmd{\poemtoc}. The initial definition is:
24015 \begin{lcode}
24016 \newcommand{\poemtoc}{section}
24017 \end{lcode}
24018 for a section-like \toc\ entry. This can be changed to, say, \texttt{chapter}
24019 or \texttt{subsection} or \ldots.
24020
24021 \begin{syntax}
24022 \cmd{\poemtitlemark}\marg{forhead} \\
24023 \cmd{\poemtitlepstyle} \\
24024 \end{syntax}
24025 \glossary(poemtitlemark)%
24026 {\cs{poemtitlemark}\marg{forhead}}%
24027 {Used to set marks for a \cs{PoemTitle}.}
24028 \glossary(poemtitlepstyle)%
24029 {\cs{poemtitlepstyle}}%
24030 {Page style for a \cs{PoemTitle}.}
24031 The macro \cmd{\poemtitlemark}
24032 is called with the argument \meta{forhead} so that it may be used
24033 to set marks for use in a page header via the normal mark process.
24034 The \cmd{\poemtitlepstyle}
24035 macro, which by default does nothing, is provided as a hook so that,
24036 for example, it can be redefined to specify a particular pagestyle that should
24037 be used. For example:
24038 \begin{lcode}
24039 \renewcommand*{\poemtitlemark}[1]{\markboth{#1}{#1}}
24040 \renewcommand*{\poemtitlepstyle}{%
24041 \pagestyle{headings}%
24042 \thispagestyle{empty}}
24043 \end{lcode}
24044
24045 \begin{syntax}
24046 \cmd{\PoemTitle*}\oarg{forhead}\marg{title} \\
24047 \cmd{\poemtitlestarmark}\marg{forhead} \\
24048 \cmd{\poemtitlestarpstyle} \\
24049 \end{syntax}
24050 \glossary(PoemTitle*)%
24051 {\cs{PoemTitle*}\oarg{fortoc}\oarg{forhead}\marg{title}}%
24052 {Typesets an unnumbered title for a poem but does not add it to the ToC.}
24053 \glossary(poemtitlestarmark)%
24054 {\cs{poemtitlestarmark}\marg{forhead}}%
24055 {Used to set marks for a \cs{PoemTitle*}.}
24056 \glossary(poemtitlestarpstyle)%
24057 {\cs{poemtitlestarpstyle}}%
24058 {Page style for a \cs{PoemTitle*}.}
24059
24060 The \cmd{\PoemTitle*} command produces an unnumbered title that is
24061 not added to the ToC. Apart from that it operates in the same manner
24062 as the unstarred version. The \cmd{\poemtitlestarmark} and
24063 \cmd{\poemtitlestarpstyle} can be redefined to set marks and pagestyles.
24064
24065 \subsection{Main Poem Title layout parameters}
24066
24067 \begin{syntax}
24068 \cmd{\PoemTitleheadstart} \\
24069 \cmd{\printPoemTitlenonum} \\
24070 \cmd{\printPoemTitlenum} \\
24071 \cmd{\afterPoemTitlenum} \\
24072 \cmd{\printPoemTitletitle}\marg{title} \\
24073 \cmd{\afterPoemTitle} \\
24074 \end{syntax}
24075 \glossary(PoemTitleheadstart)%
24076 {\cs{PoemTitleheadstart}}%
24077 {Called at the start of typesetting a \cs{PoemTitle}.}
24078 \glossary(printPoemTitlenum)%
24079 {\cs{printPoemTitlenum}}%
24080 {Typesets the number for a \cs{PoemTitle}.}
24081 \glossary(printPoemTitlenonum)%
24082 {\cs{printPoemTitlenonum}}%
24083 {Used instead of \cs{printPoemTitlenum} for an unnumbered \cs{PoemTitle}.}
24084 \glossary(afterPoemTitlenum)%
24085 {\cs{afterPoemTitlenum}}%
24086 {Called after printing the number of a \cs{PoemTitle}.}
24087 \glossary(printPoemTitletitle)%
24088 {\cs{printPoemTitletitle}\marg{title}}%
24089 {Typesets the title of a \cs{PoemTitle}.}
24090 \glossary(afterPoemTitle)%
24091 {\cs{afterPoemTitle}}%
24092 {Called after printing the title of a \cs{PoemTitle}.}
24093
24094
24095 The essence of the code used to typeset a numbered \meta{title} from
24096 a \cmd{\PoemTitle} is:
24097 \begin{lcode}
24098 \PoemTitleheadstart
24099 \printPoemTitlenum
24100 \afterPoemTitlenum
24101 \printPoemTitletitle{title}
24102 \afterPoemTitle
24103 \end{lcode}
24104 If the title is unnumbered then \cmd{\printPoemTitlenonum} is used
24105 instead of the \cmd{\printPoemTitlenum} and
24106 \cmd{\afterPoemTitlenum} pair of macros.
24107
24108 The various elements of this can be modified to change the layout.
24109 By default the number is centered above the title, which is also typeset
24110 centered, and all in a \cmd{\large} font.
24111
24112 The elements are detailed in the next section.
24113
24114 \subsection{Detailed Poem Title layout parameters}
24115
24116 \begin{syntax}
24117 \lnc{\beforePoemTitleskip} \\
24118 \cmd{\PoemTitlenumfont} \\
24119 \lnc{\midPoemTitleskip} \\
24120 \cmd{\PoemTitlefont} \\
24121 \lnc{\afterPoemTitleskip} \\
24122 \end{syntax}
24123 \glossary(beforePoemTitleskip)%
24124 {\cs{beforePoemTitleskip}}%
24125 {Vertical space before a poem title.}
24126 \glossary(midPoemTitleskip)%
24127 {\cs{midPoemTitleskip}}%
24128 {Vertical space between the number and text of a poem title.}
24129 \glossary(afterPoemTitleskip)%
24130 {\cs{afterPoemTitleskip}}%
24131 {Vertical space after a poem title}
24132 \glossary(PoemTitlenumfont)%
24133 {\cs{PoemTitlenumfont}}%
24134 {Font for the number of a poem title}
24135 \glossary(PoemTitlefont)%
24136 {\cs{PoemTitlefont}}%
24137 {Font for the text of a poem title}
24138
24139
24140 As defined, \cmd{\PoemTitleheadstart} inserts vertical space
24141 before a poem title. The default definition is:
24142 \begin{lcode}
24143 \newcommand*{\PoemTitleheadstart}{\vspace{\beforePoemTitleskip}}
24144 \newlength{\beforePoemTitleskip}
24145 \setlength{\beforePoemTitleskip}{1\onelineskip}
24146 \end{lcode}
24147
24148 \cmd{\printPoemTitlenum} typesets the number for a poem title.
24149 The default definition, below, prints the number centered and in
24150 a large font.
24151 \begin{lcode}
24152 \newcommand*{\printPoemTitlenum}{\PoemTitlenumfont \thepoem}
24153 \newcommand*{\PoemTitlenumfont}{\normalfont\large\centering}
24154 \end{lcode}
24155
24156 The definition of \cmd{\printPoemTitlenonum}, which is used
24157 when there is no number, is simply
24158 \begin{lcode}
24159 \newcommand*{\printPoemTitlenonum}{}
24160 \end{lcode}
24161
24162 \cmd{\afterPoemTitlenum} is called between setting the number
24163 and the title. It ends a paragraph (thus making sure any previous
24164 \cmd{\centering} is used) and then may add some vertical
24165 space. The default definition is:
24166 \begin{lcode}
24167 \newcommand*{\afterPoemTitlenum}{\par\nobreak\vskip \midPoemTitleskip}
24168 \newlength{\midPoemTitleskip}
24169 \setlength{\midPoemTitleskip}{0pt}
24170 \end{lcode}
24171
24172 The default definition of \cmd{\printPoemTitletitle} is below.
24173 It typesets the title centered and in a large font.
24174 \begin{lcode}
24175 \newcommand*{\printPoemTitletitle}[1]{\PoemTitlefont #1}
24176 \newcommand*{\PoemTitlefont}{\normalfont\large\centering}
24177 \end{lcode}
24178
24179 The macro \cmd{\afterPoemTitle} finishes off the title
24180 typesetting. The default definition is:
24181 \begin{lcode}
24182 \newcommand*{\afterPoemTitle}{\par\nobreak\vskip \afterPoemTitleskip}
24183 \newlength{\afterPoemTitleskip}
24184 \setlength{\afterPoemTitleskip}{1\onelineskip}
24185 \end{lcode}
24186
24187
24188
24189 %\clearpage
24190 \section{Examples}
24191
24192 Here are some sample verses using the class facilities.
24193
24194 First a Limerick, but titled\index{poem title} and centered:
24195 \begin{lcode}
24196 \renewcommand{\poemtoc}{subsection}
24197 \PlainPoemTitle
24198 \PoemTitle{A Limerick}
24199 \settowidth{\versewidth}{There was a young man of Quebec}
24200 \begin{verse}[\versewidth]
24201 There was a young man of Quebec \\
24202 Who was frozen in snow to his neck. \\
24203 \vin When asked: `Are you friz?' \\
24204 \vin He replied: `Yes, I is, \\
24205 But we don't call this cold in Quebec.'
24206 \end{verse}
24207 \end{lcode}
24208 which gets typeset as below. The \cmd{\poemtoc} is redefined
24209 to \texttt{subsection} so that the \cmd{\poemtitle} titles
24210 are entered\index{poem title!in ToC} into the \toc\ as
24211 subsections. The titles will not be numbered because of the
24212 \cmd{\PlainPoemTitle} declaration.
24213
24214 \renewcommand{\poemtoc}{subsection}
24215 \PlainPoemTitle
24216 \PoemTitle{A Limerick}
24217 \settowidth{\versewidth}{There was a young man of Quebec}
24218 \begin{verse}[\versewidth] \index[lines]{There was a young man of Quebec}
24219 There was a young man of Quebec \\
24220 Who was frozen in snow to his neck. \\
24221 \vin When asked: `Are you friz?' \\
24222 \vin He replied: `Yes, I is, \\
24223 But we don't call this cold in Quebec.'
24224 \end{verse}
24225
24226 \vspace{\onelineskip}
24227 %\ablankline
24228
24229 Next is the Garden verse within the \Ie{altverse} environment. Unlike
24230 earlier renditions this one is titled\index{poem title} and centered.
24231 \begin{lcode}
24232 \settowidth{\versewidth}{But now my love is dead}
24233 \PoemTitle{Love's lost}
24234 \begin{verse}[\versewidth]
24235 \begin{altverse}
24236 \garden
24237 \end{altverse}
24238 \end{verse}
24239 \end{lcode}
24240 Note how the alternate lines\index{stanza!indent alternate lines}
24241 are automatically indented in the typeset result below.
24242
24243 \settowidth{\versewidth}{But now my love is dead}
24244 \PoemTitle{Love's lost}
24245 \begin{verse}[\versewidth]\index[lines]{I used to love my garden}
24246 \begin{altverse}
24247 \garden
24248 \end{altverse}
24249 \end{verse}
24250
24251 \vspace{\onelineskip}
24252 % \ablankline
24253
24254 It is left up to you how you might want to add information about
24255 the author\index{poem!author} of a poem. Here is one example of a
24256 macro for this:
24257 \begin{lcode}
24258 \newcommand{\attrib}[1]{%
24259 \nopagebreak{\raggedleft\footnotesize #1\par}}
24260 \end{lcode}
24261 \providecommand{\attrib}[1]{%
24262 \nopagebreak{\raggedleft\footnotesize #1\par}}
24263
24264 This can be used as in the next bit of doggerel.
24265 \begin{lcode}
24266 \PoemTitle{Fleas}
24267 \settowidth{\versewidth}{What a funny thing is a flea}
24268 \begin{verse}[\versewidth]
24269 What a funny thing is a flea. \\
24270 You can't tell a he from a she. \\
24271 But he can. And she can. \\
24272 Whoopee!
24273 \end{verse}
24274 \attrib{Anonymous}
24275 \end{lcode}
24276
24277 \PoemTitle{Fleas}
24278 \settowidth{\versewidth}{What a funny thing is a flea}
24279 \begin{verse}[\versewidth]\index[lines]{What a funny thing is a flea}
24280 What a funny thing is a flea. \\
24281 You can't tell a he from a she. \\
24282 But he can. And she can. \\
24283 Whoopee!
24284 \end{verse}
24285 \attrib{Anonymous}
24286
24287 \vspace{\onelineskip}
24288 %\ablankline
24289
24290 The next example demonstrates the automatic line wrapping for
24291 overlong\index{stanza!long line} lines.
24292 \begin{lcode}
24293 \PoemTitle{In the beginning}
24294 \settowidth{\versewidth}{And objects at rest tended to
24295 remain at rest}
24296 \begin{verse}[\versewidth]
24297 Then God created Newton, \\
24298 And objects at rest tended to remain at rest, \\
24299 And objects in motion tended to remain in motion, \\
24300 And energy was conserved
24301 and momentum was conserved
24302 and matter was conserved \\
24303 And God saw that it was conservative.
24304 \end{verse}
24305 \attrib{Possibly from \textit{Analog}, circa 1950}
24306 \end{lcode}
24307
24308 %%\enlargethispage{\baselineskip}
24309 \PoemTitle{In the beginning}
24310 \settowidth{\versewidth}{And objects at rest tended to remain at rest}
24311 \begin{verse}[\versewidth]\index[lines]{Then God created Newton}
24312 Then God created Newton, \\
24313 And objects at rest tended to remain at rest, \\
24314 And objects in motion tended to remain in motion, \\
24315 And energy was conserved
24316 and momentum was conserved
24317 and matter was conserved \\
24318 And God saw that it was conservative.
24319 \end{verse}
24320 \attrib{Possibly from \textit{Analog}, circa 1950}
24321
24322 \vspace{\onelineskip}
24323 %\ablankline
24324
24325 The following verse demonstrates the use of a forced\index{stanza!line break}
24326 linebreak; I have
24327 used the \cmd{\\>} command instead of the more descriptive,
24328 but discursive, \cmd{\verselinebreak}. It also
24329 has a slightly different title\index{poem title!styling} style.
24330 \begin{lcode}
24331 \renewcommand{\PoemTitlefont}{%
24332 \normalfont\large\itshape\centering}
24333 \poemtitle{Mathematics}
24334 \settowidth{\versewidth}{Than Tycho Brahe, or Erra Pater:}
24335 \begin{verse}[\versewidth]
24336 In mathematics he was greater \\
24337 Than Tycho Brahe, or Erra Pater: \\
24338 For he, by geometric scale, \\
24339 Could take the size of pots of ale;\\
24340 \settowidth{\versewidth}{Resolve by}%
24341 Resolve, by sines \\>[\versewidth] and tangents straight, \\
24342 If bread or butter wanted weight; \\
24343 And wisely tell what hour o' the day \\
24344 The clock does strike, by Algebra.
24345 \end{verse}
24346 \attrib{Samuel Butler (1612--1680)}
24347 \end{lcode}
24348
24349 %%\clearpage
24350
24351 \renewcommand{\PoemTitlefont}{\normalfont\large\itshape\centering}
24352 \PoemTitle{Mathematics}
24353 \settowidth{\versewidth}{Than Tycho Brahe, or Erra Pater:}
24354 \begin{verse}[\versewidth]\index[lines]{In mathematics he was greater}
24355 In mathematics he was greater \\
24356 Than Tycho Brahe, or Erra Pater: \\
24357 For he, by geometric scale, \\
24358 Could take the size of pots of ale;\\
24359 \settowidth{\versewidth}{Resolve by}%
24360 Resolve, by sines \\>[\versewidth] and tangents straight, \\
24361 If bread or butter wanted weight; \\
24362 And wisely tell what hour o' the day \\
24363 The clock does strike, by Algebra.
24364 \end{verse}
24365 \attrib{Samuel Butler (1612--1680)}
24366
24367 \vspace{\onelineskip}
24368 %\ablankline
24369 %\clearpage
24370
24371 Another limerick, but this time taking advantage of
24372 the \Ie{patverse}\index{verse!indent pattern}
24373 environment. If you are typesetting a series of limericks
24374 a single \cmd{\indentpattern} will do for all of them.
24375 \begin{lcode}
24376 \settowidth{\versewidth}{There was a young lady of Ryde}
24377 \indentpattern{00110}
24378 \needspace{7\onelineskip}
24379 \PoemTitle{The Young Lady of Ryde}
24380 \begin{verse}[\versewidth]
24381 \begin{patverse}
24382 There was a young lady of Ryde \\
24383 Who ate some apples and died. \\
24384 The apples fermented \\
24385 Inside the lamented \\
24386 And made cider inside her inside.
24387 \end{patverse}
24388 \end{verse}
24389 \end{lcode}
24390 Note that I used the \cmd{\needspace} command to ensure that
24391 the limerick will not get broken across a page.
24392
24393 \settowidth{\versewidth}{There was a young lady of Ryde}
24394 \indentpattern{00110}
24395 \needspace{7\onelineskip}
24396 \PoemTitle{The Young Lady of Ryde}
24397 \begin{verse}[\versewidth]\index[lines]{There was a young lady of Ryde}
24398 \begin{patverse}
24399 There was a young lady of Ryde \\
24400 Who ate some apples and died. \\
24401 The apples fermented \\
24402 Inside the lamented \\
24403 And made cider inside her inside.
24404 \end{patverse}
24405 \end{verse}
24406
24407 \vspace{\onelineskip}
24408
24409
24410 The next example is a song you may have heard of. This uses
24411 \cmd{\flagverse} for labelling\index{stanza!number} the stanzas,
24412 and because the lines are numbered\index{line number} they can be referred to.
24413
24414 \begin{lcode}
24415 \settowidth{\versewidth}{In a cavern, in a canyon,}
24416 \PoemTitle{Clementine}
24417 \begin{verse}[\versewidth]
24418 \linenumberfrequency{2}
24419 \begin{altverse}
24420 \flagverse{1.} In a cavern, in a canyon, \\
24421 Excavating for a mine, \\
24422 Lived a miner, forty-niner, \label{vs:49} \\
24423 And his daughter, Clementine. \\!
24424 \end{altverse}
24425
24426 \begin{altverse}
24427 \flagverse{\textsc{chorus}} Oh my darling, Oh my darling, \\
24428 Oh my darling Clementine. \\
24429 Thou art lost and gone forever, \\
24430 Oh my darling Clementine.
24431 \end{altverse}
24432 \linenumberfrequency{0}
24433 \end{verse}
24434 The `forty-niner' in line~\ref{vs:49} of the song
24435 refers to the gold rush of 1849.
24436 \end{lcode}
24437
24438 \settowidth{\versewidth}{In a cavern, in a canyon,}
24439 \PoemTitle{Clementine}
24440 \begin{verse}[\versewidth]\index[lines]{In a cavern, in a canyon}
24441 \linenumberfrequency{2}
24442 \begin{altverse}
24443 \flagverse{1.} In a cavern, in a canyon, \\
24444 Excavating for a mine, \\
24445 Lived a miner, forty-niner, \label{vs:49} \\
24446 And his daughter, Clementine. \\!
24447 \end{altverse}
24448
24449 \begin{altverse}
24450 \flagverse{\textsc{chorus}} Oh my darling, Oh my darling, \\
24451 Oh my darling Clementine. \\
24452 Thou art lost and gone forever, \\
24453 Oh my darling Clementine.
24454 \end{altverse}
24455 \linenumberfrequency{0}
24456 \end{verse}
24457
24458 \vspace{\onelineskip}
24459
24460 The `forty-niner' in line~\ref{vs:49} of the song
24461 refers to the gold rush of 1849.
24462
24463 %\ablankline
24464
24465 The last example is a much more ambitious use\index{stanza!indent pattern}
24466 of \cmd{\indentpattern}. In
24467 this case it is defined as:
24468 \begin{lcode}
24469 \indentpattern{0135554322112346898779775545653222345544456688778899}
24470 \end{lcode}
24471 and the result is shown on the next page.
24472
24473
24474 \clearpage
24475 \PoemTitle{Mouse's Tale}
24476 \settowidth{\versewidth}{a mouse that morning}
24477 \indentpattern{0135554322112346898779775545653222345544456688778899}
24478 \begin{verse}[\versewidth]\index[lines]{Fury said to}
24479 \setlength{\vgap}{1em}
24480 \begin{patverse}
24481 \large Fury said to \\
24482 a mouse, That \\
24483 he met \\
24484 in the \\
24485 house, \\
24486 \normalsize `Let us \\
24487 both go \\
24488 to law: \\
24489 \emph{I} will \\
24490 prosecute \\
24491 \textit{you.} --- \\
24492 Come, I'll \\
24493 \small take no \\
24494 denial; \\
24495 We must \\
24496 have a \\
24497 trial: \\
24498 For \\
24499 \footnotesize really \\
24500 this \\
24501 morning \\
24502 I've \\
24503 nothing \\
24504 to do.' \\
24505 Said the \\
24506 mouse to \\
24507 \scriptsize the cur, \\
24508 Such a \\
24509 trial, \\
24510 dear sir, \\
24511 With no \\
24512 jury or \\
24513 judge, \\
24514 would be \\
24515 wasting \\
24516 our breath.' \\
24517 \tiny `I'll be \\
24518 judge, \\
24519 I'll be \\
24520 jury.' \\
24521 Said \\
24522 cunning \\
24523 old Fury; \\
24524 `I'll try \\
24525 the whole \\
24526 cause \\
24527 and \\
24528 condemn \\
24529 you \\
24530 to \\
24531 death.' \par
24532 \end{patverse}
24533 \end{verse}
24534 \attrib{Lewis Carrol, \textit{Alice's Adventures in Wonderland}, 1865}
24535
24536
24537 \index{verse|)}
24538
24539 %#% extend
24540 %#% extstart include boxes-verbatims-and-files.tex
24541
24542 \svnidlong
24543 {$Ignore: $}
24544 {$LastChangedDate: 2025-09-19 16:06:27 +0200 (Fri, 19 Sep 2025) $}
24545 {$LastChangedRevision: 873 $}
24546 {$LastChangedBy: [email protected] $}
24547
24548 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
24549 %%%%%% membook
24550
24551
24552 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
24553 \chapter{Boxes, verbatims and files} \label{chap:bvf}\label{chap:boxes}
24554 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
24555
24556 The title of this chapter indicates that it deals with three
24557 disconnected topics, but there is method in the seeming peculiarity.
24558 By the end of the chapter you will be able to write \ltx\ code that
24559 lets you put things in your document source at one place and have them
24560 typeset at a different place, or places. For example, if you are writing
24561 a text book that includes questions and answers then you could write
24562 a question and answer together yet have the answer typeset at the
24563 end of the book.
24564
24565 Writing in one place and printing in another is based on outputting
24566 stuff to a file\index{file!write} and then inputting
24567 it\index{file!read} for processing at another place
24568 or time. This is just how \ltx\ produces the \toc. It is often important
24569 when writing to a file that \ltx\ does no processing of any macros, which
24570 implies that we need to be able to write verbatim. One use of verbatim
24571 in \ltx\ is to typeset computer code or the like, and to clearly
24572 distinguish the code from the main text it is often typeset within a box.
24573 Hence the chapter title.
24574
24575 The class extends the kinds of boxes\index{box} normally provided,
24576 extends the default verbatims\index{verbatim}, and provides a simple means
24577 of writing\index{file!write} and reading\index{file!read} files.
24578
24579 One problem with verbatims\index{verbatim!in argument} is that they
24580 can not be used as part of
24581 an argument to a command. For example to typeset something in a
24582 framed\index{frame!minipage}
24583 \Ie{minipage} the obvious way is to use the \Ie{minipage} as the argument
24584 to the \cmd{\fbox} macro:
24585 \begin{lcode}
24586 \fbox{\begin{minipage}{6cm}
24587 Contents of framed minipage
24588 \end{minipage}}
24589 \end{lcode}
24590 This works perfectly well until the contents includes some verbatim
24591 material, whereupon you will get nasty
24592 error\index{\cs{verb} illegal in command argument} messages. However this
24593 particular conundrum is solvable, even if the solution is not particularly
24594 obvious. Here it is.
24595
24596 We can put things into a box, declared via \cmd{\newsavebox}, and typeset
24597 the contents of the box later via \cmd{\usebox}. The most common way
24598 of putting things into a save box is by the \cmd{\sbox} or \cmd{\savebox}
24599 macros, but as the material for saving is one of the arguments to these
24600 macros this approach fails. But, \Ie{lrbox} is an environment form of
24601 \cmd{\sbox}, so it can handle verbatim material. The code below,
24602 after getting a new save box, defines a new \Ie{framedminipage}
24603 environment\index{frame!minipage!verbatim} which is used just
24604 like the standard \Ie{minipage}.
24605 The \Ie{framedminipage}
24606 starts an \Ie{lrbox} environment and then
24607 starts a \Ie{minipage} environment, after which comes the contents.
24608 At the end it closes the two environments and calls \cmd{\fbox} with its
24609 argument being the contents of the saved box \emph{which have already been
24610 typeset}.
24611 \begin{lcode}
24612 \newsavebox{\minibox}
24613 \newenvironment{framedminipage}[1]{%
24614 \begin{lrbox}{\minibox}\begin{minipage}{#1}}%
24615 {\end{minipage}\end{lrbox}\fbox{\usebox{\minibox}}}
24616 \end{lcode}
24617
24618 \vspace{\onelineskip}
24619 \noindent\textbf{Question 1.} Can you think of any improvements to
24620 the definition of the \Ie{framedminipage} environment?
24621
24622 \vspace{\onelineskip}
24623 \noindent\textbf{Question 2.} An answer to question 1 is at the end of this
24624 chapter. Suggest how it was put there.
24625
24626
24627
24628 \section{Boxes}
24629
24630 \index{box!framed|(}
24631 \index{frame!box|(}
24632
24633 \ltx\ provides some commands to put a box round some text. The class
24634 extends the available kinds of boxes.
24635
24636
24637 \begin{syntax}
24638 \senv{framed} text \eenv{framed} \\
24639 \senv{shaded} text \eenv{shaded} \\
24640 \senv{snugshade} text \eenv{snugshade} \\
24641 %%%%%\cmd{\frameasnormaltrue} \cmd{\frameasnormalfalse} \\
24642 \end{syntax}
24643 \glossary(framed)%
24644 {\senv{framed}}%
24645 {Put a ruled box around the contents of the environment; the box can include
24646 pagebreaks.}
24647 \glossary(shaded)%
24648 {\senv{shaded}}%
24649 {Put a colored background behind the contents of the environment, which
24650 can include pagebreaks. The color extends into the margins a little.}
24651 \glossary(snugshade)%
24652 {\senv{snugshade}}%
24653 {Like \Pe{shaded} but does not bleed into the margins.}
24654 The \Ie{framed}, \Ie{shaded}, and \Ie{snugshade}
24655 environments, which were created by Donald Arseneau\index{Arseneau, Donald}
24656 as part of his \Lpack{framed} package~\cite{FRAMED},
24657 put their contents
24658 into boxes\index{box!include pagebreak} that break across pages.
24659 The \Ie{framed} environment delineates
24660 the box by drawing a rectangular frame. If there is a pagebreak in
24661 the middle of the box, frames are drawn on both pages.
24662
24663 The \Ie{shaded} environment typesets the box with a
24664 shaded\index{box!shaded background} or
24665 colored background. This requires the use of the \Lpack{color}
24666 package~\cite{COLOR}, which is one of the required \ltx\ packages,
24667 or the \Lpack{xcolor} package~\cite{XCOLOR}.
24668 The shading color is \texttt{shadecolor}, which you have to define before
24669 using the environment. For
24670 example, to have a light gray background:
24671 \begin{lcode}
24672 \definecolor{shadecolor}{gray}{0.9}
24673 \end{lcode}
24674 For complete information on this see the documentation for the
24675 \Lpack{color} or \Lpack{xcolor} packages, or one of the \ltx\ books like the
24676 \textit{Graphics Companion}~\cite{GCOMPANION}.
24677 In the \Ie{snugshaded} environment the box clings more closely to its
24678 contents than it does in the \Ie{shaded} environment.
24679
24680 \begin{recommended}
24681 See the \Lpack{tcolorbox} package by Thomas~F.~Sturm. An impressive
24682 system of boxes, decorations and much much more. All based on TikZ,
24683 and highly configurable.
24684 \end{recommended}
24685
24686
24687
24688 %% Following the declaration \cmd{\frameasnomaltrue}, which is the
24689 %default, normal paragraphing is used for the framed text. On the
24690 %%other hand, following the declaration \cmd{\frameasnormalfalse}
24691 %the paragraphing follows the \Ie{minipage} style layout (i.e.,
24692 %%no indentation of the first line).
24693
24694 Be aware that the boxes we present in this manual are somewhat
24695 delicate; they do not work in all circumstances. For example they will
24696 not work with the \Lpack{multicol} package~\cite{MULTICOL}, and any
24697 floats or footnotes in the boxes will disappear.
24698
24699 \begin{syntax}
24700 \lnc{\FrameRule} \lnc{\FrameSep} \lnc{\FrameHeightAdjust} \\
24701 \end{syntax}
24702 \glossary(FrameRule)%
24703 {\cs{FrameRule}}%
24704 {Thickness of the rules around an \Pe{framed} environment.}
24705 \glossary(FrameSep)%
24706 {\cs{FrameSep}}%
24707 {Separation between the surrounding box and text in a \Pe{framed} or
24708 \Pe{shaded} environment.}
24709 \glossary(FrameHeightAdjust)%
24710 {\cs{FrameHeightAdjust}}%
24711 {Height of the top of a frame in a \Pe{framed} environment
24712 above the baseline at the top of a page.}
24713 The \Ie{framed} environment puts the text into an `\cmd{\fbox}' with
24714 the settings:
24715 \begin{lcode}
24716 \setlength{\FrameRule}{\fboxrule}
24717 \setlength{\FrameSep}{3\fboxsep}
24718 \end{lcode}
24719 The macro \cmd{\FrameHeightAdjust} specifies the height of the top of the frame
24720 above the baseline at the top of a page; its initial definition is:
24721 \begin{lcode}
24722 \providecommand*{\FrameHeightAdjust}{0.6em}
24723 \end{lcode}
24724
24725 \index{frame!box!styling}
24726 \begin{syntax}
24727 \cmd{\MakeFramed}\marg{settings} \cmd{\endMakeFramed} \\
24728 \cmd{\FrameCommand} \cmd{\FrameRestore} \\
24729 \end{syntax}
24730 \glossary(MakeFramed)%
24731 {\cs{MakeFramed}\marg{settings}}%
24732 {The \Pe{MakeFramed} environment is the workhorse for the
24733 \Pe{framed}, \Pe{shaded}, etc., environments.
24734 The \meta{settings} argument controls the final appearance and
24735 should include a \cs{FrameRestore} to reset things back to normal.}
24736 \glossary(endMakeFramed)%
24737 {\cs{endMakeFramed}}%
24738 {Ends the \Pe{MakeFramed} environment.}
24739 \glossary(FrameCommand)%
24740 {\cs{FrameCommand}}%
24741 {Draws a `frame'.}
24742 \glossary(FrameRestore)%
24743 {\cs{FrameRestore}}%
24744 {Restores settings after a `frame'.}
24745 Internally, the environments are specified using the \Ie{MakeFramed}
24746 environment. The \meta{setting} should contain any adjustments to the
24747 text width
24748 (applied to \lnc{\hsize} and using the \lnc{\width} of the frame itself)
24749 and a `restore' command, which is normally the provided \cmd{\FrameRestore}
24750 macro. The frame itself is drawn via the
24751 \cmd{\FrameCommand}, which can be changed to obtain other boxing styles. The
24752 default definition equates to an \cmd{\fbox} and is:
24753 \begin{lcode}
24754 \newcommand*{\FrameCommand}{%
24755 \setlength{\fboxrule}{\FrameRule}\setlength{\fboxsep}{\FrameSep}%
24756 \fbox}
24757 \end{lcode}
24758 For example, the \Ie{framed}, \Ie{shaded} and \Ie{snugshade} environments
24759 are defined as
24760 \begin{lcode}
24761 \newenvironment{framed}{% % uses default \FrameCommand
24762 \MakeFramed{\advance\hsize -\width \FrameRestore}}%
24763 {\endMakeFramed}
24764 \newenvironment{shaded}{% % redefines \FrameCommand as \colorbox
24765 \def\FrameCommand{\fboxsep=\FrameSep \colorbox{shadecolor}}%
24766 \MakeFramed{\FrameRestore}}%
24767 {\endMakeFramed}
24768 \newenvironment{snugshade}{% A tight version of shaded
24769 \def\FrameCommand{\colorbox{shadecolor}}%
24770 \MakeFramed{\FrameRestore\@setminipage}}%
24771 {\par\unskip\endMakeFramed}
24772 \end{lcode}
24773
24774 If you wanted a narrow, centered, framed\index{frame!narrow box}
24775 environment you could do something like this:
24776 \begin{lcode}
24777 \newenvironment{narrowframed}{%
24778 \MakeFramed{\setlength{\hsize}{22pc}\FrameRestore}}%
24779 {\endMakeFramed}
24780 \end{lcode}
24781 where \texttt{22pc} will be the width of the new framed environment.
24782
24783
24784 \begin{syntax}
24785 \senv{leftbar} text \eenv{leftbar} \\
24786 \end{syntax}
24787 \glossary(leftbar)%
24788 {\senv{leftbar}}%
24789 {Draws a thick vertical line in the left margin alongside the contents
24790 of the environment.}
24791
24792 The \Ie{leftbar} environment draws a thick vertical line at the
24793 left\index{rule!in margin} of the text. It is defined as
24794 \begin{lcode}
24795 \newenvironment{leftbar}{%
24796 \def\FrameCommand{\vrule width 3pt \hspace{10pt}}%
24797 \MakeFramed{\advance\hsize -\width \FrameRestore}}%
24798 {\endMakeFramed}
24799 \end{lcode}
24800
24801 By changing the \meta{setting} for \cmd{\MakeFramed} and the
24802 definition of \cmd{\FrameCommand} you can obtain a variety of framing
24803 styles. For instance, to have rounded corners to the
24804 frame\index{frame!rounded corners} instead of
24805 the normal sharp ones, you can use the \Lpack{fancybox}
24806 package~\cite{FANCYBOX} and the following code:
24807 \begin{lcode}
24808 \usepackage{fancybox}
24809 \newenvironment{roundedframe}{%
24810 \def\FrameCommand{%
24811 \cornersize*{20pt}%
24812 \setlength{\fboxsep}{5pt}%
24813 \ovalbox}%
24814 \MakeFramed{\advance\hsize-\width \FrameRestore}}%
24815 {\endMakeFramed}
24816 \end{lcode}
24817
24818 \index{frame!title|(}
24819 A framed environment is normally used to distinguish its contents
24820 from the surrounding text. A title for the environment may be useful, and
24821 if there was a pagebreak in the middle, a title on the continuation could
24822 be desireable. Doing this takes a bit more work than I have shown so far.
24823 This first part was inspired by a posting to \ctt\ by
24824 Donald Arseneau\index{Arseneau, Donald}.\footnote{On 2003/10/24 in the thread
24825 \textit{framed.sty w/heading?}. The particulars are no longer applicable as
24826 the framing code in question then has since been revised.}.
24827 \PWnote{2009/06/25}{Rewrote section and code for titled frames.}
24828 % \begin{comment}
24829 % This first part is from a posting to \ctt\ by
24830 % Donald Arseneau\index{Arseneau, Donald}.\footnote{On 2003/10/24 in the thread
24831 % \textit{framed.sty w/heading?}}.
24832
24833 % \begin{lcode}
24834 % \newcommand{\FrameTitle}[2]{%
24835 % \fboxrule=\FrameRule \fboxsep=\FrameSep
24836 % \fbox{\vbox{\nobreak \vskip -0.7\FrameSep
24837 % \rlap{\strut#1}\nobreak\nointerlineskip% left justified
24838 % \vskip 0.7\FrameSep
24839 % \hbox{#2}}}}
24840 % \newenvironment{framewithtitle}[2][\FrameFirst@Lab\ (cont.)]{%
24841 % \def\FrameFirst@Lab{\textbf{#2}}%
24842 % \def\FrameCont@Lab{\textbf{#1}}%
24843 % \def\FrameCommand##1{%
24844 % \FrameTitle{\FrameCurrent@Lab}{##1}%
24845 % \global\let\FrameCurrent@Lab\FrameNext@Lab
24846 % \global\let\FrameNext@Lab\FrameCont@Lab
24847 % }%
24848 % \global\let\FrameCurrent@Lab\FrameFirst@Lab
24849 % \global\let\FrameNext@Lab\FrameFirst@Lab
24850 % \MakeFramed{\advance\hsize-\width \FrameRestore}}%
24851 % {\endMakeFramed}
24852 % \end{lcode}
24853 % \end{comment}
24854
24855 \begin{lcode}
24856 \newcommand{\FrameTitle}[2]{%
24857 \fboxrule=\FrameRule \fboxsep=\FrameSep
24858 \fbox{\vbox{\nobreak \vskip -0.7\FrameSep
24859 \rlap{\strut#1}\nobreak\nointerlineskip% left justified
24860 \vskip 0.7\FrameSep
24861 \hbox{#2}}}}
24862 \newenvironment{framewithtitle}[2][\FrameFirst@Lab\ (cont.)]{%
24863 \def\FrameFirst@Lab{\textbf{#2}}%
24864 \def\FrameCont@Lab{\textbf{#1}}%
24865 \def\FrameCommand##1{%
24866 \FrameTitle{\FrameFirst@Lab}{##1}}%
24867 \def\FirstFrameCommand##1{%
24868 \FrameTitle{\FrameFirst@Lab}{##1}}%
24869 \def\MidFrameCommand##1{%
24870 \FrameTitle{\FrameCont@Lab}{##1}}%
24871 \def\LastFrameCommand##1{%
24872 \FrameTitle{\FrameCont@Lab}{##1}}%
24873 \MakeFramed{\advance\hsize-\width \FrameRestore}}%
24874 {\endMakeFramed}
24875 \end{lcode}
24876
24877 The \Ie{framewithtitle} environment, which is the end goal of this
24878 exercise, acts like the \Ie{framed} environment except that it puts
24879 a left-justified title just after the top of the frame box and before the
24880 regular contents.
24881 \begin{syntax}
24882 \senv{framewithtitle}\oarg{cont-title}\marg{title} text \\
24883 \eenv{framewithtitle} \\
24884 \end{syntax}
24885 The \meta{title} is set in a bold font. If the optional \meta{cont-title}
24886 argument is given then \meta{cont-title} is used as the title on
24887 any suceeding pages, otherwise the phrase `\meta{title} (cont.)' is used
24888 for the continuation title.
24889
24890 If you would like the titles centered, replace the line
24891 marked `left justified' in the code for \cmd{\FrameTitle} with the line:
24892 \begin{lcode}
24893 \rlap{\centerline{\strut#1}}\nobreak\nointerlineskip% centered
24894 \end{lcode}
24895
24896 The code for the \Ie{frametitle} environment is not obvious. The difficulty
24897 in creating the environment was that the underlying framing code goes through
24898 the `stuff' to be framed by first trying to fit it all onto one page
24899 (\cs{FrameCommand}). If it does not fit, then it takes as much as will fit
24900 and typesets that using \cs{FirstFrameCommand}, then tries to typeset the
24901 remainder on the next page. If it all fits then it uses \cs{LastFrameCommand}.
24902 If it doesn't fit, it typesets as much as it can using \cs{MidFrameCommand},
24903 and then tries to set the remainder on the following page. The process repeats
24904 until all has been set.
24905
24906 If you would prefer to have the title at the top outside the frame the
24907 above code needs adjusting.
24908 % \begin{comment}
24909 % \begin{lcode}
24910 % \newcommand{\TitleFrame}[2]{%
24911 % \fboxrule=\FrameRule \fboxsep=\FrameSep
24912 % \vbox{\nobreak \vskip -0.7\FrameSep
24913 % \rlap{\strut#1}\nobreak\nointerlineskip% left justified
24914 % \vskip 0.7\FrameSep
24915 % \noindent\fbox{#2}}}
24916 % \newenvironment{titledframe}[2][\FrameFirst@Lab\ (cont.)]{%
24917 % \def\FrameFirst@Lab{\textbf{#2}}%
24918 % \def\FrameCont@Lab{\textbf{#1}}%
24919 % \def\FrameCommand##1{%
24920 % \TitleFrame{\FrameCurrent@Lab}{##1}
24921 % \global\let\FrameCurrent@Lab\FrameNext@Lab
24922 % \global\let\FrameNext@Lab\FrameCont@Lab
24923 % }%
24924 % \global\let\FrameCurrent@Lab\FrameFirst@Lab
24925 % \global\let\FrameNext@Lab\FrameFirst@Lab
24926 % \MakeFramed{\hsize\textwidth
24927 % \advance\hsize -2\FrameRule
24928 % \advance\hsize -2\FrameSep
24929 % \FrameRestore}}%
24930 % {\endMakeFramed}
24931 % \end{lcode}
24932 % \end{comment}
24933
24934 \begin{lcode}
24935 \newcommand{\TitleFrame}[2]{%
24936 \fboxrule=\FrameRule \fboxsep=\FrameSep
24937 \vbox{\nobreak \vskip -0.7\FrameSep
24938 \rlap{\strut#1}\nobreak\nointerlineskip% left justified
24939 \vskip 0.7\FrameSep
24940 \noindent\fbox{#2}}}
24941 \newenvironment{titledframe}[2][\FrameFirst@Lab\ (cont.)]{%
24942 \def\FrameFirst@Lab{\textbf{#2}}%
24943 \def\FrameCont@Lab{\textbf{#1}}%
24944 \def\FrameCommand##1{%
24945 \TitleFrame{\FrameFirst@Lab}{##1}}
24946 \def\FirstFrameCommand##1{%
24947 \TitleFrame{\FrameFirst@Lab}{##1}}
24948 \def\MidFrameCommand##1{%
24949 \TitleFrame{\FrameCont@Lab}{##1}}
24950 \def\LastFrameCommand##1{%
24951 \TitleFrame{\FrameCont@Lab}{##1}}
24952 \MakeFramed{\hsize\textwidth
24953 \advance\hsize -2\FrameRule
24954 \advance\hsize -2\FrameSep
24955 \FrameRestore}}%
24956 {\endMakeFramed}
24957 \end{lcode}
24958
24959 \begin{syntax}
24960 \senv{titledframe}\oarg{cont-title}\marg{title} text \eenv{titledframe} \\
24961 \end{syntax}
24962 The \Ie{titledframe} environment is identical to \Ie{framewithtitle}
24963 except that the title is placed just before the frame. Again, if
24964 you would like a centered title, replace the line marked `left justified'
24965 in \cmd{\TitleFrame} by
24966 \begin{lcode}
24967 \rlap{\centerline{\strut#1}}\nobreak\nointerlineskip% centered
24968 \end{lcode}
24969
24970 You can adjust the code for the \Ie{framewithtitle} and \Ie{titledframe}
24971 environments to suit your own purposes, especially as they are not
24972 part of the class so you would have to type them in yourself anyway
24973 if you wanted to use them, using whatever names you felt suitable.
24974
24975 \index{frame!title|)}
24976
24977 The class provides two further environments in addition to those
24978 from the \Lpack{framed} package.
24979 \begin{syntax}
24980 \senv{qframe} text \eenv{qframe} \\
24981 \senv{qshade} text \eenv{qshade} \\
24982 \end{syntax}
24983
24984 When used within, say, a \Ie{quotation} environment, the \Ie{framed}
24985 and \Ie{shaded} environments do not closely box the indented text. The
24986 \Ie{qframe} and \Ie{qshade} environments do provide close
24987 boxing.\footnote{Donald Arseneau has said that he may put something similar
24988 in a later version the \Ie{framed} package.}
24989 The difference can be seen in the following \Ie{quotation}.
24990
24991 \begin{quotation}
24992 This is the start of a \Ie{quotation} environment. It forms the basis showing
24993 the difference between the \Ie{framed} and \Ie{qframe} environments.
24994
24995 \begin{qframe}
24996 This is the second paragraph in the \Ie{quotation} environment and in turn it
24997 is within the \Ie{qframe} environment.
24998 \end{qframe}
24999
25000 \begin{framed}
25001 This is the third paragraph in the \Ie{quotation} environment and in turn it
25002 is within the \Ie{framed} environment.
25003 \end{framed}
25004
25005 This is the fourth and final paragraph within the \Ie{quotation} environment
25006 and is not within either a \Ie{qfame} or \Ie{framed} environment.
25007 \end{quotation}
25008
25009 If you want to put a frame inside an \Ie{adjustwidth} environment
25010 then you may well find that \Ie{qframe} or \Ie{qshade} meet your
25011 expections better than \Ie{framed} of \Ie{shaded}. Of course, it does
25012 depend on what your expectations are.
25013
25014 \index{frame!box|)}
25015 \index{box!framed|)}
25016
25017 \section{Long comments}
25018
25019 The \% comment character can be used to comment out (part of) a line
25020 of \tx\ code, but this gets tedious if you need to comment out long
25021 chunks of code.\footnote{Though most modern \LaTeX{} editors has a
25022 feature to out comment a highlighted piece of code, and tools to
25023 uncomment it again.}
25024
25025 \begin{syntax}
25026 \senv{comment} text to be skipped over \eenv{comment} \\
25027 \end{syntax}
25028 \glossary(comment)%
25029 {\senv{comment}}%
25030 {Skip over the environment.}
25031 \index{comment out text}
25032 As an extreme form of font changing, although it doesn't actually work that
25033 way, anything in a \Ie{comment} environment will not appear in the
25034 document; effectively, \ltx\ throws it all away. This can be useful
25035 to temporarily discard chunks of stuff instead of having to mark each line
25036 with the \% comment character.
25037 \begin{note}
25038 One thing to remember with the \Ie{comment}, is that your editing
25039 programme might not regocnise the enclosed code as being ``commented
25040 out'' and you might end up being confused as to where the boundaries
25041 of the commented code actually are.
25042
25043 As most editors has methods to outcomment blocks of code with \%, it
25044 might be better to use just that.
25045 \end{note}
25046
25047
25048
25049
25050 \begin{syntax}
25051 \cmd{\newcomment}\marg{name} \\
25052 \cmd{\commentsoff}\marg{name} \\
25053 \cmd{\commentson}\marg{name} \\
25054 \end{syntax}
25055 \glossary(newcomment)%
25056 {\cs{newcomment}\marg{name}}%
25057 {Define a new comment environment called \meta{name}.}
25058 \glossary(commentsoff)%
25059 {\cs{commentsoff}\marg{name}}%
25060 {Process contents of the \meta{name} comment environment.}
25061 \glossary(commentson)%
25062 {\cs{commentson}\marg{name}}%
25063 {Skip contents of the \meta{name} comment environment.}
25064 The class lets you define your own comment environment via the
25065 \cmd{\newcomment} command which defines a comment environment called
25066 \meta{name}. In fact the class itself uses \verb?\newcomment{comment}? to
25067 define the \Ie{comment} environment. A comment environment \meta{name}
25068 may be switched off so that its contents are not ignored by using the
25069 \cmd{\commentsoff} declaration. It may be switched on later by the
25070 \cmd{\commentson} declaration. In either case \meta{name} must have
25071 been previously declared as a comment environment via \cmd{\newcomment}.
25072
25073 Suppose, for example, that you are preparing a draft document for
25074 review by some others and you want to include some notes for the reviewers.
25075 Also, you want to include some private comments in the source for yourself.
25076 You could use the \Ie{comment} environment for your private comments and
25077 create another environment for the notes to the reviewers. These notes
25078 should not appear in the final document. Your source might then look like:
25079 \begin{lcode}
25080 \newcomment{review}
25081 \ifdraftdoc\else
25082 \commentsoff{review}
25083 \fi
25084 ...
25085 \begin{comment}
25086 Remember to finagle the wingle!
25087 \end{comment}
25088 ...
25089 \begin{review}
25090 \textit{REVIEWERS: Please pay particular attention to this section.}
25091 \end{review}
25092 ...
25093 \end{lcode}
25094
25095 Comment environments cannot be nested, nor can they overlap.
25096 The environments in the code below will not work in the manner that might
25097 be expected:
25098 \begin{lcode}
25099 \newcomment{acomment} \newcomment{mycomment}
25100 \begin{comment}
25101 \begin{acomment} %% comments cannot be nested
25102 ...
25103 \end{acomment}
25104 ...
25105 \begin{mycomment}
25106 ...
25107 \end{comment}
25108 ...
25109 \end{mycomment} %% comments cannot overlap
25110 \end{lcode}
25111
25112 More encompassing \Ie{comment} environments are available if you
25113 use Victor Eijkhout's \Lpack{comment} package~\cite{COMMENT}.
25114
25115 \fancybreak{}
25116
25117 Do note that due to most syntax highlighting not being aware of your
25118 \Ie{comment}-like envs they are easy to miss in the code.
25119
25120 \begin{tip}
25121 On a modern kernel, you can easily make a comment like env simple via
25122 \begin{lcode}
25123 \NewDocumentEnvironment{FooBar}{+b}{}{}
25124 \end{lcode}
25125 The \verb?+b? part tells the env to gobble up its entire contents
25126 into \verb?#1?, which we then do not use.
25127 \end{tip}
25128
25129
25130
25131 \section{Verbatims}
25132
25133 \index{verbatim|(}
25134
25135 Standard \ltx\ defines the \cmd{\verb} and \cmd{\verb*} commands
25136 for typesetting short pieces of text verbatim, short because they
25137 cannot include a linebreak. For longer verbatim texts the
25138 \Ie{verbatim} or \Ie{verbatim*} environments can be used. The star forms
25139 indicate spaces in the verbatim text by outputing a \verb*? ? mark for
25140 each space. The class extends the standard verbatims in various ways.
25141
25142 \index{verbatim!short}
25143 If you have to write a lot of \cmd{\verb} text, as I have had to do for
25144 this book, it gets tedious to keep on typing this sort of thing:
25145 \verb?\verb!verbatim text!?. Remember that the character immediately after
25146 the \cmd{\verb}, or \cmd{\verb*}, ends the verbatim processing.
25147 \begin{syntax}
25148 \cmd{\MakeShortVerb}\marg{backslash-char} \\
25149 \cmd{\MakeShortVerb*}\marg{backslash-char} \\
25150 \cmd{\DeleteShortVerb}\marg{backslash-char} \\
25151 \end{syntax}
25152 \glossary(MakeShortVerb)%
25153 {\cs{MakeShortVerb}\marg{backslash-char}}%
25154 {Makes \meta{char} a shorthand for \cs{verb}\meta{char}.}
25155 \glossary(MakeShortVerb*)%
25156 {\cs{MakeShortVerb*}\marg{backslash-char}}%
25157 {Makes \meta{char} a shorthand for \cs{verb*}\meta{char}.}
25158 \glossary(DeleteShortVerb)%
25159 {\cs{DeleteShortVerb}\marg{backslash-char}}%
25160 {Returns \meta{char} to its normal meaning instead of being a shorthand
25161 for \cs{verb}\meta{char}.}
25162 The \cmd{\MakeShortVerb} macro takes a character preceded by a backslash
25163 as its argument, say \verb?\!?, and makes that character equivalent to
25164 \verb?\verb!?. Using the character a second time will stop the verbatim
25165 processing.
25166 Doing, for example \verb?\MakeShortVerb{\!}?, lets you then use
25167 \verb?!verbatim text!?
25168 instead of the longer winded \verb?\verb!verbatim text!?.
25169 The \cs{MakeShortVerb*} makes a version that uses \verb?\verb*? internally.
25170
25171 You have to pick as the short verb character one that you are unlikely
25172 to use; a good choice is often the \verb?|? bar character as this
25173 rarely used in normal text. This choice, though may be unfortunate if
25174 you want to have any tabulars with vertical lines, as the bar
25175 character is used to specify those. The \cmd{\DeleteShortVerb} macro
25176 is provided for this contingency; give it the same argument as an
25177 earlier \cmd{\MakeShortVerb} and it will restore the short verb
25178 character to its normal state.
25179
25180 The \cmd{\MakeShortVerb}, \cmd{\MakeShortVerb} and
25181 \cmd{\DeleteShortVerb} macros come from the \Lpack{shortvrb} package
25182 which is automatically loaded by the class.
25183
25184 \fancybreak{}
25185
25186
25187 \begin{syntax}
25188 \cmd{\setverbatimfont}\marg{font-declaration} \\
25189 \end{syntax}
25190 \glossary(setverbatimfont)%
25191 {\cs{setverbatimfont}\marg{fontspec}}%
25192 {Sets the font to be used for verbatim text.}
25193 The default font\index{verbatim!changing font} for verbatims is the normal
25194 sized monospaced font. The declaration
25195 \cmd{\setverbatimfont} can be used to specify a different font.
25196 The class default is
25197 \begin{lcode}
25198 \setverbatimfont{\normalfont\ttfamily}
25199 \end{lcode}
25200 To use a smaller version simply say
25201 \begin{lcode}
25202 \setverbatimfont{\normalfont\ttfamily\small}
25203 \end{lcode}
25204
25205 A monospaced font is normally chosen as verbatim text is often used
25206 to present program code or typewritten text. If you want a more exotic
25207 font, try this
25208 \begin{lcode}
25209 \setverbatimfont{\fontencoding{T1}\fontfamily{cmss}\selectfont}
25210 \end{lcode}
25211 and your verbatim text will then look like %%
25212 \setverbatimfont{\fontencoding{T1}\fontfamily{cmss}\selectfont}
25213 \begin{verbatim}
25214 We are no longer using the boring old typewriter font
25215 for verbatim text. We used the T1 encoding
25216 to make sure that characters that are often ligatures
25217 like ``, or '', or ---, or <, or >, print as expected.
25218 After this we will switch back to the default verbatim font via
25219 \setverbatimfont{\normalfont\ttfamily}
25220 \end{verbatim}
25221 \setverbatimfont{\normalfont\ttfamily} In the normal way of things
25222 with an OT1 fontencoding,\footnote{No-one should use OT1 encoding
25223 anymore.} typesetting the ligatures mentioned above in the sans
25224 font produces: {\fontencoding{OT1}\fontfamily{cmss}\selectfont
25225 ligatures like ``, or '', or ---, or <, or >}, which is not what
25226 happens in the \cmd{\verbatim} environment.
25227
25228
25229 \begin{syntax}
25230 \senv{verbatim} anything \eenv{verbatim} \\
25231 \senv{verbatim*} anything \eenv{verbatim*} \\
25232 \end{syntax}
25233 \glossary(verbatim)%
25234 {\senv{verbatim}}%
25235 {Typeset the contents verbatim.}
25236 In the \Ie{verbatim} environment\footnote{This version of the \Ie{verbatim}
25237 environment is heavily based on the \Lpack{verbatim} package~\cite{VERBATIM}
25238 but does provide some extensions.}
25239 you can write anything you want (except
25240 \eenv{verbatim}), and it will be typeset exactly as written. The \Ie{verbatim*}
25241 environment is similar except, like with \cmd{\verb*}, spaces and tabs will be
25242 indicated with a \verb*? ? mark.
25243
25244
25245 \begin{Changed}[January 2024]
25246 The following macros are no longer used. They will either issue a
25247 warning or do nothing. Users are encouraged to remove them.
25248 \cmd{\tabson}\oarg{number}, \cmd{\tabsoff} (was the default),
25249 \cmd{\wrappingon}, \cmd{\wrappingoff} (was the default).
25250
25251 These macro enabled tabs marking (by displaying tabs as sseveral
25252 spaces) and automatic line wrapping (at white space) for
25253 \Ie{verbatim} (it was never applied to \Ie{verbatim*}). As part of a
25254 restructuring these features are no longer supported.
25255 \end{Changed}
25256
25257
25258
25259 % \begin{syntax}
25260 % \cmd{\tabson}\oarg{number} \\
25261 % \cmd{\tabsoff} \\
25262 % \end{syntax}
25263 % \glossary(tabson)%
25264 % {\cs{tabson}\oarg{number}}%
25265 % {Set \meta{number} of spaces in a verbatim for a TAB character;
25266 % default 4.}
25267 % \glossary(tabsoff)%
25268 % {\cs{tabsoff}}%
25269 % {Ignore extra TAB spaces in a verbatim.}
25270 % \index{verbatim!with tab spaces}
25271 % The standard \Ie{verbatim} environment ignores any TAB characters; with
25272 % the class's environment after calling the \cmd{\tabson} declaration
25273 % the environment will handle TAB characters. By default 4 spaces are used
25274 % to represent a TAB; the optional \meta{number} argument to the declaration
25275 % will set the number of spaces for a TAB to be \meta{number}.
25276 % Some folk like to use 8 spaces for a TAB, in which case they would need
25277 % to declare \verb?\tabson[8]?. Unremarkably, the declaration \cmd{\tabsoff}
25278 % switches off TABs. The class default is \cmd{\tabsoff}.
25279
25280 % \begin{syntax}
25281 % \cmd{\wrappingon} \\
25282 % \cmd{\wrappingoff} \\
25283 % \lnc{\verbatimindent} \\
25284 % \cmd{\verbatimbreakchar} \\
25285 % \end{syntax}
25286 % \glossary(wrappingon)%
25287 % {\cs{wrappingon}}%
25288 % {Wrap overlong verbatim lines.}
25289 % \glossary(wrappingoff)%
25290 % {\cs{wrappingoff}}%
25291 % {The normal behaviour of not wrapping overlong verbatim lines.}
25292 % \glossary(verbatimindent)%
25293 % {\cs{verbatimindent}}%
25294 % {Indent for wrapped overlong verbatim lines.}
25295 % \glossary(verbatimbreakchar)%
25296 % {\cs{verbatimbreakchar}}%
25297 % {Character indicating a verbatim line is being wrapped.}
25298 % As noted, whatever is written in a \Ie{verbatim} environment is output
25299 % just as written, even if lines are too long\index{verbatim!wrap long lines}
25300 % to fit on the page. The
25301 % declaration \cmd{\wrappingon} lets the environment break lines so that they
25302 % do not overflow. The declaration \cmd{\wrappingoff} restores the normal
25303 % behaviour.
25304
25305 % The following is an example of how a wrapped verbatim line looks. In
25306 % the source the contents of the \Ie{verbatim} was written as a single line.
25307 % \wrappingon
25308 % \begin{verbatim}
25309 % This is an example of line wrapping in the verbatim environment. It is a single line in the source and the \wrappingon declaration has been used.
25310 % \end{verbatim}
25311 % \wrappingoff
25312
25313 % The wrapped portion of verbatim lines are indented from the left margin
25314 % by the length \lnc{\verbatimindent}. The value can be changed by the usual
25315 % length changing commands. The end of each line that has been wrapped is marked
25316 % with the \meta{char} character of the \cmd{\verbatimbreakchar} macro.
25317 % The class default is \verb?\char`\%?, so that lines are
25318 % marked with \verb?%?.
25319 % To put a `/' mark at the end of wrapped lines you can do
25320 % \begin{lcode}
25321 % \renewcommand*\verbatimbreakchar{\char'\/}
25322 % \end{lcode}
25323 % If you need something more exotic, you need to wrap it in a box:
25324 % \begin{lcode}
25325 % \renewcommand*\verbatimbreakchar{\mbox{$\downarrow$}}
25326 % \end{lcode}
25327 % which will make `$\downarrow$' the end marker.\footnote{Internally the
25328 % \cs{discretionary} macro is used to typeset \cs{verbatimbreakchar},
25329 % so the break char should be what ever \cs{discretionary} can
25330 % handle.}
25331
25332 % \begin{caveat}
25333 % \cmd{\wrappingon} combined with \Ie{verbatim*} does not work, the
25334 % wrapping part is ignored. Currently there are no plans to fix this.
25335 % \end{caveat}
25336
25337
25338 \subsection{Boxed verbatims}
25339
25340 \begin{recommended}
25341 Again the \Lpack{tcolorbox} package also offers boxed verbatim, and
25342 can be combined with packages like \Lpack{listings} or
25343 \Lpack{minted}.
25344 \end{recommended}
25345
25346
25347
25348 Verbatim environments are often used to present program code or, as
25349 in this book, \ltx\ code. For such applications it can be useful to
25350 put the code in a box, or to number the code lines, or perhaps both.
25351
25352 \begin{syntax}
25353 \senv{fboxverbatim} anything \eenv{fboxverbatim} \\
25354 \end{syntax}
25355 \glossary(fboxverbatim)%
25356 {\senv{fboxverbatim}}%
25357 {Puts a frame around the verbatim material. Page breaks are not allowed.}
25358 The \Ie{fboxverbatim} environment\index{frame!verbatim}\index{verbatim!frame}
25359 typesets its contents verbatim and
25360 puts a tightly fitting frame around the result; in a sense it is similar
25361 to the \cmd{\fbox} command.
25362
25363 \begin{syntax}
25364 \senv{boxedverbatim} anything \eenv{boxedverbatim} \\
25365 \senv{boxedverbatim*} anything \eenv{boxedverbatim*} \\
25366 \end{syntax}
25367 \glossary(boxedverbatim)%
25368 {\senv{boxedverbatim}}%
25369 {May put a box around the verbatim material; lines may be numbered and page
25370 breaks are allowed.}
25371 \glossary(boxedverbatim*)%
25372 {\senv{boxedverbatim*}}%
25373 {May put a box around the verbatim* material; lines may be numbered and page
25374 breaks are allowed.}
25375 The \Ie{boxedverbatim} and \Ie{boxedverbatim*} environments are like
25376 the \Ie{verbatim} and \Ie{verbatim*} environments except that a box,
25377 allowing page breaks, may be put around the verbatim text and the lines
25378 of text\index{line number} may be numbered.\index{boxed verbatim}\index{numbered lines}
25379 The particular format of the output can be
25380 controlled as described below.
25381 \begin{syntax}
25382 \cmd{\bvbox} \cmd{\bvtopandtail} \cmd{\bvsides} \cmd{\nobvbox} \\
25383 \lnc{\bvboxsep} \\
25384 \end{syntax}
25385 \glossary(bvbox)%
25386 {\cs{bvbox}}%
25387 {Rectangular boxes will be drawn for \Pe{boxedverbatim} environments.}
25388 \glossary(nobvbox)%
25389 {\cs{nobvbox}}%
25390 {\Pe{boxedverbatim} environments will not be framed in any way.}
25391 \glossary(bvtopandtail)%
25392 {\cs{bvtopandtail}}%
25393 {Draw horizontal rules before and after \Pe{boxedverbatim} environments.}
25394 \glossary(bvsides)%
25395 {\cs{bvsides}}%
25396 {Draw vertical rules on each side of \Pe{boxedverbatim} environments.}
25397 \glossary(bvboxsep)%
25398 {\cs{bvboxsep}}%
25399 {Separation between text and framing in \Pe{boxedverbatim} environments.}
25400 Four styles of boxes are provided and you can extend these. Following
25401 the \cmd{\bvbox} declaration, a box is drawn round the verbatim text, breaking
25402 at page boundaries if necessary; this is the default style. Conversely,
25403 no boxes are drawn after the \cmd{\nobvbox} declaration. With the
25404 \cmd{\bvtopandtail} declaration horizontal lines are drawn at the start and
25405 end of the verbatim text, and with the \cmd{\bvsides} declarations, vertical
25406 lines are drawn at the left and right of the text. The separation between
25407 the lines and the text is given by the length \lnc{\bvboxsep}.
25408
25409 The following hooks are provided to set your own
25410 boxing\index{frame!verbatim!styling}\index{verbatim!frame!styling} style.
25411 \begin{syntax}
25412 \cmd{\bvtoprulehook} \cmd{\bvtopmidhook} \cmd{\bvendrulehook} \\
25413 \cmd{\bvleftsidehook} \cmd{\bvrightsidehook} \\
25414 \end{syntax}
25415 \glossary(bvtoprulehook)%
25416 {\cs{bvtoprulehook}}%
25417 {Called at the start of a \Pe{boxedverbatim} environment and after a pagebreak.}
25418 \glossary(bvtopmidhook)%
25419 {\cs{bvtopmidhook}}%
25420 {Called after \cs{bvtoprulehook} at the start of a \Pe{boxedverbatim} environment.}
25421 \glossary(bvendrulehook)%
25422 {\cs{bvendrulehook}}%
25423 {Called at the end of a \Pe{boxedverbatim} environment, and before a pagebreak.}
25424 \glossary(bvleftsidehook)%
25425 {\cs{bvleftsidehook}}%
25426 {Called before each line in a \Pe{boxedverbatim} environment.}
25427 \glossary(bvrightsidehook)%
25428 {\cs{bvrightsidehook}}%
25429 {Called after each line in a \Pe{boxedverbatim} environment.}
25430 The macros \cmd{\bvtoprulehook} and \cmd{\bvendrulehook} are called at
25431 the start and end of the \Ie{boxedverbatim} environment, and before and after
25432 page breaks. The macros
25433 \cmd{\bvleftsidehook} and \cmd{\bvrightsidehook} are called at the start
25434 and end of each verbatim line. The macro \cmd{\bvtopmidhook} is
25435 called after \cmd{\bvtoprulehook} at the start of the environment.
25436 It can be used to add some space if \cmd{\bvtoprulehook} is empty.
25437
25438 \begin{syntax}
25439 \cmd{\bvperpagetrue} \cmd{\bvperpagefalse} \\
25440 \cmd{\bvtopofpage}\marg{text} \cmd{\bvendofpage}\marg{text} \\
25441 \end{syntax}
25442 \glossary(bvperpagetrue)%
25443 {\cs{bvperpagetrue}}%
25444 {Visibly break a \Pe{boxedverbatim} at a page break using \cs{bvtopofpage}
25445 and \cs{bvendofpage}.}
25446 \glossary(bvperpagefalse)%
25447 {\cs{bvperpagefalse}}%
25448 {Do not mark page breaks in a \Pe{boxedverbatim}.}
25449 \glossary(bvtopofpage)%
25450 {\cs{bvtopofpage}\marg{text}}%
25451 {Use \meta{text} as the \Pe{boxedverbatim} page break marker at the top of
25452 a page.}
25453 \glossary(bvendofpage)%
25454 {\cs{bvendofpage}\marg{text}}%
25455 {Use \meta{text} as the \Pe{boxedverbatim} page break marker at the bottom
25456 of a page.}
25457 The command \cmd{\bvperpagetrue} indicates
25458 that a box should be visibly broken at a pagebreak, while there should
25459 be no visible break for \cmd{\bvperpagefalse}.
25460 If the box continues on to another page then it may be advantageous
25461 to place some sort of heading before the verbatim continues. Following
25462 the declaration \cmd{\bvperpagetrue} the \meta{text} argument to
25463 \cmd{\bvtopofpage} will be typeset after any pagebreak. For example you
25464 could set:
25465 \begin{lcode}
25466 \bvtopofpage{continued}
25467 \end{lcode}
25468 to print `continued' in the normal text font.
25469
25470 By default, the class sets
25471 \begin{lcode}
25472 \bvendofpage{\hrule\kern-.4pt}
25473 \end{lcode}
25474 which causes the \cmd{\hrule} to be drawn at the end of a page as the
25475 visible break (the rule is 0.4pt thick and the kern backs up
25476 that amount after the rule, so it effectively takes no vertical space).
25477 This is not always suitable. For instance, if there will be
25478 a `continued' message at the top of the following page it may seem odd
25479 to draw a line at the bottom of the previous page. In this case, setting
25480 \begin{lcode}
25481 \bvendofpage{}
25482 \end{lcode}
25483 will eliminate the rule.
25484
25485 As examples of the use of
25486 these hooks, here is how some of the boxed verbatim styles are defined.
25487
25488 The default style is \cmd{\bvbox},
25489 which puts separate full boxes on each page.
25490 \begin{lcode}
25491 \newcommand{\bvbox}{%
25492 \bvperpagetrue
25493 \renewcommand{\bvtoprulehook}{\hrule \nobreak \vskip-.1pt}%
25494 \renewcommand{\bvleftsidehook}{\vrule}%
25495 \renewcommand{\bvrightsidehook}{\vrule}%
25496 \renewcommand{\bvendrulehook}{\hrule}%
25497 \renewcommand{\bvtopmidhook}{\rule{0pt}{2\fboxsep} \hss}%
25498 }
25499 \end{lcode}
25500 The \cmd{\nobvbox} turns off all boxing, and is defined as
25501 \begin{lcode}
25502 \newcommand{\nobvbox}{%
25503 \bvperpagefalse
25504 \renewcommand{\bvtoprulehook}{}%
25505 \renewcommand{\bvleftsidehook}{}%
25506 \renewcommand{\bvrightsidehook}{}%
25507 \renewcommand{\bvendrulehook}{}%
25508 \renewcommand{\bvtopmidhook}{\rule{0pt}{2\fboxsep} \hss}%
25509 }
25510 \end{lcode}
25511 The definitions of the other styles, \cmd{\bvtopandtail} and \cmd{\bvsides},
25512 are intermediate between \cmd{\bvbox} and \cmd{\nobvbox} in the obvious
25513 manner.
25514
25515
25516 \begin{syntax}
25517 \cmd{\linenumberfrequency}\marg{nth} \\
25518 \cmd{\resetbvlinenumber} \\
25519 \cmd{\setbvlinenums}\marg{first}\marg{startat} \\
25520 \cmd{\linenumberfont}\marg{font declaration} \\
25521 \end{syntax}
25522 \glossary(linenumberfrequency)%
25523 {\cs{linenumberfrequency}\marg{nth}}%
25524 {Number every \meta{nth} line in a \Pe{boxedverbatim} or a \Pe{verse}.}
25525 \glossary(resetbvlinenumber)%
25526 {\cs{resetbvlinenumber}}%
25527 {Resets the \Pe{boxedverbatim} line number to zero.}
25528 \glossary(setbvlinenums)%
25529 {\cs{setbvlinenums}\marg{first}\marg{startat}}%
25530 {The first line of the following \Pe{boxedverbatim} is number \marg{first}
25531 and the
25532 first printed line number should be \meta{startat}.}
25533 \glossary(linenumberfont)%
25534 {\cs{linenumberfont}\marg{fontspec}}%
25535 {Specify the font for line numbers.}
25536
25537 The command \cmd{\linenumberfrequency} controls the
25538 numbering\index{line number!frequency} of lines in
25539 a \Ie{boxedverbatim} --- every \meta{nth} line will be numbered.
25540 If \meta{nth} is 0 or less,
25541 then no lines are numbered, if \meta{nth} is 1 then each line is numbered,
25542 and if \meta{nth} is \texttt{n}, where \texttt{n} is 2 or more, then
25543 only every \texttt{n}th line is numbered. Line numbering is continuous
25544 from one instance
25545 of the \Ie{boxedverbatim} environment to the next. Outside the environment
25546 the line numbers\index{line number!reset} can be reset at any time by the
25547 command \cmd{\resetbvlinenumber}.
25548
25549 The \cmd{\setbvlinenums} macro can be
25550 used to specify that the number of the first line of the following
25551 \Ie{boxedverbatim}
25552 shall be \meta{first} and the first printed number shall be \meta{startat}.
25553
25554 The \cmd{\linenumberfont} declaration sets
25555 \meta{font declaration} as the font\index{line number!font} for the
25556 line numbers. The default specification for this is:
25557 \begin{lcode}
25558 \linenumberfont{\footnotesize\rmfamily}
25559 \end{lcode}
25560 Line numbers\index{line number!position} are always set at the left of
25561 the lines because there
25562 is no telling how long a line might be and it might clash with a line number
25563 set at the right.
25564 \begin{syntax}
25565 \cmd{\bvnumbersinside} \\
25566 \cmd{\bvnumbersoutside} \\
25567 \end{syntax}
25568 \glossary(bvnumbersinside)%
25569 {\cs{bvnumbersinside}}%
25570 {Line numbers typeset inside a \Pe{boxedverbatim} box.}
25571 \glossary(bvnumbersoutside)%
25572 {\cs{bvnumbersoutside}}%
25573 {Line numbers typeset outside a \Pe{boxedverbatim} box.}
25574 Line numbers are typeset inside the box after the declaration
25575 \cmd{\bvnumberinside} and are typeset outside the box after the
25576 declaration \cmd{\bvnumbersoutside}. The default is to print
25577 the numbers inside the box.
25578
25579 Verbatim tabbing, but not wrapping, applies to the \Ie{boxedverbatim}
25580 environment.
25581
25582
25583
25584 \subsection{New verbatims}
25585
25586 \index{verbatim!new|(}
25587 The class implementation of verbatims lets you define your
25588 own kind of verbatim environment. Unfortunately this is not quite
25589 as simple as saying
25590 \begin{lcode}
25591 \newverbatim{myverbatim}{...}{...}
25592 \end{lcode}
25593 as you can for defining normal environments. Instead, the general scheme
25594 is
25595 \begin{lcode}
25596 \newenvironment{myverbatim}%
25597 {<non-verbatim stuff> \verbatim <more non-verbatim stuff>}%
25598 {\endverbatim}
25599 \end{lcode}
25600 In particular, you cannot use either the \cmd{\begin} or \cmd{\end}
25601 macros inside the definition of the new verbatim environment. For example,
25602 the following code will not work
25603 \begin{lcode}
25604 \newenvironment{badverbatim}%
25605 {NBG\begin{verbatim}}{\end{verbatim}}
25606 \end{lcode}
25607 and this won't work either
25608 \begin{lcode}
25609 \newenvironment{badverbatim}%
25610 {\begin{env}\verbatim}{\endverbatim\end{env}}
25611 \end{lcode}
25612 And, as with the standard \Ie{verbatim} environment, you cannot use
25613 the new one in the definition of a new command.
25614
25615 For an example of something that does work, this next little piece of
25616 typesetting was done in a new verbatim environment I have called
25617 \texttt{verbexami}, which starts and ends with a horizontal rule, and it
25618 shows the definition of \texttt{verbexami}.
25619 \newenvironment{verbexami}%
25620 {\par\noindent\hrule The verbexami environment \verbatim}%
25621 {\endverbatim\hrule}
25622
25623 \vspace{0.5\onelineskip}
25624 \begin{verbexami}
25625 \newenvironment{verbexami}%
25626 {\par\noindent\hrule The verbexami environment \verbatim}%
25627 {\endverbatim\hrule}
25628 \end{verbexami}
25629 \vspace{0.5\onelineskip}
25630
25631 And this is a variation on the theme, with the environment again being
25632 enclosed by horizontal rules.
25633 \newenvironment{verbexamii}%
25634 {\vspace{0.5\baselineskip}\hrule
25635 \vspace{0.2\baselineskip} Verbexamii \verbatim \textsc{Is this fun?}}%
25636 {\endverbatim\hrule\vspace{0.3\baselineskip}}
25637
25638 \vspace{0.5\onelineskip}
25639 \begin{verbexamii}
25640 \newenvironment{verbexamii}%
25641 {\vspace{0.5\baselineskip}\hrule \vspace{0.2\baselineskip}
25642 Verbexamii \verbatim \textsc{Is this fun?}}%
25643 {\endverbatim\hrule\vspace{0.3\baselineskip}}
25644 \end{verbexamii}
25645 \vspace{0.5\onelineskip}
25646
25647 As no doubt you agree, these are not memorable examples of
25648 the typesetter's art but do indicate that you can define your own
25649 verbatim environments and may need to take a bit of care to get something
25650 that passes muster.
25651
25652 I will give some more useful examples, but mainly based on environments
25653 for writing verbatim files as I think that these provide a broader
25654 scope.
25655
25656
25657 \subsection{Example: the \texttt{lcode} environment}
25658
25659 In this manual all the example \ltx\ code has been typeset in
25660 the \Ie{lcode} environment; this is a verbatim environment defined
25661 especially for the purpose. Below I describe the
25662 code for defining my \Ie{lcode} environment, but first here
25663 is a simple definition of a verbatim environment, which I will
25664 call \texttt{smallverbatim},
25665 that uses the \cmd{\small} font\index{verbatim!font} instead of the
25666 normalsize font.
25667 \begin{lcode}
25668 \newenvironment{smallverbatim}%
25669 {\setverbatimfont{\normalfont\ttfamily\small}%
25670 \verbatim}%
25671 {\endverbatim}
25672 \end{lcode}
25673
25674 The \Ie{verbatim} environment is implemented as a kind of \Ie{trivlist},
25675 and lists usually have extra vertical space before and after them. For
25676 my environment I did not want any extra spacing\index{list!spaces}
25677 so I defined the
25678 macro \cmd{\@zeroseps} to zero the relevant list spacings. I also wanted
25679 the code lines to be inset a little, so I defined a new length
25680 called \lnc{\gparindent} to use as the indentation.
25681 \begin{lcode}
25682 \makeatletter
25683 \newcommand{\@zeroseps}{\setlength{\topsep}{\z@}%
25684 \setlength{\partopsep}{\z@}%
25685 \setlength{\parskip}{\z@}}
25686 \newlength{\gparindent} \setlength{\gparindent}{\parindent}
25687 \setlength{\gparindent}{0.5\parindent}
25688 % Now, the environment itself
25689 \newenvironment{lcode}{\@zeroseps
25690 \renewcommand{\verbatim@startline}{%
25691 \verbatim@line{\hskip\gparindent}}
25692 \small\setlength{\baselineskip}{\onelineskip}\verbatim}%
25693 {\endverbatim
25694 \vspace{-\baselineskip}%
25695 \noindent
25696 }
25697 \makeatother
25698 \end{lcode}
25699
25700 Unless you are intimately familiar with the inner workings of the
25701 \Ie{verbatim} processing you deserve an explanation of the \Ie{lcode}
25702 definition.
25703
25704 Extremely roughly, the code for \cmd{\verbatim} looks like this:
25705 \begin{lcode}
25706 \def\verbatim{%
25707 \verbatim@font
25708 % for each line, until \end{verbatim}
25709 \verbatim@startline
25710 % collect the characters in \verbatim@line
25711 \verbatim@processline{\the\verbatim@line\par}
25712 % repeat for the next line
25713 }
25714 \end{lcode}
25715 The code first calls \cmd{\verbatim@font} to set the font to be used.
25716 Then, for each line it does the following:
25717 \begin{itemize}
25718 \item Calls the macro \cmd{\verbatim@startline} to start
25719 off the output version of the line.
25720 \item Collects all the characters comprising the line
25721 as a single token called \cmd{\verbatim@line}.
25722 \item If the characters are the string `\verb?\end{verbatim}?' it finishes
25723 the verbatim environment.
25724 \item Otherwise it calls the macro \cmd{\verbatim@processline} whose
25725 argument is the characters in the
25726 line, treated as a paragraph. It then starts all over again with
25727 the next line.
25728 \end{itemize}
25729
25730 I configured the \cmd{\verbatim@startline}
25731 macro to indent the line of text using a horizontal skip of \lnc{\gparindent}.
25732 The rest of the initialisation code, before calling \cmd{\verbatim}
25733 to do the real processing, just sets up the vertical spacing.
25734
25735
25736 \index{verbatim!new|)}
25737
25738 \index{verbatim|)}
25739
25740
25741
25742
25743 \section{Files}
25744
25745 \index{file|(}
25746
25747 \ltx\ reads and writes various files as it processes a document.
25748 Obviously it reads the document source file, or files, and it writes
25749 the \pixfile{log} file recording what it has done. It also reads and writes
25750 the \pixfile{aux} file, and may read and write other files like a
25751 \pixfile{toc} file.
25752
25753 On occasions it can be useful to get \ltx\ to read and/or write
25754 other files of your own choosing. Unfortunately standard \ltx\ does
25755 not provide any easy method for doing this. The \Mname\ class
25756 tries to rectify this.
25757
25758 \begin{syntax}
25759 \cmd{\jobname} \\
25760 \end{syntax}
25761 \glossary(jobname)%
25762 {\cs{jobname}}%
25763 {The name of the document's main source file.}
25764 When you run \ltx\ on your source file, say \texttt{fred.tex}, \ltx\
25765 stores the name of this file (\texttt{fred}) in the macro \cmd{\jobname}.
25766 \ltx\ uses this to name the various files that it writes out --- the
25767 \pixfile{dvi} or \pixfile{pdf} file, the \pixfile{log} file, the
25768 \pixfile{aux} file, etc.
25769
25770 \index{stream|(}
25771
25772 \tx\ can read from 16 input streams\index{stream!limited number}
25773 and can write to 16 output
25774 streams. Normally an input stream\index{stream!input} is allocated for each
25775 kind of file that will be read\index{file!read} and an
25776 output\index{stream!output} stream for each kind of file that will
25777 be written\index{file!write}. On the input side, then, at least two
25778 streams are allocated, one for the source \pixfile{tex} file and
25779 one for the \pixfile{aux} file.
25780 On the output side again at least two streams are allocated, one for
25781 the \pixfile{log} file and one for the \pixfile{aux} file.
25782 When \pixfile{toc} and other similar
25783 files are also part of the \ltx\ process you can see that many of the
25784 16 input and output streams may be allocated before you can get to use one
25785 yourself.
25786
25787 \begin{syntax}
25788 \cmd{\newoutputstream}\marg{stream} \\
25789 \cmd{\newinputstream}\marg{stream} \\
25790 \end{syntax}
25791 \glossary(newoutputstream)%
25792 {\cs{newoutputstream}\marg{stream}}%
25793 {Creates a new output stream called \meta{stream}.}
25794 \glossary(newinputstream)%
25795 {\cs{newinputstream}\marg{stream}}%
25796 {Creates a new input stream called \meta{stream}.}
25797 The macros \cmd{\newoutputstream} and \cmd{\newinputstream} respectively
25798 create a new output\index{stream!new output} and input\index{stream!new input}
25799 stream called \meta{stream}, where \meta{stream}
25800 should be a string of alphabetic characters, like \texttt{myout} or
25801 \texttt{myin}.
25802 The \meta{stream} names must be unique, you cannot use the same name
25803 for two streams even if one is a input stream and the other is an output
25804 stream. If all the 16 streams of the given type have already been allocated
25805 \tx\ will issue a message telling you about this, of the form:%
25806 \index{No room for a new write}\index{No room for a new read}
25807 \begin{lcode}
25808 No room for a new write % for an output stream
25809 No room for a new read % for an input stream
25810 \end{lcode}
25811
25812 The two \cs{new...stream} commands also provide two empty macros called
25813 \verb?\atstreamopen<stream>? and \verb?\atstreamclose<stream>?.
25814 If these macros already exist then they are left undisturbed.
25815 For example if you do:
25816 \begin{lcode}
25817 \newcommand{\atstreamopenmyout}{...}
25818 \newoutputstream{myout}
25819 \newinputstream{myin}
25820 \end{lcode}
25821 Then you will find that three new commands have been created like:
25822 \begin{lcode}
25823 \newcommand{\atstreamclosemyout}{}
25824 \newcommand{\atstreamopenmyin}{}
25825 \newcommand{\atstreamclosemyin}{}
25826 \end{lcode}
25827 You can use \cmd{\renewcommand} to change the definitions of these if you
25828 wish.
25829
25830 \begin{syntax}
25831 \cmd{\IfStreamOpen}\marg{stream}\marg{true-code}\marg{false-code} \\
25832 \end{syntax}
25833 \glossary(IfStreamOpen)%
25834 {\cs{IfStreamOpen}\marg{stream}\marg{yes}\marg{no}}%
25835 {If \meta{stream} is open then the \meta{yes} argument is processed
25836 otherwise the \meta{no} argument is processed.}
25837 The macro \cmd{\IfStreamOpen} checks whether or not the \meta{stream}
25838 stream\index{stream!check open} is open. If it is then
25839 the \meta{true-code} argument is processed,
25840 while when it is not open the \meta{false-code} argument is processed.
25841
25842 \subsection{Writing to a file}
25843
25844 \index{file!write|(}
25845
25846 One stream may be used for writing to several different files, although not
25847 simultaneously.
25848
25849 \begin{syntax}
25850 \cmd{\openoutputfile}\marg{filename}\marg{stream} \\
25851 \cmd{\closeoutputstream}\marg{stream} \\
25852 \end{syntax}
25853 \glossary(openoutputfile)%
25854 {\cs{openoutputfile}\marg{filename}\marg{stream}}%
25855 {Attaches the file \meta{filename} to the output \meta{stream}.}
25856 \glossary(closeoutputstream)%
25857 {\cs{closeoutputstream}\marg{stream}}%
25858 {Detaches and closes the file associated with the output \meta{stream}.}
25859 The command \cmd{\openoutputfile} opens\index{file!open} the file
25860 called \meta{filename},
25861 either creating it if it does not exist, or emptying it if it already exists.
25862 It then attaches the file to the output\index{stream!output}
25863 stream called \meta{stream} so that
25864 it can be written to, and then finally calls the macro
25865 named \verb?\atstreamopen<stream>?.
25866
25867 The command \cmd{\closeoutputstream} firstly calls the macro named
25868 \verb?\atstreamclose<stream>? then closes\index{stream!close output} the
25869 output stream \meta{stream}, and finally detaches and
25870 closes\index{file!close} the associated file.
25871
25872 \begin{syntax}
25873 \cmd{\addtostream}\marg{stream}\marg{text} \\
25874 \end{syntax}
25875 \glossary(addtostream)%
25876 {\cs{addtostream}\marg{stream}\marg{text}}%
25877 {Adds \meta{text} to the file associated with the output \meta{stream}.}
25878 The \cmd{\addtostream} command writes \meta{text} to the output stream
25879 \meta{stream}, and hence to whatever file is currently attached to the
25880 stream. The \meta{stream} must be open. Any commands within the \meta{text}
25881 argument will be processed before being written. To prevent command
25882 expansion, precede the command in question with \cmd{\protect}.
25883
25884 Writing\index{file!write!verbatim} verbatim text to a file is
25885 treated specially as it is likely
25886 to be the most common usage.
25887 \begin{syntax}
25888 \senv{verbatimoutput}\marg{file} anything \eenv{verbatimoutput} \\
25889 \senv{writeverbatim}\marg{stream} anything \eenv{writeverbatim} \\
25890 \end{syntax}
25891 \glossary(verbatimoutput)%
25892 {\senv{verbatimoutput}\marg{file}}%
25893 {The contents of the environment are written verbatim to the \meta{file}
25894 file, overwriting anything previously in the file.}
25895 \glossary(writeverbatim)%
25896 {\senv{writeverbatim}\marg{stream}}%
25897 {The contents of the environment are written verbatim to the \meta{stream}
25898 stream.}
25899 The text within a \Ie{verbatimoutput} environment is written verbatim
25900 to the \meta{file} file. Alternatively, the contents of the
25901 \Ie{writeverbatim} environment are written verbatim to the \meta{stream}
25902 stream.
25903
25904 Specifically, \Ie{verbatimoutput} opens the specified file, writes
25905 to it, and then closes the file. This means that if \Ie{verbatimoutput}
25906 is used more than once to write to a given
25907 file, then only the contents of the last of these outputs is captured
25908 in the file.
25909 On the other hand, you can use \Ie{writeverbatim} several times to write
25910 to the file attached to the stream and, providing the stream has not
25911 been closed in the meantime, all will be captured.
25912
25913 \index{file!write|)}
25914
25915 \subsection{Reading from a file}
25916
25917 \index{file!read|(}
25918
25919 One stream may be used for reading from several files, although not
25920 simultaneously.
25921
25922 \begin{syntax}
25923 \cmd{\openinputfile}\marg{filename}\marg{stream} \\
25924 \cmd{\closeinputstream}\marg{stream} \\
25925 \end{syntax}
25926 \glossary(openinputfile)%
25927 {\cs{openinputfile}\marg{filename}\marg{stream}}%
25928 {Attaches the file \meta{filename} to the input \meta{stream}.}
25929 \glossary(closeinputstream)%
25930 {\cs{closeinputstream}\marg{stream}}%
25931 {Detaches and closes the file associated with the input \meta{stream}.}
25932 The command \cmd{\openinputfile} opens\index{file!open} the file
25933 called \meta{filename}
25934 and attaches it to the input\index{stream!input} stream called
25935 \meta{stream} so that
25936 it can be read from. Finally it calls the macro named
25937 \verb?\atstreamopen<stream>?.
25938 It is an error if \meta{filename} can not be found.
25939
25940 The command \cmd{\closeinputstream} calls the macro named
25941 \verb?\atstreamclose<stream>?, closes\index{stream!close input} the
25942 output stream \meta{stream}, and then detaches and closes\index{file!close}
25943 the associated file.
25944
25945 \begin{syntax}
25946 \cmd{\readstream}\marg{stream} \\
25947 \end{syntax}
25948 \glossary(readstream)%
25949 {\cs{readstream}\marg{stream}}%
25950 {Reads the entire contents of the file associated with the input \meta{stream}.}
25951 The command \cmd{\readstream} reads the entire contents of the file
25952 currently associated with the input stream \meta{stream}. This
25953 provides the same functionality as \cmd{\input}\marg{filename}.
25954
25955 \begin{syntax}
25956 \cmd{\readaline}\marg{stream} \\
25957 \end{syntax}
25958 \glossary(readaline)%
25959 {\cs{readaline}\marg{stream}}%
25960 {Reads a single line from the file associated with the input \meta{stream}.}
25961 The \cmd{\readaline} reads\index{file!read!single line} what \tx\
25962 considers to be one line from
25963 the file that is currently associated with the input stream \meta{stream}.
25964
25965 Multiple lines can be read by calling \cmd{\readaline} multiple times.
25966 A warning is issued if there are no more lines to be read (i.e., the
25967 end of the file has been reached).
25968
25969 Just as for writing, reading files\index{file!read!verbatim}
25970 verbatim is treated specially.
25971 \begin{syntax}
25972 \cmd{\verbatiminput}\marg{file} \cmd{\verbatiminput*}\marg{file} \\
25973 \cmd{\boxedverbatiminput}\marg{file} \cmd{\boxedverbatiminput*}\marg{file} \\
25974 \cmd{\readverbatim}\marg{stream} \cmd{\readverbatim*}\marg{stream} \\
25975 \cmd{\readboxedverbatim}\marg{stream} \cmd{\readboxedverbatim*}\marg{stream} \\
25976 \end{syntax}
25977 \glossary(verbatiminput)%
25978 {\cs{verbatiminput}\marg{file}}%
25979 {Acts like \Pe{verbatim} except the contents is read from the \meta{file} file.}
25980 \glossary(verbatiminput*)%
25981 {\cs{verbatiminput*}\marg{file}}%
25982 {Acts like \Pe{verbatim*} except the contents is read from the \meta{file} file.}
25983 \glossary(boxedverbatiminput)%
25984 {\cs{boxedverbatiminput}\marg{file}}%
25985 {Acts like \Pe{boxedverbatim} except the contents is read from the \meta{file} file.}
25986 \glossary(boxedverbatiminput*)%
25987 {\cs{boxedverbatiminput*}\marg{file}}%
25988 {Acts like \Pe{boxedverbatim*} except the contents is read from the \meta{file} file.}
25989 \glossary(readverbatim)%
25990 {\cs{readverbatim}\marg{stream}}%
25991 {Acts like \Pe{verbatim} except the contents is read from the file
25992 associated with the input \meta{stream}.}
25993 \glossary(readverbatim*)%
25994 {\cs{readverbatim*}\marg{stream}}%
25995 {Acts like \Pe{verbatim*} except the contents is read from the file
25996 associated with the input \meta{stream}.}
25997 \glossary(readboxedverbatim)%
25998 {\cs{readboxedverbatim}\marg{stream}}%
25999 {Acts like \Pe{boxedverbatim} except the contents is read from the file
26000 associated with the input \meta{stream}.}
26001 \glossary(readboxedverbatim*)%
26002 {\cs{readboxedverbatim*}\marg{stream}}%
26003 {Acts like \Pe{boxedverbatim*} except the contents is read from the file
26004 associated with the input \meta{stream}.}
26005 The commands \cmd{\verbatiminput} and
26006 \cmd{\boxedverbatiminput},\index{frame!verbatim}\index{verbatim!frame}
26007 and their
26008 starred versions, act like the \Ie{verbatim} and \Ie{boxedverbatim}
26009 environments, except that they get their text from the \meta{file} file.
26010 It is an error if \meta{file} cannot be found.
26011 Similarly, \cmd{\readverbatim} and \cmd{\readboxedverbatim} get their
26012 text from the file currently attached to the \meta{stream} input stream.
26013 It is an error if \meta{stream} is not open for input.
26014
26015 \index{file!read|)}
26016
26017 \subsection{Example: endnotes}
26018
26019 \LMnote{2010/10/28}{It is confusing for users that the manual contain
26020 an example as to how one manual provide endnotes, when memoir
26021 actually provide the functionality in a later section.}
26022 \index{endnotes}
26023 \begin{itshape}
26024 In an earier version of the manual, this section contained an
26025 example as to how one could make endnotes. The example is now
26026 irrelevant, since \theclass\ contain something similar to end notes
26027 called page notes, see \Sref{sec:endnotes} on
26028 page~\pageref{sec:endnotes}.
26029
26030 Those interested in the code from the old example, can find it in
26031 the manual source (it has just been commented out).
26032 \end{itshape}
26033
26034 % \begin{comment}
26035 % \index{endnotes|(}
26036
26037 % Books like biographies often quote sources for quotations by the subject,
26038 % or sources for statements of fact and so on, at the end of the book or chapter.
26039 % These are often like a collected set of footnotes. The example shows
26040 % a somewhat rough and ready approach to implementing endnotes.
26041
26042 % Typically endnotes come in one of two forms: they are like a normal
26043 % footnote, except that the note text is on another page, or; there is
26044 % no mark in the body of the text and the note is identified via a small
26045 % quote from the text and its page number.
26046 % The example is for the footnote-like form and for endnotes collected
26047 % at the end of the document, with an appropriate heading to distinguish
26048 % notes from different chapters.
26049
26050 % We have to be careful in choosing names for the macros we will be
26051 % defining for endnotes. Remember, you cannot use \cmd{\newcommand}
26052 % to define a new command whose name starts \cs{end...}, so \cs{endnote}
26053 % appears to be out.
26054 % However, the \tx\ primitive \cmd{\def} command does let you define
26055 % a command starting with \cs{end...}. The syntax of the \cmd{\def} command,
26056 % like
26057 % that of many of \tx\ macros, looks strange to \ltx\ eyes. The major
26058 % disadvantage in using \cmd{\def} is that it will merrily overwrite any
26059 % previous definition with the same name (the \ltx\ \cmd{\newcommand} won't
26060 % let you do that). I could use \cmd{\def} for an \cs{endnote} macro, like
26061 % \begin{lcode}
26062 % \long\def\endnote#1{...}
26063 % \end{lcode}
26064 % I won't do that, though, as there is at least one \ltx\ class that includes
26065 % a \texttt{note} environment and that means that \cs{endnote} is already defined
26066 % in that class. To avoid potential pitfalls like that I'll use \cs{enote}
26067 % rather than the more evocative \cs{endnote}.
26068
26069 % We need a new counter for the endnotes, starting afresh with each chapter,
26070 % and to print in arabic numerals.
26071 % \begin{lcode}
26072 % \newcounter{enote}[chapter]
26073 % \renewcommand{\theenote}{\arabic{enote}}
26074 % \end{lcode}
26075 % And we need a macro to typeset the text of the note. This will take two
26076 % arguments, the number of the note, and the text.
26077 % \begin{lcode}
26078 % \DeclareRobustCommand{\enotetext}[2]{%
26079 % \par\noindent \textsuperscript{#1} #2\par
26080 % \vspace{\baselineskip}}
26081 % \end{lcode}
26082 % This makes sure that it starts a new non-indented paragraph, then typesets
26083 % the first argument (the number) as a superscript and then processes the
26084 % second argument (the text of the note). After that it makes sure that
26085 % any paragraph is ended and puts some vertical space in case there is
26086 % another note following.
26087
26088 % The basic idea is to define a command, \cs{enote}\marg{text}, like
26089 % \cmd{\footnote}, that will write \meta{text} to a file\index{file!write}
26090 % which will be read in later to typeset the \meta{text}.
26091
26092 % To this end, we need an output stream, and we will use a file with
26093 % extension \pixfile{ent}, the first
26094 % part of the file name being the name of the \ltx\ source file; this is
26095 % available via the \cmd{\jobname} macro.
26096 % \begin{lcode}
26097 % \newoutputstream{notesout}
26098 % \openoutputfile{\jobname.ent}{notesout}
26099 % \newcommand{\printendnotes}{%
26100 % \closeoutputstream{notesout}%
26101 % \input{\jobname.ent}}
26102 % \end{lcode}
26103 % The \cmd{\printendnotes} macro can be called at the appropriate place in the
26104 % document to print any endnotes. It closes the output file and
26105 % then inputs it\index{file!read} to print the endnotes.
26106
26107 % As well as putting the notes into the file we are also going to
26108 % add a heading indicating the chapter. Rather than invent a completely
26109 % new kind of heading I'll simply use \cmd{\subsection*} --- the starred
26110 % form so that there will be no \prtoc{} entry.
26111 % \begin{lcode}
26112 % \DeclareRobustCommand{\enotehead}[1]{%
26113 % \subsection*{Notes for chapter #1}}
26114 % \end{lcode}
26115 % The argument to the \cs{enotehead} macro is the number of a chapter. Also
26116 % needed is a method for determining when this heading should be added to
26117 % the endnote file. One simple way is using a counter holding the chapter
26118 % number. Initialise the counter to something that is an invalid
26119 % chapter number.
26120 % \begin{lcode}
26121 % \newcounter{savechap}
26122 % \setcounter{savechap}{-1000}
26123 % \end{lcode}
26124
26125 % We have the pieces ready, and all that remains is to define
26126 % the \cs{enote} macro, which will take one argument --- the text of the
26127 % note.
26128 % \begin{lcode}
26129 % \newcommand{\enote}[1]{%
26130 % \refstepcounter{enote}% increment the counter
26131 % \textsuperscript{\theenote}% typeset it as a superscript
26132 % \ifnum\value{savechap}=\value{chapter}\else % in a new chapter
26133 % \setcounter{savechap}{\value{chapter}% save the number
26134 % \addtostream{notesout}{\enotehead{\thechapter}}% the heading
26135 % \fi
26136 % \addtostream{notesout}{\enotetext{\theenote}{#1}}}
26137 % \end{lcode}
26138 % \cs{enote}, which is used just like \cmd{\footnote}, increments the
26139 % counter for endnotes, typesets that as a superscript, and then writes
26140 % the \cs{enotetext} command to the endnotes file. Entries in the \pixfile{ent}
26141 % file will look like:
26142 % \begin{lcode}
26143 % ...
26144 % \enotehead{3} % for chapter 3
26145 % \enotetext{1}{First end note in chapter 3.}
26146 % \enotetext{2}{The next end note.}
26147 % ...
26148 % \end{lcode}
26149
26150 % You can try this, perhaps changing the definition of \cs{enotetext}
26151 % to give a better looking presentation of an endnote. There is, however,
26152 % a caveat if you use \cs{enote}.
26153
26154 % \vspace{\onelineskip}
26155 % \noindent\textbf{Question 3.} What is the caveat?
26156
26157 % If you can't
26158 % think what it might be, don't worry as it will be dealt with in another
26159 % example.
26160
26161 % \index{endnotes|)}
26162 % \end{comment}
26163
26164 \subsection{Example: end floats}
26165
26166 \index{end floats|(}
26167
26168 There are some documents where all figures are required to be grouped
26169 in one place, for instance at the end of the document or perhaps at the
26170 end of each chapter. Grouping at the end of a document with
26171 chapters is harder, so we'll tackle that one.
26172
26173 The basic idea is to write out verbatim\index{verbatim!write}
26174 each figure environment and then read them all back in at the end.
26175 We will use a stream,\index{stream} let's call
26176 it \texttt{tryout}, and call our file for figures \file{tryout.fig}.
26177 \begin{lcode}
26178 \newoutputstream{tryout}
26179 \openoutputfile{tryout.fig}{tryout}
26180 \end{lcode}
26181
26182 If all were simple, in the document we could then just do
26183 \begin{lcode}
26184 \begin{writeverbatim}{tryout}
26185 \begin{figure} ... \end{figure}
26186 \end{writeverbatim}
26187 ...
26188 \closeoutputstream{tryout}
26189 \input{tryout.fig}
26190 \end{lcode}
26191
26192 So, what's the problem?
26193
26194 By default figure captions are numbered per chapter, and are preceeded
26195 by the chapter number; more precisely, the definition of a figure number
26196 is
26197 \begin{lcode}
26198 \thechapter.\arabic{figure}
26199 \end{lcode}
26200 If we simply lump all the figures at
26201 the end, then they
26202 will all be numbered as if they were in the final chapter.
26203 For the sake of argument assume that the last chapter is number 10.
26204 The nth figure will then be numbered 10.n.
26205 One thing that we
26206 can do rather simply is to change the definition of the figure by using
26207 another counter, let's call it \texttt{pseudo}, instead of the chapter.
26208 \begin{lcode}
26209 \newcounter{pseudo}
26210 \renewcommand{\thepseudo}{\arabic{pseudo}}
26211 \renewcommand{\thefigure}{\thepseudo.\arabic{figure}}
26212 \end{lcode}
26213 Now, all we should have to do is arrange that the proper value of
26214 \texttt{pseudo}
26215 is available before each figure is typeset at the end. The code around
26216 the \Ie{figure} environments might then look like this
26217 \begin{lcode}
26218 \addtostream{tryout}{\protect\setcounter{pseudo}{\thechapter}}
26219 \begin{writeverbatim}{tryout}
26220 \begin{figure}...
26221 \end{lcode}
26222 and a part of the file might then look like
26223 \begin{lcode}
26224 ...
26225 \setcounter{pseudo}{4}
26226 \begin{figure}...
26227 \end{lcode}
26228 The \cmd{\protect} before the \cmd{\setcounter} command will stop it
26229 from expanding before it is written to the file, while the \cmd{\thechapter}
26230 command \emph{will} be expanded to give the actual number of the current
26231 chapter. This looks better as now at least the figure will be numbered 4.n
26232 instead of 10.n.
26233
26234 There is one last snag --- figure numbers are reset at the start of each
26235 chapter --- but if we just dump the figures at the end of the document
26236 then although the chapter part of the number will alter appropriately
26237 because of the \texttt{pseudo} process,
26238 the second part of the number will just increase continuously. It looks
26239 as though we should write out a change to the chapter counter at the start
26240 of each chapter. If we do that, then we should be able to get rid of the
26241 \texttt{pseudo} counter, which sounds good. But, and this is almost the
26242 last but,
26243 what if there are chapters after we have read in the figure file? To
26244 cater for this the chapter number of the last chapter before the file must
26245 be saved, and then restored after the figures have been processed.
26246
26247 Finally, wouldn't it be much better for the user if everything was
26248 wrapped up in an environment that handled all the messy stuff?
26249
26250 Here is the final code that I am going to produce which, by the way,
26251 is displayed in the \Ie{boxedverbatim} environment\index{line number}
26252 with line numbers and the following settings, just in case there is
26253 a page break in the middle of the box.
26254 \begin{lcode}
26255 \nobvbox
26256 \bvperpagetrue
26257 \bvtopofpage{\begin{center}\normalfont%
26258 (Continued from previous page)\end{center}}
26259 \bvendofpage{}
26260 \resetbvlinenumber
26261 \linenumberfrequency{1}
26262 \bvnumbersoutside
26263 \linenumberfont{\footnotesize\rmfamily}
26264 \begin{boxedverbatim}
26265 ...
26266 \end{lcode}
26267
26268 \nobvbox
26269 \bvperpagetrue
26270 \bvtopofpage{\begin{center}\normalfont%
26271 (Continued from previous page)\end{center}}
26272 \bvendofpage{}
26273 \resetbvlinenumber
26274 \linenumberfrequency{1}
26275 \bvnumbersoutside
26276 \linenumberfont{\footnotesize\rmfamily}
26277 \begin{boxedverbatim}
26278 \newoutputstream{tryout}
26279 \openoutputfile{\jobname.fig}{tryout}
26280 \newcounter{pseudo}
26281 \renewcommand{\thefigure}{\thepseudo.\arabic{figure}}
26282 \newenvironment{writefigure}{%
26283 \ifnum\value{chapter}=\value{pseudo}\else
26284 \setcounter{pseudo}{\value{chapter}}
26285 \addtostream{tryout}{\protect\stepcounter{chapter}}
26286 \addtostream{tryout}{\protect\addtocounter{chapter}{-1}}
26287 \addtostream{tryout}{%
26288 \protect\setcounter{pseudo}{\thechapter}}
26289 \fi
26290 \addtostream{tryout}{\protect\begin{figure}}
26291 \writeverbatim{tryout}}%
26292 {\endwriteverbatim\finishwritefigure}
26293 \newcommand{\finishwritefigure}{%
26294 \addtostream{tryout}{\protect\end{figure}}}
26295 \newcommand{\printfigures}{%
26296 \closeoutputstream{tryout}%
26297 \input{\jobname.fig}%
26298 }
26299 \end{boxedverbatim}
26300 \linenumberfrequency{0}
26301 The above code should be either put in the preamble\index{preamble}
26302 or in a separate package\index{package} file.
26303
26304 The first four lines of the code perform the initial setup described
26305 earlier. Lines 1 and 2 set up for outputting\index{file!write} to a file
26306 \verb?\jobname.fig?, which
26307 is where the figures will be collected. Lines 3 and 4 create the
26308 new counter\index{new!counter}
26309 we need and change the construction of the figure number. The rest of the code
26310 defines a new environment\index{new!environment} \Ie{writefigure}
26311 which is to be used instead
26312 of the \Ie{figure} environment. It writes its content out to the
26313 \texttt{tryout} stream.
26314
26315 In line 6 a check is made to see if the current values of the
26316 \Icn{chapter} and \Icn{pseudo} counters are the same;
26317 nothing is done if they are. If they are
26318 different, it means that this is the first figure in the chapter and we have
26319 to put appropriate information into the figure file. Line 7 sets the
26320 \Icn{pseudo} counter to the value of the \Icn{chapter} counter
26321 (if there is another \Ie{writefigure} in the chapter it will then
26322 skip over the code in lines 7 to 11).
26323 The next lines put (where N is the number of the current chapter):
26324 \begin{lcode}
26325 \stepcounter{chapter}
26326 \addtocounter{chapter}{-1}
26327 \setcounter{pseudo}{N}
26328 \end{lcode}
26329 into the figure file. Stepping the chapter number (by one) resets the
26330 following figure number, and then subtracting one from the stepped number
26331 returns the chapter number to its original value.
26332 Finally the counter \Icn{pseudo} is set to the number of the
26333 current chapter.
26334
26335 Line 13 puts
26336 \begin{lcode}
26337 \begin{figure}
26338 \end{lcode}
26339 into the figure file, and line 14 starts the
26340 \Ie{writeverbatim}\index{verbatim!write} environment.
26341
26342 For the end of the \Ie{writefigure} environment (line 15), the
26343 \Ie{writeverbatim} environment is ended and after that the
26344 \cmd{\finishwritefigure} macro
26345 is called. This is defined in lines 16 and 17, and simply writes
26346 \begin{lcode}
26347 \end{figure}
26348 \end{lcode}
26349 out to the figure file. The \cmd{\endwriteverbatim}, and any other kind of
26350 \cs{end...verbatim}, command is very sensitive to anything that follows it,
26351 and in this case did not like to be immediately followed by an
26352 \verb?\addtostream{...}?, but did not mind it being wrapped up in
26353 the \cmd{\finishwritefigure} macro.
26354
26355 The \cmd{\printfigures} macro defined in the last three lines of the code
26356 simply closes the output stream\index{stream!output} and then inputs the
26357 figures\index{file!read} file.
26358
26359 As an example of how this works, if we have the following source code:
26360 \begin{lcode}
26361 \chapter{The fifth chapter}
26362 ...
26363 \begin{writefigure}
26364 %% illustration and caption
26365 \end{writefigure}
26366 ...
26367 \begin{writefigure}
26368 %% another illustration and caption
26369 \end{writefigure}
26370 \end{lcode}
26371 then the figure file will contain the following (shown verbatim in the
26372 \Ie{fboxverbatim}\index{framed!verbatim} environment).
26373
26374 \begin{fboxverbatim}
26375 \stepcounter{chapter}
26376 \addtocounter{chapter}{-1}
26377 \setcounter{pseudo}{5}
26378 \begin{figure}
26379 %% illustration and caption
26380 \end{figure}
26381 \begin{figure}
26382 %% another illustration and caption
26383 \end{figure}
26384 \end{fboxverbatim}
26385
26386 \index{end floats|)}
26387
26388
26389 \subsection{Example: questions and answers}
26390
26391 \index{questions and answers|(}
26392
26393 Text books often have questions at the end of a chapter. Sometimes answers
26394 are also provided at the end of the book, or in a separate teachers guide.
26395 During the draft stages of such a book it is useful to keep the
26396 questions and answers together in the source and paper drafts, only removing
26397 or repositioning the answers towards the end of the writing process.
26398
26399 This example provides an outline for meeting these desires. For
26400 pedagogical purposes I use a \cmd{\label} and \cmd{\ref} technique although
26401 there are better methods. The example also shows that not
26402 everything works as expected --- it is a reasonably accurate rendition
26403 of the process that I actually went through in designing it.
26404
26405 First we need a counter for the questions and we'll use an
26406 environment\index{environment!new}
26407 for questions as these may be of any complexity. The environment takes one
26408 argument --- a unique key to be used in a \cmd{\label}.
26409 \begin{lcode}
26410 \newcounter{question} \setcounter{question}{0}
26411 \renewcommand{\thequestion}{\arabic{question}}
26412 \newenvironment{question}[1]%
26413 {\refstepcounter{question}
26414 \par\noindent\textbf{Question \thequestion:}\label{#1}}%
26415 {\par}
26416 \end{lcode}
26417 I have used \cmd{\refstepcounter} to increment\index{counter!increment}
26418 the counter so that
26419 the \cmd{\label} will refer to it, and not some external counter.
26420
26421 We will use a file, called \verb?\jobname.ans? to collect the answers
26422 and this will be written\index{file!write} to by a stream.\index{stream}
26423 There is also a convenience
26424 macro, \cmd{\printanswers}, for the user to call to print the answers.
26425 \begin{lcode}
26426 \newoutputstream{ansout}
26427 \end{lcode}
26428
26429
26430 A matching environment\index{environment!new} for answers is required.
26431 The argument to the environment is the key of the question.
26432
26433 In \Lopt{draft} mode it is simple, just typeset the answer and no need to
26434 bother with any file printing (remember that \piif{ifdraftdoc} is \ptrue\ for a
26435 \Lopt{draft} mode document).
26436 \begin{lcode}
26437 \ifdraftdoc % when in draft mode
26438 \newenvironment{answer}[1]%
26439 {\par\noindent\textbf{Answer \ref{#1}:}}%
26440 {\par}
26441 \newcommand{\printanswers}{}
26442 \else % when not in draft mode
26443 \end{lcode}
26444
26445 In \Lopt{final} mode the \Ie{answer} environment must write its contents
26446 verbatim to the \pixfile{ans} file for printing by \cmd{\printanswers}.
26447 Dealing with these in reverse order, this is the definition of
26448 \cmd{\printanswer} when not in \Lopt{draft} mode.
26449 \begin{lcode}
26450 \newcommand{\printanswers}{%
26451 \closeoutputstream{ansout}
26452 \input{\jobname.ans}}
26453 \end{lcode}
26454
26455 Now for the tricky bit, the \Ie{answer} environment. First define an
26456 environment\index{environment!new} that makes sure our
26457 output\index{stream!output} stream is open, and which then
26458 writes the answer title to the stream.
26459 \begin{lcode}
26460 \newenvironment{@nswer}[1]{\@bsphack
26461 \IfStreamOpen{ansout}{}{%
26462 \openoutputfile{\jobname.ans}{ansout}%
26463 }%
26464 \addtostream{ansout}{\par\noindent\textbf{Answer \ref{#1}:}}%
26465 }{\@esphack}
26466 \end{lcode}
26467 The macros \cmd{\@bsphack} and \cmd{\@esphack} are \ltx\ kernel macros
26468 that will gobble\index{space!gobble} extraneous spaces around the
26469 environment. In other words,
26470 this environment will take no space in the typeset result. The
26471 \cmd{\IfStreamOpen} macro is used to test whether or not the stream is open,
26472 and if it isn't then it opens it. The answer title is then written
26473 out to the stream. Now we can define the \Ie{answer} environment so that
26474 its contents get written out\index{write!verbatim} verbatim.
26475 \begin{lcode}
26476 \newenvironment{answer}[1]%
26477 {\@bsphack\@nswer{#1}\writeverbatim{ansout}}%
26478 {\par\endwriteverbatim\end@nswer\@esphack}
26479 \fi % end of \ifdraftdoc ...\else ...
26480 \end{lcode}
26481
26482 When I was testing this code I had a surprise as I got nasty error messages
26483 from \ltx\ the first time around, but it worked fine when I processed the
26484 source a second time! The problem lies in the code line
26485 \begin{lcode}
26486 \addtostream{ansout}{\par\noindent\textbf{Answer \ref{#1}:}}%
26487 \end{lcode}
26488
26489 The first time around, \ltx\ processed the \cmd{\ref} command and of
26490 course it was undefined. In this case \cmd{\ref} gets replaced by the
26491 code to print the error message, which involves macros that have \texttt{@}
26492 in their names, which \ltx\ only understands under special circumstances.
26493 The second time around \cmd{\ref} gets replaced by the question number
26494 and all is well. I then remembered that some commands need
26495 protecting\index{protect}
26496 when they are written out, so I tried (I've wrapped the line to fit)
26497 \begin{lcode}
26498 \addtostream{ansout}{\par\noindent
26499 \protect\makeatletter\textbf{Answer
26500 \protect\ref{#1}:}\protect\makeatother}%
26501 \end{lcode}
26502 which did work but seemed very clumsy.
26503
26504 I then took another line of attack, and looked at the definition
26505 of \cmd{\ref} to see if I could come up with something that didn't
26506 expand into \texttt{@} names. The result of this was
26507 \begin{lcode}
26508 \addtostream{ansout}{\par\noindent\textbf{Answer
26509 \quietref{#1}:}}%
26510 \end{lcode}
26511 In the kernel file \file{ltxref.dtx} I found the definition of \cmd{\ref}
26512 and it used a macro \cmd{\@setref} (shown below) to do its work.
26513 My \cmd{\quietref} locally changes the definition of \cmd{\@setref}
26514 and then calls \cmd{\ref}, which will then use the modified \cmd{\@setref}.
26515 \begin{lcode}
26516 \def\@setref#1#2#3{% %% kernel definition
26517 \ifx#1\relax
26518 \protect\G@refundefinedtrue
26519 \nfss@text{\reset@font\bfseries ??}%
26520 \@latex@warning{Reference `#3' on page \thepage \space
26521 undefined}%
26522 \else
26523 \expandafter#2#1\null
26524 \fi}
26525
26526 \DeclareRobustCommand{\quietref}[1]{\begingroup
26527 \def\@setref##1##2##3{%
26528 \ifx##1\relax ??\else
26529 \expandafter##2##1\null
26530 \fi
26531 \ref{#1}\endgroup}
26532 \end{lcode}
26533
26534 Having gone all round the houses, the simplest solution was actually
26535 one that I had skipped over
26536 \begin{lcode}
26537 \addtostream{ansout}{\par\noindent\textbf{Answer
26538 \protect\ref{#1}:}}%
26539 \end{lcode}
26540
26541 The advantage of using the \cmd{\label} and \cmd{\ref} mechanism is that
26542 a question and its answer need not be adjacent in the source; I think that
26543 you have seen some of the disadvantages. Another disadvantage is that it
26544 is difficult to use, although not impossible, if you want the answers in
26545 a separate document.
26546
26547 The real answer to all the problems is force an answer to come immediately
26548 after the question in the source and to use the \Icn{question} counter
26549 directly, as in the endnotes\index{endnotes} example. In the traditional manner,
26550 this is left as an exercise for the
26551 reader.
26552
26553 \index{questions and answers|)}
26554
26555 \index{stream|)}
26556
26557 \index{file|)}
26558
26559 \section{Answers}
26560
26561 \noindent\textbf{Question 1.} As a convenience, the
26562 argument\index{argument!optional} to the
26563 environment could be made optional, defaulting, say, to the current
26564 line width. If the default width is used the frame will be wider
26565 than the line width, so we really ought to make the width argument
26566 specify the width of the frame instead of the minipage. This
26567 means calculating a reduced width for the minipage based on
26568 the values of \lnc{\fboxsep} and \lnc{\fboxrule}.
26569 \begin{lcode}
26570 \newsavebox{\minibox}
26571 \newlength{\minilength}
26572 \newenvironment{framedminipage}[1][\linewidth]{%
26573 \setlength{\minilength}{#1}
26574 \addtolength{\minilength}{-2\fboxsep}
26575 \addtolength{\minilength}{-2\fboxrule}
26576 \begin{lrbox}{\minibox}\begin{minipage}{\minilength}}%
26577 {\end{minipage}\end{lrbox}\fbox{\usebox{\minibox}}}
26578 \end{lcode}
26579
26580
26581 \vspace{\onelineskip}
26582 \noindent\textbf{Question 2.} There are at least three reasonable answers.
26583 In increasing or decreasing order of probability (your choice) they are:
26584 \begin{itemize}
26585 \item I took Sherlock Holmes' advice and followed the methods outlined
26586 in the chapter;
26587 \item I used a package, such as the \Lpack{answer} package which is designed
26588 for the purpose;
26589 \item I just wrote the answers here.
26590 \end{itemize}
26591
26592 \LMnote{2010/10/28}{Removed this answer as we have removed the question}
26593 % \vspace{\onelineskip}
26594 % \noindent\textbf{Question 3.} If \ltx\ writes text out to an external
26595 % file which will be read by \ltx\ at some time, any
26596 % fragile\index{fragile} commands
26597 % in the text must be \cmd{\protect}ed.\index{protect}
26598
26599 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
26600 %%%%%%%%% mbook
26601
26602 %#% extend
26603 %#% extstart include cross-referencing.tex
26604
26605 \svnidlong
26606 {$Ignore: $}
26607 {$LastChangedDate: 2025-08-08 14:39:37 +0200 (Fri, 08 Aug 2025) $}
26608 {$LastChangedRevision: 859 $}
26609 {$LastChangedBy: [email protected] $}
26610
26611 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
26612 \chapter{Cross referencing} \label{chap:xref}
26613 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
26614
26615 %\section{Introduction}
26616
26617 A significant aspect of \ltx\ is that it provides a variety of
26618 cross referencing\index{cross reference} methods, many of
26619 which are automatic. An example
26620 of an automatic\index{cross reference!automatic} cross reference is the way in which a \cmd{\chapter}
26621 command automatically adds its title and page number to the \toc,
26622 or where a \cmd{\caption} adds itself to a \listofx.
26623
26624 Some cross references have to be
26625 specifically\index{cross reference!specified} specified, such as
26626 a reference in the text to a particular chapter number, and for
26627 these \ltx\ provides a general mechanism that does not require you
26628 to remember the particular number and more usefully does not require
26629 you to remember to change the reference if the chapter number is later
26630 changed.
26631
26632 \section{Labels and references} \label{sec:lab&ref}
26633
26634 \index{reference!by number|(}
26635
26636 The general \ltx\ cross reference method uses a pair of macros.
26637 \begin{syntax}
26638 \cmd{\label}\marg{labstr} \\
26639 \cmd{\ref}\marg{labstr} \cmd{\pageref}\marg{labstr} \\
26640 \end{syntax}
26641 \glossary(label)%
26642 {\cs{label}\marg{labstr}}%
26643 {Associates the current (section, caption, \ldots) number, and page number,
26644 to \meta{labstr}.}
26645 \glossary(ref)%
26646 {\cs{ref}\marg{labstr}}%
26647 {Prints the (section, or other) number associated with \meta{labstr}
26648 from a \cs{label}.}
26649 \glossary(pageref)%
26650 {\cs{pageref}\marg{labstr}}%
26651 {Prints the page number associated with \meta{labstr}
26652 from a \cs{label}.}
26653 You can put a \cmd{\label} command where you want to label\index{label}
26654 some numbered
26655 element in case you might want to refer to the number from elsewhere in
26656 the document. The \meta{labstr} argument is a sequence of letters, digits,
26657 and punctuation symbols; upper and lower case letters are different.
26658 The \cmd{\ref} macro prints the number\index{reference!to label}
26659 associated with \meta{labstr}.
26660 The \cmd{\pageref} macro prints the number of the
26661 page\index{reference!to page} where the
26662 \cmd{\label} specifying the \meta{labstr} was placed.
26663
26664 The \cmd{\label} and \cmd{\ref} mechanism is simple to use and
26665 works well but
26666 on occasions you might be surprised\index{reference!unexpected result}
26667 at what \cmd{\ref} prints.
26668
26669 \ltx\ maintains a current \textit{ref}
26670 value\index{reference!current value} which is
26671 set\index{reference!set current value} by
26672 the \cmd{\refstepcounter} command. This command is used by the sectioning
26673 commands, by \cmd{\caption}, by numbered environments like
26674 \Ie{equation}, by \cmd{\item} in an \Ie{enumerate} environment, and
26675 so on. The \cmd{\label} command\index{label} writes an entry in the
26676 \pixfile{aux} file consisting of the \meta{labstr}, the current
26677 \textit{ref} value\index{reference!current value} and the curent
26678 page\index{page!current number} number.
26679 A \cmd{\ref} command picks up the \textit{ref}
26680 value for \meta{labstr} and prints it. Similarly \cmd{\pageref} prints
26681 the page number for \meta{labstr}.
26682
26683 The critical point is that the \cmd{\label} command picks up the
26684 value set by the \emph{most recent} visible\footnote{Remember, a
26685 change within a group, such as an environment, is not visible
26686 outside the group.} \cmd{\refstepcounter}.
26687 \begin{itemize}
26688 \item A \cmd{\label} after a \cmd{\section} picks up the \cmd{\section}
26689 number, not the \cmd{\chapter} number.
26690 \item A \cmd{\label} after a \cmd{\caption} picks up the caption number.
26691 \item A \cmd{\label} \emph{before} a \cmd{\caption} picks up the surrounding
26692 sectional number.
26693 \end{itemize}
26694 If you are defining your own macro that sets a counter, the counter value
26695 will be invisible to any \cmd{\label} unless it is
26696 set\index{reference!set current value} using \cmd{\refstepcounter}.
26697
26698 % ***
26699
26700
26701 \begin{syntax}
26702 \cmd{\fref}\marg{labstr} \cmd{\figurerefname} \\
26703 \cmd{\tref}\marg{labstr} \cmd{\tablerefname} \\
26704 \cmd{\pref}\marg{labstr} \cmd{\pagerefname} \\
26705 \end{syntax}
26706 \glossary(fref)%
26707 {\cs{fref}\marg{labstr}}%
26708 {Prints a named (\cs{figurerefname}) reference to a \cs{label}ed figure. Deprecated, to be removed in 2026.}
26709 \glossary(figurerefname)%
26710 {\cs{figurerefname}}%
26711 {Name for a figure used by \cs{fref}.}
26712 \glossary(tref)%
26713 {\cs{tref}\marg{labstr}}%
26714 {Prints a named (\cs{tablerefname}) reference to a \cs{label}ed table. Deprecated, to be removed in 2026.}
26715 \glossary(tablerefname)%
26716 {\cs{tablerefname}}%
26717 {Name for a table used by \cs{tref}.}
26718 \glossary(pref)%
26719 {\cs{pref}\marg{labstr}}%
26720 {Prints a named (\cs{pagerefname}) reference to a \cs{label} page reference. Deprecated, to be removed in 2026.}
26721 \glossary(pagerefname)%
26722 {\cs{pagerefname}}%
26723 {Name for a page used by \cs{pref}.}
26724 The class provides these more particular named\index{reference!to figure}
26725 references to a figure\index{figure!reference},
26726 table\index{table!reference}\index{reference!to table} or
26727 page\index{page!reference}\index{reference!to page}. For example the
26728 default definitions of \cmd{\fref} and
26729 \cmd{\pref} are
26730 \begin{lcode}
26731 \newcommand{\fref}[1]{\figurerefname~\ref{#1}}
26732 \newcommand{\pref}[1]{\pagerefname~\pageref{#1}}
26733 \end{lcode}
26734 and can be used as
26735 \begin{lcode}
26736 \ldots footnote parameters are shown in~\fref{fig:fn}
26737 on~\pref{fig:fn}.
26738 \end{lcode}
26739 which in this document prints as:
26740 \begin{syntax}
26741 \ldots footnote parameters are shown in~\fref{fig:fn} on~\pref{fig:fn}. \\
26742 \end{syntax}
26743
26744 \begin{syntax}
26745 \cmd{\Aref}\marg{labstr} \cmd{\appendixrefname} \\
26746 \cmd{\Bref}\marg{labstr} \cmd{\bookrefname} \\
26747 \cmd{\Pref}\marg{labstr} \cmd{\partrefname} \\
26748 \cmd{\Cref}\marg{labstr} \cmd{\chapterrefname} \\
26749 \cmd{\Sref}\marg{labstr} \cmd{\sectionrefname} \\
26750 \end{syntax}
26751 \glossary(Aref)%
26752 {\cs{Aref}\marg{labstr}}%
26753 {Prints a named (\cs{appendixrefname}) reference to a \cs{label}ed appendix. Deprecated, to be removed in 2026.}
26754 \glossary(appendixrefname)%
26755 {\cs{appendixrefname}}%
26756 {Name for an appendix used by \cs{Aref}.}
26757 \glossary(Bref)%
26758 {\cs{Bref}\marg{labstr}}%
26759 {Prints a named (\cs{bookrefname}) reference to a \cs{label}ed book. Deprecated, to be removed in 2026.}
26760 \glossary(bookrefname)%
26761 {\cs{bookrefname}}%
26762 {Name for a book used by \cs{Bref}.}
26763 \glossary(Pref)%
26764 {\cs{Pref}\marg{labstr}}%
26765 {Prints a named (\cs{partrefname}) reference to a \cs{label}ed part. Deprecated, to be removed in 2026.}
26766 \glossary(partrefname)%
26767 {\cs{partrefname}}%
26768 {Name for a part used by \cs{Pref}.}
26769 \glossary(Cref)%
26770 {\cs{Cref}\marg{labstr}}%
26771 {Prints a named (\cs{chapterrefname}) reference to a \cs{label}ed chapter. Deprecated, to be removed in 2026.}
26772 \glossary(chapterrefname)%
26773 {\cs{chapterrefname}}%
26774 {Name for a chapter used by \cs{Cref}.}
26775 \glossary(Sref)%
26776 {\cs{Sref}\marg{labstr}}%
26777 {Prints a named (\cs{sectionrefname}) reference to a \cs{label}ed section. Deprecated, to be removed in 2026.}
26778 \glossary(sectionrefname)%
26779 {\cs{sectionrefname}}%
26780 {Name for a section used by \cs{Sref}.}
26781 Similarly, specific commands are supplied for referencing sectional
26782 divisions; \cmd{\Aref}\index{reference!to appendix} for \appendixrefname,
26783 \cmd{\Bref}\index{reference!to book} for \bookrefname,
26784 \cmd{\Pref}\index{reference!to part} for \partrefname,
26785 \cmd{\Cref}\index{reference!to chapter} for \chapterrefname,
26786 and \cmd{\Sref}\index{reference!to section} for divisions
26787 below \chapterrefname. For example:
26788 \begin{lcode}
26789 This is \Sref{sec:lab&ref} in \Cref{chap:xref}.
26790 \end{lcode}
26791 This is \Sref{sec:lab&ref} in \Cref{chap:xref}.
26792
26793 \begin{Deprecated}[July 2025]
26794 Please note that the macros described above, \cs{fref}, \cs{tref},
26795 \cs{pref}, \cs{Aref}, \cs{Bref}, \cs{Pref}, \cs{Cref}, \cs{Sref}
26796 have been marked as deprecated as of July 2025 and will be removed
26797 from the class in Summer of 2026. Until then, they will give a
26798 warning at first use.
26799
26800 Users are encouraged to define the macros manually in your preamble. The default versions are
26801 \begin{verbatim}
26802 \newcommand*{\fref}[1]{\figurerefname~\ref{#1}}
26803 \newcommand*{\tref}[1]{\tablerefname~\ref{#1}}
26804 \newcommand*{\pref}[1]{\pagerefname~\pageref{#1}}
26805 \newcommand*{\Aref}[1]{\appendixrefname~\ref{#1}}
26806 \newcommand*{\Bref}[1]{\bookrefname~\ref{#1}}
26807 \newcommand*{\Pref}[1]{\partrefname~\ref{#1}}
26808 \newcommand*{\Cref}[1]{\chapterrefname~\ref{#1}}
26809 \newcommand*{\Sref}[1]{\sectionrefname\ref{#1}}
26810 % here \figurerefname just points to \figurename...
26811 \end{verbatim}
26812 For now the class will define these macros at the begining of the
26813 document, \emph{unless} we can see they are already defined (e.g. by
26814 the user or some package). That way the warning also disappears.
26815
26816 Why remove this? While useful, macros like this are associated with
26817 personal or document preferences. Therefore it is better that the
26818 user define exactly what they need. The class should not have
26819 provided these macros in the first place, it should have been an
26820 example in the manual and be added to the setup for the manual (it
26821 is now).
26822
26823 As an example of user preference: most people use \Lpack{hyperref}
26824 and might like the entire thing to be a link, not just the number:
26825 \begin{verbatim}
26826 \newcommand*{\fref}[1]{\hyperref[#1]{\figurerefname~\ref*{#1}}
26827 \end{verbatim}
26828 Several packages already provide similar syntax.
26829 \end{Deprecated}
26830
26831
26832
26833 \index{reference!by number|)}
26834
26835 \section{Reference by name} \label{sec:nxref}
26836
26837 \index{reference!by name|(}
26838
26839 In technical works it is common to reference a chapter, say, by its
26840 number. In non-technical works such cross references are likely to be
26841 rare, and when they are given it is more likely that the chapter title
26842 would be used instead of the number, as in:
26843 \begin{lcode}
26844 The chapter \textit{\titleref{chap:bringhurst}} describes \ldots
26845 \end{lcode}
26846 The chapter \textit{\titleref{chap:bringhurst}} describes \ldots
26847
26848 % There are two packages, \Lpack{nameref}~\cite{NAMEREF} and
26849 % \Lpack{titleref}~\cite{TITLEREF}, that let you refer to things by name
26850 % instead of number. Over time \Lpack{nameref} has turned out to be the
26851 % industry standard.
26852
26853 \begin{Changed}[Summer 2023]
26854 We are now autoloading the \Lpack{nameref} (see \cite{NAMEREF}) and
26855 use that for our implementation for \cmd{\titleref} (it is just an
26856 alias for \cmd{\nameref}).\footnotemark
26857 \end{Changed}
26858 \footnotetext{This change fixes several incompatability issues we've
26859 had with the old implementation of \cs{titleref}, which needed a
26860 redefinition of \cs{label} to work. For the coming PDF-tagging
26861 project such redefinitions of kernel macros like \cs{label} is
26862 frowned upon. At their end the kernel team has updated \cmd{\label}
26863 for even easier sopport for \Lpack{nameref}.}
26864
26865 \begin{syntax}
26866 \cmd{\titleref}\marg{labstr} \qquad
26867 \cmd{\titleref*}\marg{labstr} \\
26868 \end{syntax}
26869 \glossary(titleref)%
26870 {\cs{titleref}\marg{labstr}}%
26871 {Prints the (section, or other) title of the number associated
26872 with \meta{labstr} from a \cs{label}.}%
26873 \glossary(titleref*)%
26874 {\cs{titleref*}\marg{labstr}}%
26875 {Similar to \cs{titleref}, but if \protect\Lpack{hyperref} is loaded this
26876 does \emph{not} add a hyperlink. Mapped onto \cs{nameref*}.}
26877 The macro \cmd{\titleref} is a class addition to the usual set of
26878 cross referencing commands. Instead of printing a number it typesets
26879 the title associated with the labelled number. This is really only useful
26880 if there \emph{is} a title, such as from a \cmd{\caption} or
26881 \cmd{\section} command. The starred version is for when
26882 \Lpack{hyperref} is loaded, then the starred version does \emph{not}
26883 create a hyperlink. If \Lpack{hyperref} is \emph{not} loaded, then the
26884 two macros does the same thing.
26885
26886
26887
26888
26889 % For an example, look at this code and its result.
26890 % \begin{egsource}{eg:sec:nxref:1}
26891 % Labels may be applied to:
26892 % \begin{enumerate}
26893 % \item Chapters, sections, etc. \label{sec:nxref:1}
26894 % ...
26895 % \item Items in numbered lists, etc. \ldots \label{sec:nxref:5}
26896 % \end{enumerate}
26897 % Item \ref{sec:nxref:1} in section \textit{\titleref{sec:nxref}}
26898 % mentions sections while item \titleref{sec:nxref:5}, on page
26899 % \pageref{sec:nxref:5} in the same section, mentions things like
26900 % items in enumerated lists that should not be referenced
26901 % by \verb?\titleref?.
26902 % \end{egsource}
26903
26904 % \begin{egresult}[Named references should be to titled elements]{eg:sec:nxref:1}
26905 % Labels may be applied to:
26906 % \begin{enumerate}
26907 % \item Chapters, sections, etc. \label{sec:nxref:1}
26908 % \item Captions
26909 % \item Legends
26910 % \item Poem titles
26911 % \item Items in numbered lists, etc. \ldots \label{sec:nxref:5}
26912 % \end{enumerate}
26913 % Item \ref{sec:nxref:1} in section \textit{\titleref{sec:nxref}}
26914 % mentions sections while item\index{reference!unexpected result}
26915 % \titleref{sec:nxref:5}, on page
26916 % \pageref{sec:nxref:5} in the same section, mentions things like
26917 % items in enumerated lists
26918 % that should not be referenced by \verb?\titleref?.
26919 % \end{egresult}
26920
26921
26922 %\newpage
26923
26924
26925 There can be three possibilities for the name of a sectional division;
26926 the full name, the name in the \toc, and the name in the page header.
26927 Aka
26928 \begin{verbatim}
26929 \section[toc][header]{title}
26930 \end{verbatim}
26931 Following the tradition used by \Lpack{nameref}\footnote{The old
26932 \cmd{\titleref} implementation did the same.} we generally use the
26933 title for the \toc{}. This corresponds to the default setting
26934 \cmd{\tocnameref}. Issuing \cmd{\headnameref} we instead use the
26935 header (if available) when preparing the title for the label.
26936
26937 \begin{syntax}
26938 \cmd{\headnameref} \cmd{\tocnameref} \\
26939 \end{syntax}
26940 \glossary(headnameref)%
26941 {\cs{headnameref}}%
26942 {Use header title for sectional title references.}
26943 \glossary(tocnameref)%
26944 {\cs{tocnameref}}%
26945 {Use \prtoc{} title for sectional title references (default).}
26946
26947 \fancybreak{}
26948
26949
26950 \Note{} In general it is \emph{not} recommended to place
26951 \cmd{\label} inside an argument for a \cmd{\chapter}, \cmd{\section},
26952 \cmd{\caption}, etc., command. At that point there is not title data
26953 available to use for the label.
26954
26955 % \fancybreak{}
26956
26957
26958 \begin{Changed}[Summer 2023]
26959 The following macros are no longer used. They will either issue a
26960 warning or an error. Users are encouraged to remove them:
26961 \cmd{\currenttitle}, \cmd{\namerefon} (is always on),
26962 \cmd{\namerefoff} and \cmd{\theTitleReference}.
26963 \end{Changed}
26964
26965
26966
26967 \index{reference!by name|)}
26968
26969
26970 %#% extend
26971 %#% extstart include backmatter.tex
26972
26973 \svnidlong
26974 {$Ignore: $}
26975 {$LastChangedDate: 2025-09-19 16:06:27 +0200 (Fri, 19 Sep 2025) $}
26976 {$LastChangedRevision: 873 $}
26977 {$LastChangedBy: [email protected] $}
26978
26979
26980 \LMnote{2010/06/09}{Several \cs{ixfile}'s changed to \cs{pixfile},
26981 with \cs{ixfile} only, no text appears in the output }
26982
26983
26984 \chapter{\prBackmatter} \label{chap:backmatter}
26985
26986 The \pixbackmatter\ consists of reference and supportive elements for
26987 the \pixmainmatter;
26988 things like bibliographies, indexes, glossaries, endnotes, and other
26989 material. The class provides additional elements and features of such
26990 matter that are not in the standard classes.
26991
26992 \section{Bibliography} \label{sec:xref:bibliography}
26993
26994 \index{bibliography|(}
26995
26996 Just as a reminder the bibliography is typeset within the
26997 \Ie{thebibliography} environment.
26998 \begin{syntax}
26999 \cmd{\bibname} \\
27000 \senv{thebibliography}\marg{exlabel} \\
27001 \cmd{\bibitem} ... \\
27002 \eenv{thebibliography} \\
27003 \end{syntax}
27004 \glossary(bibname)%
27005 {\cs{bibname}}%
27006 {The title for a bibliography}
27007 \glossary(thebibliography)%
27008 {\senv{thebibliography}\marg{exlabel}}%
27009 {Environment for typesetting a bibliography. \meta{exlabel} is an arbitrary
27010 piece of text as wide as the widest label for the bibliographic items.}
27011 \glossary(bibitem)%
27012 {\cs{bibitem}}%
27013 {Starts a new bibliographic entry in a \Pe{thebibliography} listing.}
27014 The environment takes one required argument, \meta{exlabel}, which is a
27015 piece of text
27016 as wide as the widest label in the bibliography. The value of
27017 \cmd{\bibname} (default `Bibliography') is used
27018 as the title.
27019
27020 \begin{syntax}
27021 \cmd{\bibintoc} \cmd{\nobibintoc} \\
27022 \end{syntax}
27023 \glossary(bibintoc)%
27024 {\cs{bibintoc}}%
27025 {Title of \Pe{thebibliography} will be added to the \prtoc.}
27026 \glossary(nobibintoc)%
27027 {\cs{nobibintoc}}%
27028 {Title of \Pe{thebibliography} is not added to the \prtoc.}
27029 The declaration \cmd{\bibintoc} will cause the \Ie{thebibliography}
27030 environment to add the title\index{bibliography!title in ToC} to
27031 the \toc, while the declaration
27032 \cmd{\nobibintoc} ensures that the title is not added to the \toc.
27033 The default is \cmd{\bibintoc}.
27034
27035 \begin{syntax}
27036 \cmd{\cite}\oarg{detail}\marg{labstr-list} \\
27037 \end{syntax}
27038 \glossary(cite)%
27039 {\cs{cite}\oarg{detail}\marg{labstr-list}}%
27040 {Citation in the text to bibliographic items specified in the
27041 \meta{labstr-list} of comma-separated bibliographic identifiers;
27042 optional information, e.g., page number, is supplied via \meta{detail}.}
27043 Within the text you call out a bibliographic\index{cite bibliographic item}
27044 reference using the
27045 \cmd{\cite} command, where \meta{labstr-list} is a comma-separated
27046 list of identifiers for the cited works; there must be no spaces in this
27047 list. The optional \meta{detail} argument is for any additional
27048 information regarding the citation such as a chapter or page number;
27049 this is printed after the main reference.
27050
27051 Various aspects of a bibliography can be changed and at this point
27052 it may be helpful to look at some of the internals of the \Ie{thebibliography}
27053 environment, which is defined like this
27054 \begin{lcode}
27055 \newenvironment{thebibliography}[1]{%
27056 \bibsection
27057 \begin{bibitemlist}{#1}}%
27058 {\end{bibitemlist}\postbibhook}
27059 \end{lcode}
27060 The bibliographic entries are typeset as a list, the \Ie{bibitemlist}.
27061
27062 \begin{syntax}
27063 \cmd{\bibsection} \\
27064 \end{syntax}
27065 \glossary(bibsection)%
27066 {\cs{bibsection}}%
27067 {Initialises the bibliography and typesets the title.}
27068 The macro \cmd{\bibsection} defines the heading\index{bibliography!heading}
27069 for the \Ie{thebibliography}
27070 environment; that is, everything before the actual list of items.
27071 It is effectively defined as
27072 \LMnote{2025/09/17}{Removed \cs{phantomsection} as \cs{chapter*} now also adds a target}
27073 \begin{lcode}
27074 \newcommand{\bibsection}{%
27075 \chapter*{\bibname}
27076 \bibmark
27077 \ifnobibintoc\else
27078 \addcontentsline{toc}{chapter}{\bibname}
27079 \fi
27080 \prebibhook}
27081 \end{lcode}
27082 If you want to change the heading, redefine \cmd{\bibsection}. For example,
27083 to have the bibliography as a numbered section instead of an unnumbered
27084 chapter, redefine it like
27085 \begin{lcode}
27086 \renewcommand{\bibsection}{%
27087 \section{\bibname}
27088 \prebibhook}
27089 \end{lcode}
27090 If you use the \Lpack{natbib}~\cite{NATBIB} and/or the
27091 \Lpack{chapterbib}~\cite{CHAPTERBIB} packages with the \Lopt{sectionbib}
27092 option, then they change \cmd{\bibsection} appropriately to typeset the
27093 heading as a numbered section.
27094
27095 \begin{syntax}
27096 \cmd{\bibmark} \\
27097 \end{syntax}
27098 \glossary(bibmark)%
27099 {\cs{bibmark}}%
27100 {Can be used in pagestyles for page headers in a bibliography.}
27101 \cs{bibmark} may be used in pagestyles for page headers in a bibliography.
27102 Its default definition is:
27103 \begin{lcode}
27104 \newcommand*{\bibmark}{}
27105 \end{lcode}
27106 but could be redefined like, say,
27107 \begin{lcode}
27108 \renewcommand*{\bibmark}{\markboth{\bibname}{}}
27109 \end{lcode}
27110
27111
27112 \begin{syntax}
27113 \cmd{\prebibhook} \cmd{\postbibhook} \\
27114 \end{syntax}
27115 \glossary(prebibhook)%
27116 {\cs{prebibhook}}%
27117 {Called between typesetting the title of a bibliography and starting
27118 the list of bibliographic entries.}
27119 \glossary(postbibhook)%
27120 {\cs{postbibhook}}%
27121 {Called after typesetting the list of of bibliographic entries.}
27122 The commands \cmd{\prebibhook} and \cmd{postbibhook} are called after
27123 typesetting the title of the bibliography and after typesetting the list of
27124 entries, respectively. By default, they are defined to do nothing. You may
27125 wish to use one or other of these to provide some general
27126 information\index{bibliography!explanatory text} about
27127 the bibliography. For example:
27128 \begin{lcode}
27129 \renewcommand{\prebibhook}{%
27130 CTAN is the Comprehensive \tx\ Archive Network and URLS for the
27131 several CTAN mirrors can be found at \url{http://www.tug.org}.}
27132 \end{lcode}
27133
27134 \index{bibliography!list styling|(}
27135
27136 \begin{syntax}
27137 \cmd{\biblistextra} \\
27138 \end{syntax}
27139 \glossary(biblistextra)%
27140 {\cs{biblistextra}}%
27141 {Called immediately after the \Pe{bibitemlist} is set up.}
27142 Just at the end of setting up the \Ie{bibitemlist} the \cmd{\biblistextra}
27143 command is called. By default this does nothing but you may change it to
27144 do something useful. For instance, it can be used to change
27145 the list parameters so that the entries are
27146 typeset flushleft.\index{bibliography!flushleft entries}
27147 \begin{lcode}
27148 \renewcommand*{\biblistextra}{%
27149 \setlength{\leftmargin}{0pt}%
27150 \setlength{\itemindent}{\labelwidth}%
27151 \addtolength{\itemindent}{\labelsep}}
27152 \end{lcode}
27153
27154 \begin{syntax}
27155 \cmd{\setbiblabel}\marg{style} \\
27156 \end{syntax}
27157 \glossary(setbiblabel)%
27158 {\cs{setbiblabel}\marg{style}}%
27159 {Define the look of the bibliographic entry identifiers.}
27160 The style of the labels\index{bibliography!label styling} marking the
27161 bibliographic entries can be set
27162 via \cmd{\setbiblabel}. The default definition is
27163 \begin{lcode}
27164 \setbiblabel{[#1]\hfill}
27165 \end{lcode}
27166 where \verb?#1? is the citation mark position, which generates flushleft
27167 marks enclosed in square brackets. To have marks just
27168 followed by a dot
27169 \begin{lcode}
27170 \setbiblabel{#1.\hfill}
27171 \end{lcode}
27172
27173 \begin{syntax}
27174 \cmd{\bibitem}\oarg{label}\marg{labstr} \\
27175 \cmd{\newblock} \\
27176 \end{syntax}
27177 \glossary(bibitem)%
27178 {\cs{bibitem}\oarg{label}\marg{labstr}}%
27179 {Introduces an entry in the bibliography. The \meta{labstr} argument
27180 corresponds to a \cs{cite}'s \meta{labstr} argument. The optional
27181 \meta{label} overides the default numerical printed entry label.}
27182 \glossary(newblock)%
27183 {\cs{newblock}}%
27184 {Used in a bibliography to indicate a convenient place in an entry to
27185 have a pagebreak.}
27186 Within the \Ie{bibitemlist} environment the entries are introduced
27187 by \cmd{\bibitem} instead of the more normal \cmd{\item} macro.
27188 The required \meta{labstr} argument is the identifier for the citation and
27189 corresponds to a \meta{labstr} for \cmd{\cite}. The items in the list
27190 are normally labelled numerically but this can be overriden by using
27191 the optional \meta{label} argument. The \cmd{\newblock} command can be used
27192 at appropriate places in the entry for encouraging a linebreak (this is
27193 used by the \Lopt{openbib} option).
27194
27195 \begin{syntax}
27196 \lnc{\bibitemsep} \\
27197 \end{syntax}
27198 \glossary(bibitemsep)%
27199 {\cs{bibitemsep}}%
27200 {Vertical space between entries in a bibliography.}
27201 In the listing the vertical space between entries is controlled by the
27202 length \lnc{\bibitemsep}, which by default is set to the normal
27203 \lnc{\itemsep} value. The vertical space is
27204 \texttt{(\lnc{\bibitemsep} + \lnc{\parsep})}. If you wish to eliminate
27205 the space between items do
27206 \begin{lcode}
27207 \setlength{\bibitemsep}{-\parsep}
27208 \end{lcode}
27209
27210 \index{bibliography!list styling|)}
27211
27212 \subsection{BibTex}
27213
27214 Often the \Lbibtex\ program~\cite{BIBTEX} is used to generate the
27215 bibliography list from database(s) of
27216 bibliographic\index{bibliographic database} data. For \Lbibtex\
27217 a bibliographic data base is a \pixfile{bib} file containing information
27218 necessary to produce entries in a bibliography. \Lbibtex\
27219 extracts the raw data from the files for each citation in the text and
27220 formats it for typesetting according to a particular style.
27221
27222
27223 \begin{syntax}
27224 \cmd{\bibliography}\marg{bibfile-list} \\
27225 \end{syntax}
27226 \glossary(bibliography)%
27227 {\cs{bibliography}\marg{bibfile-list}}%
27228 {Print the bibliography having used \Pbibtex\ to extract entries from
27229 the \meta{bibfile-list} of comma-separated names of \file{bib} files.}
27230 The bibliography will be printed at the location of the \cmd{\bibliography}
27231 command. Its argument is a comma-separated list of \Pbibtex\ \pixfile{bib} files
27232 which will be searched by \Lbibtex\ to generate the bibliography.
27233 Only the file name(s) should be supplied, the extension must not be given.
27234
27235
27236 \begin{syntax}
27237 \cmd{\nocite}\marg{labstr} \verb?\nocite{*}? \\
27238 \end{syntax}
27239 \glossary(nocite)%
27240 {\cs{nocite}\marg{labstr}}%
27241 {Add entry \meta{labstr} to the bibliography, but with no in-text citation.}
27242 The command \cmd{\nocite} causes \Lbibtex\ to make an entry
27243 in the bibliography but no citation will appear in the text. The special
27244 case \verb?\nocite{*}? causes \emph{every} entry in the database to be
27245 listed in the bibliography.
27246
27247 \begin{syntax}
27248 \cmd{\bibliographystyle}\marg{style} \\
27249 \end{syntax}
27250 \glossary(bibliographystyle)%
27251 {\cs{bibliographystyle}\marg{style}}%
27252 {Typeset the bibliographic entries according to \meta{style}.}
27253 Many different \Pbibtex\ styles\index{BibTeX style?\Pbibtex\ style}
27254 are available and the particular one to be used is specified
27255 by calling \cmd{\bibliographystyle} before the bibliography itself.
27256 The `standard' bibliography \meta{style}s follow the general schemes
27257 for mathematically oriented papers and are:
27258 \begin{itemize}
27259 \item[\texttt{plain}]\index{BibTeX style?\Pbibtex\ style!plain?\texttt{plain}}
27260 The entry format is similar to one suggested by
27261 Mary-Claire van Leunen~\cite{LEUNEN92}, and entries are sorted
27262 alphabetically and labelled with numbers.
27263 \item[\texttt{unsrt}]\index{BibTeX style?\Pbibtex\ style!unsrt?\texttt{unsrt}}
27264 The format is the same as \texttt{plain} but
27265 that entries are ordered by the citation order in the text.
27266 \item[\texttt{alpha}]\index{BibTeX style?\Pbibtex\ style!alpha?\texttt{alpha}}
27267 The same as \texttt{plain} but entries are
27268 labelled like `Wil89', formed from the author and publication date.
27269 \item[\texttt{abbrv}]\index{BibTeX style?\Pbibtex\ style!abbrv?\texttt{abbrv}}
27270 The same as \texttt{plain} except that some elements, like month
27271 names, are abbreviated.
27272 \end{itemize}
27273 There are many other styles available, some of which are used
27274 in collaboration with a package, one popular one being
27275 Patrick Daly's \Lpack{natbib}~\cite{NATBIB} package for the kinds of
27276 author-year citation styles used in the natural sciences.
27277 Another package is \Lpack{jurabib}~\cite{JURABIB} for citation styles
27278 used in legal documents where the references are often given in footnotes
27279 rather than listed at the end of the document.
27280
27281 I assume you know how to
27282 generate\index{running BibTeX?running \Pbibtex} a bibliography using \Lbibtex,
27283 so this is just a quick reminder. You first run \ltx\
27284 on your document, having specified the bibliography style, cited
27285 your reference material and listed the relevant \Lbibtex\ database(s).
27286 You then run \Lbibtex, and after running \ltx\ twice more the
27287 bibliography should be complete. After a change to your citations you have to
27288 run \ltx\ once, \Lbibtex\ once, and then \ltx\ twice more to get an
27289 updated set of references.
27290
27291 The format and potential contents of a \Pbibtex\
27292 database\index{BibTeX database?\Pbibtex\ database} file
27293 (a \pixfile{bib} file) are specified in detail in Lamport~\cite{LAMPORT94}
27294 and the first of the \btitle{Companions}~\cite{COMPANION}.
27295 Alternatively
27296 there is the documentation by Oren Patashnik~\cite{BIBTEX} who wrote the
27297 \Lbibtex\ program.
27298
27299 \index{BibTeX style?\Pbibtex\ style!changing|(}
27300
27301 A \Pbibtex\ style, specified in a \pixfile{bst} file, is written
27302 using an anonymous stack based language
27303 created specifically for this purpose. If you can't find a
27304 \Pbibtex\ style\index{BibTeX style?\Pbibtex\ style}
27305 that provides what you want you can either use the
27306 \Lpack{makebst}~\cite{MAKEBST} package
27307 which leads you through creating your own style via a question and answer
27308 session, or you can directly write your own. If you choose the latter
27309 approach then Patashnik's \textit{Designing BibTeX files}~\cite{BIBTEXHACK}
27310 is essential reading. As he says, it is best to take an existing style and
27311 modify it rather than starting from scratch.
27312
27313 % \begin{comment}
27314
27315 % This is what I did for the
27316 % style for this book, as all I wanted was a slight change and extension
27317 % to the standard
27318 % \texttt{alpha}\index{BibTeX style?\Pbibtex\ style!alpha?\texttt{alpha}}
27319 % style, which is in \file{alpha.bst}\ixfile{bst}.
27320
27321 % There were three things that I wanted to do:
27322 % \begin{itemize}
27323 % \item Add an `isbn' field to the entries so an ISBN\index{ISBN} number
27324 % could be easily quoted;
27325 % \item Add an `annote' field so that I could perhaps provide an
27326 % annotated\index{bibliography!annotated}
27327 % bibliography;
27328 % \item Use the modern \cmd{\emph} command instead of the deprecated \cmd{\em}
27329 % command for titles;
27330 % \end{itemize}
27331
27332 % If you aren't interested in how I did it, skip the next part,
27333 % but if you are you might find it easier to follow if you have a copy
27334 % of the \pixfile{alpha.bst} file to hand.
27335
27336 % This is what I did, although not in this order as I kept flitting
27337 % back and forth in order to resolve the problems that arose.
27338 % \begin{itemize}
27339 % \item Copied the \pixfile{alpha.bst} file to a new file I called
27340 % \pixfile{typo.bst} as my new style was to be called \texttt{typo}.
27341
27342 % \item Near the start of the file are some lines:
27343 % \begin{lcode}
27344 % ENTRY
27345 % { address
27346 % author
27347 % ...
27348 % year
27349 % isbn
27350 % annote
27351 % }
27352 % \end{lcode}
27353 % at the end of which I added the \texttt{isbn} and \texttt{annote}. These are
27354 % the fields that may apear in an entry. Later I have to describe how these
27355 % fields are to be dealt with.
27356
27357 % \item
27358 % Shortly after the \texttt{ENTRY} list there is a set of \texttt{FUNCTION}
27359 % specifications, the 17th of which is called \texttt{emphasize}. This is the
27360 % only place in the file where the \cmd{\em} macro appears, so this is what I
27361 % have to modify so that the \texttt{typo} style will use \cmd{\emph} instead
27362 % of \cmd{\em}. My revised definition is:
27363 % \begin{lcode}
27364 % FUNCTION {emphasize}
27365 % { duplicate$ empty$
27366 % { pop$ "" }
27367 % %% { "{\em " swap$ * "}" * } % original, change to
27368 % { "\emph{ " swap$ * "}" * } % PW mod
27369 % if$
27370 % }
27371 % \end{lcode}
27372 % I didn't (and still don't) know just how the function operated but my
27373 % modification worked.
27374
27375 % \item
27376 % After this were a lot of functions of the form \verb?{format.something}?
27377 % which I took to be the formatting instructions for the fields. Looking
27378 % at the various functions I added the following ones.
27379 % \begin{lcode}
27380 % %% PW added format.isbn
27381 % FUNCTION {format.isbn}
27382 % { isbn empty$
27383 % { "" }
27384 % { new.block " ISBN " isbn * }
27385 % if$
27386 % }
27387
27388 % %% PW added format.annote
27389 % { annote empty$
27390 % { "" }
27391 % { " \begin{quotation}\noindent " annote *
27392 % " \end{quotation} " * }
27393 % if$
27394 % }
27395
27396 % %% PW added fin.annote
27397 % { annote empty$
27398 % { }
27399 % { newline$ }
27400 % if$
27401 % }
27402 % \end{lcode}
27403 % %$
27404
27405 % \item
27406 % The last thing that I had to do was to get the entries to write
27407 % out the new \texttt{annote} and \texttt{isbn} fields. As an example, here
27408 % is the revised function for a \texttt{booklet} entry, which is one of the
27409 % shorter ones.
27410 % \begin{lcode}
27411 % FUNCTION {booklet}
27412 % { output.bibitem
27413 % format.authors output
27414 % new.block
27415 % format.title "title" output.check
27416 % howpublished address new.block.checkb
27417 % howpublished output
27418 % address output
27419 % format.date output
27420 % format.isbn output %% PW added
27421 % new.block
27422 % note output
27423 % fin.entry
27424 % format.annote write$ %% PW added
27425 % fin.annote %% PW added
27426 % }
27427 % \end{lcode}
27428 % %$
27429
27430 % I added similar lines to all the other entry functions except, for example,
27431 % the \texttt{article} function where I only added the \texttt{annote}
27432 % lines as I assumed that an article would not have an ISBN\index{ISBN}.
27433
27434 % \end{itemize}
27435
27436 % It took me three or four attempts to make it all work as I didn't
27437 % really know what I was doing. I basically copied something that looked
27438 % close to what I might need, changed some names, and tried it out. If it
27439 % didn't work then I tried something a bit different until it did.
27440 % For someone who knew what they were doing it would have been a trivial
27441 % task and they would probably have used a more elegant solution, but
27442 % it works and didn't take too long.
27443 % \end{comment}
27444
27445 \index{BibTeX style?\Pbibtex\ style!changing|)}
27446
27447
27448 \subsection{BibLaTeX}
27449
27450 BibLaTeX generally refers to the package \Lpack{biblatex} and its
27451 accompanying external programme \Lprog{biber}. Like \Lprog{bibtex} it
27452 uses \texttt{.bib} files to store the data, and generally suppors more
27453 data types and keys than most \Lprog{bibtex} styles. Including proper
27454 type and key support for online resources. Users are generally
27455 refered to \cite{BIBLATEX}.
27456
27457 In contrast to BibTeX, \Lpack{biblatex} does all its formatting using
27458 \LaTeX{} macros, \Lprog{biber} just makes sure to get the right data
27459 out of the \texttt{.bib} file(s) and put into a format that
27460 \Lpack{biblatex} understands.
27461
27462 Note that \Lprog{biber} will assume your \texttt{.bib} files are saved
27463 as UTF-8 text, whereas standard \Lprog{bibtex} can only really handle
27464 ansii.
27465
27466
27467
27468
27469 \index{bibliography|)}
27470
27471 \section{Index} \label{sec:xref:index}
27472
27473
27474 It is time to take a closer look at indexing. The class allows
27475 multiple indexes\index{index!multiple} and an index may be typeset as a
27476 single\indextwo{index}{single column} or a
27477 double\indextwo{index}{double column} column.
27478
27479 The general process is to put indexing commands into your source text,
27480 and \ltx\ will write this raw indexing data to an \pixfile{idx} file.
27481 The raw index data is then processed, not by \ltx\ but by yourself if you
27482 have plenty of spare time on your hands, or more usually by a separate
27483 program, to create a sorted list of indexed items in a second file (usually
27484 an \pixfile{ind} file). This can then be input to \ltx\ to print the sorted
27485 index data.
27486
27487 \subsection{Printing an index}
27488 \index{index!printing|(}
27489
27490 \begin{syntax}
27491 \cmd{\makeindex}\oarg{file} \\
27492 \cmd{\printindex}\oarg{file} \\
27493 \end{syntax}
27494 \glossary(makeindex)%
27495 {\cs{makeindex}\oarg{file}}%
27496 {Preamble command to collect raw index information. By default this
27497 is written to file \cs{jobname}\texttt{.idx}. If the optional argument
27498 is used it may be written to file \meta{file}\texttt{.idx}.}
27499 \glossary(printindex)%
27500 {\cs{printindex}\oarg{file}}%
27501 {Print the sorted index. By default this is read from file
27502 \cs{jobname}\texttt{.ind}. If the optional argument is given
27503 it will read the data from file \meta{file}\texttt{.ind}.}
27504 In order to make \ltx\ collect indexing information the declaration
27505 \cmd{\makeindex} must be put in the preamble\index{preamble}. By default
27506 the raw index data is put into the \file{jobname.idx}\ixfile{idx} file. If
27507 the optional \meta{file} argument is given then index data can be
27508 output to \file{file.idx}. Several \cmd{\makeindex} declarations
27509 can be used provided they each call for a different file.
27510
27511 The \cmd{\printindex} command will print\index{index!print} an index
27512 where by default the indexed items are assumed to be in a file called
27513 \pixfile{jobname.ind}\ixfile{ind}. If the optional \meta{file} argument
27514 is given
27515 then the indexed items are read from the file called \file{file.ind}.
27516
27517 % The typical method of generating an \pixfile{ind} file containing
27518 %the sorted index entries from the raw index data in an
27519 %\pixfile{idx} file is to use the \Lmakeindex\ program~\cite{CHEN88}.
27520
27521
27522 \begin{syntax}
27523 \senv{theindex} entries \eenv{theindex} \\
27524 \cmd{\onecolindex} \cmd{\twocolindex} \\
27525 \cmd{\indexname} \\
27526 \end{syntax}
27527 \glossary(theindex)%
27528 {\senv{theindex}}%
27529 {Environment for typesetting an index}
27530 \glossary(onecolindex)%
27531 {\cs{onecolindex}}%
27532 {Typeset index in one column.}
27533 \glossary(twocolindex)%
27534 {\cs{twocolindex}}%
27535 {Typeset index in two columns (the default).}
27536 \glossary(indexname)%
27537 {\cs{indexname}}%
27538 {Name used for the theindex title.}
27539 The index entries are typeset within the \Ie{theindex}
27540 environment. By default it is typeset with two
27541 columns\indextwo{double column}{index}
27542 but following the \cmd{\onecolindex} declaration the environment
27543 uses a single\indextwo{index}{single column} column.
27544 The default two column behaviour is restored
27545 after the \cmd{\twocolindex} declaration.
27546 The index\indextwo{index}{name} title is given by the current value of
27547 \cmd{\indexname} (default `Index').
27548
27549 \begin{syntax}
27550 \cmd{\indexintoc} \cmd{\noindexintoc} \\
27551 \end{syntax}
27552 \glossary(indexintoc)%
27553 {\cs{indexintoc}}%
27554 {Add the index title to the \prtoc\ (the default).}
27555 \glossary(noindexintoc)%
27556 {\cs{noindexintoc}}%
27557 {Do not add the index title to the \prtoc.}
27558 The declaration \cmd{\indexintoc} will cause the \Ie{theindex}
27559 environment to add the title\index{index!title in ToC} to the \toc,
27560 while the declaration
27561 \cmd{\noindexintoc} ensures that the title is not added to the \toc.
27562 The default is \cmd{\indexintoc}.
27563
27564 \begin{syntax}
27565 \lnc{\indexcolsep} \\
27566 \lnc{\indexrule} \\
27567 \end{syntax}
27568 \glossary(indexcolsep)%
27569 {\ls{indexcolsep}}%
27570 {Width of the gutter in two column indexes.}
27571 \glossary(indexrule)%
27572 {\ls{indexrule}}%
27573 {Width of the inter-column rule in two column indexes.}
27574 The length \lnc{\indexcolsep} is the width of the gutter between the two
27575 index columns\index{index!double column!gutter}
27576 The length \lnc{\indexrule}, default
27577 value 0pt, is the thickness of a vertical rule separating the two columns.
27578
27579
27580 \begin{syntax}
27581 \cmd{\preindexhook} \\
27582 \end{syntax}
27583 \glossary(preindexhook)%
27584 {\cs{preindexhook}}%
27585 {Called between typesetting an index's title and the start of the list.}
27586 The macro \cmd{\preindexhook}\index{index!explanatory text}
27587 is called after the title is typeset and
27588 before the index listing starts. By default it does nothing but
27589 can be changed. For example
27590 \begin{lcode}
27591 \renewcommand{\preindexhook}{Bold page numbers are used
27592 to indicate the main reference for an entry.}
27593 \end{lcode}
27594
27595 \begin{syntax}
27596 \cmd{\indexmark} \\
27597 \end{syntax}
27598 \glossary(indexmark)%
27599 {\cs{indexmark}}%
27600 {Can be used in pagestyles for page headers in an index.}
27601 \cs{indexmark} may be used in pagestyles for page headers in an index.
27602 Its default definition is:
27603 \begin{lcode}
27604 \newcommand*{\indexmark}{}
27605 \end{lcode}
27606 but could be redefined like, say,
27607 \begin{lcode}
27608 \renewcommand*{\indexmark}{\markboth{\indexname}{\indexname}}
27609 \end{lcode}
27610
27611
27612
27613
27614 \begin{syntax}
27615 \cmd{\ignorenoidxfile} \\
27616 \cmd{\reportnoidxfile} \\
27617 \end{syntax}
27618 \glossary(ignorenoidxfile)%
27619 {\cs{ignorenoidxfile}}%
27620 {Do not report attempts to use an \file{idx} file that has not been
27621 declared by \cs{makeindex}.}
27622 \glossary(reportnoidxfile)%
27623 {\cs{reportnoidxfile}}%
27624 {Report attempts to use an \file{idx} file that has not been
27625 declared by \cs{makeindex}.}
27626 Following the declaration \cmd{\ignorenoidxfile}, which is the default,
27627 LaTeX will silently pass over attempts to use an \pixfile{idx} file which has
27628 not been declared via \cmd{\makeindex}. After the declaration
27629 \cmd{\reportnoidxfile} LaTeX will whine about any attempts to
27630 write to an unopened file.
27631
27632 \index{index!printing|)}
27633
27634 \subsection{Preparing an index}
27635
27636 \index{index!preparation|(}
27637
27638 It it is easy for a computer to provide a list of all the words you
27639 have used, and where they were used. This is called a
27640 concordance\index{concordance}.
27641 Preparing an index, though, is not merely a gathering of words but
27642 is an intellectual
27643 process that involves recognising and naming concepts, constructing a
27644 logical hierarchy of these and providing links between related concepts.
27645 No computer can do that for you though it can help with some tasks, such as
27646 sorting things into alphabetical order, eliminating duplicates, and so forth.
27647
27648 Several iterations may be required before you have an acceptable index.
27649 Generally you pick out the important words or phrases used on the first pass.
27650 Part of the skill of indexing is finding appropriate words to describe things
27651 that may not be obvious from the text. If there are several ways of describing
27652 something they may all be included using a `see'
27653 reference\index{index!see reference} to the most
27654 obvious of the terms, alternatively you could
27655 use `see also'\index{index!see also reference} references
27656 between the items. Entries should be broken down into subcategories so
27657 that any particular item will not have a long string of page numbers and
27658 your reader is more likely to quickly find the relevant place. After having
27659 got the first index you will most probably have to go back and correct
27660 all the sins of ommission and commission, and start the cycle again.
27661
27662 I found that indexing this manual was the most difficult part of preparing
27663 it. It was easy to index the names of all the macros, environments, and so on
27664 as I had commands that would simultaneously print and index these. It was
27665 the concepts that was difficult. I inserted \cmd{\index} commands as I went
27666 along at what seemed to be appropriate places but turned out not to be.
27667 I would use slightly different words for the same thing, and what was worse
27668 the same word for different things. It took a long time to improve it to
27669 its present rather pitiful state.
27670
27671 \begin{syntax}
27672 \cmd{\index}\oarg{file}\marg{stuff} \\
27673 \end{syntax}
27674 \glossary(index)%
27675 {\cs{index}\oarg{file}\marg{stuff}}%
27676 {Add \meta{stuff} and the current page number to the raw index data.
27677 By default this is written to
27678 file \cs{jobname}\texttt{.idx}. If the optional argument
27679 is given it will be written to file \meta{file}\texttt{.idx}.}
27680 The \cmd{\index} macro specifies that \meta{stuff} is to appear in
27681 an index. By default the raw index data --- the \meta{stuff} and the
27682 page number --- will be output
27683 to the \pixfile{jobname.idx}\ixfile{idx} file, but if the optional \meta{file}
27684 argument is given then output will be to the \file{file.idx} file.
27685
27686 This book has two\index{index!multiple} indexes.
27687 The main index uses the default indexing
27688 commands, while the second index does not. They are set up like this:
27689 \begin{lcode}
27690 % in preamble
27691 \makeindex
27692 \makeindex[lines]
27693 % in body
27694 ...\index{main} ...\index[lines]{First line} ...
27695 ...
27696 % at the end
27697 \clearpage
27698 % main index
27699 \pagestyle{Index}
27700 \renewcommand{\preindexhook}{%
27701 The first page number is usually, but not always,
27702 the primary reference to the indexed topic.\vskip\onelineskip}
27703 \printindex
27704
27705 % second index
27706 \clearpage
27707 \pagestyle{ruled}
27708 \renewcommand{\preindexhook}{}
27709 \renewcommand{\indexname}{Index of first lines}
27710 \onecolindex
27711 \printindex[lines]
27712 \end{lcode}
27713
27714
27715 \begin{syntax}
27716 \cmd{\specialindex}\marg{file}\marg{counter}\marg{stuff} \\
27717 \end{syntax}
27718 \glossary(specialindex)%
27719 {\cs{specialindex}\marg{file}\marg{counter}\marg{stuff}}%
27720 {Add \meta{stuff} and the current value of \meta{counter}
27721 to the raw index data file \meta{file}\texttt{.idx}.}
27722 The \cmd{\index} command uses the page number\index{reference!to page}
27723 as the reference for
27724 the indexed item. In contrast the \cmd{\specialindex} command uses
27725 the \meta{counter} as the reference\index{reference!to counter}
27726 for the indexed \meta{stuff}.
27727 It writes \meta{stuff} to the \file{file.idx} file, and also writes
27728 the page number (in parentheses) and the value of the \meta{counter}.
27729 This means that indexing can be with respect to something other than page
27730 numbers. However, if the \Lpack{hyperref} package is used the special
27731 index links will be to pages even though they will appear to be with
27732 respect to the \meta{counter}; for example, if figure numbers are used
27733 as the index reference the hyperref link will be to the page where the
27734 figure caption appears and not to the figure itself.
27735
27736
27737 \begin{syntax}
27738 \cmd{\showindexmarks} \cmd{\hideindexmarks} \\
27739 \cmd{\indexmarkstyle} \\
27740 \end{syntax}
27741 \glossary(showindexmarks)%
27742 {\cs{showindexmarks}}%
27743 {The \meta{stuff} argument to \cs{index} and \cs{specialindex} will
27744 be printed in the margin (for use in noting what has been indexed where).}
27745 \glossary(hideindexmarks)%
27746 {\cs{hideindexmarks}}%
27747 {The \meta{stuff} argument to \cs{index} and \cs{specialindex} will
27748 not be printed in the margin (the default).}
27749 \glossary(indexmarkstyle)%
27750 {\cs{indexmarkstyle}}%
27751 {Font style for printing index marks in the margin.}
27752 The declaration \cmd{\showindexmarks} causes the argument to practically
27753 any \cmd{\index} and \cmd{\specialindex} to be
27754 printed\index{index!show indexed items} in the margin of the
27755 page where the indexing command was issued. The argument is printed using
27756 the \cmd{\indexmarkstyle} which is initially specified as
27757 \begin{lcode}
27758 \indexmarkstyle{\normalfont\footnotesize\ttfamily}
27759 \end{lcode}
27760 For reasons I don't fully understand, spaces in the argument are displayed
27761 as though it was typeset using the starred version of \cmd{\verb}.
27762 The \cmd{\hideindexmarks}, which is the default, turns off
27763 \cmd{\showindexmarks}.
27764
27765 The standard classes just provide the plain \cmd{\index} command with
27766 no optional \meta{file} argument. In those classes the contents of the
27767 \file{jobname.idx} file is limited to the index entries actually seen in
27768 the document. In particular, if you are using \cmd{\include} for
27769 some parts of the document and \cmd{\includeonly} to exclude one or more
27770 files, then any \cmd{\index} entries in an excluded file will not appear
27771 in the \file{jobname.idx} file. The new implementation of indexing eliminates
27772 that potential problem.
27773
27774 \begin{syntax}
27775 \cmd{\item} \cmd{\subitem} \cmd{\subsubitem} \\
27776 \end{syntax}
27777 \glossary(item)%
27778 {\cs{item}}%
27779 {Introduces a main index entry.}
27780 \glossary(subitem)%
27781 {\cs{subitem}}%
27782 {Introduces a subsidiary index entry.}
27783 \glossary(subsubitem)%
27784 {\cs{subsubitem}}%
27785 {Introduces a third level index entry.}
27786 The \Ie{theindex} environment\index{index!entry levels} supports
27787 three levels of entries.
27788 A \cmd{\item} command
27789 flags a main\index{index!main entry} entry; a subentry\index{index!subentry}
27790 of a main entry is indicated by
27791 \cmd{\subitem} and a subentry\index{index!subentry!subsubentry}
27792 of a subentry is flagged by
27793 \cmd{\subsubitem}. For example a portion of an index might look like:
27794 \egstart[-2em]
27795 \begin{lcode}
27796 \item bridge, 2,3,7
27797 \subitem railway, 24
27798 \subsubitem Tay, 37
27799 \end{lcode}
27800 \egmid
27801 bridge, 2, 3, 7\\
27802 \hspace*{2em} railway, 24 \\
27803 \hspace*{4em} Tay, 37
27804 \egend
27805 \noindent if the Tay Bridge\footnote{A railway (railroad) bridge in Scotland
27806 that collapsed in 1879 killing 90 people. The disaster lives for ever in
27807 the poem \textit{The Tay Bridge Disaster} by William McGonagall (1830--?),
27808 the first verse of which goes:
27809 \begin{verse}
27810 Beautiful Railway Bridge of the Silv'ry Tay!\index[lines]{Beautiful
27811 Railway Bridge of the Silv'ry Tay} \\
27812 Alas! I am very sorry to say \\
27813 That ninety lives have been taken away \\
27814 On the last Sabbath day of 1879, \\
27815 Which will be remember'd for a very long time.
27816 \end{verse}}
27817 was mentioned on page 37.
27818
27819 \index{index!preparation|)}
27820
27821
27822 \subsection{MakeIndex}
27823
27824 It is possible, but time consuming and error prone, to create your
27825 index by hand from the output of the \cmd{\index} commands you have scattered
27826 throughout the text. Most use the \Lmakeindex\ program to do this
27827 for them; there is also the \Lprog{xindy} program~\cite{XINDY}
27828 but this is much less known.
27829
27830
27831 \begin{syntax}
27832 \cmd{\xindyindex} \\
27833 \end{syntax}
27834 It turns out that \Lprog{xindy} cannot handle a \Mname\
27835 hyperindex\index{hyperindex} (which
27836 can be obtained with the aid of the \Lpack{hyperref} package), although
27837 \Lmakeindex\ can do so.\footnote{This deficiency in \Pprog{xindy}
27838 was discovered by Frederic Connes\index{Connes, Frederic}, who also provided
27839 the \cs{xindyindex} command.}
27840 If you are going to use \Lprog{xindy} to process
27841 the raw index data put \cmd{\xindyindex} in the preamble, which will prevent
27842 hyperindexing\index{hyperindex}.
27843
27844 \fancybreak{}
27845
27846
27847 %%\index{MakeIndex?\Pmakeindex!raw data|(}
27848 \Iprogsub{MakeIndex}{raw data|(}%
27849
27850 \Lmakeindex\ reads an \pixfile{idx} file containg the raw index
27851 data (which may include some commands to \Lmakeindex\ itself), sorts
27852 the data, and then outputs an \pixfile{ind} file containing the sorted data,
27853 perhaps with some \ltx\ commands to control the printing.
27854 \Lmakeindex\ was created as a general purpose index processing program
27855 and its operation can be controlled by a
27856 `makeindex configuration file'%
27857 %%\index{MakeIndex?\Pmakeindex!configuration file}%
27858 \Iprogsub{MakeIndex}{configuration file}%
27859 \index{configuration file!MakeIndex?\Pmakeindex}
27860 (by default this is an \pixfile{ist} file). Such a file consists of two
27861 parts. The first
27862 part specifies \Pmakeindex\ commands that can be included in the
27863 \meta{stuff} argument to \cmd{\index}. The second part controls how
27864 the sorted index data is to be output.
27865
27866 I will only describe the most common elements of what you can put in
27867 an \pixfile{ist} file; consult the \Pmakeindex\
27868 manual~\cite{CHEN88}, or the \btitle{Companion}~\cite{COMPANION}, for all
27869 the details.
27870
27871 You can embed commands, in the form of single characters,
27872 in the argument to \cmd{\index} that guide
27873 \Lmakeindex\ in converting the raw \pixfile{idx} file into an
27874 \pixfile{ind} file for final typesetting. The complete set of these
27875 is given in \tref{tab:configin}. They all have defaults and you can modify
27876 these via a \Lmakeindex\ configuration file.
27877
27878 \newcommand*{\kwd}[1]{\texttt{#1}}
27879 \newcommand*{\kty}[1]{\textit{(#1)}}
27880
27881 \begin{table}
27882 \centering
27883 \caption{\Pmakeindex\ configuration file input parameters} \label{tab:configin}
27884 \begin{tabular}{llp{0.5\textwidth}}\toprule
27885 \multicolumn{1}{c}{Keyword} & \multicolumn{1}{c}{Default} & \multicolumn{1}{c}{Description} \\ \midrule
27886 \kwd{keyword} \kty{s} & \verb?"\\indexentry"? &
27887 The argument to this command is a \Pmakeindex{} index entry \\
27888 \kwd{arg\_open} \kty{c} & \verb?'{'? &
27889 Argument start delimeter \\
27890 \kwd{arg\_close} \kty{c} & \verb?'}'? &
27891 Argument end delimeter \\
27892 \kwd{range\_open} \kty{c} & \verb?'('? &
27893 Start of an explicit page range \\
27894 \kwd{range\_close} \kty{c} & \verb?')'? &
27895 End of an explicit page range \\
27896 \kwd{level} \kty{c} & \verb?'!'? &
27897 Character denoting a new subitem level \\
27898 \kwd{actual} \kty{c} & \verb?'@'? &
27899 Character denoting that the following text is to appear in the
27900 actual index file \\
27901 \kwd{encap} \kty{c} & \verb?'|'? &
27902 Character denoting that the rest of the argument is to be used as
27903 an encapsulating command for the page number \\
27904 \kwd{quote} \kty{c} & \verb?'"'? &
27905 Character that escapes the following character \\
27906 \kwd{escape} \kty{c} & \verb?'\\'? &
27907 Symbol with no special meaning unless followed by the \kwd{quote}
27908 character, when both characters will be printed. The \kwd{quote}
27909 and \kwd{escape} characters must be different. \\
27910 \kwd{page\_compositor} \kty{s} & \verb?"-"? &
27911 Composite number separator \\
27912 \bottomrule
27913 \multicolumn{3}{c}{\kty{s} of type string, \kty{c} of type character}
27914 \end{tabular}
27915 \end{table}
27916
27917 In the simplest case you just use the name of the index item as the
27918 argument to the \cmd{\index} command. However, spaces are significant as far
27919 as \Lmakeindex\ is concerned. The following three uses of \cmd{\index}
27920 will result in three different entries in the final index \\
27921 \verb*?\index{ entry}? \verb*?\index{entry}? \verb*?\index{entry }?\footnote{Unless you remember to pass the \texttt{-c} option to \Lmakeindex, then spaces at either end are removed and all other spaces are collapsed to single spaces. It is recommended to always use this option.}
27922
27923 \begin{figure}
27924 \centering
27925 \begin{small}
27926 \begin{tabular}{ll|l}
27927 p. v: & \verb?\index{Alf}? & \verb?\indexentry{Alf}{v}? \\
27928 p. 1: & \verb?\index{Alf}? & \verb?\indexentry{Alf}{1}? \\
27929 p. 2: & \verb?\index{Alf}? & \verb?\indexentry{Alf}{2}? \\
27930 p. 3: & \verb?\index{Alf}? & \verb?\indexentry{Alf}{3}? \\
27931 p. 5: & \verb?\index{Alfabet|see{Bet}}? & \verb?\indexentry{Alfabet|see{Bet}}{5}? \\
27932 p. 7: & \verb?\index{Alf@\textit{Alf}}? & \verb?\indexentry{Alf@\textit{Alf}}{7}? \\
27933 & \verb?\index{Bet|textbf}? & \verb?\indexentry{Bet|textbf}{7}? \\
27934 p. 8: & \verb?\index{Alf!Bet!Con}? & \verb?\indexentry{Alf!Bet!Con}{8}? \\
27935 p. 9: & \verb?\index{Alf!Dan}? & \verb?\indexentry{Alf!Dan}{9}? \\
27936 \end{tabular}\par
27937 \end{small}
27938 \caption{Raw indexing: (left) index commands in the source text; (right)
27939 \file{idx} file entries}
27940 \end{figure}
27941
27942 \begin{figure}
27943 \centering
27944 \egstart
27945 \begin{lcode}
27946 \begin{theindex}
27947 \item Alf, v, 1-3
27948 \subitem Bet
27949 \subsubitem Con, 8
27950 \subitem Dan, 9
27951 \item \textit{Alf}, 7
27952 \item Alfabet, \see{Bet}{5}
27953 \indexspace
27954 \item Bet, \textbf{7}
27955 \end{theindex}
27956 \end{lcode}
27957 \egmid
27958 Alf, v, 1-3 \\
27959 \hspace*{2em} Bet \\
27960 \hspace*{4em} Con, 8 \\
27961 \hspace*{2em} Dan, 9 \\
27962 \textit{Alf}, 7 \\
27963 Alfabet, \textit{see} Bet \\[0.5\onelineskip]
27964 Bet, \textbf{7}
27965 \egend
27966 \caption{Processed index: (left) alphabeticized \file{ind} file;
27967 (right) typeset index}
27968 \end{figure}
27969
27970 \subsubsection{The \texttt{!} character}
27971
27972 The \texttt{level} specifier starts a new minor level, or subitem,
27973 with a maximum of two sub-levels. The default \texttt{level} specifier
27974 is the special character \texttt{!}\index{"! (ls)?\texttt{"!} (level specifier)}. For example:
27975 \begin{lcode}
27976 \index{item!sub item!sub sub item}
27977 \end{lcode}
27978
27979 \subsubsection{The \texttt{@} character}
27980
27981 An indexable item may be represented in two portions, separated
27982 by the \texttt{actual} specifier, which by default is the
27983 \texttt{@} character\index{@ (as)?\texttt{@} (actual specifier)}.
27984 The portion before the \texttt{@} is used
27985 when \Lmakeindex\ sorts the raw index data, and the portion after
27986 the \texttt{@} is used as the entry text. For example:
27987 \begin{lcode}
27988 \index{MakeIndex@\textit{MakeIndex}}
27989 \end{lcode}
27990 will result in the final index entry of \verb?\textit{MakeIndex}? in the
27991 alphabetic position accorded to \verb?MakeIndex?.
27992 The same treatment can be applied for subitems:
27993 \begin{lcode}
27994 \index{program!MakeIndex@\textit{MakeIndex}!commands}
27995 \end{lcode}
27996
27997 \subsubsection{The \texttt{|} character}
27998
27999 Anything after the \texttt{encap} specifier, which by default
28000 is the \texttt{|} character\index{"| (es)?\texttt{"|} (encap specifier)},
28001 is treated as applying to the page number. In general
28002 \begin{lcode}
28003 \index{...|str}
28004 \end{lcode}
28005 will produce a page number, say n, in the form
28006 \begin{lcode}
28007 \str{n}
28008 \end{lcode}
28009 For example, if you wanted the page number of one particular entry
28010 to be in a bold font, say to indicate that this is where the entry
28011 is defined, you would do
28012 \begin{lcode}
28013 \index{entry|textbf}
28014 \end{lcode}
28015
28016 As a special case, if you want an index item to have a page range
28017 put the two
28018 characters \verb?|(? at the end of the argument on the first page, and
28019 the character pair \verb?|)? at the end of the argument on the last page.
28020 For example:
28021 \begin{lcode}
28022 ... \index{range|(} pages about range \index{range|)} ...
28023 \end{lcode}
28024 The two arguments must match exactly except for the final \verb?(?
28025 and \verb?)?. You can also do
28026 \begin{lcode}
28027 \index{...|(str}
28028 \end{lcode}
28029 which will produce a page range of the form
28030 \begin{lcode}
28031 \str{n-m}
28032 \end{lcode}
28033 In this case, if the range is only a single page, the result is simply
28034 \begin{lcode}
28035 \str{n}
28036 \end{lcode}
28037
28038 \begin{syntax}
28039 \cmd{\see}\marg{text}\marg{page} \cmd{seename} \\
28040 \cmd{\seealso}\marg{text}\marg{page} \cmd{alsoname} \\
28041 \end{syntax}
28042 \glossary(see)%
28043 {\cs{see}}%
28044 {\textit{see} entry in an index using \cs{seename} for the wording.}
28045 \glossary(seename)%
28046 {\cs{seename}}%
28047 {Wording for a \textit{see} index entry.}
28048 \glossary(seealso)%
28049 {\cs{seealso}}%
28050 {\textit{see also} entry in an index using \cs{alsoname} for the wording.}
28051 \glossary(alsoname)%
28052 {\cs{alsoname}}%
28053 {Wording for a \textit{see also} index entry.}
28054 The macros \cmd{\see}\index{index!see reference} and
28055 \cmd{\seealso}\index{index!see also reference} are specifically for use in
28056 an \cmd{\index} command after the \texttt{|}. The \cmd{\see} command
28057 replaces the page number by the phrase `\textit{see} \meta{text}',
28058 while the \cmd{\seealso} command adds `\textit{see also} \meta{text}'
28059 to the entry.
28060 For example, in the source for this manual I have
28061 \begin{lcode}
28062 \index{chapter!style|see{chapterstyle}}
28063 \index{figure|seealso{float}}
28064 \end{lcode}
28065 A \cmd{\see} or \cmd{\seealso}
28066 should be used once only for a particular entry. The `see' texts for
28067 \cmd{\see} and \cmd{\seealso} are stored in \cmd{\seename}
28068 and \cmd{\alsoname}, whose default definitions are:
28069 \begin{lcode}
28070 \newcommand*{\seename}{see}
28071 \newcommand*{alsoname}{see also}
28072 \end{lcode}
28073
28074 \subsubsection{The \texttt{"} and \texttt{\bs} characters}
28075
28076 If, for some reason, you want to index something that includes one
28077 of the \texttt{!}, \texttt{@}, \texttt{|} or \texttt{"} characters there
28078 is the difficulty of persuading \Lmakeindex\ to ignore the special
28079 meaning. This is solved by the \texttt{quote} specifier, which is
28080 normally the \texttt{"} character\index{\"" (qs)?\texttt{""} (quote specifier)}.
28081 The character
28082 immediately after \texttt{"} is treated as non-special. For example,
28083 if you needed to index the \texttt{@} and \texttt{!} characters:
28084 \begin{lcode}
28085 \index{"@ (commercial at)}
28086 \index{"! (exclamation)}
28087 \end{lcode}
28088 The leading \texttt{"} is stripped off before entries are alphabetized.
28089
28090 The \texttt{escape} specifier is used to strip the special meaning
28091 from the \texttt{quote} specifier. This is usually the \texttt{\bs}
28092 character\index{"\ (es)?\texttt{\bs} (escape specifier)}.
28093 So, to index the double quote character itself:
28094 \begin{lcode}
28095 \index{\" (double quote)}
28096 \end{lcode}
28097
28098 \subsubsection{Example of using the special characters}
28099
28100 Here is a short example of indexing the special characters. Given an
28101 input like this in the document
28102 \begin{lcode}
28103 \index{exclamation mark ("!)}
28104 \index{vicious|see{circle}}
28105 \index{atsign@\texttt{"@} sign|\textbf}
28106 \index{quote!double ("")}
28107 \index{circle|see{vicious}}
28108 \end{lcode}
28109 then an index could eventually be produced that looks like:
28110 \begin{quote}
28111 \texttt{@} sign, \textbf{30}\\
28112 circle, \textit{see} vicious\\
28113 exclamation mark (!), 21 \\
28114 quote \\
28115 \hspace*{1.5em} double ("), 47 \\
28116 vicious, \textit{see} circle\\
28117 \end{quote}
28118
28119
28120 %%\index{MakeIndex?\Pmakeindex!raw data|)}
28121 \Iprogsub{MakeIndex}{raw data|)}%
28122
28123 \subsection{Controlling MakeIndex output}
28124
28125 %%\index{MakeIndex?\Pmakeindex!output styling|(}
28126 \Iprogsub{MakeIndex}{output styling|(}%
28127
28128 \tref{tab:configout} lists the parameters that control \Pmakeindex's
28129 output, except for the keywords that control the setting of page numbers.
28130 The special characters and strings are not fixed within the
28131 \Lmakeindex\ program. The program will read an \pixfile{ist} file
28132 in which you can redefine all of \Lmakeindex's defaults.
28133
28134 \begin{table}
28135 \begin{adjustwidth}{-1.5cm}{-1.5cm}
28136 \centering
28137 \caption{\Pmakeindex\ configuration file output parameters} \label{tab:configout}
28138 \begin{tabular}{llp{0.5\textwidth}}\toprule
28139 \multicolumn{1}{c}{Keyword} & \multicolumn{1}{c}{Default} & \multicolumn{1}{c}{Description} \\ \midrule
28140 \kwd{preamble} \kty{s} & \verb?"\\begin{theindex}\n"? &
28141 Text for the start of the output file \\
28142 \kwd{postamble} \kty{s} & \verb?"\n\n\\end{theindex}\n"? &
28143 Text at the end of the output file \\ \midrule
28144 %\kwd{setpage\_prefix} \kty{s} & \verb?"\n\\setcounter{page}{"? &
28145 % Prefix for the command setting the page number \\
28146 %\kwd{setpage\_suffix} \kty{s} & \verb?"}\n"? &
28147 % Suffix for the command setting the page number \\ \midrule
28148 \kwd{group\_skip} \kty{s} & \verb?"\n\n\\indexspace\n"? &
28149 Vertical space before a new letter group \\
28150 \kwd{heading\_prefix} \kty{s} & \verb?""? &
28151 Prefix for heading for a new letter group \\
28152 \kwd{heading\_suffix} \kty{s} & \verb?""? &
28153 Suffix for heading for a new letter group \\
28154 \kwd{headings\_flag} \kty{n} & \verb?0? &
28155 A value $= 0$ inserts nothing between letter groups.
28156 A value $>0$ includes an uppercase instance of the new symbol,
28157 while a value $<0$ includes a lowercase instance, all
28158 within \kwd{heading\_prefix} and \kwd{heading\_suffix} \\ \midrule
28159 \kwd{item\_0} \kty{s} & \verb?"\n\item "? &
28160 Command inserted in front of a level 0 entry \\
28161 \kwd{item\_1} \kty{s} & \verb?"\n \subitem "? &
28162 As above for a level 1 entry \\
28163 \kwd{item\_2} \kty{s} & \verb?"\n \subsubitem "? &
28164 As above for a level 2 entry \\
28165 \kwd{item\_01} \kty{s} & \verb?"\n \subitem "? &
28166 Command inserted in front of a level 1 entry starting at level 0 \\
28167 \kwd{item\_12} \kty{s} & \verb?"\n \subsubitem "? &
28168 Command inserted in front of a level 2 entry starting at level 1 \\
28169 \kwd{item\_x1} \kty{s} & \verb?"\n \subitem "? &
28170 Command inserted in front of a level 1 entry when the parent level
28171 has no page numbers \\
28172 \kwd{item\_x2} \kty{s} & \verb?"\n \subitem "? &
28173 As above for a level 2 entry \\ \midrule
28174 \kwd{delim\_0} \kty{s} & \verb?", "? &
28175 Delimiter between level 0 entry and first page number \\
28176 \kwd{delim\_1} \kty{s} & \verb?", "? &
28177 As above for level 1 entry \\
28178 \kwd{delim\_2} \kty{s} & \verb?", "? &
28179 As above for level 2 entry \\
28180 \kwd{delim\_n} \kty{s} & \verb?", "? &
28181 Delimiter between page numbers \\
28182 \kwd{delim\_r} \kty{s} & \verb?"-"? &
28183 Designator for a page range \\ \midrule
28184 \kwd{encap\_prefix} \kty{s} & \verb?"\\"? &
28185 Prefix in front of a page encapsulator \\
28186 \kwd{encap\_infix} \kty{s} & \verb?"{"? &
28187 Infix for a page encapsulator \\
28188 \kwd{encap\_suffix} \kty{s} & \verb?"}"? &
28189 Suffix for a page encapsulator \\ \midrule
28190 \kwd{page\_precedence} \kty{s} & \verb?"rnaRA"? &
28191 Page number precedence for sorting.
28192 \texttt{r} and \texttt{R} are lower- and uppercase roman;
28193 \texttt{a} and \texttt{A} are lower- and uppercase alphabetic;
28194 \texttt{n} is numeric \\ \midrule
28195 \kwd{line\_max} \kty{n} & \verb?"72"? &
28196 Maximum length of an output line \\
28197 \kwd{indent\_space} \kty{s} & \verb?"\t\t"? &
28198 Indentation commands for wrapped lines \\
28199 \kwd{indent\_length} \kty{n} & \verb?"16"? &
28200 Indentation length for wrapped lines \\
28201 \bottomrule
28202 \multicolumn{3}{c}{\kty{s} of type string, \kty{n} of type number,
28203 \texttt{"\bs n"} and \texttt{"\bs t"} are newline and tab.}
28204 \end{tabular}
28205 \end{adjustwidth}
28206 \end{table}
28207
28208 I have used a file called \file{memman.ist} for configuring
28209 \Lmakeindex\ for this manual. Here it is:
28210 \begin{lcode}
28211 % MakeIndex style file memman.ist
28212
28213 % @ is a valid character in some entries, use ? instead
28214 actual '?'
28215
28216 % output main entry <entry> as: \item \idxmark{<entry>},
28217 item_0 "\n\\item \\idxmark{"
28218 delim_0 "}, "
28219 % not forgetting the subitem case
28220 item_x1 "} \n \\subitem "
28221
28222 % Wrap and uppercase head letters
28223 headings_flag 1
28224 heading_prefix "\\doidxbookmark{"
28225 heading_suffix "}"
28226 \end{lcode}
28227
28228 Many items that I need to index include \texttt{@} as part of their
28229 names, which is one of the special characters.
28230 The \texttt{actual} line says that the character \texttt{?} performs
28231 the same function as the default \texttt{@} (and by implication, \texttt{@}
28232 is not a special character as far as \Lmakeindex\ is concerned).
28233
28234 The \verb?item_0? line says that a main entry in the generated index
28235 starts
28236 \begin{lcode}
28237 \item \idxmark{
28238 \end{lcode}
28239 and the \verb?delim_0? and \verb?item_x1? lines say that the main entry ends
28240 \begin{lcode}
28241 }, % or
28242 }
28243 \subitem
28244 \end{lcode}
28245 Thus, main entries will appear in an \pixfile{ind} file like
28246 \begin{lcode}
28247 \item \idxmark{a main entry}, <list of page numbers>
28248 \item \idxmark{a main entry with no page numbers}
28249 \subitem subitem, <list of page numbers>
28250 \end{lcode}
28251
28252 %%\index{MakeIndex?\Pmakeindex!output styling|)}
28253 \Iprogsub{MakeIndex}{output styling|)}%
28254
28255
28256 Read the \Lmakeindex\ manual~\cite{CHEN88} for full details
28257 on how to get \Lmakeindex\ to do what you want.
28258
28259 \LMnote{2009/06/30}{described \doidxbookmark} The
28260 \verb?\doidxbookmark? that is used to wrap around the letter group
28261 headers, can be used to not only style the group header, but can also
28262 be used to add the headers in the bookmarks list. This can be done
28263 using \LMnote{2025/09/17}{Using \cs{MakeLinkTarget} instead of
28264 \cs{phantomsection}, and moved it}
28265 \begin{lcode}
28266 \newcommand{\doidxbookmark}[1]{{\def\@tempa{Symbols}\def\@tempb{#1}%
28267 \centering\bfseries
28268 \MakeLinkTarget[index]{}%
28269 \ifx\@tempa\@tempb %
28270 Non letters
28271 \pdfbookmark[0]{Non letters}{NonLetters-idx}%
28272 \else
28273 #1%
28274 \pdfbookmark[0]{#1}{#1-idx}%
28275 \fi%
28276 \vskip\onelineskip\par}}
28277 \end{lcode}
28278 By adding suitable labels it is possible to add a representation of
28279 the bookmarks into the margin of the index it self. Drop an email if
28280 interested. Using Expl3 we can do it a bit simpler (remember spaces
28281 are ignored inside Expl3, hence the \verb|~|'s, here they just means
28282 space).
28283 \begin{lcode}
28284 \ExplSyntaxOn
28285 \NewDocumentCommand\doidxbookmark{m}
28286 {{
28287 \centering\bfseries
28288 \MakeLinkTarget[index]{}
28289 \str_if_eq:nnTF{#1}{Symbols}
28290 { Non~letters \pdfbookmark[0]{Non~letters}{NonLetters-idx} }
28291 { #1 \pdfbookmark[0]{#1}{#1-idx} }
28292 \vskip\onelineskip\par
28293 }}
28294 \ExplSyntaxOff
28295 \end{lcode}
28296
28297
28298 \subsection{Indexing and the \Lpack{natbib} package}
28299
28300 The \Lpack{natbib} package~\cite{NATBIB} will make an index
28301 of citations if
28302 \cmd{\citeindextrue} is put in the preamble after the \Lpack{natbib}
28303 package is called for.
28304
28305 \begin{syntax}
28306 \cmd{\citeindexfile} \\
28307 \end{syntax}
28308 \glossary(citeindexfile)%
28309 {\cs{citeindexfile}}%
28310 {File name for the citation index.}
28311 The name of the file for the citation index is stored in the
28312 macro \cmd{\citeindexfile}. This is initially defined as:
28313 \begin{lcode}
28314 \newcommand{\citeindexfile}{\jobname}
28315 \end{lcode}
28316 That is, the citation entries will be written to the default
28317 \pixfile{idx} file.
28318 This may be not what you want so you can change this, for example to:
28319 \begin{lcode}
28320 \renewcommand{\citeindexfile}{names}
28321 \end{lcode}
28322 If you do change \cmd{\citeindexfile} then you have to put
28323 \begin{lcode}
28324 \makeindex[\citeindexfile]
28325 \end{lcode}
28326 \emph{before}
28327 \begin{lcode}
28328 \usepackage[...]{natbib}
28329 \end{lcode}
28330
28331 So, there are effectively two choices, either along the lines of
28332 \begin{lcode}
28333 \renewcommand{\citeindexfile}{authors} % write to authors.idx
28334 \makeindex[\citeindexfile]
28335 \usepackage{natbib}
28336 \citeindextrue
28337 ...
28338 \renewcommand{\indexname}{Index of citations}
28339 \printindex[\citeindexfile]
28340 \end{lcode}
28341 or along the lines of
28342 \begin{lcode}
28343 \usepackage{natbib}
28344 \citeindextrue
28345 \makeindex
28346 ...
28347 \printindex
28348 \end{lcode}
28349
28350 \section{Glossaries}
28351
28352
28353 \begin{recommended}
28354 Have a look at the \Lpack{glossaries-extra} by Nicola Talbot (it is
28355 an extention to \Lpack{glossaries} by the same author). It uses an
28356 external programme (\Lprog{makeglossaries}) to sort and handle the
28357 glossaries.
28358 \end{recommended}
28359
28360
28361 Unlike indexes, \ltx\ provides less than minimal support for
28362 glossaries. It provides a \cmd{\makeglossary} command for initiating a glossary
28363 and a \cmd{\glossary} command which puts its argument, plus the page number,
28364 into a \file{glo} file, and that's it. \Mname, combined with the
28365 \Lmakeindex\ program~\cite{CHEN88}, enables you to generate
28366 and print a glossary in
28367 your document. The commands for creating a glossary are similar to those
28368 for indexes.
28369
28370 \begin{syntax}
28371 \cmd{\makeglossary}\oarg{file} \\
28372 \end{syntax}
28373 \glossary(makeglossary)%
28374 {\cs{makeglossary}\oarg{file}}%
28375 {Opens file \cs{jobname.glo}, or \cs{file.glo}, for glossary entries}%
28376
28377 You have to put \cmd{\makeglossary} in your preamble if you want a glossary.
28378 This opens a file called by default \verb?\jobname.glo?. If you use the
28379 optional \meta{file} argument the file \verb?file.glo? will be opened.
28380 A glossary \file{glo} file is analagous to an index \file{idx} file.
28381
28382 \begin{syntax}
28383 \cmd{\printglossary}\oarg{file} \\
28384 \end{syntax}
28385 \glossary(printglossary)%
28386 {\cs{printglossary}\oarg{file}}%
28387 {Prints the glossary from file \cs{jobname.gls}, or \cs{file.gls}}%
28388 To print a glossary call \cmd{\printglossary} which will print the glossary
28389 from file \verb?\jobname.gls?, or from \verb?file.gls? if the optional
28390 argument is used. A glossary \file{gls} file is analagous to an
28391 index \file{ind} file.
28392
28393 \begin{syntax}
28394 \cmd{\glossary}\oarg{file}\parg{key}\marg{term}\marg{desc} \\
28395 \end{syntax}
28396 \glossary(glossary)%
28397 {\cs{glossary}\oarg{file}\parg{key}\marg{term}\marg{description}}%
28398 {Adds \meta{term} and its description, \meta{desc}, to a glossary file ---
28399 \cs{jobname.glo} by default or to \cs{file.glo}. The optional argument
28400 \meta{key} can be used to provide a different sort key for \meta{term}.}
28401
28402 Use the \cmd{\glossary} command to add a \meta{term} and its description,
28403 \meta{desc},
28404 to a glossary file. By default this will be \verb?\jobname.glo? but if the
28405 optional \meta{file} argument is given then the information will be written
28406 to \verb?file.glo?. The \parg{key} argument is optional. If present then
28407 \meta{key} will be added to the file to act as a sort key for the \meta{term},
28408 otherwise \meta{term} will be used as the sort key.
28409
28410 By using the optional \meta{file} arguments you can have several
28411 glossaries, subject to \tx's limitations on the number of files that can
28412 be open at any one time.
28413
28414 A simple glossary entry might be:
28415 \begin{lcode}
28416 \glossary{glossary}{A list of terms and their descriptions.}
28417 \end{lcode}
28418
28419 The glossary facilites are designed so that the \Lmakeindex\ program
28420 can be used to convert the raw glossary data in a \file{glo} file into
28421 the printable glossary in a \file{gls} file.
28422
28423 \begin{syntax}
28424 \senv{theglossary} entry list \eenv{theglossary} \\
28425 \end{syntax}
28426 \glossary(theglossary)%
28427 {\senv{theglossary}}%
28428 {Environment for typesetting a glossary.}%
28429
28430 Glossary entries are typeset in a \Ie{theglossary} environment. It is assumed
28431 that a \file{gls} file will contain a complete \Ie{theglossary} environment,
28432 from \senv{theglossary} all the way through to \eenv{theglossary}.
28433
28434 \begin{syntax}
28435 \cmd{\glossitem}\marg{term}\marg{desc}\marg{ref}\marg{num} \\
28436 \end{syntax}
28437 \glossary(glossitem)%
28438 {\cs{glossitem}\marg{term}\marg{desc}\marg{ref}\marg{num}}%
28439 {Glossary entry used in a \Pe{theglossary} environment}%
28440
28441 A \cmd{\glossitem} is a glossary entry within a \Ie{theglossary} environment
28442 for a \meta{term} with \meta{description}. The \meta{num} argument is the
28443 page or section where the corresponding \cmd{\glossary} was issued. The
28444 \meta{ref} argument, if not empty, might be the section or page number
28445 corresponding to the \meta{num} page or section number. The default definition
28446 is
28447 \begin{lcode}
28448 \newcommand{\glossitem}[4]{#1 #2 #3 #4}
28449 \end{lcode}
28450 which is not very exciting. You may well prefer to use your own definition.
28451
28452 \subsection{Controlling the glossary}
28453
28454 \subsubsection{Setting up makeindex}
28455
28456 If you just run \Lmakeindex\ on a \file{glo} file you will get lots
28457 of errors; \Lmakeindex\ has to be configured to read a \file{glo}
28458 file and generate a useful \file{gls} file as by default it expects to read
28459 an index \file{idx} file and produce an index \file{ind} file. A configuration
28460 file like an index \file{ist} file will be needed. There is no recommended
28461 extension for such a file but I have come to favour \file{gst}. The
28462 command line for \Lmakeindex\ to create a sorted glossary from the raw
28463 data in a \file{glo} file, say \texttt{fred.glo}, using a configuration
28464 file called, say \texttt{basic.gst}, is
28465 \begin{lcode}
28466 makeindex -s basic.gst -o fred.gls fred.glo
28467 \end{lcode}
28468 For other jobs just change the file names appropriately.
28469
28470 So, what is in a \file{gst} file? The potential contents were described
28471 earlier, but at a minimum you need this:
28472 \begin{lcode}
28473 %%% basic.gst basic makindex glossary style file
28474 %%% Output style parameters
28475 preamble "\\begin{theglossary}"
28476 postamble "\n\\end{theglossary}\n"
28477 item_0 "\n\\glossitem"
28478 delim_0 "{\\memglonum{"
28479 encap_suffix "}}}"
28480 headings_flag 1
28481 heading_prefix "\\doglobookmark{"
28482 heading_suffix "}"
28483 %%% Input style parameters
28484 keyword "\\glossaryentry"
28485 \end{lcode}
28486
28487 The \verb?keyword? line says that each entry in an input (\file{glo}) file
28488 will be of the form:
28489 \begin{lcode}
28490 \glossaryentry{entry text}{number}
28491 \end{lcode}
28492 and by a miracle of coding, this is what \Pclass{memoir} will put in a
28493 \file{glo} file for each \cmd{\glossary} command.
28494
28495 The \verb?preamble? and \verb?postamble? lines tell the program to start
28496 and end its output file with \senv{theglossary} and \eenv{theglossary},
28497 respectively.
28498 The \verb?item_0? tells the program to start each output entry with
28499 \cmd{\glossitem}. The \verb?delim_0? says that \verb?{\memglonum{?
28500 should be put between the end of the entry text and the (page) number. Finally
28501 \verb?encap_suffix? requests \verb?}}}? to be put after any `encapsulated'
28502 (page) number.
28503
28504 A complete listing of the possible entries in a configuration file,
28505 also called a style file, for \Lmakeindex{} is in
28506 tabless~\ref{tab:configin} and~\ref{tab:configout} with the exception
28507 of the output file page number setting keywords.
28508
28509 \LMnote{2009/06/30}{Added bookmarks for letter groups in the glossary}
28510 The \verb?\doglobookmark? macro can be used to add bookmarks for the
28511 letter groups. In the case of this manual we do not write anything,
28512 just add the letters to the glossary entry in the bookmark list. In
28513 \Lpack{memsty} \verb?\doglobookmark? is defined as
28514 \LMnote{2025/09/17}{Replaced \cs{phantomsection}, used \cs{MakeLinkTarget} and moved it}
28515 \begin{lcode}
28516 \newcommand\doglobookmark[1]{%
28517 \def\@tempa{Symbols}\def\@tempb{#1}%
28518 \MakeLinkTarget[glossaries]{}%
28519 \ifx\@tempa\@tempb %
28520 \pdfbookmark[0]{Non letters}{Nonletters-glo}%
28521 \else%
28522 \pdfbookmark[0]{#1}{#1-glo}%
28523 \fi%
28524 }
28525 \end{lcode}
28526 \Lmakeindex\ uses the word 'Symbols' to specify the group that does not
28527 start with a letter.
28528
28529
28530 \subsubsection{Raw input data}
28531
28532 \begin{syntax}
28533 \cmd{\@@wrglom@m}\marg{file}\marg{key}\marg{term}\marg{desc}\marg{ref}\marg{num}\\
28534 \end{syntax}
28535 The \cmd{\glossary} macro writes its arguments to the \file{aux} file
28536 in the form of arguments to the \cmd{\@@wrglom@m} internal macro. In turn
28537 this calls a series of other macros that eventually write the data
28538 to the \meta{file} \file{glo} file
28539 in the format (where \verb+@+ is the actual flag):
28540 \begin{lcode}
28541 \glossaryentry{key@{\memgloterm{term}} {\memglodesc{desc}}{\memgloref{ref}}
28542 |memglonumf}{num}
28543 \end{lcode}
28544 which \Lmakeindex\ then effectively converts into
28545 \begin{lcode}
28546 \glossitem{\memgloterm{term}}{\memglodesc{desc}}{\memgloref{ref}}
28547 {\memglonum{\memglonumf{num}}}
28548 \end{lcode}
28549
28550 \begin{syntax}
28551 \cmd{\memgloterm}\marg{term} \\
28552 \cmd{\memglodesc}\marg{desc} \\
28553 \cmd{\memgloref}\marg{ref} \\
28554 \cmd{\memglonum}\marg{num} \\
28555 \end{syntax}
28556 \glossary(memgloterm)%
28557 {\cs{memgloterm}\marg{term}}%
28558 {Wrapper round a glossary term.}%
28559 \glossary(memglodesc)%
28560 {\cs{memglodesc}\marg{desc}}%
28561 {Wrapper round a glossary description.}%
28562 \glossary(memgloref)%
28563 {\cs{memgloref}\marg{ref}}%
28564 {Wrapper round a glossary ref.}%
28565 \glossary(memglonum)%
28566 {\cs{memglonum}\marg{num}}%
28567 {Wrapper round glossary numbers.}%
28568 These macros can be redefined to format the various parts of a glossary entry.
28569 Their default definitions are simply
28570 \begin{lcode}
28571 \newcommand{\memgloterm}[1]{#1}
28572 \newcommand{\memglodesc}[1]{#1}
28573 \newcommand{\memgloref}[1]{#1}
28574 \newcommand{\memglonum}[1]{#1}
28575 \end{lcode}
28576 For example, if you wanted the term in bold, the description in italics,
28577 and no numbers:
28578 \begin{lcode}
28579 \renewcommand{\memgloterm}[1]{\textbf{#1}}
28580 \renewcommand{\memglodesc}[1]{\textit{#1}}
28581 \renewcommand{\memglonum}[1]{}
28582 \end{lcode}
28583
28584 There are several macros that effect a glossary entry
28585 but which must not be directly modified (the \cs{memglonumf} shown above
28586 as part of the \cmd{\glossaryentry} is one of these).
28587 Each of the following \cs{changegloss...} macros takes an optional \meta{file}
28588 argument. The changes to the underlying macro apply only to the
28589 glossary of that particular \meta{file} (or the \cs{jobname} file
28590 if the argument is not present.
28591 \begin{syntax}
28592 \cmd{\changeglossactual}\oarg{file}\marg{char} \\
28593 \cmd{\changeglossref}\oarg{file}\marg{thecounter} \\
28594 \cmd{\changeglossnum}\oarg{file}\marg{thecounter} \\
28595 \cmd{\changeglossnumformat}\oarg{file}\marg{format} \\
28596 \end{syntax}
28597 \glossary(changeglossactual)%
28598 {\cs{changeglossactual}\oarg{file}\marg{char}}%
28599 {Specifies \meta{char} as the \texttt{actual} character for
28600 glossary \meta{file}.}%
28601 \glossary(changeglossref)%
28602 {\cs{changeglossref}\oarg{file}\marg{thecounter}}%
28603 {Specifies \meta{thecounter} as the \meta{ref} for
28604 glossary \meta{file}.}%
28605 \glossary(changeglossnum)%
28606 {\cs{changeglossnum}\oarg{file}\marg{thecounter}}%
28607 {Specifies \meta{thecounter} as the \meta{num} for
28608 glossary \meta{file}.}%
28609 \glossary(changeglossnumformat)%
28610 {\cs{changeglossnumformat}\oarg{file}\marg{format}}%
28611 {Specifies \meta{format} as the format for \meta{num} for
28612 glossary \meta{file}.}%
28613
28614 \cmd{\changeglossactual} sets \meta{char} as the \texttt{actual} character
28615 for the \meta{file} glossary. It is initially \verb+@+. This must match
28616 with the \texttt{actual} specified for the \file{gst} file that will
28617 be applied.
28618
28619 \cmd{\changeglossref} specifies that \meta{thecounter} should be used
28620 to generate the \meta{ref} for the \meta{file} glossary. It is
28621 initially nothing.
28622
28623 \cmd{\changeglossnum} specifies that \meta{thecounter} should be used
28624 to generate the \meta{num} for the \meta{file} glossary. It is
28625 initially \cs{thepage}.
28626
28627 \cmd{\changeglossnumformat} specifies that \meta{format} should be used
28628 to format the \meta{num} for the \meta{file} glossary. The format
28629 of \meta{format} is \verb?|form?, where \verb?|? is the \texttt{encap}
28630 character specified in the \file{gst} file, and \verb?form? is a
28631 formatting command, taking one argument (the number), without any backslash.
28632 For example
28633 \begin{lcode}
28634 \changeglossnumformat{|textbf}
28635 \end{lcode}
28636 to get bold numbers. It is
28637 initially set as \verb?|memjustarg?, where this is defined as:
28638 \begin{lcode}
28639 \newcommand{\memjustarg}[1]{#1}
28640 \end{lcode}
28641 There must be a format defined for the \meta{num} otherwise the arguments
28642 to \cmd{\glossitem} will not be set correctly.
28643
28644
28645 The \cmd{\makeglossary} command uses the \cs{change...}
28646 commands to define the initial versions, so only use the \cs{change...}
28647 macros \emph{after} \cmd{\makeglossary}.
28648 In this document an early version of the glossary was set up by
28649 \begin{lcode}
28650 \makeglossary
28651 \changeglossactual{?}
28652 \makeatletter
28653 \changeglossnum{\@currentlabel}
28654 \makeatother
28655 \changeglossnum{\thepage}
28656 \end{lcode}
28657 The first call of \cmd{\changeglossnum} makes the number the current
28658 numbered chapter, or numbered section, or numbered \ldots. I didn't
28659 like that when I tried it, so the second call resets the number to
28660 the page number.
28661
28662 \subsubsection{The listing}
28663
28664 The final glossary data in the \file{gls} file is typeset in the
28665 \Ie{theglossary} environment, which is much like the \Ie{theindex}
28666 and \Ie{thebibliography} environments.
28667
28668 The environment starts off with a chapter-style unnumbered title.
28669 There are several macros for specifying what happens after that.
28670
28671 \begin{syntax}
28672 \cmd{\glossaryname} \\
28673 \cmd{\glossarymark} \\
28674 \cmd{\glossaryintoc} \cmd{\noglossaryintoc} \\
28675 \end{syntax}
28676 \glossary(glossaryname)%
28677 {\cs{glossaryname}}%
28678 {Name for a glossary.}%
28679 \glossary(glossarymark)%
28680 {\cs{glossarymark}}%
28681 {Redefine to specify marks for headers.}%
28682 \glossary(glossaryintoc)%
28683 {\cs{glossaryintoc}}%
28684 {Declaration to add glossary title to the ToC.}%
28685 \glossary(noglossaryintoc)%
28686 {\cs{noglossaryintoc}}%
28687 {Declaration to prohibit adding glossary title to the ToC.}%
28688
28689 The title for the glossary is \cmd{\glossaryname} whose initial definition
28690 is
28691 \begin{lcode}
28692 \newcommand*{\glossaryname}{Glossary}
28693 \end{lcode}
28694 \cmd{\glossarymark}, which by default does nothing, can be redefined to
28695 set marks for headers. The glossary title will be added to the ToC
28696 if the \cmd{\glossaryintoc} declaration is in force, but will not be
28697 added to the ToC following the \cmd{\noglossaryintoc}.
28698
28699 \begin{syntax}
28700 \cmd{\preglossaryhook} \\
28701 \end{syntax}
28702 \glossary(preglossaryhook)%
28703 {\cs{preglossaryhook}}%
28704 {Vacuous macro called after a glossary title is typeset.}
28705 The macro \cmd{\preglossaryhook} is called after the glossary title
28706 has been typeset. By default it does nothing, but you could redefine
28707 it to, for example, add some explanatory material before the entries
28708 start.
28709
28710 \begin{syntax}
28711 \cmd{\onecolglossary} \cmd{\twocolglossary} \\
28712 \lnc{\glossarycolsep} \lnc{\glossaryrule} \\
28713 \end{syntax}
28714 \glossary(onecolglossary)%
28715 {\cs{onecolglossary}}%
28716 {Declaration for a single column glossary.}%
28717 \glossary(onecolglossaryfalse)%
28718 {\cs{twocolglossary}}%
28719 {Declaration for a two column glossary.}%
28720 \glossary(glossarycolsep)%
28721 {\cs{glossarycolsep}}%
28722 {Columns separation in a two column glossary.}%
28723 \glossary(glossaryrule)%
28724 {\cs{glossaryrule}}%
28725 {Width of inter-column rule in a two column glossary.}%
28726
28727 The glossary can be typeset in two columns (\cmd{\twocolglossary})
28728 but by default (\cmd{\onecolglossary}) it is set in one column.
28729 When two columns are used, the length \lnc{\glossarycolsep} is the
28730 distance between the columns and the length \lnc{\glossaryrule} is
28731 the width (default 0) of a vertical rule between the columns.
28732
28733 \begin{syntax}
28734 \cmd{\begintheglossaryhook} \\
28735 \cmd{\atendtheglossaryhook} \\
28736 \end{syntax}
28737 \glossary(begintheglossaryhook)%
28738 {\cs{begintheglossaryhook}}%
28739 {Vacuous macro called as the last thing by \senv{theglossary}.}
28740 \glossary(atendtheglossaryhook)%
28741 {\cs{atendtheglossaryhook}}%
28742 {Vacuous macro called as the first thing by \eenv{theglossary}.}
28743
28744 The last thing that \senv{theglossary} does is call
28745 \cmd{\begintheglossaryhook}. Similarly, the first thing that is done at
28746 the end of the environment is to call \cmd{\atendtheglossaryhook}.
28747 By default these macros do nothing but you can redefine them.
28748
28749 For example, if you wanted the glossary in the form of a description
28750 list, the following will do that.
28751 \begin{lcode}
28752 \renewcommand*{\begintheglossaryhook}{\begin{description}}
28753 \renewcommand*{\atendtheglossaryhook}{\end{description}}
28754 \renewcommand{\glossitem}[4]{\item[#1:] #2 #3 #4}
28755 \end{lcode}
28756
28757 \subsubsection{The glossary for this document}
28758
28759 The following is the code I have used to produce the glossary
28760 in this document.
28761
28762 This is the code in the \file{sty} file that I used.
28763 \begin{lcode}
28764 \makeglossary
28765 \changeglossactual{?}
28766 \changeglossnum{\thepage}
28767 \changeglossnumformat{|hyperpage}%% for hyperlinks
28768 \renewcommand*{\glossaryname}{Command summary}
28769 \renewcommand*{\glossarymark}{\markboth{\glossaryname}{\glossaryname}}
28770 \renewcommand{\glossitem}[4]{%
28771 \sbox\@tempboxa{#1 \space #2 #3 \makebox[2em]{#4}}%
28772 \par\hangindent 2em
28773 \ifdim\wd\@tempboxa<0.8\linewidth
28774 #1 \space #2 #3 \dotfill \makebox[2em][r]{#4}\relax
28775 \else
28776 #1 \dotfill \makebox[2em][r]{#4}\\
28777 #2 #3
28778 \fi}
28779 \end{lcode}
28780
28781 The redefinition of \cmd{\glossitem} works as follows (it is similar
28782 to code used in the setting of a \cmd{\caption}):
28783 \begin{enumerate}
28784 \item Put the whole entry into a temporary box.
28785 \item Set up a hanging paragraph with 2em indentation after the first line.
28786 \item Check if the length of the entry is less than 80\% of the linewidth.
28787 \item For a short entry set the name, description, and any reference then
28788 fill the remainder of the line with dots with the number at the right
28789 margin.
28790 \item For a longer entry, set the title and number on a line, separated
28791 by a line of dots, then set the description (and reference) on
28792 the following lines.
28793 \end{enumerate}
28794
28795 The \file{gst} file I have used for this document has a few more items
28796 than the basic one.
28797 \begin{lcode}
28798 %%% memman.gst makindex glossary style file for memman and friends
28799 %%% Output style parameters
28800 preamble "\\begin{theglossary}"
28801 postamble "\n\\end{theglossary}\n"
28802 group_skip "\n\\glossaryspace\n"
28803 item_0 "\n\\glossitem"
28804 delim_0 "{\\memglonum{"
28805 encap_suffix "}}}"
28806 indent_space "\t"
28807 indent_length 2
28808 %%% Input style parameters
28809 keyword "\\glossaryentry"
28810 actual '?'
28811 page_compositor "."
28812 \end{lcode}
28813
28814 The \verb?group_skip? line asks that \verb?\glossaryspace? be put between the
28815 last entry for one letter and the first for the next letter.
28816 The \verb?indent_space? and \verb?indent_length? give a smaller indent for
28817 continuation lines in the output than the default.
28818
28819 The \verb?actual? entry says that the input file will use \verb+?+ instead
28820 of the default \verb+@+ as the flag for separating a key from the start of
28821 the real entry. The \verb?page_compositor? indicates that any compound numbers
28822 will be like \verb?1.2.3? instead of the default \verb?1-2-3?.
28823
28824 In the document the raw data is collected by the \cmd{\glossary} commands
28825 in the body of the text. For instance, although I have not actually used
28826 the first two:
28827 \begin{lcode}
28828 \glossary(cs)%
28829 {\cs{cs}\marg{name}}%
28830 {Typesets \texttt{name} as a macro name with preceding backslash,
28831 e.g., \cs{name}.}%
28832 \glossary(gmarg)%
28833 {\cs{gmarg}\marg{arg}}%
28834 {Typesets \texttt{arg} as a required argument, e.g., \marg{arg}.}
28835 \glossary(glossaryname)%
28836 {\cs{glossaryname}}%
28837 {Name for a glossary}%
28838 \glossary(memgloterm)%
28839 {\cs{memgloterm}\marg{term}}%
28840 {Wrapper round a glossary term.}%
28841 \end{lcode}
28842
28843 Any change to the glossary entries will be reflected in the
28844 \file{glo} produced from that LaTeX run. \Lmakeindex\ has to be run
28845 the \file{glo} file using the appropriate \file{gst} configuration file,
28846 and then LaTeX run again to get the corrected, sorted and formatted result
28847 printed by \cmd{\printglossary}.
28848
28849 In particular, for this document, which also includes an index so that
28850 can be processed when the glossary is processed.
28851 \begin{lcode}
28852 pdflatex memman
28853 makeindex -s memman.gst -o memman.gls memman.glo
28854 makeindex -s memman.ist memman %%% for the index
28855 makeindex lines %%% for the index of first lines
28856 pdflatex memman
28857 \end{lcode}
28858
28859
28860 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
28861
28862 \LMnote{2013/05/02}{Section about endnotes moved page-notes.tex}
28863
28864
28865
28866 %#% extend
28867 %#% extstart include miscellaneous.tex
28868
28869 \svnidlong
28870 {$Ignore: $}
28871 {$LastChangedDate: 2025-10-21 17:01:03 +0200 (Tue, 21 Oct 2025) $}
28872 {$LastChangedRevision: 886 $}
28873 {$LastChangedBy: [email protected] $}
28874
28875 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
28876 %\clearpage
28877 %\pagestyle{Ruled}
28878 %%\chapterstyle{demo}
28879 %\chapterstyle{veelo}
28880 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
28881
28882 \chapter{Miscellaneous} \label{chap:misc}
28883
28884 \setlength{\prechapterprecisshift}{-\onelineskip}
28885
28886 \chapterprecis{In which we talk of many things, but not shoes
28887 or ships or sealing wax, nor cabbages and kings.}
28888
28889 \noindent This chapter started with the \cmd{\chapterprecis} command to add
28890 the above text, which is also added to the \prtoc.
28891
28892 The class provides a miscellany of minor facilities, which are described
28893 here.
28894
28895 \section{Draft documents}
28896
28897 The \Lopt{draft} option marks any overfull lines with black rectangles,
28898 otherwise the appearance is the same as for a \Lopt{final} document.
28899
28900 \begin{syntax}
28901 \piif{ifdraftdoc} \\
28902 \end{syntax}
28903 \glossary(ifdraftdoc)%
28904 {\cs{ifdraftdoc}}%
28905 {\ptrue\ if the \Popt{draft} class option has been used.}
28906 The \piif{ifdraftdoc} macro is provided so that you can add extra
28907 things that you might want to happen when processing a draft; for example
28908 you might want to have each page header\index{header} (or footer\index{footer}) include the word `DRAFT'.
28909 The code to do this can be put into a construct like the following:
28910 \begin{lcode}
28911 \ifdraftdoc
28912 % special things for a draft document
28913 \else
28914 % perhaps special things for a non-draft document
28915 \fi
28916 \end{lcode}
28917
28918
28919 \section{Change marks}
28920
28921 When preparing a manuscript it normally goes through several iterations.
28922 The macros described in this section can be used to identify changes made to
28923 a document throughout its lifecycle.
28924
28925 The commands below implement a simplified version of the change
28926 marking in the \Lclass{iso} class~\cite{ISOCLASS}.
28927
28928 \begin{syntax}
28929 \cmd{\changemarks} \cmd{\nochangemarks} \\
28930 \end{syntax}
28931 \glossary(changemarks)%
28932 {\cs{changemarks}}%
28933 {Print change marks.}
28934 \glossary(nochangemarks)%
28935 {\cs{nochangemarks}}%
28936 {Do not print change marks.}
28937 The change marking macros only work properly when the \Lopt{draft} class
28938 option is used. Additionally, the marks are only printed when the
28939 \cmd{\changemarks} declaration is in effect. Using \cmd{\nochangemarks}
28940 switches off any marking.
28941
28942 \begin{syntax}
28943 \cmd{\added}\marg{change-id} \\
28944 \cmd{\deleted}\marg{change-id} \\
28945 \cmd{\changed}\marg{change-id} \\
28946 \end{syntax}
28947 \glossary(added)%
28948 {\cs{added}\marg{change-id}}%
28949 {Change mark for someting added; \meta{change-id} is put in the margin.}
28950 \glossary(deleted)%
28951 {\cs{deleted}\marg{change-id}}%
28952 {Change mark for someting deleted; \meta{change-id} is put in the margin.}
28953 \glossary(changed)%
28954 {\cs{changed}\marg{change-id}}%
28955 {Change mark for someting changed; \meta{change-id} is put in the margin.}
28956 Each of these macros puts a symbol and \meta{change-id} into the
28957 margin\index{margin} near
28958 where the command is given. The \cmd{\added} macro indicates that something
28959 has been added to the manuscript and uses $\oplus$ as its symbol. The
28960 \cmd{\deleted} macro is for indicating that something has been deleted and uses
28961 the $\neq$ symbol. The macro \cmd{\changed} uses the $\Leftrightarrow$ symbol
28962 to indicate that something has been changed.
28963
28964 These marking commands should be attached to some word or punctuation
28965 mark in the text otherwise extraneous spaces may creep into the typeset
28966 document.
28967
28968 \section{Trim marks}
28969
28970 When the class \Lopt{showtrims} option is used, trim
28971 marks can be placed on each page, usually to indicate where the stock should
28972 be trimmed to obtain the planned page size.
28973
28974 \begin{syntax}
28975 \cmd{\showtrimsoff} \cmd{\showtrimson} \\
28976 \end{syntax}
28977 \glossary(showtrimsoff)%
28978 {\cs{showtrimsoff}}%
28979 {Switch off any trim marks.}
28980 \glossary(showtrimson)%
28981 {\cs{showtrimson}}%
28982 {If the \Popt{showtrims} option has been used, switch on any trim marks
28983 (this is the default).}
28984 If the \Lopt{showtrims} class option has been used then the \cmd{\showtrimsoff}
28985 declaration switches off the trim marks; the \cmd{\showtrimson} declaration,
28986 which is the default, switches on the trim marks. These declarations do
28987 nothing if the \Lopt{showtrims} option has not been used.
28988
28989
28990 \begin{Changed}
28991 From the \LaTeX\ format dated 2020/10/01 we changed the way
28992 trimmarks are added to the pages. It will now go through the
28993 »\texttt{shipout/background}« hook instead of changing the
28994 \cmd{\shipout} routine directly. This also have the advantage that
28995 the hooks can be reordered if say you want something to be added to
28996 \texttt{shipout/background} \emph{before} the trimmarks are added.
28997 For more details about the hooks see \cite{LTHOOKS,LTSHIPOUT}.
28998
28999 The trimmarks will have the hook label »\texttt{memoir/trimmarks}«.
29000 \end{Changed}
29001
29002
29003 \LMnote{2013/05/01}{added caveat}
29004 \begin{caveat}
29005 Most modern \LaTeX\ editors make use of the \emph{synctex} features
29006 in, say, pdf\LaTeX\ to enable \emph{reverse search} from the PDF
29007 previewer back to the source code in the editor. That is, click in a
29008 certain manner in the PDF previewer and you will be taken to the
29009 corresponding (or there about) line in the source code.
29010
29011 Apparently the \emph{synctex} feature does not like the trimmarks
29012 the class provide, or the \pstyle{showlocs} page style. The code
29013 line one is referred back to may be off by tens of lines.
29014
29015 Currently, there is no known workarounds for this deficiency.
29016
29017 NB: We have yet to see if the 2020/10/01 format update and change to
29018 the trimmarks implementation will fix this issue.
29019
29020 \end{caveat}
29021
29022
29023
29024
29025
29026
29027 Trim marks can be placed at each corner of the (trimmed) page, and also
29028 at the middle of each side of the page.
29029
29030 \begin{syntax}
29031 \cmd{\trimXmarks} \\
29032 \cmd{\trimLmarks} \\
29033 \cmd{\trimFrame} \\
29034 \cmd{\trimNone} \\
29035 \cmd{\trimmarkscolor} \\
29036 \end{syntax}
29037 \glossary(trimXmarks)%
29038 {\cs{trimXmarks}}%
29039 {Trim marks of crosses at the four corners of the trimmed page.}
29040 \glossary(trimLmarks)%
29041 {\cs{trimLmarks}}%
29042 {Trim marks of `L' shapes at the four corners of the trimmed page.}
29043 \glossary(trimFrame)%
29044 {\cs{trimFrame}}%
29045 {Trim mark of a frame drawn round the trimmed page boundary.}
29046 \glossary(trimNone)%
29047 {\cs{trimNone}}%
29048 {No trim marks.}
29049 \glossary(trimmarkscolor)%
29050 {\cs{trimmarkscolor}}%
29051 {Empty macro that can be redefined to give a specific color to the trimmarks.}
29052
29053 Some predefined trimming styles are provided. After the declaration
29054 \cmd{\trimXmarks} marks in the shape of a cross are placed at the four
29055 corners of the page. The declaration \cmd{\trimLmarks} calls for corner marks
29056 in the shape of an `L', in various orientations depending on the particular
29057 corner. After \cmd{\trimFrame} a frame will be drawn around each page,
29058 coinciding with the page boundaries. The declaration \cmd{\trimNone}
29059 disables all kinds of trim marking. All three plus \cs{quarkmarks}
29060 (described below) is visibly shown on \fref{fig:trimmarks}.
29061
29062 The macro \cs{trimmarkscolor} is despite its name a normal (empty)
29063 macro. By redefining it one can change the color of the trimmarks,
29064 handy for example if the document has a dark background color. To make
29065 them blue use
29066 \begin{lcode}
29067 \newcommand*{\trimmarkscolor}{\color{blue}}
29068 \end{lcode}
29069
29070
29071 \begin{syntax}
29072 \cmd{\trimmarks} \\
29073 \cmd{\tmarktl} \cmd{\tmarktr} \cmd{\tmarkbr} \cmd{\tmarkbl} \\
29074 \cmd{\tmarktm} \cmd{\tmarkmr} \cmd{\tmarkbm} \cmd{\tmarkml} \\
29075 \end{syntax}
29076 \glossary(trimmarks)%
29077 {\cs{trimmarks}}%
29078 {Displays 8 (in)visible trim marks round the boundary of the trimmed page.}
29079 \glossary(tmarktl)%
29080 {\cs{tmarktl}}%
29081 {Trim mark for top left of trimmed page.}
29082 \glossary(tmarktm)%
29083 {\cs{tmarktm}}%
29084 {Trim mark for top middle of trimmed page.}
29085 \glossary(tmarktr)%
29086 {\cs{tmarktr}}%
29087 {Trim mark for top right of trimmed page.}
29088 \glossary(tmarkmr)%
29089 {\cs{tmarkmr}}%
29090 {Trim mark for middle right of trimmed page.}
29091 \glossary(tmarkbr)%
29092 {\cs{tmarkbr}}%
29093 {Trim mark for bottom right of trimmed page.}
29094 \glossary(tmarkbm)%
29095 {\cs{tmarkbm}}%
29096 {Trim mark for bottom middle of trimmed page.}
29097 \glossary(tmarkbl)%
29098 {\cs{tmarkbl}}%
29099 {Trim mark for bottom left of trimmed page.}
29100 \glossary(tmarkml)%
29101 {\cs{tmarkml}}%
29102 {Trim mark for middle left of trimmed page.}
29103 \glossary(tmarktl)%
29104 {\cs{tmarktl}}%
29105 {Trim mark for top left of trimmed page.}
29106 The \cmd{\trimmarks} macro is responsible for displaying up to 8 marks. The
29107 marks are defined as zero-sized pictures which are placed strategically
29108 around the borders of the page.
29109
29110 The command \cmd{\trimmarks} places the pictures \cmd{\tmarktl},
29111 \cmd{\tmarktr},
29112 \cmd{\tmarkbl}, and \cmd{\tmarkbr} at the top left, top right,
29113 bottom right and bottom left corners of the page. The pictures
29114 \cmd{\tmarktm}, \cmd{\tmarkmr}, \cmd{\tmarkbm}, and \cmd{\tmarkml} are placed
29115 at the top middle, middle right, bottom middle and middle left of the
29116 edges of the page. All these \verb?\tmark..? macros should expand to zero-sized
29117 pictures.
29118
29119 \begin{syntax}
29120 \cmd{\trimmark} \\
29121 \end{syntax}
29122 \glossary(trimmark)%
29123 {\cs{trimmark}}%
29124 {Cross mark used by \cs{trimXmarks}.}
29125 The declaration \cmd{\trimXmarks} uses \cmd{\trimmark} for the corner
29126 crosses. This is defined as
29127 \begin{lcode}
29128 \newcommand{\trimmark}{%
29129 \begin{picture}(0,0)
29130 \setlength{\unitlength}{1cm}\thicklines
29131 \put(-2,0){\line(1,0){4}}
29132 \put(0,-2){\line(0,1){4}}
29133 \end{picture}}
29134 \end{lcode}
29135 which produces a zero-sized picture of a 4cm cross. Then \cmd{\trimXmarks}
29136 is defined as:
29137 \begin{lcode}
29138 \newcommand*{\trimXmarks}{%
29139 \let\tmarktl\trimmark
29140 \let\tmarktr\trimmark
29141 \let\tmarkbr\trimmark
29142 \let\tmarkbl\trimmark}
29143 \end{lcode}
29144
29145
29146 As an example, to draw short lines marking the half-height of the page,
29147 try this:
29148 \begin{lcode}
29149 \renewcommand*{\tmarkml}{%
29150 \begin{picture}(0,0)%
29151 \unitlength 1mm
29152 \thinlines
29153 \put(-2,0){\line(-1,0){10}}
29154 \end{picture}}
29155 \renewcommand*{\tmarkmr}{%
29156 \begin{picture}(0,0)%
29157 \unitlength 1mm
29158 \thinlines
29159 \put(2,0){\line(1,0){10}}
29160 \end{picture}}
29161 \end{lcode}
29162 Thin horizontal lines of length 10mm will be drawn at the middle left and
29163 middle right of the page, starting 2mm outside the page boundary. This
29164 is what we do (now) by default for all four middle parts.
29165
29166
29167 \begin{syntax}
29168 \cmd{\quarkmarks} \\
29169 \cmd{\registrationColour}\marg{mark} \\
29170 \end{syntax}
29171 \glossary(quarkmarks)%
29172 {\cs{quarkmarks}}%
29173 {Trim marks in the style of Quark Xpress registration marks, typeset with
29174 \cs{registrationColour}.}
29175 \glossary(registrationColour)%
29176 {\cs{registrationColour}\marg{mark}}%
29177 {Typesets \cs{quarkmarks}.}
29178 Following the declaration \cmd{\quarkmarks} and trim marks will be in
29179 the style of Quark Xpress registration marks.\footnote{The code for this
29180 was donated by William Adams\index{Adams, William}.} The marks will be
29181 typeset using \cmd{\registrationColour}. The default definition is simply
29182 \begin{lcode}
29183 \newcommand*{\RegistrationColour}[1]{#1}
29184 \end{lcode}
29185 but you can change that to, say, print the marks in particular
29186 color. See \fref{fig:trimmarks}.
29187
29188 \fancybreak{}
29189
29190 Say you've added something into the background and want the trim marks
29191 to come out on top. Then, assuming you added to the background via the
29192 \texttt{shipout/background} hook, say
29193 \begin{lcode}
29194 \AddToHook{shipout/background}[bg]{
29195 \put(0,-\stockheight){\color{gray}\rule{\stockwidth}{\stockheight}}
29196 }
29197 \end{lcode}
29198 then you can execute run \texttt{bg} before \texttt{memoir/trimmarks}
29199 via
29200 \begin{lcode}
29201 \DeclareHookRule{shipout/background}{bg}{before}{memoir/trimmarks}
29202 \end{lcode}
29203
29204
29205
29206
29207
29208 \begin{figure}[htbp]
29209 \centering
29210 \ifpdf%
29211 \subbottom[\cs{trimXmarks}
29212 (default)]{\includegraphics[page=1,scale=0.5]{trims-example}}
29213 \qquad\qquad
29214 \subbottom[\cs{trimLmarks}]{\includegraphics[page=2,scale=0.5]{trims-example}}
29215 \\%
29216 \subbottom[\cs{trimFrame}]{\includegraphics[page=3,scale=0.5]{trims-example}}
29217 \qquad\qquad
29218 \subbottom[\cs{quarkmarks}]{\includegraphics[page=4,scale=0.5]{trims-example}}
29219 \else%
29220 \texttt{examples only inserted in pdf-mode, now we can write and
29221 work in DVI-mode, /daleif}
29222 \fi%
29223 \caption{The four trimmark types}
29224 \label{fig:trimmarks}
29225 \end{figure}
29226
29227
29228
29229
29230
29231 \section{Sheet numbering}
29232
29233 One purpose of trim marks is to show a printer where the stock
29234 should be trimmed. In this application it can be useful to also note the
29235 sheet number on each page, where the sheet number is 1 for the first page
29236 and increases by 1 for each page thereafter. The sheet number is independent
29237 of the page number.
29238
29239 \begin{syntax}
29240 \Icn{sheetsequence} \\
29241 \cmd{\thesheetsequence} \\
29242 \end{syntax}
29243 \glossary(sheetsequence)%
29244 {\Pcn{sheetsequence}}%
29245 {Counter for sheets (similar to \Pcn{page} for pages).}
29246 \glossary(thesheetsequence)%
29247 {\cs{thesheetsequence}}%
29248 {Typesets the current sheet sequence number.}
29249 The macro \cmd{\thesheetsequence} typesets the current sheet sequence number
29250 and is analogous to the \cmd{\thepage} macro.
29251
29252 \begin{syntax}
29253 \Icn{lastsheet} \\
29254 \Icn{lastpage} \\
29255 \end{syntax}
29256 \glossary(lastsheet)%
29257 {\Pcn{lastsheet}}%
29258 {Counter holding the number of sheets processed during the \emph{previous}
29259 \ltx\ run.}
29260 \glossary(lastpage)%
29261 {\Pcn{lastpage}}%
29262 {Counter holding the number of the last page processed during the \emph{previous}
29263 \ltx\ run.}
29264 The counter \Icn{lastsheet} holds the number of sheets processed during
29265 the \emph{previous} run of LaTeX. Similarly, the counter \Icn{lastpage}
29266 holds the number of the last page processed during the previous run.
29267 Note that the last page number is not necessarily the same as the last
29268 sheet number. For example: \\
29269 \textit{In this document this is
29270 sheet \thesheetsequence\ of \thelastsheet\ sheets,
29271 and page \thepage\ of \thelastpage.}
29272
29273 The previous sentence was the result of processing the following
29274 code
29275 \begin{lcode}
29276 \textit{In this document this is
29277 sheet \thesheetsequence\ of \thelastsheet\ sheets,
29278 and page \thepage\ of \thelastpage.}
29279 \end{lcode}
29280
29281 You may wish to use the sheet and/or page numbers as part of some
29282 trim marks. The following will note the sheet numbers above the page.
29283 \begin{lcode}
29284 \newcommand*{\trimseqpage}{%
29285 \begin{picture}(0,0)
29286 \unitlength 1mm
29287 \put(0,2){\makebox(0,0)[b]{Sheet: \thesheetsequence\ of \thelastsheet}}
29288 \end{picture}}
29289 \let\tmarktm\trimseqpage
29290 \end{lcode}
29291
29292 \section{Gatherings or signatures}
29293
29294 Sometimes publishers request that they be supplied with a total number of
29295 pages that meet their planned \emph{gatherings}\index{gathering}.\footnote{There
29296 was a thread on \ctt, \textit{pagenumber mod 4?} about this in 2008.}
29297 For instance
29298 a gathering may consist of 8 leaves, and as there are two pages to a leaf this
29299 is equivalent to 16 pages. To meet this particular requirement there must be
29300 a total of $8N$ leaves, or equivalently $16N$ pages, where $N$ will be
29301 the number of gatherings.
29302
29303 \begin{syntax}
29304 \cmd{\leavespergathering}\marg{num} \\
29305 \end{syntax}
29306 \glossary(leavespergathering)%
29307 {\cs{leavespergathering}\marg{num}}%
29308 {Ensure that the correct number of pages are output to make up gatherings
29309 of \meta{num} leaves each.}
29310 The command \cmd{\leavespergathering} ensures that there will be exactly the
29311 right number of pages output to make a complete set of gatherings of \meta{num}
29312 leaves (2\meta{num} pages) each --- if necessary blank pages will be output
29313 at the end to make up the correct tally. If \meta{num} is less than two (the default)
29314 then no additional pages will be output.
29315
29316
29317 \section{Time}
29318
29319 \begin{syntax}
29320 \cmd{\printtime} \cmd{\printtime*} \\
29321 \cmd{\hmpunct} \cmd{\amname} \cmd{\pmname} \\
29322 \end{syntax}
29323 \glossary(printtime)%
29324 {\cs{printtime}}%
29325 {Prints the time of day using a 24 hour clock.}
29326 \glossary(printtime*)%
29327 {\cs{printtime*}}%
29328 {Prints the time of day using a 12 hour clock.}
29329 \glossary(hmpunct)%
29330 {\cs{hmpunct}}%
29331 {Punctuation between hours and minutes in \cs{printtime} (default :)}
29332 \glossary(amname)%
29333 {\cs{amname}}%
29334 {Abbreviation for ante meridiem used in \cs{printtime*} (default am)}
29335 \glossary(pmname)%
29336 {\cs{pmname}}%
29337 {Abbreviation for post meridiem used in \cs{printtime*} (default am)}
29338
29339 The \cmd{\printtime} command\footnote{I based the code on a similar macro
29340 in \btitle{\tx\ for the Impatient}~\cite{IMPATIENT}.}
29341 prints the time of day when the document is
29342 processed using the 24 hour clock while \cmd{\printtime*} uses a 12
29343 hour clock. For example, the effect of the
29344 next piece of code is shown below.
29345 \begin{lcode}
29346 This document was processed on: \today\ at \printtime\ (\printtime*).
29347 \end{lcode}
29348 This document was processed on: \today\ at \printtime\ (\printtime*).
29349
29350 The punctuation between the hours and minutes is \cmd{\hmpunct} which
29351 defaults to a colon (:). The macros \cmd{\amname} and \cmd{\pmnane} hold
29352 the abbreviations for \textit{ante meridiem} and \textit{post meridiem},
29353 respecitively; the defaults are `\amname' and `\pmname'.
29354
29355 According to the \btitle{Chicago Manual of Style}~\cite{CMS} there
29356 should be no punctuation between the hours and minutes in the 24 hour system.
29357 For the 12 hour system it recommends that small caps be used for the
29358 divisions of the day (e.g., \textsc{a.m.} and \textsc{p.m.}) and also
29359 that the American practice is to use a colon as the separator between
29360 hours and minutes whereas the English practice is to use a period (known
29361 to the English as a `full stop'). I don't know what the traditions are
29362 in other orthographies.
29363
29364 The \cmd{\quarkmarks} declaration uses \cmd{\printtime}, so be careful
29365 if you change it.
29366
29367
29368 \begin{recommended}
29369 Nicola Talbot's \Lpack{datetime2} package~\cite{DATETIME2} provides
29370 a much more comprehensive collection of styles for printing the time;
29371 also for dates.
29372 \end{recommended}
29373
29374 \section{Page breaks before lists}
29375
29376 A sentence or two may be used to introduce a list (e.g., \Ie{itemize})
29377 and it can be annoying if there is a page break between the introductory words
29378 and the first item.
29379 \begin{syntax}
29380 \cmd{\noprelistbreak} \\
29381 \end{syntax}
29382 \glossary(noprelistbreak)%
29383 {\cs{noprelistbreak}}%
29384 {Putting this immediately before an \Pe{itemize} (or \Pe{enumerate}, or \ldots)
29385 environment should prevent a pagebreak.}
29386
29387 Putting \cmd{\noprelistbreak} immediately before the \verb?\begin{itemize}?
29388 should prevent a page break. Ideally, there should be no blank lines
29389 between the end of the introduction and the start of the list.
29390
29391 \section{Changing counters}
29392
29393 This is effectively a bundling of the \Lpack{chngcntr}
29394 package~\cite{CHNGCNTR}.
29395
29396 \begin{syntax}
29397 \cmd{\newcounter}\marg{ctr}\oarg{within} \\
29398 \cmd{\thectr} \\
29399 \end{syntax}
29400 \glossary(newcounter)%
29401 {\cs{newcounter}\marg{ctr}\oarg{within}}%
29402 {Creates a new counter \Pcn{ctr}, optionally reset when counter \Pcn{within}
29403 changes.}
29404 \glossary(thectr)%
29405 {\cs{thectr}}%
29406 {Typesets the value of the counter \Pcn{ctr}.}
29407 In \ltx\ a new counter called, say \Pcn{ctr}, is created by the
29408 \cmd{\newcounter} command as \verb?\newcounter{ctr}?.
29409 If the optional \meta{within}
29410 argument is given, the counter \Pcn{ctr} is reset to zero each time the
29411 counter called \Pcn{within} is changed; the \Pcn{within} counter
29412 must exist before it is used as the optional argument. The command
29413 \verb?\thectr? typesets the value
29414 of the counter \Pcn{ctr}. This is automatically defined for you by the
29415 \cmd{\newcounter} command to typeset arabic numerals.
29416
29417 \begin{syntax}
29418 \cmd{\counterwithin}\oarg{format}\marg{ctr}\marg{within}\footnotemark \\
29419 \cmd{\counterwithin*}\marg{ctr}\marg{within}\footnotemark[\thefootnote] \\
29420 \end{syntax}
29421 \footnotetext{These have been provided by the kernel since 2018, thus is no longer provided by the class it self. The optional argment was added in 2021.}
29422 \glossary(counterwithin)%
29423 {\cs{counterwithin}\oarg{format}\marg{ctr}\marg{within}}%
29424 {Makes the counter \Pcn{ctr} (created via \cs{newcounter}) act as though
29425 it had been initially defined to be reset by counter \Pcn{within} (specifically it resets whenever \meta{within} is stepped).
29426 It also redefines \cs{thectr} to
29427 \cs{thewithin.}\meta{format}\texttt\{\meta{within}\texttt\} (default format being \cs{arabic}).
29428 }
29429 \glossary(counterwithin*)%
29430 {\cs{counterwithin*}\marg{ctr}\marg{within}}%
29431 {Makes the counter \Pcn{ctr} (created via \cs{newcounter}) act as though
29432 it had been initially defined to be reset by counter \Pcn{within}, leaving
29433 the original definition of \cs{thectr}.}
29434 The \cmd{\counterwithin} macro makes a \meta{ctr} that has been initially
29435 defined by \verb?\newcounter{ctr}? act as though it had been defined by
29436 \verb?\newcounter{ctr}[within]? (that is it resets whenever \meta{within} is stepped).
29437 It also redefines the \cs{thectr} command to be \verb?\thewithin.format{ctr}?
29438 (default format is \cs{arabic}). The starred version of the command does not change
29439 he original definition of \cs{thectr}.
29440
29441 \begin{syntax}
29442 \cmd{\counterwithout}\oarg{format}\marg{ctr}\marg{within}\footnotemark[\thefootnote] \\
29443 \cmd{\counterwithout*}\marg{ctr}\marg{within}\footnotemark[\thefootnote] \\
29444 \end{syntax}
29445 \glossary(counterwithout)%
29446 {\cs{counterwithout}\marg{ctr}\marg{within}}%
29447 {Makes the counter \Pcn{ctr} (created via
29448 \cs{newcounter}\marg{ctr}\oarg{within}) act as though
29449 it had been initially defined via \cs{newcounter}\marg{ctr} (that is removes it from being reset whenever \meta{within} is stepped).
29450 It also redefines \cs{thectr} to be \meta{format}\texttt\{\meta{ctr}\texttt\} (default format being \cs{arabic}).}
29451 \glossary(counterwithout*)%
29452 {\cs{counterwithout*}\marg{ctr}\marg{within}}%
29453 {Makes the counter \Pcn{ctr} (created via
29454 \cs{newcounter}\marg{ctr}\oarg{within}) act as though
29455 it had been initially defined via \cs{newcounter}\marg{ctr},
29456 leaving the original definition of \cs{thectr}.}
29457 The \cmd{\counterwithout} macro makes the \Pcn{ctr} counter that has been
29458 initially
29459 defined by \verb?\newcounter{ctr}[within]? act as though it had been defined by
29460 \verb?\newcounter{ctr}?. In other terms, if \meta{ctr} is being reset whenever
29461 \meta{within} is stepped, \cs{counterwithout} removes \meta{ctr} from this reset.
29462 Additionally it redefines the \cs{thectr} command
29463 to be \verb?format{ctr}? (default format is \cs{arabic}). The starred version of the command
29464 does nothing to the original definition of \verb?\thectr?.
29465
29466 Any number of \verb?\counterwithin{ctr}{...}? and \verb?\counterwithout{ctr}{...}?
29467 commands can be issued for a given counter \Pcn{ctr} if you wish to toggle
29468 between the two styles. The current value of \Pcn{ctr} is unaffected by these
29469 commands. If you want to change the value use \cmd{\setcounter}, and to change
29470 the typesetting style use \cmd{\renewcommand} on \cs{thectr}.
29471
29472
29473
29474
29475
29476
29477 \LMnote{2010/01/30}{Added \cs{letcountercounter}}
29478 \begin{syntax}
29479 \cmd{\letcountercounter}\marg{counterA}\marg{counterB}\\
29480 \cmd{\unletcounter}\marg{counterA}\\
29481 \end{syntax}
29482 At times it is handy to `let' one counter act as if it was a
29483 different counter. Say you have two constructions, each with their
29484 own counter A and B, now you want them to cooperate, counting in
29485 unison. This can be done using the \verb?\letcountercounter?.
29486
29487 \cs{letcountercounter}\marg{counterA}\marg{counterB} \cs{let}s
29488 (make the same) \meta{counterA} to \meta{counterB}. The
29489 original of \meta{counterA} is kept, such that you can unlet it later.
29490
29491 \cs{unletcounter}\marg{counterA} restores \meta{counterA} to its un\cs{let}
29492 condition.
29493
29494 This feature can be quite handy. Say for instance you want figures and
29495 tables to counter within the same counter (say table), then we need
29496 each change to the \verb?figure? counter to actually act on the
29497 \verb?table? counter. \verb?\letcountercounter{figure}{table}? solves
29498 the problem.
29499
29500
29501
29502 \section{New new and provide commands}
29503
29504 \begin{syntax}
29505 \cmd{\newloglike}\marg{cmd}\marg{string} \\
29506 \cmd{\newloglike*}\marg{cmd}\marg{string} \\
29507 \end{syntax}
29508 \glossary(newloglike)%
29509 {\cs{newloglike}\marg{cmd}\marg{string}}%
29510 {Creates a new log-like function command \meta{cmd} typesetting
29511 \meta{string}.}
29512 \glossary(newloglike*)%
29513 {\cs{newloglike}\marg{cmd}\marg{string}}%
29514 {Creates a new log-like function command \meta{cmd} typesetting
29515 \meta{string}, which can take limits.}
29516 The class provides means of creating new math log-like functions. For
29517 example you might want to do
29518 \begin{lcode}
29519 \newloglike{\Ei}{Ei}
29520 \end{lcode}
29521 if you are using the exponential integral function in your work.
29522 The starred version of the command creates a function that takes limits
29523 (like the \cmd{\max} function).
29524
29525 The \ltx\ kernel defines the \cmd{\providecommand} macro that acts
29526 like \cmd{\newcommand} if the designated macro has not been defined
29527 previously, otherwise it does nothing. The class adds to that limited
29528 repertoire.
29529
29530 \begin{syntax}
29531 \cmd{\provideenvironment}\marg{name}\oarg{numargs}\oarg{optarg}\marg{begindef}\marg{enddef} \\
29532 \cmd{\providelength}\marg{cmd} \\
29533 \cmd{\providecounter}\marg{ctr}\oarg{within} \\
29534 \cmd{\provideloglike}\marg{cmd}\marg{string} \\
29535 \cmd{\provideloglike*}\marg{cmd}\marg{string} \\
29536 \end{syntax}
29537 \glossary(provideenvironment)%
29538 {\cs{provideenvironment}\marg{name}\oarg{numarks}\oarg{optarg}\marg{begindef}\marg{enddef}}%
29539 {A `provide' version of \cs{(re)newenvironment}.}
29540 \glossary(providelength)%
29541 {\cs{providelength}\marg{cmd}}%
29542 {A `provide' version of \cs{newlength}.}
29543 \glossary(providecounter)%
29544 {\cs{providecounter}\marg{ctr}\oarg{within}}%
29545 {A `provide' version of \cs{newcounter}.}
29546 \glossary(provideloglike)%
29547 {\cs{provideloglike}\marg{cmd}\marg{string}}%
29548 {A `provide' version of \cs{newloglike}.}
29549 \glossary(provideloglike*)%
29550 {\cs{provideloglike*}\marg{cmd}\marg{string}}%
29551 {A `provide' version of \cs{newloglike*}.}
29552 The macros \cmd{\provideenvironment}, \cmd{\providelength}
29553 and \cmd{\providecounter} take the same arguments as their \verb?\new...?
29554 counterparts. If the environment, length or counter has not been defined
29555 then it is defined accordingly, otherwise the macros do nothing except
29556 produce a warning message for information purposes.
29557
29558 The \cmd{\provideloglike} commands are for math log-like functions,
29559 but they do not produce any warning messages.
29560
29561 \section{Changing macros} \label{sec:addtodef}
29562
29563 \begin{recommended}
29564 See also the \Lpack{xpatch}/\Lpack{etoolbox} and \Lpack{letltxmacro}
29565 packages.\footnotemark
29566
29567 Additionally the LaTeX-format of October 2020 include some new
29568 hooking features e.g. to hook into environments, see \cite{LTHOOKS}
29569 (see section 2.8.1 for some utility macros). The new format also
29570 adds \cs{NewCommandCopy} and \cs{RenewCommandCopy} which are
29571 extended versions of what \Lpack{letltxmacro} provides.
29572
29573 Note that \cs{NewCommandCopy} will be preferred over \cs{let} as
29574 more and more macros are made robust which \cs{let} cannot handle
29575 easily.
29576 \end{recommended}
29577 \footnotetext{\Lpack{xpatch} and thus also \Lpack{etoolbox} are automatically loaded by the class.}
29578
29579
29580
29581 Commands are provided for extending simple macro
29582 definitions.\index{extend a macro}\index{add to a macro}
29583
29584 \begin{syntax}
29585 \cmd{\addtodef}\marg{macro}\marg{prepend}\marg{append} \\
29586 \cmd{\addtoiargdef}\marg{macro}\marg{prepend}\marg{append} \\
29587 \end{syntax}
29588 \glossary(addtodef)%
29589 {\cs{addtodef}\marg{macro}\marg{prepend}\marg{append}}%
29590 {Inserts \meta{prepend} at the start of the current definition of
29591 \meta{macro} and \meta{append} at the end, treating the result
29592 as if it had been defined by \cs{renewcommand}. Deprecated, will be removed in 2026.}
29593 \glossary(addtoiargdef)%
29594 {\cs{addtoiargdef}\marg{macro}\marg{prepend}\marg{append}}%
29595 {Inserts \meta{prepend} at the start of the current definition of
29596 \meta{macro} (which takes a single argument) and \meta{append} at the
29597 end, treating the result as if it had been defined by \cs{renewcommand}.
29598 Deprecated, will be removed in 2026.}
29599 \begin{Deprecated}[February 2024]
29600 Both macros \cs{addtodef} and \cs{addtoiargdef} will be removed in
29601 2026. The same (and better) effect can be done via \cmd{\patchcmd},
29602 \cmd{\pretocmd} and \cmd{\apptocmd} from \Lpack{etoolbox} which is
29603 already loaded.
29604 \end{Deprecated}
29605 The macro \cmd{\addtodef} inserts \meta{prepend} at the start of the
29606 current definition of \meta{macro} and puts \meta{append} at the end,
29607 where \meta{macro} is the name of a macro (including the backslash) which
29608 takes no arguments. The \cmd{\addtoiargdef} macro is similar except that
29609 \meta{macro} is the name of a macro that takes one argument.
29610
29611 For example the following are two equivalent
29612 definitions of \verb?\mymacro?:
29613 \begin{lcode}
29614 \newcommand{\mymacro}[1]{#1 is a violinist in spite of being tone deaf}
29615 \end{lcode}
29616 and
29617 \begin{lcode}
29618 \newcommand{\mymacro}[1]{#1 is a violinist}
29619 \addtoiargdef{\mymacro}{}{ in spite of being tone deaf}
29620 \end{lcode}
29621
29622 The \cmd{\addtoiargdef} (and \cmd{\addtodef}) commands
29623 can be applied several times to the same \meta{macro}. Revising the
29624 previous example we could have
29625 \begin{lcode}
29626 \newcommand{\mymacro}[1]{#1 is a violinist}
29627 \addtoiargdef{\mymacro}{Although somewhat elderly, }%
29628 { in spite of being tone deaf}
29629 \addtoiargdef{\mymacro}{}{ and a bagpiper}
29630 \end{lcode}
29631 which is equivalent to
29632 \begin{lcode}
29633 \newcommand{\mymacro}[1]{%
29634 Although somewhat elderly, #1 is a violinist
29635 in spite of being tone deaf and a bagpiper}
29636 \end{lcode}
29637
29638 The \meta{prepend} and \meta{append} arguments may include \ltx\ code,
29639 as shown in this extract from the class code:
29640 \begin{lcode}
29641 \addtoiargdef{\date}{}{%
29642 \begingroup
29643 \renewcommand{\thanks}[1]{}
29644 \renewcommand{\thanksmark}[1]{}
29645 \renewcommand{\thanksgap}[1]{}
29646 \protected@xdef\thedate{#1}
29647 \endgroup}
29648 \end{lcode}
29649 Note that in the case of \cmd{\addtoiargdef} an argument can also refer
29650 to the original argument of the \meta{macro}.
29651
29652 \begin{syntax}
29653 \cmd{\addtodef*}\marg{macro}\marg{prepend}\marg{append} \\
29654 \cmd{\addtoiargdef*}\marg{macro}\marg{prepend}\marg{append} \\
29655 \end{syntax}
29656 \glossary(addtodef*)%
29657 {\cs{addtodef*}\marg{macro}\marg{prepend}\marg{append}}%
29658 {Inserts \meta{prepend} at the start of the current definition of
29659 \meta{macro} and \meta{append} at the end, treating the result as if it had
29660 been defined by \cs{renewcommand*}. Deprecated, will be removed in 2026.}
29661 \glossary(addtoiargdef*)%
29662 {\cs{addtoiargdef*}\marg{macro}\marg{prepend}\marg{append}}%
29663 {Inserts \meta{prepend} at the start of the current definition of
29664 \meta{macro} (which takes a single argument) and \meta{append} at the
29665 end, treating the result as if it had been defined by \cs{renewcommand*}.
29666 Deprecated, will be removed in 2026.}
29667 \begin{Deprecated}[February 2024]
29668 Both macros \cs{addtodef*} and \cs{addtoiargdef*} will be removed in
29669 2026. As mentioned above their effect can be done using tools from
29670 \Lpack{etoolbox}.
29671 \end{Deprecated}
29672 These starred versions are for use when the original \meta{macro}
29673 was defined via \cmd{\newcommand*}. Using the starred versions is
29674 like using \cmd{\renewcommand*} and the unstarred versions are like
29675 having used \cmd{\renewcommand}. It is the version (starred or unstarred)
29676 of a sequence of \verb?\addto...? commands that counts when determining whether
29677 the equivalent \verb?\renew...? is treated as starred or unstarred.
29678
29679 The \verb?\addto...? macros cannot be used to delete any code from
29680 \meta{macro} nor to add anything except at the start and end. Also,
29681 in general, they cannot be used to change the definition of a macro that
29682 takes an optional argument, or a starred macro.
29683
29684 \begin{syntax}
29685 \cmd{\patchcommand}\marg{macro}\marg{start-code}\marg{end-code} \\
29686 \end{syntax}
29687 \glossary(patchcommand)%
29688 {\cs{patchcommand}\marg{macro}\marg{start-code}\marg{end-code}}%
29689 {Inserts \meta{start-code} before the current definition of the
29690 \meta{macro} and \marg{end-code} at the end of the current definition.
29691 Deprecated, will be removed in 2026.}%
29692 \begin{Deprecated}[February 2024]
29693 \cs{patchcommand} will be removed in 2026. Use the various patching
29694 macros from \Lpack{etoolbox} or \Lpack{xpatch} instead.
29695 \end{Deprecated}
29696
29697
29698 The \cmd{\patchcommand} is from the late
29699 Michael Downes'\index{Downes, Michael}
29700 \Lpack{patchcmd} package~\cite{PATCHCMD}.
29701 It inserts the \meta{start-code} at
29702 the start of the current definition of the macro \meta{macro},
29703 and inserts \meta{end-code} at the end of its current definition.
29704 The \meta{macro} can have zero to nine parameters. If \meta{macro}
29705 uses \cmd{\futurelet} (e.g., it is a starred command or takes an
29706 optional argument) only \meta{start-code} is useful ---
29707 \meta{end-code} must be empty otherwise things get messed up. If
29708 \meta{macro} has any delimited arguments then \cmd{\patchcommand}
29709 cannot be used.
29710
29711 \begin{recommended}
29712 Again \Lpack{xpatch} and \Lpack{etoolbox} (both loaded by \theclass)
29713 are recommended. See the commands
29714 \begin{syntax}
29715 \cmd{\xpatchcmd}\marg{macro}\marg{search}\marg{replace}\marg{success}\marg{failure} \\
29716 \cmd{\xapptocmd}\marg{macro}\marg{code}\marg{success}\marg{failure} \\
29717 \cmd{\xpretocmd}\marg{macro}\marg{code}\marg{success}\marg{failure} \\
29718 \cmd{\patchcmd}\marg{macro}\marg{search}\marg{replace}\marg{success}\marg{failure} \\
29719 \cmd{\apptocmd}\marg{macro}\marg{code}\marg{success}\marg{failure} \\
29720 \cmd{\pretocmd}\marg{macro}\marg{code}\marg{success}\marg{failure} \\
29721 \end{syntax}
29722 Here \cmd{\xpatchcmd} can patch some macros can \cmd{\patchcmd}
29723 cannot. The combination of \verb|\(x)pretocmd| and
29724 \verb|\(x)apptocmd| give the same result as \cmd{\patchcommand}.
29725 \end{recommended}
29726
29727
29728 \section{String arguments}
29729
29730 In the code for the class I have sometimes used macro arguments
29731 that consist of a `string', like the \texttt{*} arguments in the page layout
29732 macros (e.g., \cmd{\settypeblocksize}), or the \texttt{flushleft},
29733 \texttt{center} and \texttt{flushright} strings for the
29734 \cmd{\makeheadposition} macro.
29735
29736 \begin{syntax}
29737 \cmd{\nametest}\marg{str1}\marg{str2} \\
29738 \piif{ifsamename} \\
29739 \end{syntax}
29740 \glossary(nametest)%
29741 {\cs{nametest}\marg{str1}\marg{str2}}%
29742 {Sets \cs{ifsamename} \ptrue\ if \meta{str1} is the same as \meta{str2},
29743 otherwise \pfalse.}
29744 \glossary(ifsamename)%
29745 {\cs{ifsamename}}%
29746 {Result from \cs{nametest}.}
29747 The macro \cmd{\nametest} takes two strings
29748 as the arguments \meta{str1} and \meta{str2}. It sets \piif{ifsamename}
29749 \ptrue\ if \meta{str1} is the same as \meta{str2}, otherwise it sets
29750 \piif{ifsamename} \pfalse. For the purposes of \cmd{\nametest}, a string is a
29751 sequence of characters which may include spaces and may include
29752 the \verb?\? backslash character; strings are equal if and only if their
29753 character sequences are identical.
29754
29755 Typically, I have used it within macros for checking on argument
29756 values. For example:
29757 \begin{lcode}
29758 \newcommand{\amacro}[1]{%
29759 \nametest{#1}{green}
29760 \ifsamename
29761 % code for green
29762 \fi
29763 \nametest{#1}{red}
29764 \ifsamename
29765 % code for red
29766 \fi
29767 ...
29768 }
29769 \end{lcode}
29770
29771 The \Lpack{etoolbox} package as a simple alternative:
29772 \begin{syntax}
29773 \cs{ifstrequal}\marg{string}\marg{string}\marg{true}\marg{false}
29774 \end{syntax}
29775
29776 \fancybreak{}
29777
29778 In the modern \LaTeX\ kernel, the Expl3 layer offers a plethora of
29779 extra string checking macros. For example \verb+\str_case_e:nnTF+
29780 which compares a string to a list of strings and code for when that
29781 string is equal. This saves a lot of space compared to nested
29782 \cs{ifsamename} towers.\footnote{See the current implementation of
29783 \cs{settypeoutlayoutunit} for an example.}
29784
29785 \section{Odd/even page checking}
29786
29787 It is difficult to check robustly if the current page is odd or even
29788 but the class does provide a robust method based on writing out a
29789 label and then checking the page reference for the label. This
29790 requires at least two \ltx\ runs to stabilise. This has been extracted
29791 from the original \Lpack{chngpage} package (which is no longer
29792 available). (The class code and \Lpack{chngpage} code is similar but
29793 not identical. There is a later package,
29794 \Lpack{changepage}~\cite{CHANGEPAGE} which contains code that is
29795 identical to the class.)
29796
29797
29798 \begin{syntax}
29799 \cmd{\checkoddpage} \\
29800 \piif{ifoddpage} \\
29801 \cmd{\strictpagecheck} \cmd{\easypagecheck} \\
29802 \end{syntax}
29803 \glossary(checkoddpage)%
29804 {\cs{checkoddpage}}%
29805 {Sets \cs{ifoddpage} \ptrue\ if called on an odd-numbered page, otherwise
29806 \pfalse.}
29807 \glossary(ifoddpage)%
29808 {\cs{ifoddpage}}%
29809 {Result of \cs{checkoddpage}.}
29810 \glossary(strictpagecheck)%
29811 {\cs{strictpagecheck}}%
29812 {\cs{checkoddpage} will use an accurate but time and space consuming method
29813 for checking for an odd page number.}
29814 \glossary(easypagecheck)%
29815 {\cs{easypagecheck}}%
29816 {\cs{checkoddpage} will use a possibly inaccurate but fast method
29817 for checking for an odd page number.}
29818 The macro \cmd{\checkoddpage} sets \piif{ifoddpage} to \ptrue\ if the current
29819 page number
29820 is odd, otherwise it sets it to \pfalse\ (the page number is even). The robust
29821 checking method involves writing and reading labels, which is what is done
29822 after the command \cmd{\strictpagecheck} is issued; it may take more than
29823 one run before everything settles down. The simple method
29824 is just
29825 to check the current page number which, because of TeX's asynchronous page
29826 breaking algorithm, may not correspond to the actual page number where the
29827 \cmd{\checkoddpage} command was issued. The simple, but faster, page checking
29828 method is used after the \cmd{\easypagecheck} command is issued.
29829
29830 \begin{syntax}
29831 \cmd{\cplabel} \\
29832 \end{syntax}
29833 \glossary(cplabel)%
29834 {\cs{cplabel}}%
29835 {Prefix for labels used by \cs{checkoddpage} odd/even page checking.}
29836 When strict page checking is used the labels consist of a number preceded
29837 by the value of \cmd{\cplabel}, whose default definition is \verb?^_? (e.g.,
29838 a label may consist of the characters \verb?^_21?). If this
29839 might clash with any of your labels, change \cmd{\cplabel} with
29840 \cmd{\renewcommand}, but
29841 the definition of \cmd{\cplabel} must be constant for any given document.
29842
29843 \section{Moving to another page} \label{sec:moving}
29844
29845 Standard \ltx\ provides the \cmd{\newpage}, \cmd{\clearpage}
29846 and \cmd{\cleardoublepage} commands for discontinuing the current
29847 page and starting a new one. The following is a bundling of the
29848 \Lpack{nextpage} package~\cite{NEXTPAGE}.
29849
29850 \begin{syntax}
29851 \cmd{\needspace}\marg{length} \\
29852 \end{syntax}
29853 \glossary(needspace)%
29854 {\cs{needspace}\marg{length}}%
29855 {Starts a new page, leaving the current page short, unless there is
29856 estimated \meta{length} vertical space left on the current page.}
29857 This macro decides if there is \meta{length} space at the bottom of the
29858 current page. If there is, it does nothing, otherwise it starts a new page.
29859 This is useful if \meta{length} amount of material is to be kept together
29860 on one page. The \cmd{\needspace} macro
29861 depends on penalties for deciding what to do which means that the reserved
29862 space is an approximation. However, except for the odd occasion, the
29863 macro gives adequate results.
29864
29865 \begin{syntax}
29866 \cmd{\Needspace}\marg{length} \\
29867 \cmd{\Needspace*}\marg{length} \\
29868 \end{syntax}
29869 \glossary(Needspace)%
29870 {\cs{Needspace}\marg{length}}%
29871 {Starts a new page, leaving the current page short, unless there is
29872 actually at least \meta{length} vertical space left on the current page. }
29873 \glossary(Needspace*)%
29874 {\cs{Needspace*}\marg{length}}%
29875 {Starts a new page, leaving the current page short unless \cs{flushbottom}
29876 is in effect, unless there is
29877 actually at least \meta{length} vertical space left on the current page.}
29878 Like \cmd{\needspace}, the \cmd{\Needspace} macro checks if there is
29879 \meta{length} space at the bottom of the current page and if there is not
29880 it starts a new page. The command should only be used between paragraphs;
29881 indeed, the first thing it does is to call \cs{par}. The \cmd{\Needspace}
29882 command checks for the actual space left on the page and is more exacting
29883 than \cmd{\needspace}.
29884
29885 If either \cmd{\needspace} or \cmd{\Needspace} produce a short page it
29886 will be ragged bottom even if \cmd{\flushbottom} is in effect. With
29887 the starred \cmd{\Needspace*} version, short pages will be flush bottom
29888 if \cmd{\flushbottom} is in effect and will be ragged bottom
29889 when \cmd{\raggedbottom} is in effect.
29890
29891 Generally speaking, use \cmd{\needspace} in preference to \cmd{\Needspace}
29892 unless it gives a bad break or the pages must be flush bottom.
29893
29894
29895 \begin{syntax}
29896 \cmd{\movetoevenpage}\oarg{text} \\
29897 \cmd{\cleartoevenpage}\oarg{text} \\
29898 \end{syntax}
29899 \glossary(movetoevenpage)%
29900 {\cs{movetoevenpage}\oarg{text}}%
29901 {Stops the current page to start typesetting on the next even page.
29902 The optional \meta{text} is put on the skipped page (if there is one).}
29903 The \cmd{\movetoevenpage} stops the current page and starts typesetting on the
29904 next even numbered page. The \verb?\clear...? version flushes out all
29905 floats\index{float} before
29906 going to the next even page. The optional \meta{text} is put on the skipped
29907 page (if there is one).
29908
29909 \begin{syntax}
29910 \cmd{\movetooddpage}\oarg{text} \\
29911 \cmd{\cleartooddpage}\oarg{text} \\
29912 \end{syntax}
29913 \glossary(movetooddpage)%
29914 {\cs{movetooddpage}\oarg{text}}%
29915 {Stops the current page to start typesetting on the next odd page.
29916 The optional \meta{text} is put on the skipped page (if there is one).}
29917 \glossary(cleartoevenpage)%
29918 {\cs{cleartooddpage}\oarg{text}}%
29919 {Flushes any pending floats to then start typesetting on the next odd page.
29920 The optional \meta{text} is put on the skipped page (if there is one).}
29921 These macros are similar to the \verb?\...evenpage? ones except that they jump
29922 to the next odd numbered page.
29923
29924 A likely example for the optional \meta{text} argument is
29925 \begin{lcode}
29926 \cleartooddpage[\vspace*{\fill}THIS PAGE LEFT BLANK\vspace*{\fill}]
29927 \end{lcode}
29928 which will put `THIS PAGE LEFT BLANK' in the centre of any
29929 potential skipped (empty) even numbered page.
29930
29931 \begin{syntax}
29932 \cmd{\cleartorecto} \cmd{\cleartoverso} \\
29933 \end{syntax}
29934 \glossary(cleartorecto)%
29935 {\cs{cleartorecto}}%
29936 {Simpler form of \cs{cleartooddpage}.}
29937 \glossary(cleartoverso)%
29938 {\cs{cleartoverso}}%
29939 {Simpler form of \cs{cleartoevenpage}.}
29940 These are slightly simpler forms\footnote{Perhaps more robust.} of
29941 \cmd{\cleartooddpage} and \cmd{\cleartoevenpage}. For example, if you wanted
29942 the \toc\ to start on a verso page, like in
29943 \btitle{The TeXbook} \cite{TEXBOOK}, then do this:
29944 \begin{lcode}
29945 \cleartoverso
29946 \tableofcontents
29947 \end{lcode}
29948
29949 \section{Number formatting}
29950
29951 Several methods are provided for formatting numbers\index{number}.
29952 Two classes of number representations\indextwo{number}{representation}
29953 are catered for.
29954 A `numeric number'\indextwo{numeric}{number} is typeset using arabic
29955 digits and a `named number'\indextwo{named}{number} is typeset using
29956 words.
29957
29958 The argument to the number formatting macros is a `number'\index{number},
29959 essentially something that resolves to a series of arabic digits. Typical
29960 arguments might be:
29961 \begin{itemize}
29962 \item Some digits, e.g., \verb?\ordinal{123} ->?
29963 \ordinal{123}
29964 \item A macro expanding to digits, e.g., \verb?\def\temp{3}\ordinal{\temp} ->?
29965 \begingroup\def\temp{3}\ordinal{\temp}\endgroup % \\
29966
29967 % Or even, for example, \verb?\ordinal{\pageref{chap:numf}} ->?
29968 % \ordinal{\pageref{chap:numf}}
29969 \item The value of a counter, e.g., \verb?\ordinal{\value{page}} ->?
29970 \ordinal{\value{page}}
29971 \item The arabic representation of a counter, e.g., \verb?\ordinal{\thepage} ->?
29972 \ordinal{\thepage}
29973
29974 However, if the representation of a counter is not completely in arabic
29975 digits, such as \verb?\thesection? which here prints as \thesection, it will
29976 produce odd errors or peculiar results if it is used as the argument.
29977 For instance: \\
29978 \verb?\ordinal{\thesection} ->? \ordinal{\thesection}
29979
29980 \end{itemize}
29981
29982 \subsection{Numeric numbers}
29983 \indextwo{numeric}{number}
29984
29985 \begin{syntax}
29986 \cmd{\cardinal}\marg{number} \\
29987 \cmd{\fcardinal}\marg{number} \\
29988 \cmd{\fnumbersep} \\
29989 \end{syntax}
29990 \glossary(cardinal)%
29991 {\cs{cardinal}\marg{number}}%
29992 {Typesets \marg{number} as a cardinal number.}
29993 \glossary(fcardinal)%
29994 {\cs{fcardinal}\marg{number}}%
29995 {Typesets \marg{number} as a cardinal number, with \cs{fnumbersep} between
29996 each triple of digits.}
29997 \glossary(fnumbersep)%
29998 {\cs{fnumbersep}}%
29999 {Separator between digit triples in numbers.}
30000 The macro \cmd{\fcardinal} prints its \meta{number} argument formatted using
30001 \cmd{\fnumbersep} between each triple of digits. The default definition
30002 of \cmd{\fnumbersep} is:
30003 \begin{lcode}
30004 \newcommand{\fnumbersep}{,}
30005 \end{lcode}
30006
30007 Here are some examples: \\
30008 \verb?\fcardinal{12} ->? \fcardinal{12} \\
30009 \verb?\fcardinal{1234} ->? \fcardinal{1234} \\
30010 \verb?\fcardinal{1234567} ->? \fcardinal{1234567} \\
30011 \verb?\renewcommand*{\fnumbersep}{\:}\fcardinal{12345678} ->?
30012 \renewcommand*{\fnumbersep}{\:}\fcardinal{12345678} \\
30013 \verb?\renewcommand*{\fnumbersep}{,\:}?
30014 \renewcommand*{\fnumbersep}{,\:}
30015
30016 The \cmd{\cardinal} macro is like \cmd{\fcardinal} except that there
30017 is no separation between any of the digits.
30018
30019 \begin{syntax}
30020 \cmd{\ordinal}\marg{number} \\
30021 \cmd{\fordinal}\marg{number} \\
30022 \cmd{\ordscript}\marg{chars} \\
30023 \end{syntax}
30024 \glossary(ordinal)%
30025 {\cs{ordinal}\marg{number}}%
30026 {Typesets \marg{number} as an ordinal number.}
30027 \glossary(fordinal)%
30028 {\cs{fordinal}\marg{number}}%
30029 {Typesets \marg{number} as an ordinal number, with \cs{fnumbersep} between
30030 each triple of digits.}
30031 \glossary(ordscript)%
30032 {\cs{ordscript}\marg{chars}}%
30033 {Typesets the ordinal characters \meta{chars}.}
30034
30035 The \cmd{\fordinal} macro typesets its \meta{number} argument as a formatted
30036 ordinal, using \cmd{\fnumbersep} as the separator. The macro \cmd{\ordinal}
30037 is similar except that there is no separation between any of the digits.
30038
30039 Some examples are: \\
30040 \verb?\fordinal{3} ->? \fordinal{3} \\
30041 \verb?\fordinal{12341} ->? \fordinal{12341} \\
30042 \verb?\renewcommand{\ordscript}[1]{\textsuperscript{#1}}? \\
30043 \verb?\fordinal{1234567} ->?
30044 \renewcommand{\ordscript}[1]{\textsuperscript{#1}}\fordinal{1234567} \\
30045 \verb?\ordinal{1234567} ->? \ordinal{1234567} \\
30046 \verb?This is the \ordinal{\value{chapter}} chapter. ->?
30047 This is the \ordinal{\value{chapter}} chapter.
30048
30049
30050 The characters denoting the ordinal (ordination?) are typeset as
30051 the argument of \cmd{\ordscript}, whose default definition is:
30052 \begin{lcode}
30053 \newcommand{\ordscript}[1]{#1}
30054 \end{lcode}
30055 As the above examples show, this can be changed to give a different
30056 appearance.
30057
30058 \begin{syntax}
30059 \cmd{\nthstring} \cmd{\iststring} \cmd{\iindstring} \cmd{\iiirdstring} \\
30060 \end{syntax}
30061 \glossary(nthstring)%
30062 {\cs{nthstring}}%
30063 {Ordinal characters for `th', e.g., as in 6th.}
30064 \glossary(iststring)%
30065 {\cs{iststring}}%
30066 {Ordinal characters for `st', e.g., as in 1st.}
30067 \glossary(iindstring)%
30068 {\cs{iindstring}}%
30069 {Ordinal characters for `nd', e.g., as in 2nd.}
30070 \glossary(iiirdstring)%
30071 {\cs{iiirdstring}}%
30072 {Ordinal characters for `rd', e.g., as in 3rd.}
30073 The ordinal characters are the values of the macros \cmd{\nthstring}
30074 (default: th) for most ordinals, \cmd{\iststring} (default: st) for
30075 ordinals ending in 1 like \ordinal{21}, \cmd{\iindstring} (default: nd)
30076 for ordinals like \ordinal{22}, and \cmd{\iiirdstring} (default: rd)
30077 for ordinals like \ordinal{23}.
30078
30079
30080 \subsection{Named numbers}
30081 \indextwo{named}{number}
30082
30083
30084 \begin{syntax}
30085 \cmd{\numtoname}\marg{number} \\
30086 \cmd{\numtoName}\marg{number} \\
30087 \cmd{\NumToName}\marg{number} \\
30088 \end{syntax}
30089 \glossary(numtoname)%
30090 {\cs{numtoname}\marg{number}}%
30091 {Typesets \meta{number} as a cardinal using lowercase words.}
30092 \glossary(numtoName)%
30093 {\cs{numtoName}\marg{number}}%
30094 {Typesets \meta{number} as a cardinal using lowercase words, but uppercase for the initial
30095 letter of the first word.}
30096 \glossary(NumtoName)%
30097 {\cs{NumtoName}\marg{number}}%
30098 {Typesets \meta{number} as a cardinal using lowercase words, but uppercase for the initial
30099 letter of each word.}
30100 The macro \cmd{\numtoname} typesets its \meta{number} argument using
30101 lowercase words. The other two macros are similar, except that
30102 \cmd{\numtoName} uses uppercase for the initial letter of the first word and
30103 \cmd{\NumToName} uses uppercase for the initial letters of all the words.
30104
30105 As examples: \\
30106 \verb?\numtoname{12345} ->? \numtoname{12345} \\
30107 \verb?\numtoName{12345} ->? \numtoName{12345} \\
30108 \verb?\NumToName{12345} ->? \NumToName{12345} \\
30109 \begin{egsource}{eg:minnum}
30110 The minimum number in TeX is \numtoname{-2147483647}
30111 (i.e., \fcardinal{-2147483647})
30112 \end{egsource}
30113 \begin{egresult}[\tx's minimum number in words (English style)]{eg:minnum}
30114 The minimum number in TeX is \numtoname{-2147483647}
30115 (i.e., \fcardinal{-2147483647})
30116 \end{egresult}
30117
30118 \begin{syntax}
30119 \cmd{\ordinaltoname}\marg{number} \\
30120 \cmd{\ordinaltoName}\marg{number} \\
30121 \cmd{\OrdinalToName}\marg{number} \\
30122 \end{syntax}
30123 \glossary(ordinaltoname)%
30124 {\cs{ordinaltoname}\marg{number}}%
30125 {Typeset \meta{number} as an ordinal using lowercase words.}
30126 \glossary(ordinaltoName)%
30127 {\cs{ordinaltoName}\marg{number}}%
30128 {Typeset \meta{number} as an ordinal using lowercase words, but uppercase the
30129 initial letter of the first word.}
30130 \glossary(OrdinaltoName)%
30131 {\cs{OrdinaltoName}\marg{number}}%
30132 {Typeset \meta{number} as an ordinal using lowercase words, but uppercase the
30133 initial letter of each word.}
30134 These three macros are similar to \cmd{\numtoname}, etc., except that they
30135 typeset the argument as a wordy ordinal.
30136
30137 For example: \\
30138 \verb?This is the \ordinaltoname{\value{chapter}} chapter. ->?
30139 This is the \ordinaltoname{\value{chapter}} chapter.
30140
30141 \begin{syntax}
30142 \cmd{\namenumberand} \cmd{\namenumbercomma} \cmd{\tensunitsep} \\
30143 \end{syntax}
30144 \glossary(namenumberand)%
30145 {\cs{namenumberand}}%
30146 {The conjunction in named numbers, default ` and '.}
30147 \glossary(namenumbercomma)%
30148 {\cs{namenumbercomma}}%
30149 {The `comma' in named numbers, default `, '.}
30150 \glossary(tensunitsep)%
30151 {\cs{tensunitsep}}%
30152 {The separator/conjoiner between tens and units in named numbers, default `-'.}
30153 By default some punctuation and conjunctions are used in the representation
30154 of named numbers. According to both American and English practice, a hyphen
30155 should be inserted between a `tens' name (e.g., fifty) and a following
30156 unit name (e.g., two). This is represented by the value of \cmd{\tensunitsep}.
30157 English practice, but not American, is to include commas (the value of
30158 \cmd{\namenumbercomma}) and conjunctions (the value of \cmd{\namenumberand})
30159 in strategic positions in the typesetting. These macros are initially
30160 defined as:
30161 \begin{lcode}
30162 \newcommand*{\namenumberand}{ and }
30163 \newcommand*{\namenumbercomma}{, }
30164 \newcommand*{\tensunitsep}{-}
30165 \end{lcode}
30166 The next example shows how to achieve American typesetting.
30167 \begin{egsource}{eg:maxnum}
30168 \renewcommand*{\namenumberand}{ }
30169 \renewcommand*{\namenumbercomma}{ }
30170 The maximum number in TeX is \numtoname{2147483647}
30171 (i.e., \cardinal{2147483647}).
30172 \end{egsource}
30173 \begin{egresult}[\tx's maximum number in words (American style)]{eg:maxnum}
30174 \renewcommand*{\namenumberand}{ }\renewcommand*{\namenumbercomma}{ }%
30175 The maximum number in TeX is \numtoname{2147483647}
30176 (i.e., \cardinal{2147483647}).
30177 \end{egresult}
30178 \renewcommand*{\namenumberand}{ and }
30179 \renewcommand*{\namenumbercomma}{, }
30180
30181 \begin{syntax}
30182 \cmd{\minusname} \cmd{\lcminusname} \cmd{\ucminusname} \\
30183 \end{syntax}
30184 \glossary(minusname)%
30185 {\cs{minusname}}%
30186 {Typeset for `minus' before negative named numbers.}
30187 \glossary(lcminusname)%
30188 {\cs{lcminusname}}%
30189 {Lowercase `minus' name, default `minus'.}
30190 \glossary(ucminusname)%
30191 {\cs{ucminusname}}%
30192 {Lowercase `minus' name with initial uppercase letter, default `Minus'.}
30193 When a named number is negative, \cmd{\minusname} is put before the
30194 spelled out number. The definitions of the above three comands are:
30195 \begin{lcode}
30196 \newcommand*{\lcminusname}{minus }
30197 \newcommand*{\ucminusname}{Minus }
30198 \let\minusname\lcminusname
30199 \end{lcode}
30200 which means that `minus' is normally all lowercase. To get `minus'
30201 typeset with an initial uppercase letter simply:
30202 \begin{lcode}
30203 \let\minusname\ucminusname
30204 \end{lcode}
30205
30206 Only one version of \cmd{\namenumberand} is supplied as I consider that
30207 it is unlikely that `and' would ever be typeset as `And'. If the initial
30208 uppercase is required, renew the macro when appropriate.
30209
30210 There is a group of macros that hold the names for the numbers. To
30211 typeset named numbers in a language other than English these will have to be
30212 changed as appropriate. You can find them in the class and patch code.
30213 The actual picking and ordering of the names is done by an internal macro
30214 called \cmd{\n@me@number}. If the ordering is not appropriate for a
30215 particular language, that is the macro to peruse and modify. Be prepared,
30216 though, for the default definitions to be changed in a later release in case
30217 there is a more efficient way of implementing their functions.
30218
30219 If you want to express numbers that fall outside \tx's range, Edward
30220 Reingold has produced a set of macros that can write out in words any number
30221 within the range $-10^{66} to 10^{66}$, that is, up to a thousand
30222 vigintillion~\cite{REINGOLD07}.
30223
30224 \subsection{Fractions}
30225
30226 When typesetting a simple fraction in text there is usually a choice
30227 of two styles, like 3/4 or $\frac{3}{4}$, which do not necessarily look
30228 as though they fit in with their surroundings. These fractions were
30229 typeset via:
30230 \begin{lcode}
30231 ... like 3/4 or $\frac{3}{4}$ ...
30232 \end{lcode}
30233
30234 \begin{syntax}
30235 \cmd{\slashfrac}\marg{top}\marg{bottom} \\
30236 \cmd{\slashfracstyle}\marg{num} \\
30237 \end{syntax}
30238 \glossary(slashfrac)%
30239 {\cs{slashfrac}\marg{top}\marg{bottom}}%
30240 {Typesets like \slashfrac{3}{4}, using the \cs{slashfracstyle} font.}
30241 \glossary(slashfracstyle)%
30242 {\cs{slashfracstyle}\marg{num}}%
30243 {Typesets \meta{num} in a particular (font, size) style.}
30244 The class provides the \cmd{\slashfrac} command which typesets its
30245 arguments like \slashfrac{3}{4}. Unlike the \cmd{\frac} command which
30246 can only be used in math mode, the \cmd{\slashfrac} command can be
30247 used in text and math modes.
30248
30249 The \cmd{\slashfrac} macro calls the \cmd{\slashfracstyle} command to
30250 reduce the size of the numbers in the fraction. You can also use
30251 \cmd{\slashfracstyle} by itself.
30252 \begin{egsource}{eg:fractions}
30253 In summary, fractions can be typeset like 3/4 or $\frac{3}{4}$
30254 or \slashfrac{3}{4} or \slashfracstyle{3/4} because several choices
30255 are provided.
30256 \end{egsource}
30257 \begin{egresult}[Varieties of fractions in text]{eg:fractions}
30258 In summary, fractions can be typeset like 3/4 or $\frac{3}{4}$
30259 or \slashfrac{3}{4} or \slashfracstyle{3/4} because several choices
30260 are provided.
30261 \end{egresult}
30262
30263 \begin{syntax}
30264 \cmd{\textsuperscript}\marg{super} \\
30265 \cmd{\textsubscript}\marg{sub} \\
30266 \end{syntax}
30267 \glossary(textsuperscript)%
30268 {\cs{textsuperscript}\marg{super}}%
30269 {Typesets \meta{super} as a superscript.}
30270 \glossary(textsubscript)%
30271 {\cs{textsubscript}\marg{sub}}%
30272 {Typesets \meta{sub} as a subscript.}
30273 While on the subject of moving numbers up and down, the kernel provides
30274 the \cmd{\textsuperscript} macro for typesetting its argument as though it
30275 is a superscript it also provides the \cmd{\textsubscript} macro
30276 for typesetting its argument like a subscript.
30277
30278 \begin{egsource}{eg:textsupsub}
30279 In normal text you can typeset superscripts like H\textsuperscript{+} and
30280 subscripts like H\textsubscript{2}O without going into math mode.
30281 \end{egsource}
30282 \begin{egresult}[Super- and subscripts in text]{eg:textsupsub}
30283 In normal text you can typeset superscripts like H\textsuperscript{+} and
30284 subscripts like H\textsubscript{2}O without going into math mode.
30285 \end{egresult}
30286 Though for chemical compounds packages like \Lpack{mhchem} and
30287 \Lpack{chemmacros} are worth a time saving look.
30288
30289
30290 \section{An array data structure}
30291
30292 \begin{note}
30293 For new projects, it is probably a better idea to have a look at
30294 what the Expl3 layer provides. It has several very useful
30295 datastructures and tools to manipulate these. See \cite{EXPL3} for
30296 details.
30297 \end{note}
30298
30299 \noindent
30300
30301 The class includes some macros for supporting the \Ie{patverse}
30302 environment which may be more generally useful.
30303
30304 \begin{syntax}
30305 \cmd{\newarray}\marg{arrayname}\marg{low}\marg{high} \\
30306 \end{syntax}
30307 \glossary(newarray)%
30308 {\cs{newarray}\marg{arrayname}\marg{low}\marg{high}}%
30309 {Defines a new indexed array datastructure called \meta{arrayname}
30310 with the (integer) index ranging from \meta{low} to \meta{high}.}
30311
30312 \cmd{\newarray} defines
30313 the \meta{arrayname} array, where \meta{arrayname} is a name like
30314 \texttt{MyArray}. The lowest and highest array indices are set to
30315 \meta{low} and \meta{high} respectively, where both are integer numbers.
30316
30317 \begin{syntax}
30318 \cmd{\setarrayelement}\marg{arrayname}\marg{index}\marg{text} \\
30319 \cmd{\getarrayelement}\marg{arrayname}\marg{index}\marg{result} \\
30320 \end{syntax}
30321 \glossary(setarrayelement)%
30322 {\cs{setarrayelement}\marg{arrayname}\marg{index}\marg{text}}%
30323 {Makes \meta{text} the contents of the \marg{index} location in
30324 array \meta{arrayname}.}
30325 \glossary(getarrayelement)%
30326 {\cs{getarrayelement}\marg{arrayname}\marg{index}\marg{result}}%
30327 {Sets the parameterless macro \meta{result} to the contents of
30328 the \marg{index} location in array \meta{arrayname}.}
30329
30330 The \cmd{\setarrayelement} macro
30331 sets the \meta{index} location in the \meta{arrayname} array to be
30332 \meta{text}. Conversely, \cmd{\getarrayelement} sets the parameterless
30333 macro \meta{result} to the contents of
30334 the \meta{index} location in the \meta{arrayname} array.
30335 For example:
30336 \begin{lcode}
30337 \setarrayelement{MyArray}{23}{$2^{23}$}
30338 \getarrayelement{MyArray}{23}{\result}
30339 \end{lcode}
30340 will result in \verb?\result? being defined as \verb?\def\result{$2^{23}$}?.
30341
30342 \begin{syntax}
30343 \cmd{\checkarrayindex}\marg{arrayname}\marg{index} \\
30344 \piif{ifbounderror} \\
30345 \end{syntax}
30346 \glossary(checkarrayindex)%
30347 {\cs{checkarrayindex}\marg{arrayname}\marg{index}}%
30348 {Checks if \meta{index} is a valid index value for the array
30349 \meta{arrayname}. Sets \cs{ifbounderror} \ptrue\ if there is a problemn
30350 otherwise \pfalse.}
30351 \cmd{\checkarrayindex} checks if
30352 \meta{arrayname} is an array and if \meta{index} is a valid index for
30353 the array. If both conditions hold then \piif{ifbounderror} is set
30354 \pfalse, but if either \meta{arrayname} is not an array or, if it is,
30355 \meta{index} is out of range then \piif{ifbounderror} is set \ptrue.
30356
30357 \begin{syntax}
30358 \cmd{\stringtoarray}\marg{arrayname}\marg{string} \\
30359 \cmd{\arraytostring}\marg{arrayname}\marg{result} \\
30360 \end{syntax}
30361 \glossary(stringtoarray)%
30362 {\cs{stringtoarray}\marg{arrayname}\marg{string}}%
30363 {Puts each character from \meta{string} sequentially into array
30364 \meta{arrayname}, starting at index 1.}
30365 \glossary(arraytostring)%
30366 {\cs{arraytostring}\marg{arrayname}\marg{result}}%
30367 {Defines the macro \meta{result} to be the sequence of characters
30368 in the array \meta{arrayname}.}
30369 The macro \cmd{\stringtoarray} puts each character
30370 from \meta{string} sequentially into the \meta{arrayname} array, starting
30371 at index 1.
30372 The macro \cmd{\arraytostring} assumes
30373 that \meta{arrayname} is an array of characters, and defines the macro
30374 \meta{result} to be that sequence of characters. For example: \\
30375 \begin{lcode}
30376 \stringtoarray{MyArray}{Chars}
30377 \arraytostring{MyArray}{\MyString}
30378 \end{lcode}
30379 is equivalent to
30380 \begin{lcode}
30381 \def\MyString{Chars}
30382 \end{lcode}
30383
30384 \begin{syntax}
30385 \cmd{\checkifinteger}\marg{num} \\
30386 \piif{ifinteger} \\
30387 \end{syntax}
30388 \glossary(checkifinteger)%
30389 {\cs{checkifinteger}\marg{num}}%
30390 {If \meta{num} is an integer and not less than zero, sets \cs{ifinteger}
30391 \ptrue, otherwise \pfalse.}
30392 The command \cmd{\checkifinteger} ckecks if \meta{num} is an integer
30393 (not less than zero). If it is then \piif{ifinteger} is set \ptrue,
30394 otherwise it is set \pfalse.
30395 %
30396 \begin{note}
30397 Please note that \cmd{\checkifinteger} may only work on simple input.
30398 \end{note}
30399
30400
30401 \section{Checking the processor}
30402
30403 Here the class loads the general \Lpack{iftex} package, see
30404 \cite{IFTEX} for details. We will list a few below.
30405
30406
30407 \subsection{Checking for pdfLaTeX}
30408
30409 Since both \ltx\ and \pixpdfltx\ actually run on \Lprog{pdfetex},
30410 where one provide DVI output and the other PDF. A proper test for
30411 \pixpdfltx\ will be
30412 \begin{syntax}
30413 \piif{ifpdftex}\\
30414 \quad\piif{ifpdf}\\
30415 \qquad... \\
30416 \quad\verb?\fi? \\
30417 \verb?\fi?
30418 \end{syntax}
30419 Note that \verb?\ifpdf...\fi? is \emph{not} enough as it only test if the current engine is capable of producing PDF.
30420 %
30421 In case you just want to load something under \ltx/\pixpdfltx\ but not under XeLaTeX/LuaLaTeX, use
30422 %
30423 \begin{syntax}
30424 \piif{iftutex}\\
30425 \verb?\else?\\
30426 \qquad \meta{code for \ltx\ or \pixpdfltx} \\
30427 \verb?\fi?
30428 \end{syntax}
30429
30430
30431
30432
30433 % Both \ltx\ and \pixpdfltx\ can be run on the same document. \ltx\ produces
30434 % a \file{.dvi} file as output, while \pixpdfltx\ can produce either a
30435 % \file{.dvi} or a \file{.pdf} file.
30436 % On modern systems \pixpdfltx\ produces a \file{pdf} file by default.
30437
30438 % If you want a \file{dvi} file output use \ltx\ and if you want a
30439 % \file{pdf} file use \pdfltx.
30440
30441 % \begin{syntax}
30442 % \piif{ifpdf} ... \verb?\fi? \\
30443 % \end{syntax}
30444 % The class provides \piif{ifpdf} (by autoloading the \Lpack{iftex}
30445 % package) which is \ptrue\ when the document is being processed by
30446 % \pixpdfltx\ and \pfalse\ otherwise. You can use it like this:
30447 % \begin{lcode}
30448 % \ifpdf
30449 % code for pdfLaTeX only
30450 % \else
30451 % code for LaTeX only
30452 % \fi
30453 % \end{lcode}
30454 % If there is no \ltx\ specific code then don't write the \verb?\else? part.
30455
30456 % \subsection{Checking for etex}
30457
30458 % Modern \ltx\ distributions use \pixetx, which is an extended version
30459 % of \tx, as the underlying engine. \pixetx\ provides some more primitives
30460 % than \tx, which may be useful, but not everybody has \pixetx\
30461 % available (Though, as of 2018, this is \emph{very} rare).
30462
30463 % \begin{syntax}
30464 % \piif{ifetex} \\
30465 % \end{syntax}
30466 % \glossary(ifetex)%
30467 % {\cs{ifetex}}%
30468 % {\ptrue\ if \etx\ is the underlying engine, otherwise \pfalse.}
30469 % \piif{ifetex} can be used to determine if \pixetx\ is being used as
30470 % the underlying engine; it is analagous to \piif{ifpdf} which tests for
30471 % \pixpdfltx\ (provided by autoloading the \Lpack{iftex} package). For
30472 % example:
30473 % \begin{lcode}
30474 % \ifetex
30475 % %%% code only processible by etex
30476 % \else
30477 % \typeout{etex is not available}
30478 % \fi
30479 % \end{lcode}
30480
30481
30482 \subsection{Checking for XeTeX}
30483
30484 This is an engine test:
30485 \begin{syntax}
30486 \piif{ifxetex} ... \verb?\fi? \\
30487 \end{syntax}
30488 \glossary(ifxetex)%
30489 {\cs{ifxetex}}%
30490 {\ptrue\ if \xetx\ is being used to process the document.}
30491
30492 In a similar manner you can use \piif{ifxetex} to check if the
30493 document is being processed by \pixxetx\ (provided by autoloading
30494 the \Lpack{iftex} package).
30495
30496 % \begin{syntax}
30497 % \cmd{\RequireXeTeX} \\
30498 % \end{syntax}
30499 % \glossary(RequireXeTeX)%
30500 % {\cs{RequireXeTeX}}%
30501 % {Generates an error if the document is not being processed by \xetx.}
30502 % The \Lpack{iftex} package also provides \cmd{\RequireXeTeX}, which
30503 % generates an error if \pixxetx\ is not being used to process the
30504 % document. This can be useful if you make your own class building upon
30505 % \Lclass{memoir}.
30506
30507 \subsection{Checking for LuaTeX}
30508 \label{sec:checking-lualatex}
30509
30510 Engine test:
30511 \begin{syntax}
30512 \piif{ifluatex} ... \verb?\fi? \\
30513 \end{syntax}
30514 \glossary(ifluatex)%
30515 {\cs{ifluatex}}%
30516 {\ptrue\ if \luatx\ is being used to process the document.}
30517 to check if the doc is being process by \luatx. Again provided by
30518 loading \Lpack{iftex}.
30519
30520 Do remember there the pseudo test \cs{iftutex} which is true whenever
30521 \cs{Umathchardef} is available, which essentially is Xe(La)TeX and
30522 Lua(La)TeX.
30523
30524
30525 \section{Leading}
30526
30527 LaTeX automatically uses different leading\index{leading} for different
30528 font sizes.
30529 \begin{syntax}
30530 \lnc{\baselineskip} \lnc{\onelineskip} \\
30531 \end{syntax}
30532 \glossary(onelineskip)%
30533 {\ls{onelineskip}}%
30534 {Distance between baselines of the document's main font and size.}
30535
30536 At any point in a document the standard LaTeX \lnc{\baselineskip} length
30537 contains the current value of the leading\footnote{This statement ignores
30538 any attempts to stretch the baseline.}. The class provides the length
30539 \lnc{\onelineskip} which contains the initial leading for the normal
30540 font. This value is useful if you are wanting to specify length values
30541 in terms of numbers of lines of text.
30542
30543 \section{Minor space adjustment}
30544
30545 The kernel provides the \cmd{\,} macro for inserting a thin space in both
30546 text and math mode. There are
30547 other space adjustment commands, such as \pixabang\ for negative thin space,
30548 and \cmd{\:} and \cmd{\;} for medium
30549 and thick spaces, which can only be used in math mode.
30550
30551 \begin{syntax}
30552 \cmd{\thinspace} \cmd{\medspace} \cmd{\:} \pixabang \\
30553 \end{syntax}
30554 \glossary(thinspace)%
30555 {\cs{thinspace}}%
30556 {A thin space (3/18 em).}
30557 \glossary(medspace)%
30558 {\cs{medspace}}%
30559 {A medium space (4/18 em).}
30560 \glossary(:)%
30561 {\cs{:}}%
30562 {A medium space (4/18 em).}
30563 \glossary(!)%
30564 {\cs{!}}%
30565 {A negative thin space (-3/18 em).}
30566 On occasions I have found it useful to be able to tweak spaces in text by some
30567 fixed amount, just as in math mode. The kernel macro \cmd{\thinspace}
30568 specifies a thin space, which is 3/18\,em.
30569 The class \cmd{\medspace} specifies a medium space of 4/18\,em.
30570 As mentioned, the kernel macro \cmd{\:} inserts
30571 a medium space in math mode. The class version can be used in both math and
30572 text mode to insert a medium space. Similarly, the class version of
30573 \pixabang{}
30574 can be used to insert a negative thin space in both text and math mode.
30575
30576 The math thick space is 5/18\,em.
30577 To specify this amount of space
30578 in text mode you can combine spacing commands as:
30579 \begin{lcode}
30580 \:\:\!
30581 \end{lcode}
30582 which will result in an overall space of 5/18\,em
30583 (from $(4 + 4 - 3)/18$).
30584
30585
30586 \section{Adding a period}
30587
30588 Much earlier, when showing the code for the sectional division styles
30589 for this document, I used the macro \cmd{\addperiod}.
30590
30591 \begin{syntax}
30592 \cmd{\addperiod}\marg{text} \\
30593 \end{syntax}
30594 This puts a period (a full stop) at the end of \meta{text}. I used it to
30595 add a period at the end of the \cmd{\paragraph} and \cmd{\subparagaph} titles.
30596 When sectional titles, like \cmd{\paragraph} are run-in, it is customary to
30597 end them with a period (or occasionally a colon).
30598
30599
30600
30601 \section{Words and phrases}
30602
30603 The class provides several macros that expand into English words or
30604 phrases. To typeset in another language these need to be changed, or an
30605 author or publisher may want some changes made to the English versions.
30606 \tref{tab:defwordsphrases} lists the macros, their default values,
30607 and where they used.
30608 % \begin{comment}
30609 % \begin{itemize}
30610 % \item[\cmd{\abstractname}] \abstractname\ --- title for \Ie{abstract} environment
30611 % \item[\cmd{\alsoname}] \alsoname\ --- used by \cmd{\seealso}
30612 % \item[\cmd{\amname}] \amname\ --- used in printing time of day
30613 % \item[\cmd{\appendixname}] \appendixname\--- name for an appendix heading
30614 % \item[\cmd{\appendixpagename}] \appendixpagename\ --- name for an \cmd{\appendixpage}
30615 % \item[\cmd{\appendixtocname}] \appendixtocname\ --- ToC entry announcing appendices
30616 % \item[\cmd{\bibname}] \bibname\ --- title for \cmd{\thebibliography} title
30617 % \item[\cmd{\bookname}] \bookname\ --- name for \cmd{\book} heading
30618 % \item[\cmd{\bookrefname}] \bookrefname\ --- used by \cmd{\Bref}
30619 % (defined as \verb?\newcommand{\bookrefname}{Book~}?)
30620
30621 % \item[\cmd{\chaptername}] \chaptername\ --- name for \cmd{chapter} heading
30622 % \item[\cmd{\chapterrefname}] \chapterrefname\ --- used by \cmd{\Cref}
30623 % (defined as \verb?\newcommand{\chapterrefname}{Chapter~}?)
30624 % \item[\cmd{\contentsname}] \contentsname\ --- title for \cmd{\tableofcontents}
30625
30626 % \item[\cmd{\figurename}] \figurename\ --- name for figure \cmd{\caption}
30627 % \item[\cmd{\figurerefname}] \figurerefname\ --- used by \cmd{\fref}
30628
30629 % \item[\cmd{\glossaryname}] Glossary --- title for \cmd{\theglossary}
30630
30631 % \item[\cmd{\indexname}] \indexname\ --- title for \cmd{\theindex}
30632
30633 % \item[\cmd{\lcminusname}] \lcminusname\ --- used in named number formatting
30634 % \item[\cmd{\listfigurename}] \listfigurename\ --- title for \cmd{\listoffigugres}
30635 % \item[\cmd{\listtablename}] \listtablename\ --- title for \cmd{\listoftables}
30636
30637 % \item[\cmd{\minusname}] \minusname\ --- used in named number formatting
30638
30639 % \item[\cmd{\namenumberand}] \namenumberand\ --- used in named number formatting
30640 % \item[\cmd{\namenumbercomma}] \namenumbercomma\ --- used in named number formatting
30641 % \item[\cmd{\notesname}] \notesname\ --- title of \cmd{\notedivision}
30642
30643 % \item[\cmd{\pagename}] \pagename\ --- for your use
30644 % \item[\cmd{\pagerefname}] \pagerefname\ --- used by \cmd{\pref}
30645 % \item[\cmd{\partname}] \partname\ --- name for \cmd{\part} heading
30646 % \item[\cmd{\partrefname}] \partrefname\ --- used by \cmd{\Pref}
30647 % (defined as \verb?\newcommand{\partrefname}{Part~}?)
30648 % \item[\cmd{\pmnane}] \pmname\ --- used in printing time of day
30649
30650 % \item[\cmd{\sectionrefname}] \sectionrefname\ --- used by \cmd{\Sref}
30651 % (defined as \verb?\newcommand{\sectionrefname}{\S}?)
30652 % \item[\cmd{\seename}] \seename\ --- used by \cmd{\see}
30653
30654 % \item[\cmd{\tablename}] \tablename\ --- name for table \cmd{\caption}
30655 % \item[\cmd{\tablerefname}] \tablerefname\ --- used by \cmd{\tref}
30656
30657 % \item[\cmd{\ucminusname}] \ucminusname\ --- used in named number formatting
30658
30659 % \end{itemize}
30660 % \end{comment}
30661
30662 \begin{table}
30663 \centering
30664 \caption{Some defined words and phrases. The term \textsuperscript{*}
30665 marks macros under language control (\Lpack{babel}), see the
30666 \cs{setlocalecaption} (old way:
30667 \cs{addto}\cs{captions}\meta{language}) feature in \Lpack{babel} for
30668 how to properly change them. Note that these should \emph{never}
30669 contain formatting such as bold etc.}\label{tab:defwordsphrases}
30670 \newcommand\B{\textsuperscript{*}}
30671 \begin{tabular}{lll}\toprule
30672 Macro & Default & Usage \\ \midrule
30673 \cmd{\abstractname} & \abstractname\B & title for \Ie{abstract} environment \\
30674 \cmd{\alsoname} & \alsoname\B & used by \cmd{\seealso} \\
30675 \cmd{\amname} & \amname\ & used in printing time of day \\
30676 \cmd{\appendixname} & \appendixname\B & name for an appendix heading \\
30677 \cmd{\appendixpagename} & \appendixpagename\ & name for an \cmd{\appendixpage} \\
30678 \cmd{\appendixtocname} & \appendixtocname\ & ToC entry announcing appendices \\
30679 \cmd{\bibname} & \bibname\B & title for \cmd{\thebibliography} \\
30680 \cmd{\bookname} & \bookname\ & name for \cmd{\book} heading \\
30681 \cmd{\bookrefname} & \bookrefname\ & used by \cmd{\Bref} \\
30682 \cmd{\chaptername} & \chaptername\B & name for \cmd{\chapter} heading \\
30683 \cmd{\chapterrefname} & \chapterrefname\ & used by \cmd{\Cref} \\
30684 \cmd{\contentsname} & \contentsname\B & title for \cmd{\tableofcontents} \\
30685 \cmd{\figurename} & \figurename\B & name for figure \cmd{\caption} \\
30686 \cmd{\figurerefname} & \figurerefname\ & used by \cmd{\fref} \\
30687 \cmd{\glossaryname} & Glossary & title for \cmd{\theglossary} \\
30688 \cmd{\indexname} & \indexname\B & title for \cmd{\theindex} \\
30689 \cmd{\lcminusname} & \lcminusname\ & used in named number formatting \\
30690 \cmd{\listfigurename} & \listfigurename\B & title for \cmd{\listoffigugres} \\
30691 \cmd{\listtablename} & \listtablename\B & title for \cmd{\listoftables} \\
30692 \cmd{\minusname} & \minusname\ & used in named number formatting \\
30693 \cmd{\namenumberand} & \namenumberand\ & used in named number formatting \\
30694 \cmd{\namenumbercomma} & \namenumbercomma\ & used in named number formatting \\
30695 \cmd{\notesname} & \notesname\ & title of \cmd{\notedivision} \\
30696 \cmd{\pagename} & \pagename\ & for your use \\
30697 \cmd{\pagerefname} & \pagerefname\ & used by \cmd{\pref} \\
30698 \cmd{\partname} & \partname\B & name for \cmd{\part} heading \\
30699 \cmd{\partrefname} & \partrefname\ & used by \cmd{\Pref} \\
30700 \cmd{\pmnane} & \pmname\ & used in printing time of day \\
30701 \cmd{\sectionrefname} & \sectionrefname\ & used by \cmd{\Sref} \\
30702 \cmd{\seename} & \seename\B & used by \cmd{\see} \\
30703 \cmd{\tablename} & \tablename\B & name for table \cmd{\caption} \\
30704 \cmd{\tablerefname} & \tablerefname\ & used by \cmd{\tref} \\
30705 \cmd{\ucminusname} & \ucminusname\ & used in named number formatting \\
30706 \bottomrule
30707 \end{tabular}
30708 \end{table}
30709
30710 Most, if not all, of the tabulated definitions are simple --- for example
30711 \begin{lcode}
30712 \newcommand*{\partname}{Part}
30713 \newcommand*{\partrefname}{Part~}
30714 \end{lcode}
30715 and so can be also changed simply.
30716
30717 The definitions of the macros for the names of numbers are more complex
30718 --- for example for the number 11 (eleven)
30719 \begin{lcode}
30720 \newcommand*{\nNamexi}{\iflowertonumname e\else E\fi leven}
30721 \end{lcode}
30722 That is, each definition includes both a lowercase and an uppercase initial
30723 letter, so a bit more care has to be taken when changing these. For specifics
30724 read the documentation of the class code.
30725
30726 \section{Symbols}
30727
30728 LaTeX lets you typeset an enormous variety of symbols.\index{symbol}
30729 The class adds
30730 nothing to the standard LaTeX capabilities in this respect.
30731 If you want to see what symbols are available then get a copy
30732 of Scott Pakin's
30733 \textit{The Comprehensive LaTeX Symbol List}~\cite{SYMBOLS}.
30734 You may have to do a little experimentation to get what you want, though.
30735
30736 For example, the \cmd{\texttrademark} command
30737 produces the trademark\index{trademark} symbol\texttrademark,
30738 but the \cmd{\textregistered} command produces\textregistered.
30739 When I wanted to use the registered trademark\index{registered trademark}
30740 symbol it needed to be
30741 typeset like a superscript
30742 instead of on the baseline. The \cmd{\textsuperscipt} macro typesets
30743 its argument like a superscript\index{superscript}, so using
30744 \begin{lcode}
30745 \textsuperscript{\textregistered}
30746 \end{lcode}
30747 gave the required result\textsuperscript{\textregistered}.
30748
30749
30750
30751
30752 \section{Two simple macros}
30753
30754 There are two trivial macros that can be generally useful.
30755 \begin{syntax}
30756 \cmd{\memjustarg}\marg{text} \\
30757 \cmd{\memgobble}\marg{text} \\
30758 \end{syntax}
30759 \glossary(memjustarg)%
30760 {\cs{memjustarg}\marg{text}}%
30761 {Definition is just \meta{text}. Do \emph{not} redefine it.}%
30762 \glossary(memgobble)%
30763 {\cs{memgobble}\marg{text}}%
30764 {Gobbles its argument. Do \emph{not} redefine it.}%
30765
30766 The \cmd{\memjustarg} macro just uses its argument and is defined as:
30767 \begin{lcode}
30768 \newcommand*{\memjustarg}[1]{#1}
30769 \end{lcode}
30770
30771 The \cmd{\memgobble} macro gobbles down and swallows its argument.
30772 Its definition is:
30773 \begin{lcode}
30774 \newcommand{\memgobble}[1]{}
30775 \end{lcode}
30776
30777 Do \emph{not} redefine either \cmd{\memjustarg} or \cmd{\memgobble}; if
30778 you do various pieces of code will behave in unexpected ways that you
30779 will not like.
30780
30781 The Expl3 layer has a plethora of similar macros, e.g. macros that
30782 expects three arguments and only leaves number two.
30783
30784
30785 \section{Vertical centering}
30786
30787 \indextwo{vertical}{centering}
30788 Earlier there was a description of a method for centering text vertically.
30789 The \Ie{vplace} environment provides a simpler and more general way.
30790 \begin{syntax}
30791 \senv{vplace}\oarg{num} text \eenv{vplace} \\
30792 \end{syntax}
30793 \glossary(vplace)%
30794 {\senv{vplace}\oarg{num}}%
30795 {The contents of this environment are centered vertically. The optional
30796 \meta{num} argument can be used to specify the ratio of the upper space
30797 to the lower space.}%
30798
30799 The contents of the \Ie{vplace} environment are vertically centered.
30800 The optional \meta{num} argument can be used to specify the ratio of the
30801 upper space to the lower space. You can put other text on the page above
30802 or below the centered text. The environment may be useful for
30803 title pages\index{title page}.
30804
30805 \section{For package writers}
30806
30807 The facilities described in this section are for anyone to use but
30808 I suspect that they may be most useful to package developers.
30809
30810 \subsection{Emulating packages}
30811
30812 \begin{syntax}
30813 \cmd{\EmulatedPackage}\marg{package}\oarg{date} \\
30814 \cmd{\EmulatedPackageWithOptions}\marg{optionlist}\marg{package}\oarg{date} \\
30815 \end{syntax}
30816 \glossary(EmulatedPackage)%
30817 {\cs{EmulatedPackage}\marg{package}\oarg{date}}%
30818 {Claim that the \meta{package} package has been loaded.}%
30819 \glossary(EmulatedPackageWithOptions)%
30820 {\cs{EmulatedPackageWithOptions}\marg{optionlist}\marg{package}\oarg{date}}%
30821 {Claim that the \meta{package} package has been loaded with options
30822 \meta{optionlist}.}%
30823 These commands are for package writers; they are based on a conversation with
30824 Donald Arseneau\index{Arseneau, Donald} on \ctt. They fool \ltx\ into
30825 thinking that the \meta{package} has already been loaded so it won't
30826 try loading it again. These are probably only useful if your
30827 package includes the actual code for \meta{package}.
30828
30829 \Mname\ does include code from several packages and uses
30830 a similar internal command to ensure that the packages are not
30831 loaded following some later \cmd{\usepackage} command. The names of the
30832 emulated packages are written to the \pixfile{log} file. At the time
30833 of writing the emulated packages are:
30834 \Lpack{abstract},
30835 \Lpack{appendix},
30836 %\Lpack{array},
30837 \Lpack{booktabs},
30838 \Lpack{ccaption},
30839 \Lpack{chngcntr},
30840 \Lpack{crop},
30841 % \Lpack{dcolumn},
30842 %\Lpack{delarray},
30843 \Lpack{enumerate},
30844 \Lpack{epigraph},
30845 %%%%%% \Lpack{framed},
30846 \Lpack{ifmtarg},
30847 \Lpack{ifpdf},
30848 \Lpack{index},
30849 \Lpack{makeidx},
30850 \Lpack{moreverb},
30851 \Lpack{needspace},
30852 \Lpack{newfile},
30853 \Lpack{nextpage},
30854 \Lpack{pagenote},
30855 \Lpack{patchcmd},
30856 \Lpack{parskip},
30857 \Lpack{setspace},
30858 \Lpack{shortvrb},
30859 \Lpack{showidx},
30860 %\Lpack{tabularx},
30861 \Lpack{titleref},
30862 \Lpack{tocbibind},
30863 \Lpack{tocloft},
30864 \Lpack{verbatim},
30865 and
30866 \Lpack{verse}.
30867 As well as the emulated packages \Mname\ provides functions
30868 inspired from those in the following packages:
30869 \Lpack{fancyhdr}, \Lpack{framed}, \Lpack{geometry}, \Lpack{sidecap},
30870 \Lpack{subfigure}, and \Lpack{titlesec}.
30871
30872
30873
30874 \begin{syntax}
30875 \cmd{\DisemulatePackage}\marg{package} \\
30876 \end{syntax}
30877 \glossary(DisemulatePackage)%
30878 {\cs{DisemulatePackage}\marg{package}}%
30879 {Undo a previous \cs{EmulatedPackage} or \cs{EmulatedPackageWithOptions}
30880 for the \meta{package} package.}%
30881 This command undoes any prior \cmd{\EmulatedPackage} or
30882 \cmd{\EmulatedPackageWithOptions} for the \meta{package} package. For example,
30883 if you wish to use the \Lpack{index} package instead of \Mname's
30884 emulation then put
30885 \begin{lcode}
30886 \DisemulatePackage{index}
30887 \usepackage{index}
30888 \end{lcode}
30889 in your preamble.
30890
30891
30892
30893 \subsection{Inserting code before and after a file, package or class}
30894
30895 \begin{Changed}
30896 As of \LaTeX\ format dated 2020/10/01 these \cs{At...} macros
30897 described below will be implemented using kernel hooks as layed out
30898 via \cite{LTFILEHOOK}. Which also means the order of the hooks can
30899 actually be changed. See \cite{LTHOOKS} for general information
30900 about the hooking feature.
30901 \end{Changed}
30902
30903 \begin{caveat}
30904 In the \marg{code} part of the hooks, any use of \# needs to be
30905 doubled. Thus if you want to redefine the macro \cs{foo} which takes
30906 an argument at the end of package \textsf{bar}, you need to use
30907 \begin{verbatim}
30908 \AtEndPackage{bar}{
30909 \renewcommand\foo[1]{something something ##1}
30910 }
30911 \end{verbatim}
30912 In the format coming after 2020/10/01 we actually only needed a single
30913 \#, but then our code is not backwards compatible, so the \#\ is now
30914 forced even in the new emplementation.
30915 \end{caveat}
30916
30917 The kernel provides two commands, \cmd{\AtBeginDocument}
30918 and \cmd{\AtEndDocument} which can only be used in the preamble,
30919 for inserting code at the start and end
30920 of the \Ie{document} environment.
30921
30922 The kernel also provides the macros
30923 \cmd{\AtEndOfPackage}\marg{code} and \cmd{\AtEndOfClass}\marg{code}
30924 for inserting code at the end of the current package or class. More precisely,
30925 these macros call the \meta{code} after the package or class file has been
30926 input via \cmd{\InputIfFileExists}.
30927
30928 The class provides a more comprensive set of macros for code
30929 insertions, which should be used before the relevant file is called for.
30930
30931 \begin{syntax}
30932 \cmd{\AtBeginFile}\marg{filename}\marg{code} \\
30933 \cmd{\AtEndFile}\marg{filename}\marg{code} \\
30934 \end{syntax}
30935 \glossary(AtBeginFile)%
30936 {\cs{AtBeginFile}\marg{filename}\marg{code}}%
30937 {Inserts \meta{code} just before the \meta{filename} is input
30938 (or included, etc.).}%
30939 \glossary(AtEndFile)%
30940 {\cs{AtEndFile}\marg{filename}\marg{code}}%
30941 {Inserts \meta{code} just after the \meta{filename} is input
30942 (or included, etc.).}%
30943 The \cmd{\AtBeginFile} macro inserts \meta{code} just before the
30944 \meta{filename} file is \cmd{\input} (or \cmd{\include}d,
30945 etc.). Similarly \cmd{\AtEndFile} inserts the \meta{code}
30946 immediately after the \meta{filename}. The \meta{filename} argument
30947 must be the same as used in the corresponding \cmd{\input}
30948 command. If \meta{filename} includes an extension, for example
30949 \texttt{fred.def}, then that is taken as the complete name,
30950 otherwise if there is no extension, for instance \texttt{fred}, then
30951 the \texttt{.tex} extension is automatically appended making the
30952 full name \texttt{fred.tex}.
30953
30954 The \cs{At...File} commands
30955 must be issued \emph{before} the corresponding \meta{filename} is input
30956 otherwise nothing will happen.
30957
30958 \begin{caveat}
30959 As of \LaTeX\ format 2020/10/01 this is \textbf{no longer true!} You
30960 will now have to provide the \texttt{.tex} extension if it is a
30961 \texttt{.tex} file you want to hook into, as in:
30962 \begin{verbatim}
30963 \AtEndFile{test.tex}{\typeout{test.tex is done}}
30964 \end{verbatim}
30965 Also note that the 2020/10/01 format will have some specific hooks
30966 what apply to \cmd{\include}. The class does not provide an
30967 interface for this and instead refers to \cite{LTFILEHOOK}.
30968
30969 Note that \cmd{\At...File} actually did not work correctly for
30970 \cmd{\include} in the old implementation, it still needed the
30971 extension! In this new implementation both \cmd{\input} and
30972 \cmd{\include} trigger.
30973 \end{caveat}
30974 \begin{Changed}
30975 By the 2020/10/01 format this is now implemented via the
30976 \texttt{file/before/filename} and \texttt{file/after/filename}
30977 hooks. We are not adding any hook label.
30978 \end{Changed}
30979
30980
30981
30982
30983 \begin{syntax}
30984 \cmd{\AtBeginPackage}\marg{pack}\marg{code} \\
30985 \cmd{\AtEndPackage}\marg{pack}\marg{code} \\
30986 \cmd{\RequireAtEndPackage}\marg{pack}\marg{code} \\
30987 \end{syntax}
30988 \glossary(AtBeginPackage)%
30989 {\cs{AtBeginPackage}\marg{pack}\marg{code}}%
30990 {Inserts \meta{code} just before the \meta{pack} package is used.}%
30991 \glossary(AtEndPackage)%
30992 {\cs{AtEndPackage}\marg{pack}\marg{code}}%
30993 {Inserts \meta{code} just after the \meta{pack} package is used.}%
30994 \glossary(RequireAtEndPackage)%
30995 {\cs{RequireAtEndPackage}\marg{pack}\marg{code}}%
30996 {Inserts \meta{code} just after the \meta{pack} package is used,
30997 or immediately if \meta{pack} has already been used.}%
30998 The \cmd{\AtBeginPackage} command will insert \meta{code} just before the
30999 \meta{pack} package is used. Similarly
31000 \cmd{\AtEndPackage} will insert the \meta{code} immediately after the
31001 \meta{pack}. The \meta{pack} argument must be the same as used in the
31002 corresponding \cmd{\usepackage} command, that is, without any
31003 extension. The \cs{At...Package} commands
31004 must be issued \emph{before} the corresponding \meta{pack} is used
31005 otherwise nothing will happen.
31006
31007 The \cmd{\RequireAtEndPackage} command will,
31008 like \cmd{\AtEndPackage}, insert \meta{code}
31009 at the end of the \meta{pack} package if it has not yet been used.
31010 If the package has already been used then the \meta{code} is
31011 called immediately.
31012
31013 \begin{Changed}
31014 By the 2020/10/01 format this is now implemented via the
31015 \texttt{package/before/pack} and \texttt{package/after/pack}
31016 hooks. We are not adding any hook label.
31017 \end{Changed}
31018
31019
31020
31021
31022 \begin{syntax}
31023 \cmd{\AtBeginClass}\marg{class}\marg{code} \\
31024 \cmd{\AtEndClass}\marg{class}\marg{code} \\
31025 \cmd{\RequireAtEndClass}\marg{class}\marg{code} \\
31026 \end{syntax}
31027 \glossary(AtBeginClass)%
31028 {\cs{AtBeginClass}\marg{pack}\marg{code}}%
31029 {Inserts \meta{code} just before the \meta{class} class is used.}%
31030 \glossary(AtEndClass)%
31031 {\cs{AtEndClass}\marg{class}\marg{code}}%
31032 {Inserts \meta{code} just after the \meta{class} class is used.}%
31033 \glossary(RequireAtEndClass)%
31034 {\cs{RequireAtEndClass}\marg{class}\marg{code}}%
31035 {Inserts \meta{code} just after the \meta{class} class is used,
31036 or immediately if \meta{class} has already been used.}%
31037 The \cmd{\AtBeginClass} command will insert \meta{code} just before the
31038 \meta{class} class is used. Similarly
31039 \cmd{\AtEndClass} will insert the \meta{code} immediately after the
31040 \meta{class}. The \meta{class} argument must be the same as used in the
31041 corresponding \cmd{\LoadClass} command, that is, without any
31042 extension. The \cs{At...Class} commands
31043 must be issued \emph{before} the corresponding \meta{class} is used
31044 otherwise nothing will happen.
31045
31046 The \cmd{\RequireAtEndClass} command will,
31047 like \cmd{\AtEndClass}, insert \meta{code}
31048 at the end of the \meta{class} class if it has not yet been used.
31049 If the class has already been used then the \meta{code} is
31050 called immediately.
31051
31052 \begin{Changed}
31053 By the 2020/10/01 format this is now implemented via the
31054 \texttt{class/before/pack} and \texttt{class/after/pack}
31055 hooks. We are not adding any hook label.
31056 \end{Changed}
31057
31058
31059
31060
31061 % There is an unfortunate interaction between the kernel's
31062 % \cmd{\AtEndOfPackage} and the class's \cmd{\AtEndPackage}, and similarly
31063 % for the \cmd{\AtEndOfClass} and \cmd{\AtEndClass}. I discovered this when
31064 % I tried to automate using the \Lpack{memhfixc} package if \Lpack{hyperref}
31065 % was being used by putting the following into the \Pclass{memoir} code
31066 % \begin{lcode}
31067 % \AtEndPackage{hyperref}{\usepackage{memhfixc}}
31068 % \end{lcode}
31069 % which caused all sorts of problems.
31070
31071 % The kernel scheme looks like this:
31072 % \begin{lcode}
31073 % \newcommand{\usepackage}[1]{%
31074 % ...
31075 % \InputIfFileExists{#1}
31076 % <AtEndOfPackage code>}
31077 % \end{lcode}
31078
31079 % The basic mechanism for implementing the class macros is by modifying
31080 % the kernel's \cmd{\InputIfFileExists} macro, which internally uses a form of
31081 % \cs{input} to read in the file, so that the inserted \meta{code} comes
31082 % immediately before and after the \cs{input}, somewhat like:
31083 % \begin{lcode}
31084 % \renewcommand{\InputIfFileExists}[1]{%
31085 % ...
31086 % <before code> \input{#1} <after code>}
31087 % \end{lcode}
31088
31089 % If \cmd{\AtEndPackage} is applied to a package that has an internal
31090 % \cmd{\AtEndOfPackage} then the result can be sketched as:
31091 % \begin{lcode}
31092 % \newcommand{\usepackage}[1]{%
31093 % ...
31094 % <before code>
31095 % \input{#1}
31096 % <after code>
31097 % <AtEndOfPackage code>
31098 % }
31099 % \end{lcode}
31100 % In other words the body of the package is read in, the \cmd{\AtEndPackage} code
31101 % is called, and then \emph{after} that the \cmd{\AtEndOfPackage} code is called.
31102
31103 % The \Lpack{hyperref} package internally uses \cmd{\AtEndOfPackage} to read
31104 % some files and \Lpack{memhfixc} had to be input after these. A way to automate
31105 % \Lpack{memhfixc} after \Lpack{hyperref} is:
31106 % \begin{lcode}
31107 % \AtEndPackage{hyperref}{%
31108 % \AtBeginDocument{\usepackage{memhfixc}}}
31109 % \end{lcode}
31110 % but this seems more trouble than it's worth especially since
31111 % Heiko\index{Oberdiek, Heiko} Oberdiek has kindly updated \Lpack{hyperref}
31112 % so that versions after 2006/11/15 will automatically load the
31113 % \Lpack{memhfixc} package.
31114
31115
31116 The 2020/10/01 format hooking features will solve a lot of issues we
31117 have had with file hooking, especially when things are delayed via
31118 \cmd{\AtBeginDocument} and you want to have your code to run after
31119 someone else's code. The hooking feature now offers users to add rules
31120 to reorder how the hooks are executed. See \cite{LTHOOKS} for details.
31121
31122 \renewcommand{\memsecinfo}[5]{\edef\Margi{#1}\edef\Margii{#2}%
31123 \edef\Margiii{#3}\edef\Margiv{#4}%
31124 \edef\Margv{#5}}
31125 \section{Heading hooks}
31126
31127 On 2nd September 2005 I posted two messages to the
31128 \texttt{comp.text.tex} newsgroup
31129 saying that I was creating a new version of \Pclass{memoir} and
31130 that I would consider inserting hooks into the class code
31131 that package writers
31132 might find useful. I got no requests for any hooks or anything
31133 else from package writers. I therefore assume that no package
31134 author sees any problems if a \Pclass{memoir} class document
31135 author uses the package.
31136
31137 However, I have provided macros that may be useful for those
31138 who want to do things with the contents of section headings,
31139 captions, and the like. The macros are called within the
31140 relevant heading or caption code, and by default are defined
31141 to do nothing.
31142
31143 Hooks for the \cmd{\book} and \cmd{\book*} commands.
31144 \begin{syntax}
31145 \cmd{\membookinfo}\marg{thebook}\marg{fortoc}\marg{title} \\
31146 \cmd{\membookstarinfo}\marg{title} \\
31147 \end{syntax}
31148 \glossary(membookinfo)%
31149 {\cs{membookinfo}\marg{thebook}\marg{fortoc}\marg{title}}%
31150 {Code hook into \cs{book}}%
31151 \glossary(membookstarinfo)%
31152 {\cs{membookstarinfo}\marg{title}}%
31153 {Code hook into \cs{book*}}%
31154
31155
31156 Hooks for the \cmd{\part} and \cmd{\part*} commands.
31157 \begin{syntax}
31158 \cmd{\mempartinfo}\marg{thepart}\marg{fortoc}\marg{title} \\
31159 \cmd{\mempartstarinfo}\marg{title} \\
31160 \end{syntax}
31161 \glossary(mempartinfo)%
31162 {\cs{mempartinfo}\marg{thepart}\marg{fortoc}\marg{title}}%
31163 {Code hook into \cs{part}}%
31164 \glossary(mempartstarinfo)%
31165 {\cs{mempartstarinfo}\marg{title}}%
31166 {Code hook into \cs{part*}}%
31167
31168 In many cases a \verb?\mem...info? macro includes an argument
31169 related to the heading's number (\meta{thepart} for \cmd{\mempartinfo}). In certain circumstances, such as a \cmd{\chapter} in the
31170 \cmd{\frontmatter}, there might not be a number even though the
31171 normal unstarred version of the command is used. In these cases
31172 the number argument (\meta{thechapter} in the case of
31173 \cmd{\memchapinfo}) is left empty.
31174
31175 Hooks for the \cmd{\chapter} and \cmd{\chapter*} commands. Note
31176 that regular chapters and those as appendices are treated
31177 differently.
31178 \begin{syntax}
31179 \cmd{\memchapinfo}\marg{thechapter}\marg{fortoc}\marg{forhead}\marg{title} \\
31180 \cmd{\memchapstarinfo}\marg{fortoc}\marg{title} \\
31181 \cmd{\memappchapinfo}\marg{thechapter}\marg{fortoc}\marg{forhead}\marg{title} \\
31182 \cmd{\memappchapstarinfo}\marg{fortoc}\marg{title} \\
31183 \end{syntax}
31184 \glossary(memchapinfo)%
31185 {\cs{memchapinfo}\marg{thechapter}\marg{fortoc}\marg{forhead}\marg{title}}%
31186 {Code hook into \cs{chapter}}%
31187 \glossary(memchapstarinfo)%
31188 {\cs{memchapstarinfo}\marg{fortoc}\marg{title}}%
31189 {Code hook into \cs{chapter*}}%
31190 \glossary(memappchapinfo)%
31191 {\cs{memappchapinfo}\marg{thechapter}\marg{fortoc}\marg{forhead}\marg{title}}%
31192 {Code hook into an appendix \cs{chapter}}%
31193 \glossary(memappchapstarinfo)%
31194 {\cs{memappchapstarinfo}\marg{fortoc}\marg{title}}%
31195 {Code hook into an appendix \cs{chapter*}}%
31196
31197 Hooks for \cmd{\section}, \cmd{\subsection}, etc., and their
31198 starred versions. \meta{name} is the type of section (e.g.,
31199 \texttt{section}, or \texttt{subsection}, or
31200 \texttt{subsubsection} or \ldots
31201 \begin{syntax}
31202 \cmd{\memsecinfo}\marg{name}\marg{thename}\marg{fortoc}\marg{forhead}\marg{title} \\
31203 \cmd{\memsecstarinfo}\marg{name}\marg{title} \\
31204 \end{syntax}
31205 \glossary(memsecinfo)%
31206 {\cs{memsecinfo}\marg{name}\marg{thename}\marg{fortoc}\marg{forhead}\marg{title}}%
31207 {Code hook into the \cs{name} section command}%
31208 \glossary(memsecstarinfo)%
31209 {\cs{memsecstarinfo}\marg{name}\marg{title}}%
31210 {Code hook into the \cs{name*} section command}%
31211
31212 Hooks for appendix-like page headings.
31213 \begin{syntax}
31214 \cmd{\memapppageinfo}\marg{title} \\
31215 \cmd{\memapppagestarinfo}\marg{title} \\
31216 \cmd{\memleadpageinfo}\marg{pstyle}\marg{cmdname}\marg{title} \\
31217 \cmd{\memleadpagestarinfo}\marg{pstyle}\marg{cmdname}\marg{title} \\
31218 \end{syntax}
31219 \glossary(memapppageinfo)%
31220 {\cs{memapppageinfo}\marg{title}}%
31221 {Code hook into \cs{appendixpage}.}%
31222 \glossary(memapppagestarinfo)%
31223 {\cs{memapppagestarinfo}\marg{title}}%
31224 {Code hook into \cs{appendixpage*}.}%
31225 \glossary(memleadpageinfo)%
31226 {\cs{memleadpageinfo}\marg{pstyle}\marg{cmdname}\marg{title}}%
31227 {Code hook into \cs{newleadpage} and \cs{renewleadpage}.}%
31228 \glossary(memleadpagestarinfo)%
31229 {\cs{memleadpageinfo}\marg{pstyle}\marg{cmdname}\marg{title}}%
31230 {Code hook into \cs{newleadpage*} and \cs{renewleadpage*}.}%
31231
31232 Hooks for \cmd{\poemtitle}, \cmd{\PoemTitle}, and their
31233 starred versions.
31234 \begin{syntax}
31235 \cmd{\mempoeminfo}\marg{title} \\
31236 \cmd{\mempoemstarinfo}\marg{title} \\
31237 \cmd{\memPoemTitleinfo}\marg{thepoem}\marg{fortoc}\marg{forhead}\marg{title} \\
31238 \cmd{\memPoemTitlestarinfo}\marg{fortoc}\marg{title} \\
31239 \end{syntax}
31240 \glossary(mempoeminfo)%
31241 {\cs{mempoeminfo}\marg{title}}%
31242 {Code hook into \cs{poemtitle}}%
31243 \glossary(mempoemstarinfo)%
31244 {\cs{mempoemstarinfo}\marg{title}}%
31245 {Code hook into \cs{poemtitle*}}%
31246 \glossary(memPoemTitleinfo)%
31247 {\cs{memPoemTitleinfo}\marg{thepoem}\marg{fortoc}\marg{forhead}\marg{title}}%
31248 {Code hook into \cs{PoemTitle}}%
31249 \glossary(memPoemTitlestarinfo)%
31250 {\cs{memPoemTitlestarinfo}\marg{fortoc}\marg{title}}%
31251 {Code hook into \cs{PoemTitle*}}%
31252
31253 Hooks for the several kinds of \cmd{\caption} and \cmd{\legend}
31254 commands.
31255 \begin{syntax}
31256 \cmd{\memcaptioninfo}\marg{type}\marg{thetype}\marg{fortoc}\marg{title} \\
31257 \cmd{\memlegendinfo}\marg{title} \\
31258 \cmd{\memnamedlegendinfo}\marg{fortoc}\marg{title} \\
31259 \cmd{\membitwonumcaptioninfo}\marg{type}\marg{thetype}\marg{fortoc1}\marg{title1} \\
31260 \hspace*{1.8in} \marg{name2}\marg{fortoc2}\marg{title2} \\
31261 \cmd{\membionenumcaptioninfo}\marg{type}\marg{thetype}\marg{fortoc1}\marg{title1} \\
31262 \hspace*{1.8in} \marg{name2}\marg{fortoc2}\marg{title2} \\
31263 \cmd{\membicaptioninfo}\marg{type}\marg{thetype}\marg{fortoc1}\marg{title1}\marg{name2}\marg{title2} \\
31264 \end{syntax}
31265 \glossary(memcaptioninfo)%
31266 {\cs{memcaptioninfo}\marg{type}\marg{thetype}\marg{fortoc}\marg{title}}%
31267 {Code hook into \cs{caption}}%
31268 \glossary(memlegendinfo)%
31269 {\cs{memlegendinfo}\marg{title}}%
31270 {Code hook into \cs{legend}}%
31271 \glossary(memnamedlegendinfo)%
31272 {\cs{memnamedlegendinfo}\marg{fortoc}\marg{title}}%
31273 {Code hook into \cs{namedlegend}}%
31274 \glossary(membitwonumcaptioninfo)%
31275 {\cs{membitwonumcaptioninfo}\marg{type} \marg{thetype} \marg{fortoc1}
31276 \marg{title1} \marg{name2} \marg{fortoc2} \marg{title2}}%
31277 {Code hook into \cs{membitwonumcaption}.}%
31278 \glossary(membionenumcaptioninfo)%
31279 {\cs{membionenumcaptioninfo}\marg{type} \marg{thetype} \marg{fortoc1}
31280 \marg{title1} \marg{name2} \marg{fortoc2} \marg{title2}}%
31281 {Code hook into \cs{membionenumcaption}.}%
31282 \glossary(membicaptioninfo)%
31283 {\cs{membicaptioninfo}\marg{type} \marg{thetype} \marg{fortoc1}
31284 \marg{title1} \marg{name2} \marg{title2}}%
31285 {Code hook into \cs{membicaption}.}%
31286
31287
31288 As an example of how one of these macros might be used,
31289 just before the start of this section I put
31290 \begin{lcode}
31291 \renewcommand{\memsecinfo}[5]{\edef\Margi{#1}\edef\Margii{#2}%
31292 \edef\Margiii{#3}\edef\Margiv{#4}%
31293 \edef\Margv{#5}}
31294 \end{lcode}
31295 and now I'm putting
31296 \begin{lcode}
31297 The arguments are: (1) `\Margi', (2) `\Margii', (3) `\Margiii',
31298 (4) `\Margiv', (5) `\Margv'.
31299 \end{lcode}
31300 The arguments are: (1) `\Margi', (2) `\Margii', (3) `\Margiii',
31301 (4) `\Margiv', (5) `\Margv'.
31302
31303 \LMnote{2010/07/01}{This is a large problem with subsubsection titles
31304 if the \cs{memsecinfo} above is used, added a warning, and made sure
31305 the test stops here.}
31306 \fancybreak{}
31307
31308 \textbf{Warning:} Be very careful with the fifth argument of this
31309 macro when using \Lpack{hyperref}, this argument will then contain a
31310 hyper link anchor, whih may cause problems when used out of context.
31311
31312 \renewcommand\memsecinfo[5]{}
31313
31314 \section{Documenting \ltx\ commands}
31315
31316 The class provides a few macros to help you if you want to describe
31317 \ltx\ commands.
31318
31319 \begin{syntax}
31320 \cmd{\bs} \cmd{\cs}\marg{name} \cmd{\cmdprint}\marg{cmd} \cmd{\cmd}\marg{cmd} \\
31321 \end{syntax}
31322 \glossary(bs)%
31323 {\cs{bs}}%
31324 {prints \bs.}
31325 \glossary(cs)%
31326 {\cs{cs}\marg{name}}%
31327 {prints \cs{name}.}
31328 \glossary(cmdprint)%
31329 {\cs{cmdprint}\marg{cmd}}%
31330 {where \meta{cmd} is a macro name like \cs{cmd}, prints \cs{cmd}.}
31331 \glossary(cmd)%
31332 {\cs{cmd}\marg{cmd}}%
31333 {where \meta{cmd} is a macro name like \cs{cmd}, prints and indexes \cs{cmd}.}
31334
31335 The macro \cs{bs} simply prints the `\bs' backslash.
31336
31337 The macro \cs{cs} prints its argument, putting a backslash in front of it. For
31338 example \verb?\cs{name}? prints \cs{name}.
31339
31340 The argument to \cs{cmdprint} should be the name of a macro, including the
31341 backslash. It is then printed as is. For instance \verb?\cmdprint{\amacro}?
31342 prints \cmdprint{\amacro}.
31343
31344 The argument to \cs{cmd} should be the name of a macro, including the
31345 backslash. It is then printed, using \cs{cmdprint}, and also added to the
31346 index file with the assumption that \verb!?! will be used as the `actual'
31347 character (the default is \verb!@! which is not of much use if you are trying
31348 to index macro names that have \verb!@! as part of their names).
31349
31350 \begin{syntax}
31351 \cmd{\meta}\marg{arg} \cmd{\marg}\marg{arg} \cmd{\oarg}\marg{arg} \cmd{\parg}\marg{arg} \\
31352 \end{syntax}
31353 \glossary(meta)%
31354 {\cs{meta}\marg{arg}}%
31355 {prints \meta{arg}.}
31356 \glossary(marg)%
31357 {\cs{marg}\marg{arg}}%
31358 {prints \marg{arg}.}
31359 \glossary(oarg)%
31360 {\cs{oarg}\marg{arg}}%
31361 {prints \oarg{arg}.}
31362 \glossary(parg)%
31363 {\cs{parg}\marg{arg}}%
31364 {prints \parg{arg}.}
31365
31366 The macro \cs{meta}\marg{arg} prints \meta{arg} for an argument to a macro.
31367
31368 The macro \cs{marg}\marg{arg} prints \marg{arg} for a required argument.
31369
31370 The macro \cs{oarg}\marg{arg} prints \oarg{arg} for an optional argument.
31371
31372 The macro \cs{parg}\marg{arg} prints \parg{arg} for a parenthesized argument.
31373
31374 \PWnote{2009/07/27}{Added chapter `For package users'}
31375
31376
31377 %#% extend
31378 %#% extstart include for-package-users.tex
31379
31380 \svnidlong
31381 {$Ignore: $}
31382 {$LastChangedDate: 2025-08-08 14:39:37 +0200 (Fri, 08 Aug 2025) $}
31383 {$LastChangedRevision: 859 $}
31384 {$LastChangedBy: [email protected] $}
31385
31386 \chapter{For package users} \label{chap:packageusers}
31387
31388 Many packages work just as well with \Pclass{memoir} as with any of the
31389 standard classes. In some instances, though, there may be a problem. In other
31390 instances the class and package have been designed to work together but
31391 you have to be careful about any code that you might write.\fxnote[author=dlf,vadj=0em]{this needs going over}
31392
31393 \section{Class/package name clash} \label{sec:nameclash}
31394
31395 A typical indication of a problem is an error message saying that a
31396 command has already been defined\index{Command \cs{...} already defined ...}
31397 (see \pref{alreadydefined}).
31398
31399 When the class and a package both use the same name for a macro that
31400 they define something has to give. For the sake of an example, assume
31401 that memoir has defined a macro called \cs{foo} and a package
31402 \Ppack{pack} that is used in the document also defines \cs{foo}. There
31403 are several options that you can choose which might resolve the
31404 difficulty.%\footnote{In many places one would see the command copying
31405 % done via \cs{let}, e.g. \cs{let}\cs{classfoo}\cs{foo}, as many
31406 % macros are moving to be robust, this can fail, or does not maintain robustness. See \cite{USRGUIDE}.}
31407 \nocite{USRGUIDE}
31408
31409
31410 \begin{enumerate}
31411
31412 \item Just keep the class definition:
31413 \begin{lcode}
31414 \documentclass{...}
31415 \let\classfoo\foo % save the class' definition
31416 \let\foo\relax % `undefine' \foo
31417 \usepackage{pack} % defines \foo
31418 \let\foo\classfoo % restore \foo to the class definition
31419 ...
31420 \foo... % the class \foo
31421 \end{lcode}
31422
31423 \item Just keep the package definition:
31424 \begin{lcode}
31425 \documentclass{...}
31426 \let\foo\relax % `undefine' \foo
31427 \usepackage{pack} % defines \foo
31428 ...
31429 \foo... % the package \foo
31430 \end{lcode}
31431
31432 \item Keep the class definition and rename the package definition:
31433 \begin{lcode}
31434 \documentclass{...}
31435 \let\classfoo\foo % save the class' definition
31436 \let\foo\relax % `undefine' \foo
31437 \usepackage{pack} % defines \foo
31438 \let\packfoo\foo % rename pack's \foo
31439 \let\foo\classfoo % restore \foo to the class definition
31440 ...
31441 \foo... % the class \foo
31442 \packfoo % the package \foo
31443 \end{lcode}
31444
31445 \item Keep the package definition and rename the class definition:
31446 \begin{lcode}
31447 \documentclass{...}
31448 \let\classfoo\foo % save the class' definition
31449 \let\foo\relax % `undefine' \foo
31450 \usepackage{pack} % defines \foo
31451 ...
31452 \foo... % the package \foo
31453 \classfoo... % the class \foo
31454 \end{lcode}
31455
31456 \end{enumerate}
31457
31458 A potential problem with these options can occur after the package is
31459 loaded and there are class or package commands that you use that,
31460 knowingly or not,
31461 call \cs{foo} expecting to get the class or the package definition, one of
31462 which is now not available (except under a different name).
31463
31464 The \Ppack{memoir} class has been available since 2001. It seems likely
31465 that if older packages clash with \Ppack{memoir} then, as eight years have
31466 gone by, the authors are unlikely to do anything about it. If a newer
31467 package clashes then contact the author of the package.
31468
31469 If all else fails, ask for help on the \pixctt\ newsgroup.
31470
31471 \section{Support for bididirectional typesetting}
31472
31473 The \Lpack{bidi} system~\cite{BIDI} provides means of bidirectional
31474 typesetting. The class has built in support for \Lpack{bidi} but this means
31475 that if you are defining your own macros there are some things you need
31476 to be aware of.
31477
31478 When dealing with bidirectional texts the left-to-right\index{LTR}
31479 (LTR) direction
31480 is the familiar one and \ltx\ is set up for this. When typesetting
31481 right-to-left (RTL)\index{RTL} \Lpack{bidi} interchanges left and right.
31482 The support in \Ppack{memoir} consists of replacing many, but not all, of
31483 the right- and left-specific constructs. The replacement macros are:
31484
31485 \begin{syntax}
31486 \cmd{\memRTLleftskip} \cmd{\memRTLrightskip} \\
31487 \cmd{\memRTLvleftskip} \cmd{\memRTLvrightskip} \\
31488 \cmd{\memRTLraggedright} \cmd{\memRTLraggedleft} \\
31489 \end{syntax}
31490 \glossary(memRTLleftskip)%
31491 {\cs{memRTLleftskip}}%
31492 {RTL (bidi) replacement for \cs{leftskip}}
31493 \glossary(memRTLrightskip)%
31494 {\cs{memRTLrightskip}}%
31495 {RTL (bidi) replacement for \cs{rightskip}}
31496 \glossary(memRTLvleftskip)%
31497 {\cs{memRTLvleftskip}}%
31498 {RTL (bidi) replacement for \cs{vleftskip}}
31499 \glossary(memRTLrightskip)%
31500 {\cs{memRTLvrightskip}}%
31501 {RTL (bidi) replacement for \cs{vrightskip}}
31502 \glossary(memRTLraggedleft)%
31503 {\cs{memRTLraggedleft}}%
31504 {RTL (bidi) replacement for \cs{raggedleft}}
31505 \glossary(memRTLraggedright)%
31506 {\cs{memRTLraggedright}}%
31507 {RTL (bidi) replacement for \cs{raggedright}}
31508
31509 In certain places, but not everywhere: \\
31510 \cmd{\memRTLleftskip} is used instead of \cmd{\leftskip} \\
31511 \cmd{\memRTLrightskip} is used instead of \cmd{\rightskip} \\
31512 \cmd{\memRTLvleftskip} is used instead of \cmd{\vleftskip} \\
31513 \cmd{\memRTLvrightskip} is used instead of \cmd{\vrightskip} \\
31514 \cmd{\memRTLraggedleft} is used instead of \cmd{\raggedleft} \\
31515 \cmd{\memRTLraggedright} is used instead of \cmd{\raggedright} \\
31516
31517 So, if you are defining any macros that use the \cs{...skip} or
31518 \cs{ragged...} macros you may have to use the \cs{memRTL...} version
31519 instead. The \Ppack{memoir} definitions of these macros are simply:
31520 \begin{lcode}
31521 \newcommand*{\memRTLleftskip}{\leftskip}
31522 \newcommand*{\memRTLrightskip}{\rightskip}
31523 ...
31524 \newcommand*{\memRTLraggedleft}{\raggedleft}
31525 \end{lcode}
31526 The \Lpack{bidi} system redefines them to suit its purposes. If your
31527 work will only be set LTR there is no need to use the \cs{memRTL...}
31528 macros in any of your code. If you might ever be producing a bidirectional
31529 document then you may have to use the \cs{memRTL...} versions of the standard
31530 commands in your code. To determine where you might have to use them
31531 you will have to consult the \Lpack{bidi} documentation as not every use
31532 of the standard commands needs to be replaced.
31533
31534
31535
31536
31537 %#% extend
31538 %#% extstart include an-example-book-design.tex
31539
31540 \svnidlong
31541 {$Ignore: $}
31542 {$LastChangedDate: 2025-09-19 16:06:27 +0200 (Fri, 19 Sep 2025) $}
31543 {$LastChangedRevision: 873 $}
31544 {$LastChangedBy: [email protected] $}
31545
31546
31547 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
31548
31549 \LMnote{2010/07/01}{This belongs here}
31550 \clearpage
31551
31552 \makeatletter
31553 % %% Bringhurst chapter style
31554 % \makechapterstyle{bringhurst}{%
31555 % \renewcommand{\chapterheadstart}{}
31556 % \renewcommand{\printchaptername}{}
31557 % \renewcommand{\chapternamenum}{}
31558 % \renewcommand{\printchapternum}{}
31559 % \renewcommand{\afterchapternum}{}
31560 % \renewcommand{\printchaptertitle}[1]{%
31561 % \raggedright\Large\scshape\MakeLowercase{##1}}
31562 % \renewcommand{\afterchaptertitle}{%
31563 % \vskip\onelineskip \hrule\vskip\onelineskip}
31564 % }
31565
31566 \setsecheadstyle{\raggedright\scshape\MakeLowercase}
31567 \setbeforesecskip{-\onelineskip}
31568 \setaftersecskip{\onelineskip}
31569
31570 %%\setsubsecheadstyle{\renewcommand\@hangfrom[1]{\noindent ##1}\raggedright\itshape}
31571 \setsubsecheadstyle{\sethangfrom{\noindent ##1}\raggedright\itshape}
31572 \setbeforesubsecskip{-\onelineskip}
31573 \setaftersubsecskip{\onelineskip}
31574
31575 %% Bringhurst page style
31576 \makepagestyle{bringhurst}
31577 \makeevenfoot{bringhurst}{\thepage}{}{}
31578 \makeoddfoot{bringhurst}{}{}{\thepage}
31579 \setlength{\pwlayi}{\headsep} % \verb?\setlength{\pwlayi}{\headsep}? headsep=\printlength{\headsep}, pwlayi = \printlength{\pwlayi}.
31580 \addtolength{\pwlayi}{\topskip} % \verb?\addtolength{\pwlayi}{\topskip}? topskip=\printlength{\topskip}, pwlayi=\printlength{\pwlayi}.
31581 \addtolength{\pwlayi}{7.3\onelineskip} % \verb?\addtolength{\pwlayi}{7.3\onelineskip}? onelineskip=\printlength{\onelineskip}, pwlayi=\printlength{\pwlayi}.
31582 \newcommand{\bringpicr}[1]{%
31583 \setlength{\unitlength}{1pt}
31584 \begin{picture}(0,0)
31585 \put(\strip@pt\marginparsep, -\strip@pt\pwlayi){%
31586 \begin{minipage}[t]{\marginparwidth}
31587 \raggedright\itshape #1
31588 \end{minipage}}
31589 \end{picture}
31590 }
31591
31592 \setlength{\pwlayii}{\marginparsep} % \verb?\setlength{\pwlayii}{\marginparsep}? marginparsep=\printlength{\marginparsep}, pwlayii=\printlength{\pwlayii}.
31593 \addtolength{\pwlayii}{\marginparwidth} % \verb?\addtolength{\pwlayii}{\marginparwidth}? marginparwidth=\printlength{\marginparwidth}, pwlayii=\printlength{\pwlayii}.
31594 \newcommand{\bringpicl}[1]{%
31595 \setlength{\unitlength}{1pt}
31596 \begin{picture}(0,0)
31597 \put(-\strip@pt\pwlayii, -\strip@pt\pwlayi){%
31598 \begin{minipage}[t]{\marginparwidth}
31599 \raggedleft\itshape #1
31600 \end{minipage}}
31601 \end{picture}
31602 }
31603
31604 \makepsmarks{bringhurst}{%
31605 \def\chaptermark##1{\markboth{##1}{##1}}
31606 \def\sectionmark##1{\markright{##1}}
31607 }
31608 \makeevenhead{bringhurst}{\bringpicl{\rightmark}}{}{}
31609 \makeoddhead{bringhurst}{}{}{\bringpicr{\leftmark}}
31610
31611
31612 \renewcommand{\cftchapterfont}{\normalfont}
31613 \renewcommand{\cftchapterpagefont}{\normalfont}
31614 \renewcommand{\cftchapterpresnum}{\bfseries}
31615 \renewcommand{\cftchapterleader}{}
31616 \renewcommand{\cftchapterafterpnum}{\cftparfillskip}
31617 %%%\settocdepth{chapter}
31618
31619 \makeatother
31620
31621
31622 \cleardoublepage
31623 \pagestyle{bringhurst}
31624 %%%\chapterstyle{bringhurst}
31625 \headstyles{bringhurst}
31626 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
31627 \PWnote{2009/07/05}{Added `book' to example design chapter title}
31628 \chapter{An example book design} \label{chap:bringhurst}
31629
31630 %unitlength=\printlength{\unitlength}, \\
31631 %pwlayi=\printlength{\pwlayi}, \\
31632 %pwlayii=\printlength{\pwlayii}.
31633
31634 \section{Introduction}
31635
31636 In this chapter I will work through a reasonably complete design
31637 exercise. Rather than trying to invent something myself I am taking the design
31638 of Bringhurst's
31639 \textit{The Elements of Typographic Style}~\cite{BRINGHURST99}
31640 as the basis of the
31641 exercise. This is sufficiently different from the normal LaTeX appearance
31642 to demonstrate most of the class capabilities, and also it is a design by
31643 a leading proponent of good typography.
31644
31645 As much as possible, this chapter is typeset according to the results
31646 of the exercise to provide both a coding and a graphic example.
31647
31648 \section{Design requirements}
31649
31650 The \textit{Elements of Typographic Style} is typeset using
31651 Minion\facesubseeidx{Minion} as the text font and Syntax\facesubseeidx{Syntax}
31652 (a sans font)
31653 for the captions.
31654 %The page layout has been
31655 %shown diagramatically in \fref{fb:1} on \pref{fb:1}, but further details need
31656 %to be described for those not fortunate enough to have a copy of their own.
31657
31658 The trimmed page size is 23 by 13.3cm. The foredge is 3.1cm and the
31659 top margin\index{margin!upper} is 1.9cm.
31660
31661 As already noted, the font for the main text is Minion\index{Minion},
31662 with 12pt leading
31663 on a 21pc measure with 42 lines per page. For the purposes of this exercise
31664 I will assume that Minion can be replaced by the font used for this
31665 manual. The captions to figures\index{figure} and tables\index{table} are
31666 unnamed and
31667 unnumbered and typeset in Syntax\index{Syntax}. The captions give the
31668 appearance of being
31669 in a smaller font size than the main text, which is often the case. I'll
31670 assume that the \cmd{\small}\cmd{\sfseries} font will reasonably do for the
31671 captions.
31672
31673 The footer\index{footer} is the same width as the
31674 typeblock\index{typeblock} and the folio\index{folio} is placed
31675 in the footer\index{footer} at the \foredge. There are two blank lines between
31676 the bottom of the typeblock\index{typeblock} and the folio\index{folio}.
31677
31678 There is no header\index{header} in the usually accepted sense of the
31679 term but the chapter title is put on recto pages and section titles are on
31680 verso pages. The running titles are placed in the \foredge\
31681 margin\index{margin!foredge?\foredge}
31682 level with the seventh line of the text in the typeblock\index{typeblock}.
31683 The recto headers\index{header} are typeset raggedright
31684 and the verso ones raggedleft.
31685
31686 Bringhurst also uses many marginal\index{marginalia} notes,
31687 their maximum width being about 51pt, and typeset raggedright in a smaller
31688 version of the textfont.
31689
31690 Chapter titles are in small caps, lowercase, in a larger font than for
31691 the main text, and a rule is placed between the title and the
31692 typeblock\index{typeblock}. The total vertical space used by a chapter
31693 title is three text lines. Chapters are not numbered in the text but are
31694 in the \toc.
31695
31696 Section titles are again in small caps, lowercase, in the same size as the
31697 text font. The titles are numbered, with both the chapter and section number.
31698
31699 A subsection title, which is the lowest subdivision in the book, is in
31700 the italic form of the textfont and is typeset as a numbered non-indented
31701 paragraph\index{paragraph}. These are usually multiline as Bringhurst
31702 sometimes uses them like an enumerated list, so on occasion there is a
31703 subsection title with no following text.
31704
31705 Only chapter titles are put into the \toc, and these are set raggedright
31706 with the page numbers immediately after the titles. There is no \lof\ or
31707 \lot.
31708
31709 Note that unlike the normal \ltx\ use of fonts, essentially only three
31710 sizes of fonts are used --- the textfont size, one a bit larger for the
31711 chapter titles, and one a bit smaller for marginal\index{marginalia} notes
31712 and captions. Also, bold fonts are not used except on special occasions,
31713 such as when he is comparing font families and uses large bold
31714 versions to make the differences easier to see.
31715
31716 \section{Specifying the page and typeblock}
31717
31718 The first and second things to do are to specify the sizes of the page
31719 after trimming and the typeblock\index{typeblock}. The trimmed size is
31720 easy as we have the dimensions.
31721 \begin{lcode}
31722 \settrimmedsize{23cm}{13.3cm}{*}
31723 \end{lcode}
31724 We want 42 lines of text, so that's what we set as the height of the
31725 typeblock\index{typeblock}; however, we have to remember to ask for
31726 \texttt{lines} as the optional \meta{algorithm} argument when we
31727 finally call \cmd{\checkandfixthelayout}.
31728 \begin{lcode}
31729 \settypeblocksize{42\onelineskip}{21pc}{*}
31730 \end{lcode}
31731
31732 To make life easier, we'll do no trimming of the top of the
31733 stock\index{stock}
31734 \begin{lcode}
31735 \setlength{\trimtop}{0pt}
31736 \end{lcode}
31737 but will trim the \foredge. The next set of calculations first sets the
31738 value of the \lnc{\trimedge} to be the \lnc{\stockwidth}; subtracting the
31739 trimmed \lnc{\paperwidth} then results in \lnc{\trimedge} being the amount
31740 to trim off the foredge.
31741 \begin{lcode}
31742 \setlength{\trimedge}{\stockwidth}
31743 \addtolength{\trimedge}{-\paperwidth}
31744 \end{lcode}
31745
31746 The sizes of the trimmed page and the typeblock\index{typeblock} have
31747 now been specified. The typeblock\index{typeblock} is now positioned on
31748 the page. The sideways positioning is
31749 easy as we know the \foredge\ margin\index{margin!foredge!\foredge}
31750 to be 3.1cm.
31751 \begin{lcode}
31752 \setlrmargins{*}{3.1cm}{*}
31753 \end{lcode}
31754 The top margin\index{margin!top} is specified as 1.9cm, which is very
31755 close to
31756 four and a half lines of text. Just in case someone might want to use a
31757 different font size, I'll specify the top margin\index{margin!top}
31758 so that it
31759 is dependent on the font size. The
31760 \lnc{\footskip} can be specified now as well (it doesn't particularly matter
31761 what we do about the header-related lengths as there isn't anything above
31762 the typeblock\index{typeblock}).
31763 \begin{lcode}
31764 \setulmargins{4.5\onelineskip}{*}{*}
31765 \setheadfoot{\onelineskip}{3\onelineskip}
31766 \setheaderspaces{\onelineskip}{*}{*}
31767 \end{lcode}
31768
31769 Lastly define the dimensions for any marginal\index{marginalia} notes.
31770 \begin{lcode}
31771 \setmarginnotes{17pt}{51pt}{\onelineskip}
31772 \end{lcode}
31773
31774 If this was for real, the page layout would have to be checked and
31775 implemented.
31776 \begin{lcode}
31777 \checkandfixthelayout[lines]
31778 \end{lcode}
31779
31780 It is possible to implement this layout just for this chapter but
31781 I'm not going to tell you either how to do it, or demonstrate it. Except
31782 under exceptional circumstances it is not good to make such drastic changes
31783 to the page layout in the middle of a document. However, the picture on
31784 \pref{fig:bplayout} illustrates
31785 how this layout would look on US letterpaper\index{paper!size!letterpaper}
31786 stock\index{stock}. Looking at the illustration suggests that the layout
31787 would look rather odd unless the stock\index{stock} was trimmed down
31788 to the page size --- another reason for not switching the layout here.
31789
31790 \begin{figure}
31791 \captiontitlefont{\small\sffamily}
31792 \captionstyle{\centerlastline}
31793 \setstocksize{11in}{8.5in}
31794 \settrimmedsize{23cm}{13.3cm}{*}
31795 \settypeblocksize{41\onelineskip}{21pc}{*}
31796 \setlength{\trimtop}{0pt}
31797 \setlength{\trimedge}{\stockwidth}
31798 \addtolength{\trimedge}{-\paperwidth}
31799 \setlrmargins{*}{3.1cm}{*}
31800 \setulmargins{4.5\onelineskip}{*}{*}
31801 \setheadfoot{\onelineskip}{3\onelineskip}
31802 \setheaderspaces{\onelineskip}{*}{*}
31803 \setmarginnotes{17pt}{51pt}{\onelineskip}
31804 \checkandfixthelayout
31805 \currentstock
31806 \oddpagelayouttrue
31807 \twocolumnlayoutfalse
31808 \drawmarginparstrue
31809 \drawparametersfalse
31810 \drawstock
31811 \vskip-2pt
31812 \legend{An illustration of Bringhurst's page layout style when printed
31813 on US letter paper stock. Also shown are the values used for the
31814 page layout parameters for this design.} \label{fig:bplayout}
31815 \end{figure}
31816
31817 \section{Specifying the sectional titling styles}
31818
31819 \subsection{The chapter style}
31820
31821 Recapping, chapter titles are in small caps, lowercase, in a larger
31822 font than for the main text, and a rule is placed between the title and the
31823 typeblock\index{typeblock}.
31824 The total vertical space used by a chapter title is three text lines.
31825 Chapters are not numbered in the text but are in the \toc.
31826 Titles in the \toc\ are in mixed case.
31827
31828 The definition of the chapterstyle is remarkably simple, as shown below.
31829 \begin{lcode}
31830 %% Bringhurst chapter style
31831 \makechapterstyle{bringhurst}{%
31832 \renewcommand{\chapterheadstart}{}
31833 \renewcommand{\printchaptername}{}
31834 \renewcommand{\chapternamenum}{}
31835 \renewcommand{\printchapternum}{}
31836 \renewcommand{\afterchapternum}{}
31837 \renewcommand{\printchaptertitle}[1]{%
31838 \raggedright\Large\scshape\MakeLowercase{##1}}
31839 \renewcommand{\afterchaptertitle}{%
31840 \vskip\onelineskip \hrule\vskip\onelineskip}
31841 }
31842 \end{lcode}
31843
31844 Most of the specification consists of nulling the majority of the normal
31845 LaTeX specification, and modifying just two elements.
31846
31847 The chapter title (via \cmd{\printchaptertitle})
31848 is typeset raggedright using the \cmd{\Large} smallcaps fonts. The
31849 \cmd{\MakeLowercase} macro is used to ensure that the entire title is
31850 lowercase before typesetting it. Titles are input in mixed case.
31851
31852 After the title is typeset the \cmd{\afterchaptertitle} macro
31853 specifies that one line is skipped, a horizontal rule
31854 is drawn and then another line is skipped.
31855
31856 \subsection{Lower level divisions}
31857
31858 Section titles are in small caps, lowercase, in the same size as the
31859 text font. The titles are numbered, with both the chapter and section number.
31860
31861 The specification is:
31862 \begin{lcode}
31863 \setsecheadstyle{\raggedright\scshape\MakeLowercase}
31864 \setbeforesecskip{-\onelineskip}
31865 \setaftersecskip{\onelineskip}
31866 \end{lcode}
31867
31868 The macro \cmd{\setsecheadstyle} lowercases the title and typesets it
31869 small caps.
31870
31871 The default skips before and after titles are rubber lengths but this does
31872 not bode well if we are trying to line something up with a particular line
31873 of text --- the presence of section titles may make slight vertical
31874 adjustments to the text lines because of the flexible spacing. So, we have
31875 to try and have fixed spacings.
31876 A single blank line is used before (\cmd{\setbeforesecskip)}
31877 and after (\cmd{\setaftersecskip}) the title text.
31878
31879 A subsection title, which is the lowest subdivision in the book, is in
31880 the italic form of the textfont and is typeset as a numbered non-indented
31881 paragraph\index{paragraph}. The code for this is below.
31882
31883 \begin{lcode}
31884 \setsubsecheadstyle{\sethangfrom{\noindent ##1}\raggedright\itshape}
31885 \setbeforesubsecskip{-\onelineskip}
31886 \setaftersubsecskip{\onelineskip}
31887 \end{lcode}
31888
31889 As in the redefinition of the \cmd{\section} style, there are fixed
31890 spaces before and after the title text. The title is typeset
31891 (\cmd{\setsubsecheadstyle}) raggedright in a normal sized italic font.
31892 The macro \cmd{\sethangfrom} is used to to redefine the internal
31893 \cmd{\@hangfrom} macro so that the title and number are typeset as a block
31894 paragraph\index{paragraph!block} instead of the default hanging
31895 paragraph\index{paragraph!hanging} style. Note the use of
31896 the double \verb?##? mark for denoting the position of the argument to
31897 \cmd{\@hangfrom}.
31898
31899 \section{Specifying the pagestyle}
31900
31901 The pagestyle is perhaps the most interesting aspect of the exercise.
31902 Instead of the chapter and section titles being put at the top of the
31903 pages they are put in the margin\index{margin} starting about seven lines
31904 below the top of the typeblock\index{typeblock}. The folios\index{folio}
31905 are put at the bottom of the page aligned with the outside of the
31906 typeblock\index{typeblock}.
31907
31908 As the folios\index{folio} are easy, we'll deal with those first.
31909 \begin{lcode}
31910 %% Bringhurst page style
31911 \makepagestyle{bringhurst}
31912 \makeevenfoot{bringhurst}{\thepage}{}{}
31913 \makeoddfoot{bringhurst}{}{}{\thepage}
31914 \end{lcode}
31915
31916 Putting text at a fixed point on a page is typically done by
31917 first putting the text into a zero width picture (which as far as LaTeX
31918 is concerned takes up zero space) and then placing the picture at the
31919 required point on the page. This can be done by hanging it from the
31920 header\index{header}.
31921
31922 We might as well treat the titles so that they will align with any
31923 marginal\index{marginalia} notes, which are \lnc{\marginparsep} (17pt)
31924 into the margin\index{margin}
31925 and \lnc{\marginparwidth} (51pt) wide. Earlier in the manual I defined
31926 two lengths called \lnc{\pwlayi} and \lnc{\pwlayii} which are no longer used.
31927 I will use these as scratch lengths in
31928 performing some of the necessary calculations.
31929
31930 For the recto page headers\index{header} the picture will be
31931 the \meta{right} part of the header\index{header} and for the verso pages
31932 the picture will be the \meta{left}
31933 part of the header\index{header}, all other parts being empty.
31934
31935 For the picture on the \meta{right} the text must be 17pt to
31936 the right of the origin, and some distance below the origin.
31937 From some experiments, this distance turns out to be the \lnc{\headsep}
31938 plus the \cmd{\topskip} plus 7.3 lines, which is calculated as follows:
31939 \begin{lcode}
31940 \setlength{\pwlayi}{\headsep}
31941 \addtolength{\pwlayi}{\topskip}
31942 \addtolength{\pwlayi}{7.3\onelineskip}
31943 \end{lcode}
31944
31945 There is a nifty internal LaTeX macro called \cmd{\strip@pt} which you
31946 probably haven't heard about, and I have only recently come across. What it
31947 does is strip the `pt' from a following length, reducing it to a plain
31948 real number. Remembering that the default \lnc{\unitlength} is 1pt we can
31949 do the following, while making sure that the current \lnc{\unitlength}
31950 \emph{is} 1pt:
31951 \begin{lcode}
31952 \makeatletter
31953 \newcommand{\bringpicr}[1]{%
31954 \setlength{\unitlength}{1pt}
31955 \begin{picture}(0,0)
31956 \put(\strip@pt\marginparsep, -\strip@pt\pwlayi){%
31957 \begin{minipage}[t]{\marginparwidth}
31958 \raggedright\itshape #1
31959 \end{minipage}}
31960 \end{picture}
31961 }
31962 \makeatother
31963 \end{lcode}
31964 The new macro \cmd{\bringpicr}\marg{text} puts \meta{text}
31965 into a \Ie{minipage} of width \lnc{\marginparwidth},
31966 typeset raggedright in an italic font, and puts the top
31967 left of the minipage at the position (\lnc{\marginparsep}, -\lnc{\pwlayi})
31968 in a zero width picture.
31969
31970 We need a different picture for the \meta{left} as the text needs to be
31971 typeset raggedleft with the right of the text 17pt from the left of the
31972 typeblock\index{typeblock}. I will use the length \lnc{\pwlayii}
31973 to calculate the sum of \lnc{\marginparsep}
31974 and \lnc{\marginparwidth}. Hence:
31975 \begin{lcode}
31976 \makeatletter
31977 \setlength{\pwlayii}{\marginparsep}
31978 \addtolength{\pwlayii}{\marginparwidth}
31979 \newcommand{\bringpicl}[1]{%
31980 \setlength{\unitlength}{1pt}
31981 \begin{picture}(0,0)
31982 \put(-\strip@pt\pwlayii, -\strip@pt\pwlayi){%
31983 \begin{minipage}[t]{\marginparwidth}
31984 \raggedleft\itshape #1
31985 \end{minipage}}
31986 \end{picture}
31987 }
31988 \makeatother
31989 \end{lcode}
31990 The new macro \cmd{\bringpicl}\marg{text} puts \meta{text}
31991 into a \Ie{minipage} of width \lnc{\marginparwidth},
31992 typeset raggedleft in an italic font, and puts the top
31993 left of the minipage at the position
31994 (-(\lnc{\marginparsep} + \lnc{\marginparwidth}), -\lnc{\pwlayi})
31995 in a zero width picture.
31996
31997
31998 Now we can proceed with the remainder of the pagestyle specification.
31999 The next bit puts the chapter and section titles into the \verb?\...mark?
32000 macros.
32001 \begin{lcode}
32002 \makeatletter
32003 \makepsmarks{bringhurst}{%
32004 \def\chaptermark##1{\markboth{##1}{##1}}
32005 \def\sectionmark##1{\markright{##1}}
32006 }
32007 \makeatother
32008 \end{lcode}
32009
32010 Finally, specify the evenhead using \cmd{\bringpicl} with the section
32011 title as its argument, and the oddhead using \cmd{\bringpicr} with the
32012 chapter title as its argument.
32013 \begin{lcode}
32014 \makeevenhead{bringhurst}{\bringpicl{\rightmark}}{}{}
32015 \makeoddhead{bringhurst}{}{}{\bringpicr{\leftmark}}
32016 \end{lcode}
32017
32018
32019 \section{Captions and the \prtoc}
32020
32021 The captions to figures\index{figure} and tables\index{table} are set
32022 in a small sans font and are neither named nor numbered, and there is no
32023 \lof\ or \lot. Setting the caption titles in the desired font is simple:
32024 \begin{lcode}
32025 \captiontitlefont{\small\sffamily}
32026 \end{lcode}
32027
32028 There are two options regarding table\index{table} and figure\index{figure}
32029 captioning: either
32030 use the \cmd{\legend} command (which produces an anonymous unnumbered title)
32031 instead of the \cmd{\caption} command, or
32032 use the \cmd{\caption} command with a modified definition. Just in case
32033 the design might change at a later date to required numbered captions,
32034 it's probably best to use
32035 a modified version of \cmd{\caption}. In this case this is simple, just give
32036 the \cmd{\caption} command the same definition as the \cmd{\legend} command.
32037 \begin{lcode}
32038 \let\caption\legend
32039 \end{lcode}
32040
32041 An aside: I initially used the default caption style (block paragraph) for
32042 the diagram on \pref{fig:bplayout}, but this looked unbalanced so now it
32043 has the last line centered. As a float\index{float} environment,
32044 like any other environment, forms a group, you can make local changes within
32045 the float\index{float}. I actually did it like this:
32046 \begin{lcode}
32047 \begin{figure}
32048 \captiontitlefont{\small\sffamily}
32049 \captionstyle{\centerlastline}
32050 ...
32051 \legend{...} \label{...}
32052 \end{figure}
32053 \end{lcode}
32054 For fine typesetting you may wish to change the style of particular captions.
32055 The default style for a single line caption works well, but for a caption with
32056 two or three lines either the \texttt{centering} or \texttt{centerlastline}
32057 style might look better. A very long caption is again probably best done in
32058 a block paragraph style.
32059
32060 Only chapter titles are included in the \toc. To specify this we
32061 use the \cmd{\settocdepth} command.
32062 \begin{lcode}
32063 \settocdepth{chapter}
32064 \end{lcode}
32065
32066 The \toc\ is typeset raggedright with no leaders and the page numbers
32067 coming immediately after the chapter title. This is specified via:
32068 \begin{lcode}
32069 \renewcommand{\cftchapterfont}{\normalfont}
32070 \renewcommand{\cftchapterpagefont}{\normalfont}
32071 \renewcommand{\cftchapterpresnum}{\bfseries}
32072 \renewcommand{\cftchapterleader}{}
32073 \renewcommand{\cftchapterafterpnum}{\cftparfillskip}
32074 \end{lcode}
32075
32076 \section{Preamble or package?}
32077
32078
32079 When making changes to the document style, or just defining a new
32080 macro or two, there is the question of where to put the changes --- in
32081 the preamble\index{preamble} of the particular document or into a separate
32082 package\index{package}?
32083
32084 If the same changes/macros are likely to be used in more than one
32085 document then I suggest that they be put into a package.
32086 If just for the single document then the choice remains open.
32087
32088 I have presented the code in this chapter as though it would be put
32089 into the preamble\index{preamble}, hence the use of \cmd{\makeatletter} and
32090 \cmd{\makeatother} to surround macros that include the
32091 \texttt{@}\idxatincode\ character (\seeatincode).
32092 The
32093 code could just as easily be put into a package\index{package} called, say,
32094 \Lpack{bringhurst}. That is, by putting all the code, except for the
32095 \cmd{\makeatletter} and \cmd{\makeatother} commands, into a file called
32096 \file{bringhurst.sty}. It is a good idea also to end the code in the file
32097 with \cmd{\endinput}; LaTeX stops reading the file at that point and
32098 will ignore any possible garbage after \cmd{\endinput}.
32099
32100 You then use the \Lpack{bringhurst} package just like any other by
32101 putting
32102 \begin{lcode}
32103 \usepackage{bringhurst}
32104 \end{lcode}
32105 in your document's preamble\index{preamble}.
32106
32107 %#% extend
32108
32109
32110 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
32111 %%%%%%%%%%%% revert to the regular styles
32112 \clearpage
32113 %%%\memmansecheads
32114 %%%\chapterstyle{demo3}
32115 \headstyles{memman}
32116 \pagestyle{ruled}
32117
32118 %#% extstart include an-example-thesis-design.tex
32119
32120 \svnidlong
32121 {$Ignore: $}
32122 {$LastChangedDate: 2025-07-31 11:37:38 +0200 (Thu, 31 Jul 2025) $}
32123 {$LastChangedRevision: 854 $}
32124 {$LastChangedBy: [email protected] $}
32125
32126 \PWnote{2009/07/05}{Added thesis design chapter}
32127 \PWnote{2009/07/08}{Revised thesis design chapter}
32128 \chapter{An example thesis design} \label{chap:thesis}
32129
32130 Many universities in the United States have strict regulations about
32131 the typography of theses.
32132 The title and administrative pages are inherently specific to a particular
32133 university, but often the design for the body of the thesis clashes
32134 with normally accepted typographic practice. This chapter presents
32135 fairly typical guidelines for some US universities and code intended
32136 to meet them. Let's call the university in question the
32137 \emph{Archibald Smythe University}, or ASU for short.
32138
32139 The requirements that are listed below are not from any single
32140 university but I have, over the years, seen each one of them. In reality
32141 there are likely to be many more nit-picking rules than I have shown.
32142
32143 It amuses me that I have never seen a printed set of requirements that
32144 followed the rules laid down therein.
32145
32146 Universities outside the US tend to be more relaxed with the result
32147 that theses from these establishments are very often more attractive (certainly
32148 less bulky) and more readable. The ASU requirements lead to an exceptionally
32149 dull and unattractive appearance.
32150
32151 \section{Example US thesis typographic requirements}
32152
32153 \subsection{General}
32154
32155 \begin{description}
32156 \item[Paper size] The thesis shall be printed on 8.5 by 11 inch plain
32157 white paper.
32158
32159 \item[Single-sided] The thesis shall be printed single-sided; that is,
32160 one side of each sheet of paper will be blank.
32161
32162 \item[Margins] Every page of the document shall meet the requirements of
32163 a 1.5~inch margin on the left and a 1~inch margin at the top, right, and
32164 bottom of the page. Nothing shall appear in any margin.
32165
32166 \item[Fonts] The thesis may be set in 10, 11 or 12pt
32167 Arial\index{Arial},
32168 Century\index{Century},
32169 Garamond\index{Garamond},
32170 Lucida Bright\index{Lucida Bright} (10pt only),
32171 Tahoma\index{Tahoma},
32172 Times\index{Times}, or
32173 Verdana\index{Verdana}.
32174 The same font and size shall be used throughout the thesis.
32175
32176 There shall be no bold type.
32177
32178 Italic type (or underlining) is limited to the names of species, genera,
32179 book titles, musical compositions, or foreign words.
32180
32181 \item[Line Spacing] All text shall be double-spaced, except material in tables
32182 and the optional biographical sketch (which must be single-spaced). You shall
32183 single-space individual footnotes and endnotes with a double space between
32184 each entry.
32185 \end{description}
32186
32187 \subsection{Preliminary matter}
32188
32189 The preliminary matter consists of the following pages in this
32190 order:
32191 \begin{enumerate}
32192 \item Title page
32193 \item Approval page
32194 \item Abstract
32195 \item Dedication (optional)
32196 \item Acknowledgements (optional)
32197 \item Table of contents
32198 \item List of tables (if there are any tables)
32199 \item List of figures (if there are any figures)
32200 \item Other lists (e.g., nomenclature, definitions, glossary of terms, etc.)
32201 \item Preface (optional but must be less than ten pages)
32202 \item Under special circumstances further sections may be allowed
32203 \end{enumerate}
32204
32205 The heading for each preliminary page (except the Dedication which shall
32206 not have a heading) is centered between the margins, in all capital letters,
32207 double-spaced and begin on the first line below the top margin.
32208
32209 The title and approval page are counted as pages one and two, but
32210 no page numbers shall appear on them. All subsequent preliminary pages are
32211 paginated with lowercase Roman numerals. Starting with `iii' on the abstract
32212 page, place all page numbers at the bottom of the page, centered between
32213 the left and right margins and upon the 1~inch bottom margin. Continue
32214 numbering consecutively on the subsequent pages up to the first page
32215 of the main text.
32216
32217 \subsubsection{Title page}
32218
32219 \begin{enumerate}
32220 \item All text shall be centered between the side margins.
32221
32222 \item Set the title in all capital letters, double-spaced,
32223 starting at the top of the page (but below the top margin).
32224 \item On a new line (double-spaced) type `by' in lowercase letters.
32225 \item On a new line (double-spaced) type your full legal name.
32226 \item At the center of the page type the appropriate description for
32227 your degree with the exact wording and line breaks as shown, and single-spaced:
32228 \begin{quote} \centering
32229 A \rule{1in}{0.4pt} Presented in Partial Fulfillment \\
32230 of the Requirements for the Degree \\
32231 \rule{2in}{0.4pt}
32232 \end{quote}
32233 Replace the blanks with the appropriate wording: Thesis and Master
32234 of Arts or Dissertation and Doctor of Philosophy.
32235 \item At the bottom of the page type `ARCHIBALD SMYTHE UNIVERSITY' in all
32236 capitals.
32237 \item Type the month and year of the date you will graduate, with the
32238 month in title case and no comma between the month and year.
32239 \item The space between your name and the degree description should equal
32240 the space between the degree description and the name of the University.
32241 \end{enumerate}
32242
32243 \subsubsection{Approval page}
32244
32245 \begin{enumerate}
32246 \item All text shall be centered between the side margins.
32247
32248 \item Set the title in all capital letters, double-spaced,
32249 starting at the top of the page (but below the top margin).
32250 \item On a new line (double-spaced) type `by' in lowercase letters.
32251 \item On a new line (double-spaced) type your full legal name in
32252 title-cased letters.
32253 \item Add two double-spaced lines (four single-spaced lines) and type
32254 `has been aproved' in lowercase
32255 \item Add a double-space.
32256 \item Type the month and year of your oral defense, with the
32257 month in title case and no comma between the month and year.
32258
32259 \item At about the center of the page type `Graduate Supervisory Committee:'
32260 \item A blank (double-spaced) line
32261 \item Type the members' names, without titles, one per line,
32262 single-spaced, as follows:
32263 \begin{enumerate}
32264 \item If you have one chair, type: the chair's name, comma, space `Chair'
32265 \item If two chairs, type: comma, space, `Co-Chair' after the first two names
32266 \item Follow with the other members' names.
32267 \end{enumerate}
32268 \item At the bottom of the page, type `ACCEPTED BY THE GRADUATE COLLEGE'
32269 \item The space between the date and `Graduate Supervisory Committe' lines
32270 should equal the space between the last member's name and the `ACCEPTED\ldots'
32271 line.
32272 \end{enumerate}
32273
32274 \subsubsection{Abstract page}
32275
32276 Center the title `ABSTRACT' at the top of the page. Number the page
32277 at the bottom, centered with the Roman numeral `iii'. If there is a second
32278 page, number it similarly with `iv'.
32279
32280 \subsubsection{Dedication and Acknowledgements (optional)}
32281
32282 \begin{itemize}
32283 \item The dedication and acknowledgements together must not exceed three
32284 pages.
32285 \item The dedication page is not titled and the text should be centered both
32286 vertically and horizontally.
32287 \item The heading for the acknowledgements page is `ACKNOWLEDGEMENTS', centered
32288 and at the top of the page.
32289 \item Continue the page numbering in lowercase Roman, at the bottom and
32290 centered.
32291 \end{itemize}
32292
32293 \subsection{Table of contents}
32294
32295 \begin{enumerate}
32296 \item Type `TABLE OF CONTENTS' centered at the top of the page.
32297 \item On the next line type the word `Page' right justified
32298 \item Begin listing any preliminary pages that follow the table of contents
32299 (e.g., lists) in ALL CAPS. The title is left justified, the page number is
32300 right justified and a dotted line fills the gap between.
32301 \item Double space between entries.
32302 \item Chapter headings and subheadings to three levels shall be listed,
32303 with a lower level being indented with respect to a higher level.
32304 \item The wording of headings shall correspond exactly to those in
32305 the main body.
32306 \item The page number is centered at the bottom of the page.
32307 \item If the listing continues for more than one page, subsequent pages
32308 shall be headed with one line consisting of `Chapter' left justified
32309 and `Page' right justified.
32310 \end{enumerate}
32311
32312 \subsection{Lists}
32313
32314 For a given kind of list (often figures or tables) called, say, `things':
32315 \begin{enumerate}
32316 \item Type `LIST OF THINGS' centered at the top of the page.
32317 \item On the next line type `Thing' left justified and `Page' right justified.
32318 \item List, double-spaced, the caption or title of the thing left justified
32319 and the page number right justified, with a dotted line between them.
32320 \item Use Roman lowercase to number the page(s) at the bottom, centered.
32321 \item If the listing continues for more than one page, subsequent pages
32322 shall be headed with one line consisting of `Thing' left justified
32323 and `Page' right justified.
32324 \end{enumerate}
32325
32326 \subsection{Main text}
32327
32328 Nothing shall appear in the margins.
32329
32330 The top line on a page is the line immediately below the top margin.
32331 The top text line is the one following that (i.e. the second line below
32332 the margin).
32333
32334 \subsubsection{Page numbering}
32335
32336 All pages are counted, but the first page of each chapter is not
32337 numbered (paginated); other pages are paginated. The first page of the
32338 main text is counted as number 1. Numbered pages have the number right
32339 justified on the top line.
32340
32341 \subsubsection{Headings}
32342
32343 Chapter headings shall be centered. On the top line type `Chapter' followed
32344 by the number. On the top text line type the heading in all uppercase.
32345 Type the text on the subsequent lines.
32346
32347 Subheadings, consisting of the number and title (not in all caps),
32348 shall be centered, with one blank line before and after.
32349
32350 \subsubsection{Captions}
32351
32352 Table captions, which are left justified, shall be put before the table
32353 itself. The first line consists of `Table' followed by the number; the caption
32354 wording commences on the next line.
32355
32356 Captions for figures are similar, except that they shall be put below the
32357 figure and `Table' replaced by `Figure'.
32358
32359 Tables and figures shall be single-spaced.
32360
32361 \subsubsection{Notes}
32362
32363 Notes may be placed at the bottom of the page (i.e., footnotes), or
32364 grouped in the backmatter (i.e., endnotes) before the reference list.
32365
32366 All notes shall be introduced by a superior number in the text, with
32367 the same number used for the text of the note. Notes should be single spaced,
32368 with double spacing between them.
32369
32370 \subsection{Backmatter}
32371
32372 The backmatter consists of the following pages, in order (all of which
32373 are optional).
32374 \begin{enumerate}
32375 \item Notes (if you are using endnotes and grouping them at the end)
32376 \item References (AKA `Bibliography' or `Works Cited')
32377 \item Appendices
32378 \item Biographical sketch (optional)
32379 \end{enumerate}
32380
32381 Pagination continues from the main text; but as with chapters, the first
32382 pages of any notes, references, or appendices are not numbered. A biographical
32383 sketch, if it is included, is the last page and is neither counted
32384 nor paginated.
32385
32386 Headings for the backmatter sections shall be in uppercase, centered, and
32387 on the top line.
32388
32389 \subsubsection{Notes}
32390
32391 The section for endnotes should begin on a new, unnumbered page. Subsequent
32392 pages should be numbered.
32393
32394 Use `NOTES', centered and at the top, as the heading for the notes section.
32395
32396 \subsubsection{References}
32397
32398 Use the reference heading appropriate for your discipline, in uppercase,
32399 centered and at the top of the page. Individual refences
32400 should be single-spaced with the second and later lines of a multiline
32401 reference indented with respect to the first line.
32402 There should be double-spacing between references.
32403
32404 \subsubsection{Appendices}
32405
32406 The heading for an appendix consists of the word `APPENDIX' followed by
32407 the uppercase letter signifying its position in the sequence of appendices
32408 (e.g., A or B or C or \ldots).
32409 This shall be centered on the top line. The title of the appendix, in
32410 uppercase, is centered on the following line. This page is not numbered.
32411 Subsequent pages are numbered and the text commences on the top text line
32412 of the following page.
32413
32414 \subsubsection{Biography}
32415
32416 The title for the optional biographical page is `BIOGRAPHICAL SKETCH',
32417 in the usual position. The text shall not exceed the one page.
32418
32419 \section{Code}
32420
32421 Given the above set of requirements we can produce code that,
32422 hopefully, will generate documents that will not fall foul of the
32423 inspectorate. For simplicity I'll do the code in the form of a
32424 package called \verb?pwasu.sty?. I will be using some \ltx\ kernel
32425 commands that you won't normally come across. Some of the macros
32426 include \idxatincode\texttt{@} as part of their name but this is safe
32427 as they are in a package, otherwise they would have to be within a
32428 \cmd{\makeatletter} \ldots \cmd{\makeatother} grouping (\seeatincode).
32429
32430 \subsection{Initialisation}
32431
32432 First, identify the package and its basic requirements.
32433 \begin{lcode}
32434 %%%% file pwasu.sty
32435 \NeedsTeXFormat{LaTeX2e}
32436 \ProvidesPackage{pwasu}[2009/04/18 v0.3 ASU thesis]
32437 \end{lcode}
32438 This is only going to work with memoir, so check if the class is being
32439 used, and if not then give an error message and stop reading the package code.
32440 \begin{lcode}
32441 %% Only works with the memoir class!!!!!!!!!!!!!!!
32442 \@ifclassloaded{memoir}{\let\endpwasu\relax}{\let\endpwasu\endinput
32443 \PackageError{pwasu}{The pwasu package only works with the memoir class}%
32444 {\@ehd}}
32445 \endpwasu
32446
32447 \end{lcode}
32448
32449 ASU is very strict about only using a single font in a single size.
32450 It is probable that
32451 at least one reference will be made to a location on the web. With \ltx\
32452 such references are set using the \Lpack{url} package, which defaults
32453 to using a monospaced font for urls. For ASU we have to make sure that
32454 they will be made using the body font (and the same applies to any verbatim
32455 text, such as computer code listings, for which we can use the
32456 \cmd{\setverbatimfont} command).
32457 \begin{lcode}
32458 \usepackage{url}
32459 \urlstyle{same}
32460 \setverbatimfont{\normalfont\rmfamily}% make verbatims use the body font
32461 \end{lcode}
32462 Ensuring that footnotes use the body font is a simple matter of redefining
32463 \cmd{\foottextfont}.
32464 \begin{lcode}
32465 \renewcommand*{\foottextfont}{\normalfont\normalsize}
32466
32467 \end{lcode}
32468
32469
32470 Noticing that the requirements can involve switching between double
32471 and single spacing, some of which will be done internally in the package,
32472 give the user a chance to change the default double spacing. The argument
32473 to \cs{setasuspacing} can be either \cmd{\OnehalfSpacing} or \cmd{\DoubleSpacing}.
32474 The result sets \cs{AsuSpacing} to be one of these commands.
32475 \begin{lcode}
32476 % To enable spacing to be changed if neccesary by the user
32477 \newcommand*{\setasuspacing}[1]{%
32478 \let\AsuSpacing#1
32479 \AsuSpacing}
32480 \setasuspacing{\DoubleSpacing}
32481 \end{lcode}
32482
32483 \subsection{Page layout}
32484
32485 As this is for an American University on letterpaper sized paper
32486 we'll assume letterpaper stock, so
32487 no cropping will be needed. Setting the side margins is easy:
32488 \begin{lcode}
32489 % left, right margins and textwidth
32490 \setlrmarginsandblock{1.5in}{1in}{*}
32491 \end{lcode}
32492
32493
32494 Setting the top and bottom margins requires more thought. \ltx\ provides the
32495 header and footer areas for page numbers. However, the requirements state
32496 that page numbers must be either on the top or bottom line (of the textblock)
32497 with the text extending down to the bottom line or up to the top line (of
32498 the textblock). I'll organise it according to the layout for the main body.
32499 Here, the top of the header is 1 inch below the top of the paper and the
32500 bottom of the text is 1 inch above the bottom of the paper (with the footer
32501 below that).
32502 \begin{lcode}
32503 %% for main body, bottom of text at 1in, footer below
32504 %% top of header at 1in, first text line double spaced
32505 %% below base of header
32506 \newlength{\linespace}
32507 \setlength{\linespace}{\baselineskip} % current equivalent of \onelineskip
32508 \setlength{\headheight}{\onelineskip}
32509 \setlength{\headsep}{\linespace}
32510 \addtolength{\headsep}{-\topskip}
32511 \setlength{\uppermargin}{1in}
32512 \addtolength{\uppermargin}{\headheight}
32513 \addtolength{\uppermargin}{\headsep}
32514 \end{lcode}
32515 And for the bottom margin:
32516 \begin{lcode}
32517 %% and for the bottom
32518 \setlength{\lowermargin}{1in}
32519 \setlength{\textheight}{\paperheight}
32520 \addtolength{\textheight}{-\uppermargin}
32521 \addtolength{\textheight}{-\lowermargin}
32522 \end{lcode}
32523 And finally for footnotes:
32524 \begin{lcode}
32525 %% footnote settings
32526 \setlength{\footskip}{\onelineskip}
32527 \setlength{\footnotesep}{\onelineskip}
32528
32529 \end{lcode}
32530 The layout on the preliminary pages is different, so I'll need
32531 some handy lengths in order to change the layout as appropriate.
32532 The user can also make adjustments with these if necessary.
32533 \begin{lcode}
32534 %% the fiddle lengths (..ta.. for title/approval page, others for prelims)
32535 \newlength{\toptafiddle} \setlength{\toptafiddle}{2\linespace}
32536 \newlength{\bottafiddle} \setlength{\bottafiddle}{0pt}
32537 \newlength{\topfiddle} \setlength{\topfiddle}{\toptafiddle}
32538 \newlength{\botfiddle} \setlength{\botfiddle}{\onelineskip}
32539 \end{lcode}
32540 That's it for the general layout, except for increasing the paragraph
32541 indentation as the line spacing is larger than normal.
32542 \begin{lcode}
32543 \setlength{\parindent}{2em}
32544 \checkandfixthelayout[nearest]
32545
32546 \end{lcode}
32547
32548 As the layout is set up, the bottom of the text is one inch above the
32549 bottom of the paper. This is fine for the main text and the Title and Approval
32550 pages but the text height must be decreased, temporarily, for the other
32551 pages in the prelims. Changes to the page layout\index{page layout!change}
32552 may be accomplished by
32553 the following sneaky procedure.
32554 First change from one- to two-column (or vice-versa), which starts a new
32555 page, make the changes, then change from two- to one-column (or vice-versa)
32556 which starts the same new page again but with the layout changes implemented.
32557 The following code implements this for the \cs{textheight} in a one
32558 column document, which is what we are dealing with here.
32559 \begin{lcode}
32560 \newcommand*{\addtotextheight}[1]{%
32561 \twocolumn
32562 \addtolength{\textheight}{#1}%
32563 \onecolumn}
32564 \end{lcode}
32565
32566 \subsection{Page styles}
32567
32568 Next I'll tackle the page styles. The style for the main body is simple,
32569 with the page number top right, and the \pstyle{empty} style is the one for
32570 chapter pages. The page number for the preliminary pages is centered
32571 at the bottom, and the \pstyle{plain} page style provides that. For the main
32572 text define the \pstyle{asu} page style.
32573 \begin{lcode}
32574 %%%% pagestyles
32575 %% the main text
32576 \makepagestyle{asu}
32577 \makeevenhead{asu}{\thepage}{}{}
32578 \makeoddhead{asu}{}{}{\thepage}
32579 \end{lcode}
32580
32581 Any `continuation' pages for the \toc, etc., have a header that consists
32582 of a name at the left and the word `Page' at the right. We need a header for
32583 each kind of listing.
32584 \begin{lcode}
32585 %% for continuation pages of the ToC, LoF, LoT
32586 \makepagestyle{toc}
32587 \makeevenfoot{toc}{}{\thepage}{}
32588 \makeoddfoot{toc}{}{\thepage}{}
32589 \makeevenhead{toc}{Chapter}{}{Page}
32590 \makeoddhead{toc}{Chapter}{}{Page}
32591 \makepagestyle{lof}
32592 \makeevenfoot{lof}{}{\thepage}{}
32593 \makeoddfoot{lof}{}{\thepage}{}
32594 \makeevenhead{lof}{Figure}{}{Page}
32595 \makeoddhead{lof}{Figure}{}{Page}
32596 \makepagestyle{lot}
32597 \makeevenfoot{lot}{}{\thepage}{}
32598 \makeoddfoot{lot}{}{\thepage}{}
32599 \makeevenhead{lot}{Table}{}{Page}
32600 \makeoddhead{lot}{Table}{}{Page}
32601 \end{lcode}
32602
32603 \subsection{The ToC and friends}
32604
32605 While we're at it, do the code for the \lof\ and \lot, which is simpler
32606 than that needed for the \toc. We have to specify our new pagestyles which
32607 can be done by extending the \cs{listof...} macros. The \cmd{\addtodef}
32608 macro makes this rather easy.
32609 \begin{lcode}
32610 %%%% The LoF
32611 \renewcommand{\listfigurename}{LIST OF FIGURES}
32612 \addtodef{\listoffigures}{\clearpage\pagestyle{lof}}{}
32613 \end{lcode}
32614 For the titles, these have to be moved up into the header area, so that
32615 they come just below the top margin, and set the initial pagestyle as
32616 \pstyle{plain}. After the title we can insert the relevant column headers.
32617 \begin{lcode}
32618 \renewcommand*{\lofheadstart}{\vspace*{-\topfiddle}}
32619 \renewcommand*{\afterloftitle}{\thispagestyle{plain}%
32620 \par\nobreak {\normalfont Figure \hfill Page}\par\nobreak}
32621
32622 \end{lcode}
32623 And the same for the \lot.
32624 \begin{lcode}
32625 %%% The LoT
32626 \renewcommand{\listtablename}{LIST OF TABLES}
32627 \addtodef{\listoftables}{\clearpage\pagestyle{lot}}{}
32628 \renewcommand*{\lotheadstart}{\vspace*{-\topfiddle}}
32629 \renewcommand*{\afterlottitle}{\thispagestyle{plain}%
32630 \par\nobreak {\normalfont Table \hfill Page}\par\nobreak}
32631
32632 \end{lcode}
32633
32634 The \toc\ is similar but we also have to deal with the entries themselves.
32635 \begin{lcode}
32636 %%%% Do the ToC
32637 \renewcommand{\contentsname}{TABLE OF CONTENTS}
32638 \addtodef{\tableofcontents}{\clearpage\pagestyle{toc}}{}
32639 \renewcommand*{\tocheadstart}{\vspace*{-\topfiddle}}
32640 \renewcommand*{\aftertoctitle}{\thispagestyle{plain}%
32641 \par\nobreak \mbox{}\hfill{\normalfont Page}\par\nobreak}
32642 \end{lcode}
32643 And the changes to the entries, all of which are set in the normal font
32644 and with dotted leaders, with no extra space between any of the entries.
32645 \begin{lcode}
32646 \renewcommand*{\cftchapterfont}{\normalfont}
32647 \renewcommand*{\cftchapterpagefont}{\normalfont}
32648 \renewcommand*{\cftchapterleader}{%
32649 \cftchapterfont\cftdotfill{\cftchapterdotsep}}
32650 \renewcommand*{\cftchapterdotsep}{\cftdotsep}
32651 \end{lcode}
32652 Unlike the typical \ltx\ \toc\ there must be no additional space before
32653 chapter entries; also, there should be no additional space inserted by
32654 the chapters in the \lof\ or \lot\ which just requires a simple redefinition
32655 of \cmd{\insertchapterspace}..
32656 \begin{lcode}
32657 %%% no extra space before the entry, or in the LoF/LoT
32658 \setlength{\cftbeforechapterskip}{0pt plus 0pt}
32659 \renewcommand*{\insertchapterspace}{}
32660 \end{lcode}
32661
32662 \subsection{Chapter styling}
32663
32664 Moving on to styling the chapter titles, the first line must be moved up
32665 into the header area, and other spacings set to give blank lines. The fonts
32666 are just the regular body font. Call the chapterstyle \cstyle{asu} and make
32667 sure that the \pstyle{empty} pagestyle is used for it.
32668
32669 \begin{lcode}
32670 %% chapter style
32671 \makechapterstyle{asu}{%
32672 \setlength{\beforechapskip}{-\topfiddle}
32673 \setlength{\midchapskip}{1.0\onelineskip}
32674 \setlength{\afterchapskip}{1.0\onelineskip}
32675 \renewcommand*{\chapnamefont}{\normalfont}
32676 \renewcommand*{\chapnumfont}{\chapnamefont}
32677 \renewcommand*{\printchapternum}{\centering\chapnumfont \thechapter}
32678 \renewcommand*{\chaptitlefont}{\normalfont\centering}
32679 \renewcommand*{\printchapternonum}{}}
32680 \aliaspagestyle{chapter}{empty}
32681
32682 \end{lcode}
32683
32684 The chapterstyle for any appendices is slightly different as the title,
32685 all in uppercase, is
32686 on one page by itself and the text starts on the following page. Call
32687 this the \cstyle{asuappendix} chapterstyle.
32688
32689 \begin{lcode}
32690 %% chapter style for appendices, text comes on following page
32691 \makechapterstyle{asuappendix}{%
32692 \setlength{\beforechapskip}{-\topfiddle}
32693 \setlength{\midchapskip}{1.0\onelineskip}
32694 \setlength{\afterchapskip}{1.0\onelineskip}
32695 \renewcommand*{\chapnamefont}{\normalfont}
32696 \renewcommand*{\chapnumfont}{\chapnamefont}
32697 \renewcommand*{\printchaptername}{%
32698 \chapnamefont\MakeUppercase{\@chapapp}}
32699 \renewcommand*{\printchapternum}{\centering\chapnumfont \thechapter}
32700 \renewcommand*{\chaptitlefont}{\normalfont\centering}
32701 \renewcommand*{\printchapternonum}{}
32702 \renewcommand*{\afterchaptertitle}{\clearpage}}
32703
32704 \end{lcode}
32705
32706 We have to extend the \cmd{\appendix} command to use the new chapter
32707 style, and also to ensure that double spacing will be used (certain elements
32708 that come before the appendices are single spaced).
32709
32710 \begin{lcode}
32711 %%% different chapter style for appendices, (and double spaced)
32712 \addtodef{\appendix}{}{\chapterstyle{asuappendix}\AsuSpacing}
32713 \end{lcode}
32714
32715 \subsection{Section, etc., styling}
32716
32717 Set up the section headings so that they are centered, use the normal
32718 font, and have a blank line before and after.
32719
32720 \begin{lcode}
32721 %%% (subsub)section styles
32722 \setsecheadstyle{\centering\normalfont}
32723 \setbeforesecskip{-1\onelineskip plus -1ex minus -.2ex}
32724 \setaftersecskip{1\onelineskip plus .2ex}
32725 \setsubsecheadstyle{\centering\normalfont}
32726 \setbeforesubsecskip{-1\onelineskip plus -1ex minus -.2ex}
32727 \setaftersubsecskip{1\onelineskip plus .2ex}
32728 \end{lcode}
32729
32730
32731 \subsection{Captions}
32732
32733 The captions are set flushleft and raggedright with the name and number
32734 on one line and the title on the following line. Fortunately floats are
32735 automatically set single spaced, which is what the requirements specify.
32736
32737 \begin{lcode}
32738 %% Captions
32739 \captiontitlefont{\normalfont}% title font
32740 \precaption{\raggedright}% for Caption N
32741 \captiondelim{\newline}% newline
32742 \captionstyle{\raggedright}% for title
32743 \setlength{\belowcaptionskip}{\onelineskip}
32744 \end{lcode}
32745
32746 \subsection{The bibliography}
32747
32748 The requirements imply that the title is likely to be `REFERENCES'.
32749 The bibliography is set single spaced but with a blank line between
32750 the entries.
32751
32752 \begin{lcode}
32753 %% for REFERENCE section
32754 \renewcommand*{\bibname}{REFERENCES}
32755 \setlength{\bibitemsep}{\onelineskip}
32756 \end{lcode}
32757
32758 The second and later lines of any entry are to be indented. We use the
32759 \cmd{\biblistextra} hook for setting this up.
32760 \begin{lcode}
32761 \renewcommand*{\biblistextra}{%
32762 \setlength{\itemsep}{\bibitemsep}
32763 \setlength{\labelwidth}{0pt}
32764 \setlength{\leftmargin}{3em}% hanging indent
32765 \setlength{\itemindent}{-\leftmargin}}
32766 \end{lcode}
32767
32768 The title for the bibliography is set via the \cmd{\bibsection} macro.
32769 The heading is unnumbered but is added to the \toc. To get the spacing
32770 right the heading, set as a \cs{chapter*}, which must be called double spaced,
32771 and then single spacing is called for after that.
32772 \begin{lcode}
32773 \renewcommand*{\bibsection}{%
32774 \AsuSpacing
32775 \chapter*{\bibname}\addcontentsline{toc}{chapter}{\bibname}
32776 \SingleSpacing}
32777 \end{lcode}
32778
32779
32780 \subsection{End notes}
32781
32782 The heading for the Notes section is similar to the bibliography
32783 heading.
32784 \begin{lcode}
32785 %% endnotes
32786 \renewcommand*{\notesname}{NOTES}
32787 \renewcommand*{\notedivision}{%
32788 \AsuSpacing
32789 \chapter*{\notesname}
32790 \addcontentsline{toc}{chapter}{\notesname}
32791 \SingleSpacing}
32792 \end{lcode}
32793
32794 The rest of the code for endnotes\index{endnotes} ensures that they are
32795 numbered
32796 continuously throughout the text, the number is set as a superscript, that
32797 there is a blank line between each entry, and that there are no subdivisions
32798 within the listing.
32799 \begin{lcode}
32800 \continuousnotenums
32801 \renewcommand*{\notenuminnotes}[1]{\textsuperscript{#1}\space}
32802 \renewcommand{\noteinnotes}[1]{#1\\}
32803 \renewcommand*{\pagenotesubhead}[3]{}% no subheads
32804 \end{lcode}
32805
32806 \subsection{Preliminary headings}
32807
32808 There can be any number of sections in the prelims. The
32809 titles for these are located in the \ltx\ header area. Here's a general
32810 macro for setting these.
32811
32812 \begin{lcode}
32813 %%% general macro for Abstract, etc., headings
32814 \newcommand*{\pretoctitle}[1]{{\clearpage\centering
32815 \vspace*{-\topfiddle}#1\par}}
32816 %%% Start the ACKNOWLEDGEMENTS
32817 \newcommand{\asuacknowledgements}{\pretoctitle{ACKNOWLEDGEMENTS}}
32818
32819 \end{lcode}
32820
32821 The Abstract is the
32822 first section after the title and approval pages. At this point we must reduce
32823 the textheight in order to raise the footer area.
32824 \begin{lcode}
32825 %%% Start the ABSTRACT
32826 \newcommand{\asuabstract}{%
32827 \addtotextheight{-\botfiddle}%
32828 \pretoctitle{ABSTRACT}}
32829 \end{lcode}
32830 While we are at this, the textheight must be reset to its default value
32831 just before the first chapter in the main matter. A simple addition to
32832 \cmd{\mainmatter} handles this.
32833 \begin{lcode}
32834 \addtodef{\mainmatter}{\addtotextheight{\botfiddle}{}
32835
32836 \end{lcode}
32837
32838 The dedication, if any, does not have a heading and the text is centered
32839 horizontally and vertically.
32840 \begin{lcode}
32841 %% make it easy to center any dedication
32842 \newcommand{\asudedication}[1]{%
32843 {\clearpage\mbox{}\vfill\centering #1 \par\vfill\clearpage}}
32844
32845 \end{lcode}
32846
32847 There may be sections in the prelims that come after the \toc, and
32848 the titles of these are added to the \toc.
32849 \begin{lcode}
32850 %% for any headings after the tocloft and before the main body
32851 \newcommand{\prelimtitle}[1]{%
32852 \pretoctitle{#1}\addcontentsline{toc}{chapter}{#1}}
32853 \end{lcode}
32854
32855 \subsection{Components of the title and approval pages}
32856
32857 There are several items that are set on the title and approval pages.
32858 In order to separate the information from the particular layout, I've
32859 defined a macro for defining each item.
32860 \begin{lcode}
32861 %%%% for the title page and approval page.
32862 % your title
32863 \newcommand{\settitle}[1]{\def\asutitle{#1}}
32864 % you
32865 \newcommand{\setauthor}[1]{\def\asuauthor{#1}}
32866 % document type (e.g., thesis)
32867 \newcommand{\setdoctype}[1]{\def\asudoctype{#1}}
32868 % possible degree
32869 \newcommand{\masters}{\def\asudegree{Master of Arts}}
32870 \newcommand{\doctors}{\def\asudegree{Doctor of Philosophy}}
32871 % defence date
32872 \newcommand{\setdefdate}[1]{\def\asudefdate{#1}}
32873 % graduation date
32874 \newcommand{\setgraddate}[1]{\def\asugraddate{#1}}
32875 % committe chair
32876 \newcommand{\setchair}[1]{\def\asuchair{#1, Chair}}
32877 % committe co-chairs
32878 \newcommand{\setchairs}[2]{%
32879 \def\asuchair{#1, Co-chair \\ #2, Co-chair}}
32880 % other members (separated by \\s)
32881 \newcommand{\setmembers}[1]{\def\asumembers{#1\par}}
32882
32883 \end{lcode}
32884
32885 Just for fun, create some default settings for these. The successful
32886 user will have changed them all!
32887 \begin{lcode}
32888 %% Use them like this, and if you don't change them you will
32889 %% get unacceptable title and/or approval pages
32890 \settitle{AN INCREDIBLE PIECE OF WORK OVER WHICH I HAVE STRUGGLED
32891 DAY AND NIGHT FOR FAR TOO LONG AND NOW IT IS OVER}
32892 \setauthor{A. N. Author}
32893 \setdoctype{Polemic}
32894 \masters % going for a Masters degree
32895 %% \doctors % going for a PhD
32896 \setdefdate{April 2018}
32897 \setgraddate{May 2021}
32898 % \setchair{A. Jones} % this one
32899 \setchairs{A. Jones}{B. Doe} % or this one
32900 \setmembers{C. Smith \\ D. Somebody \\ Some One Else \\ Yet Another}
32901 \end{lcode}
32902
32903 \subsection{The title and approval pages}
32904
32905 \PWnote{2009/07/09}{Added 2 ASU figures}
32906 An example of a title page is shown in \fref{fig:titleASUt} and
32907 an example of the corresponding approval page is in \fref{fig:titleASUa}.
32908
32909 \begin{figure}
32910 \centering
32911 \begin{showtitle}
32912 \titleASUt
32913 \end{showtitle}
32914 \caption{Example Archibald Smythe University title page}\label{fig:titleASUt}
32915 \end{figure}
32916
32917 \begin{figure}
32918 \centering
32919 \begin{showtitle}
32920 \titleASUa
32921 \end{showtitle}
32922 \caption{Example Archibald Smythe University approval page}\label{fig:titleASUa}
32923 \end{figure}
32924
32925 Now we can set up the layouts for the title and approval pages. The
32926 information typeset on these pages is obtained from the previous set of
32927 commands. Note that the last line on each of these pages has to be set
32928 upon the bottom margin. The ASU inspectorate is likely to be very
32929 keen on this, perhaps using a ruler to measure the actual distance from
32930 the bottom of the page to ensure that it is the magic 1~inch. I have
32931 included an \cmd{\enlargethispage} by the amount \cs{bottafiddle} so the
32932 user can make any fine adjustment that might be requested. Similarly, the
32933 length \cs{toptafiddle} may be altered to fine tune the position of the
32934 title. Hopefully, neither of these tweaks will be needed, but if so, then use
32935 \cmd{\addtolength} instead of \cmd{\setlength} to make an adjustement.
32936
32937 \begin{lcode}
32938 %%% typesets the TITLE page
32939 \newcommand{\thetitlepage}{{%
32940 \clearpage
32941 \thispagestyle{empty}
32942 \centering
32943 \vspace*{-\toptafiddle}
32944 \asutitle \\ by \\ \asuauthor
32945 \vfill
32946
32947 {\SingleSpace
32948 A \asudoctype\ Presented in Partial Fulfillment \\
32949 of the Requirements for the Degree \\
32950 \asudegree\par}
32951
32952 \vfill
32953 ARCHIBALD SMYTHE UNIVERSITY \\
32954 \asugraddate
32955 \par
32956 \enlargethispage{\bottafiddle}
32957 \clearpage}}
32958
32959 \end{lcode}
32960
32961 And similary for the approval page.
32962
32963 \begin{lcode}
32964 %%% typesets the APPROVAL page
32965 \newcommand{\approvalpage}{{%
32966 \thispagestyle{empty}
32967 \centering
32968 \vspace*{-\toptafiddle}
32969 \asutitle \\ by \\ \asuauthor \\[3\onelineskip]
32970 has been approved \\
32971 \asudefdate
32972
32973 \vfill
32974
32975 Graduate Supervisory Committee: \\[-0.5\onelineskip]
32976 {\SingleSpacing
32977 \asuchair \\
32978 \asumembers}
32979
32980 \vfill
32981 ACCEPTED BY THE GRADUATE COLLEGE
32982 \par
32983 \enlargethispage{\bottafiddle}
32984 \clearpage}}
32985 \end{lcode}
32986
32987 \subsection{The last bits}
32988
32989 The biographical sketch has a title (which is not added to
32990 the \toc), the text is single spaced and there is no page number.
32991 It is easiest to provide this as an environment.
32992 \begin{lcode}
32993 %%% put your biographical text in this environment
32994 %% \begin{biosketch} I'm a person who has accomplished .... \end{biosketch}
32995 \newenvironment{biosketch}{%
32996 \pretoctitle{BIOGRAPHICAL SKETCH}\thispagestyle{empty}\SingleSpacing}%
32997 {}
32998 \end{lcode}
32999
33000 Make sure that the requisite initial page style and appropriate
33001 chapter style is used.
33002 \begin{lcode}
33003 %% use the asu chapterstyle and plain pagestyle
33004 \chapterstyle{asu}
33005 \pagestyle{plain}
33006
33007 %%%%%%%%%%%%%%% end of *.sty file
33008 \endinput
33009 %%%%%%%%%%%%%%%
33010 \end{lcode}
33011
33012 \section{Usage}
33013
33014 This is a sketch of how an ASU thesis could be
33015 written.\fxnote[author=dlf,vadj=0em]{add something about modern free
33016 font packages}
33017
33018 With the wide textblock, 12pt is too small for reading ease, so best not
33019 to use 11pt or 10pt.
33020
33021 Times Roman\index{Times Roman} comes with \ltx, but you are
33022 effectively writing a book,
33023 not a newspaper column. If you have Garamond\index{Garamond}
33024 or Lucida Bright\index{Lucida Bright} then
33025 seriously consider using one or other of them.\footnote{Garamond is a
33026 commercial font and, for example, is available along with many other fonts
33027 from FontSite (\url{http://www.fontsite.com})
33028 with \ltx\ support from \url{http://contrapunctus.net/fs500tex}.
33029 Lucida Bright, another commercial font,
33030 is available from TUG at \url{http://tug.org/store/lucida} and is supported
33031 by several \ltx\ packages.} Lucida Bright is probably more appropriate if
33032 your thesis includes mathematics while Garamond is perhaps more in keeping
33033 if your thesis topic falls into the humanities area.
33034 If the requirements did not limit your choices then there are other
33035 fonts that might better express your work. In any case
33036 I suggest that you do not use a sans font (e.g.,
33037 Arial\index{Arial},
33038 Tahoma\index{Tahoma} or
33039 Verdana\index{Verdana} from the ASU list).
33040
33041 \begin{lcode}
33042 \documentclass[oneside,12pt]{memoir}
33043 \usepackage{mathptmx} % Times New Roman
33044 \usepackage{pwasu} % the package
33045
33046 \end{lcode}
33047
33048 The general sequence in your document, after you have set the data for
33049 the TITLE and APPROVAL pages and any other specifics and packages in the
33050 preamble, is:
33051 \begin{lcode}
33052 % if you can get away without the default \DoubleSpacing, then
33053 %\setasuspacing{\OnehalfSpacing}
33054 %% if you use endnotes, then
33055 \makepagenote
33056 \begin{document}
33057 \maxtocdepth{subsection} % put 3 levels into the ToC
33058 \frontmatter
33059 \thetitlepage
33060 \approvalpage
33061 \asuabstract
33062 abstract text
33063 %% if you have any acknowledgements, then
33064 \asuacknowledgements
33065 acknowledgements text
33066 % \asudedication{ text } % if you want a dedication
33067 \tableofcontents
33068 % \listoffigures % if you have any figures
33069 % \listoftables % if you have any tables
33070 %%% if you have more prelim sections, then
33071 %%% \clearpage
33072 %%% \pagestyle{plain}
33073 %%% \prelimtitle{title} text % for each section before main text
33074 \mainmatter
33075 \pagestyle{asu}
33076 \chapter{...} % start of your main text
33077 ... report on lots of incredible work, now you are on your
33078 own until...
33079
33080 %% if endnotes then
33081 \printpagenotes
33082 %% if a bibliography then
33083 \begin{thebibliography}...\end{thebibliography}
33084 %% if appendices, then
33085 \appendix
33086 \chapter{...}
33087 ...
33088 %% if Biographical sketch then
33089 \begin{biosketch} ... \end{biosketch}
33090 \end{document}
33091
33092 \end{lcode}
33093
33094 If you actually try any of the above code and it does not work, then
33095 I may have made a typo or two, or maybe you have, or perhaps we both have.
33096 In any event, the code is more of a sketch of what might be needed than
33097 a prescription of how it must be done.
33098
33099 \section{Comments}
33100
33101 Having read through the requirements you will have realised
33102 that whatever committees set them had not advanced beyond the 19th century
33103 technology of the typewriter\index{typewriter}.\footnote{Remington sold
33104 their first commercial typewriter in 1873 which even then had the QWERTY
33105 keyboard layout. By 1910 typewriter designs were pretty well standardised.}
33106 When I wrote my thesis some forty years ago
33107 it was, of necessity, single sided so that carbon copies could be made
33108 by the typist\index{typist} (who would have objected strongly to having
33109 to type the hundred
33110 and fifty or so pages six times). I must admit, though, that the sixth copy
33111 was almost too faint and blurry to be read comfortably even though the typist
33112 had used thin paper and kept replacing the carbon paper.
33113 In this day of double sided printers and double sided copiers I see no
33114 reason except inertia to keep a single sided requirement. Many students,
33115 and faculty members, have beaten their heads against
33116 the diehards and very rarely have they managed to prevail.
33117
33118 \PWnote{2009/07/09}{Added comments on Sneep's thesis}
33119 In contrast to the ASU style I have a copy of a doctoral
33120 thesis~\cite{SNEEP04} for Vrije Universiteit, Amsterdam. This is a
33121 professionally printed 100 page, double sided, glossy paperbound book with an
33122 attractive coloured
33123 photograph of a sunset on the front and rear covers. The page size is 40.5pc by
33124 57pc with spine and top margins of 5pc and foredge and bottom margins of
33125 7pc.\footnote{Professional printers use points and picas for their
33126 measurements.} The textblock, then, is 28.5 by 45pc set with 45 lines of
33127 a 10pt Lucida Bright seriffed font.
33128 Chapter and section heads are in a sans font, with the chapter heads larger
33129 than the section heads. Caption names are a bold sans with the caption text
33130 in an italic. Headers on the verso pages are the chapter title with the section
33131 title as the recto header. The page numbers are in the footers by the foredge
33132 margin. Altogether, a much more appealing production
33133 than Archibald Smythe University will permit.
33134
33135 %#% extend
33136
33137 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
33138 %%%%%%%%%% appendices
33139 \appendix
33140 \appendixpage*
33141 %%\pagestyle{ruled}
33142
33143 %%\chapterstyle{normal}
33144 %%\chapterstyle{section}
33145 %%\chapterstyle{demo3}
33146
33147 %#% extstart include packages-and-maros.tex
33148
33149 \svnidlong
33150 {$Ignore: $}
33151 {$LastChangedDate: 2025-09-19 16:06:27 +0200 (Fri, 19 Sep 2025) $}
33152 {$LastChangedRevision: 873 $}
33153 {$LastChangedBy: [email protected] $}
33154
33155 \chapter{Packages and macros}
33156
33157 The \Mname\ class does not provide for everything that you
33158 have seen in the manual. We have used some packages that you are very likely
33159 to have in your \ltx\ distribution, and have supplemented these with some
33160 additional macros, some of which we will show you.\fxnote[author=dlf,vadj=0em]{need to be rewritten}
33161
33162 \section{Packages}
33163
33164 The packages that we have used that you are likely to have, and if
33165 you do not have them please consider getting them,
33166 are:
33167 \begin{itemize}
33168 % \item \Lpack{etex} lets you take advantage of e\tx's extended support
33169 % for counters and such.
33170
33171 % Note that from 2015 and onwards, the allocation of extra
33172 % registers have now been build into the LaTeX kernel. Thus in
33173 % most cases the \Lpack{etex} package is no longer
33174 % necessary. There are how ever extra very special features left
33175 % in \Lpack{etex} that \emph{some} users may need. In that case
33176 % please remember to load \Lpack{etex} by placing
33177 % \verb|\RequirePackage{etex}| \emph{before} \cs{documentclass}!
33178 \item \Lpack{url}~\cite{URL} is for typesetting URL's without worrying
33179 about special characters or line breaking.
33180
33181 Nowadays \Lpack{xurl}~\cite{XURL} is probably better as it allows
33182 more preak points.
33183
33184
33185 % \item \Lpack{fixltx2e}~\cite{FIXLTX2E} eliminates some infelicities
33186 % of the original LaTeX kernel. In particular it maintains the order
33187 % of floats\index{float} on a twocolumn\index{column!double} page
33188 % and ensures the correct marking
33189 % on a twocolumn\index{column!double} page.
33190
33191 % Note that as of 2015, the functionality of this package has been
33192 % merged into the \LaTeX{} kernel. Loading this package does nothing.
33193
33194
33195 \item \Lpack{alltt}~\cite{ALLTT} is a basic package which provides a
33196 verbatim-like environment but \verb?\?, \verb?{?, and \verb?}? have their
33197 usual meanings (i.e., \ltx\ commands are not disabled).
33198 \item \Lpack{graphicx}~\cite{GRAPHICX} is a required package for
33199 performing various kinds of graphical functions.
33200 \item \Lpack{color}~\cite{COLOR} is a required package for using color,
33201 or \Lpack{xcolor}~\cite{XCOLOR} is an enhanced version of \Lpack{color}.
33202 \item \Lpack{latexsym} gives access to some extra symbols.
33203 \item \Lpack{amsmath} for when you are doing anything except the
33204 simplest kind of maths typeseting.
33205 \item \Lpack{fontenc} for using fonts with anything other than the
33206 original \texttt{OT1} encoding (i.e., for practically any font).
33207 \item \Lpack{pifont} for typesetting Pifonts
33208 (i.e., Symbol\facesubseeidx{Symbol} and
33209 Zapf Dingbats\facesubseeidx{Zapf Dingbats})
33210 \end{itemize}
33211
33212 Apart from the packages that are supplied as part of the \Mname\
33213 distribution, the packages that I used and you most likely do not have are:
33214 \begin{itemize}
33215 \item \Lpack{layouts}~\cite{LAYOUTS}. I used it for all the layout diagrams.
33216 For example, \fref{fig:displaysechead} and \fref{fig:runsechead}
33217 were drawn simply by:
33218 \begin{lcode}
33219 \begin{figure}
33220 \centering
33221 \setlayoutscale{1}
33222 \drawparameterstrue
33223 \drawheading{}
33224 \caption{Displayed sectional headings} \label{fig:displaysechead}
33225 \end{figure}
33226
33227 \begin{figure}
33228 \centering
33229 \setlayoutscale{1}
33230 \drawparameterstrue
33231 \runinheadtrue
33232 \drawheading{}
33233 \caption{Run-in sectional headings} \label{fig:runsechead}
33234 \end{figure}
33235 \end{lcode}
33236 The package also lets you try experimenting with different layout
33237 parameters and draw diagrams showing what the results would be in a document.
33238
33239 The version of \Lpack{layouts} used for this manual is
33240 v2.4 dated 2001/04/30. Earlier versions will fail when attempting
33241 to draw some figures
33242 ( e.g., to draw \fref{fig:oddstock}).
33243
33244 \item \Lpack{fonttable}~\cite{FONTTABLE}. I used this for the font tables
33245 (e.g., \tref{tab:symbolglyphs}).
33246 You must have at least version 1.3 dated April 2009
33247 for processing the manual (earlier versions are likely to produce errors
33248 in the number formatting area with minor, but odd looking, effect on
33249 the printed result).
33250
33251 \end{itemize}
33252
33253
33254 \section{Macros}
33255
33256 Originally the preamble\index{preamble} of the manual contained many macro
33257 definitions, probably more than most documents would because:
33258 \begin{itemize}
33259 \item I am having to typeset many \ltx\ commands, which require
33260 some sort of special processing;
33261 \item I have tried to minimize the number of external packages needed
33262 to \ltx\ this manual satisfactorily, and so have copied various
33263 macros from elsewhere;
33264 \item I wanted to do some automatic indexing\index{index};
33265 \item I wanted to set off the syntax specifications and the code examples
33266 from the main text.
33267 \end{itemize}
33268 I have since put the majority of these into a package file called
33269 \file{memsty.sty}.
33270 To get the whole glory you will have to read the preamble\index{preamble},
33271 and the \Lpack{memsty} package file but I show a few of the macros below
33272 as they may be of more general interest.
33273
33274 \begin{syntax}
33275 \cmd{\Ppstyle}\marg{pagestyle} \cmd{\pstyle}\marg{pagestyle} \\
33276 \end{syntax}
33277 The command \cmd{\Ppstyle} prints its argument in the font used to indicate
33278 pagestyles and the command \cmd{\pstyle} prints its pagestyle argument and also
33279 makes a pagestyle entry in the index\index{index}. Its definition is
33280 \begin{lcode}
33281 \newcommand*{\pstyle}[1]{\Ppstyle{#1}%
33282 \index{#1 pages?\Ppstyle{#1} (pagestyle)}%
33283 \index{pagestyle!#1?\Ppstyle{#1}}}
33284 \end{lcode}
33285 The first part prints the argument in the text and the second adds two
33286 entries to the \file{idx} file. The fragment \verb?#1 pages? is what
33287 the \Lmakeindex\ program will use for sorting entries, and the
33288 fragment following the \texttt{?} character is what will be put into the
33289 index\index{index}.
33290
33291 \begin{syntax}
33292 \cmd{\Pcstyle}\marg{chapterstyle} \cmd{\cstyle}\marg{chapterstyle} \\
33293 \end{syntax}
33294 The command \cmd{\Pcstyle} prints its argument in the font used to indicate
33295 chapterstyles and \cmd{\cstyle} prints its chapterstyle argument
33296 and also makes a chapterstyle entry in the
33297 index\index{index}. Its definition is
33298 \begin{lcode}
33299 \newcommand*{\cstyle}[1]{\Pcstyle{#1}%
33300 \index{#1 chaps?\Pcstyle{#1} (chapterstyle)}%
33301 \index{chapterstyle!#1?\Pcstyle{#1}}}
33302 \end{lcode}
33303 which is almost identical to \cmd{\pstyle}.
33304
33305 There is both a \cstyle{companion} chapterstyle and a \pstyle{companion}
33306 pagestyle. The strings used for sorting the index\index{index} entries for
33307 these are
33308 \texttt{companion chaps} and \texttt{companion pages} respectively, so
33309 the chapterstyle will come before the pagestyle in the index\index{index}.
33310 The reason for distinguishing between the string used for sorting and the
33311 actual entry is
33312 partly to distinguish between different kinds of entries for a single name
33313 and partly to avoid any formatting commands messing up the sorted order.
33314
33315 \begin{syntax}
33316 \senv{syntax} syntax \eenv{syntax} \\
33317 \end{syntax}
33318 The \Ie{syntax} environment is for specifying command and environment
33319 syntax. Its definition is
33320 \begin{lcode}
33321 \newcommand*{\tightcenter}{%
33322 \topsep=0.25\onelineskip\trivlist \centering\item\relax}
33323 \def\endtigthcenter{\endtrivlist}
33324 \newenvironment{syntax}{\begin{tightcenter}
33325 \begin{tabular}{|p{0.9\linewidth}|} \hline}%
33326 {\hline
33327 \end{tabular}
33328 \end{tightcenter}}
33329 \end{lcode}
33330 It is implemented in terms of the \Ie{tabular} environment, centered within
33331 the typeblock, which forms
33332 a box that will not be broken across a pagebreak. The box frame
33333 is just the normal horizontal and vertical lines that you can use with
33334 a \Ie{tabular}. The width is fixed at 90\% of the text width. As it
33335 is a \Ie{tabular} environment, each line of syntax must be ended with
33336 \cmd{\\}. Note that normal \ltx\ processing occurs within the \Ie{syntax}
33337 environment, so you can effectively put what you like inside it.
33338 The \Ie{center} environment is defined in terms of a \Ie{trivlist} and
33339 \cmd{\centering}. I wanted to be able to control the space before and
33340 after the `\cmd{\centering}' so I defined the \Ie{tightcenter} environment
33341 which enabled me to do this.
33342
33343
33344 \begin{syntax}
33345 \senv{lcode} LaTeX code \eenv{lcode} \\
33346 \end{syntax}
33347 I use the \Ie{lcode} environment for showing examples of \ltx\ code. It
33348 is a special kind of \Ie{verbatim} environment where the font size is
33349 \cmd{\small} but the normal \lnc{\baselineskip} is used, and each line
33350 is indented.
33351
33352 At the bottom the environment is defined in terms of a \Ie{list},
33353 although that is not obvious from the code; for details see the
33354 class code~\cite{MEMCODE}. I wanted the environment to be a tight list
33355 and started off by defining two helper items.
33356 \begin{lcode}
33357 % \@zeroseps sets list before/after skips to minimum values
33358 \newcommand*{\@zeroseps}{\setlength{\topsep}{\z@}
33359 \setlength{\partopsep}{\z@}
33360 \setlength{\parskip}{\z@}}
33361 % \gparindent is relative to the \parindent for the body text
33362 \newlength{\gparindent} \setlength{\gparindent}{0.5\parindent}
33363 \end{lcode}
33364 The macro \cmd{\@zeroseps} sets the before, after and middle skips in
33365 a list to 0pt (\cmd{\z@} is shorthand for 0pt). The length \lnc{\gparindent}
33366 will be the line indentation in the environment.
33367 \begin{lcode}
33368 % Now we can do the new lcode verbatim environment.
33369 % This has no extra before/after spacing.
33370 \newenvironment{lcode}{\@zeroseps
33371 \renewcommand{\verbatim@startline}%
33372 {\verbatim@line{\hskip\gparindent}}
33373 \small\setlength{\baselineskip}{\onelineskip}\verbatim}%
33374 {\endverbatim
33375 \vspace{-\baselineskip}\noindent}
33376 \end{lcode}
33377
33378 The fragment \verb?{\hskip\gparindent}? puts \lnc{\gparindent} space at
33379 the start of each line.
33380
33381 The fragment \verb?\small\setlength{\baselineskip}{\onelineskip}? sets the
33382 font size to be \cmd{\small}, which has a smaller \lnc{\baselineskip}
33383 than the normal font, but this is corrected for by changing the local
33384 \lnc{\baselineskip} to the normal skip, \lnc{\onelineskip}. At the end
33385 of the environment there is a negative space of one line to compensate
33386 for a one line space that LaTeX inserts.
33387
33388 %%% \Sref{sec:versal} is in the design manual
33389 % \begin{comment}
33390 % The two versals in \Sref{sec:versal} were typeset with macros defined
33391 % in \Lpack{memsty}. The poorer of the two used the \cmd{\drop}
33392 % macro which was written for \ltx\ v2.09 by David Cantor and Dominik Wujastyk
33393 % in 1998. The better used the \cmd{\versal} macro. Now, if you want
33394 % to try your hand at this sort of thing there are some more packages
33395 % on CTAN. I have found that the \Lpack{lettrine} package~\cite{LETTRINE}
33396 % serves my needs.
33397 % \end{comment}
33398
33399
33400 %#% extend
33401 %#% extstart include showcases.tex
33402
33403 \svnidlong
33404 {$Ignore: $}
33405 {$LastChangedDate: 2010-05-13 17:10:00 +0200 (Thu, 13 May 2010) $}
33406 {$LastChangedRevision: 210 $}
33407 {$LastChangedBy: daleif $}
33408
33409 \chapter{Showcases}
33410 \label{cha:showcases}
33411
33412 The \theclass\ memoir class has several features that involve a
33413 \emph{style} and it provide several of these styles. This chapter is
33414 used to showcase these styles.
33415
33416
33417 \begingroup
33418 % because of hyperref warnings
33419
33420
33421 \section{Chapter styles}
33422 \label{sec:chapter-styles}
33423
33424 \index{chapterstyle|(}
33425
33426 For more about defining chapter styles, see
33427 \Sref{sec:chapter-headings}, \pref{sec:chapter-headings}.
33428
33429 \begin{demochap}[-3\onelineskip]{default}\end{demochap}
33430
33431 \begin{demochap}[2\onelineskip]{section}\end{demochap}
33432
33433 \begin{demochap}[2\onelineskip]{hangnum}\end{demochap}
33434
33435 \begin{demochap}[2\onelineskip]{companion}\end{demochap}
33436
33437 \begin{demochap}[-1\onelineskip]{article}\end{demochap}
33438
33439 \begin{demochap}[-2\onelineskip]{bianchi}\end{demochap}
33440
33441 \begin{demochap}{bringhurst}\end{demochap}
33442
33443 \begin{demochap}[-2\onelineskip]{brotherton}\end{demochap}
33444
33445 \begin{demochap}{chappell}\end{demochap}
33446
33447 \begin{demochap}[-2\onelineskip]{crosshead}\end{demochap}
33448
33449 \begin{demochap}[-\onelineskip]{culver}\end{demochap}
33450
33451 \begin{demochap}[-4\onelineskip]{dash}\end{demochap}
33452
33453 \begin{demochap}[-\onelineskip]{demo2}\end{demochap}
33454
33455 \begin{demochap}[-2\onelineskip]{dowding}\end{demochap}
33456
33457 \begin{demochap}{ell}\end{demochap}
33458
33459 \begin{demochap}[-4\onelineskip]{ger}\end{demochap}
33460
33461 \begin{demochap}[-2\onelineskip]{komalike}\end{demochap}
33462
33463 \begin{demochap*}[-2\onelineskip]{lyhne}\end{demochap*}
33464
33465 \clearpage
33466
33467 \begin{demochap*}[-2\onelineskip]{madsen}\end{demochap*}
33468
33469 \begin{demochap}[-3\onelineskip]{ntglike}\end{demochap}
33470
33471 \begin{demochap}[-\onelineskip]{southall}\end{demochap}
33472
33473 \begin{demochap}[-1\onelineskip]{tandh}\end{demochap}
33474
33475 \begin{demochap}{thatcher}\end{demochap}
33476
33477 \begin{demochap*}[-2\onelineskip]{veelo}\end{demochap*}
33478
33479 \begin{demochap}{verville}\end{demochap}
33480
33481 \FloatBlock
33482
33483
33484 \begin{demochap}[-1\onelineskip]{wilsondob}\end{demochap}
33485
33486
33487 The code for some of these styles is given in below. For details of
33488 how the other chapter styles are defined, look at the documented class
33489 code. This should give you ideas if you want to define your own style.
33490
33491 Note that it is not necessary to define a new chapterstyle if you want
33492 to change the chapter headings --- you can just change the individual
33493 macros without putting them into a style.
33494
33495
33496 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
33497
33498
33499 \subsection{Chappell}
33500
33501 A style that includes rules is one that I based on the chapter heads
33502 in~\cite{CHAPPELL99} and which I have called \cstyle{chappell} after the
33503 first author. The style, which is shown in \fref{dcchappell}, can easily form
33504 the basis for general heads in non-technical books.
33505 \begin{lcode}
33506 \makechapterstyle{chappell}{%
33507 \setlength{\beforechapskip}{0pt}
33508 \renewcommand*{\chapnamefont}{\large\centering}
33509 \renewcommand*{\chapnumfont}{\large}
33510 \renewcommand*{\printchapternonum}{%
33511 \vphantom{\printchaptername}%
33512 \vphantom{\chapnumfont 1}%
33513 \afterchapternum
33514 \vskip -\onelineskip}
33515 \renewcommand*{\chaptitlefont}{\Large\itshape}
33516 \renewcommand*{\printchaptertitle}[1]{%
33517 \hrule\vskip\onelineskip \centering\chaptitlefont ##1}}
33518 \end{lcode}
33519
33520
33521 The style centers the chapter number, draws a rule across the page under
33522 it, and below that comes the title, again centered. All the fiddling
33523 in the \cs{printchapternonum} macro is to try and ensure that the rule
33524 above the title is at the same height whether or not the chapter is numbered
33525 (the ToC being an example of an unnumbered heading).
33526
33527 \subsection{Demo, Demo2 and demo3}
33528
33529 I created a \cstyle{demo} chapterstyle quite a time ago and used it
33530 on occasions in earlier editions of this Manual. Here is the original code.
33531 \begin{lcode}
33532 \makechapterstyle{demo}{%
33533 \renewcommand*{\printchaptername}{\centering}
33534 \renewcommand*{\printchapternum}{\chapnumfont \numtoName{\c@chapter}}
33535 \renewcommand*{\chaptitlefont}{\normalfont\Huge\sffamily}
33536 \renewcommand*{\printchaptertitle}[1]{%
33537 \hrule\vskip\onelineskip \raggedleft \chaptitlefont ##1}
33538 \renewcommand*{\afterchaptertitle}%
33539 {\vskip\onelineskip \hrule\vskip \afterchapskip}
33540 }% end demo
33541 \end{lcode}
33542
33543 This has one serious failing and what I now believe is a poor design
33544 decision. The failing is that if you have any appendices that use the
33545 \cstyle{demo} chapterstyle then they are numbered instead of being lettered.
33546 The poor design is that the position of the title with respect to the top
33547 of the page is not the same for numbered and unnumbered chapters.
33548 The \cstyle{demo2} chapterstyle below fixes both of these at the expense
33549 of simplicity (at least for me).
33550 \begin{lcode}
33551 \makechapterstyle{demo2}{%
33552 \renewcommand*{\printchaptername}{\centering}
33553 \renewcommand*{\printchapternum}{\chapnumfont
33554 \ifanappendix \thechapter \else \numtoName{\c@chapter}\fi}
33555 \renewcommand*{\chaptitlefont}{\normalfont\Huge\sffamily}
33556 \renewcommand*{\printchaptertitle}[1]{%
33557 \hrule\vskip\onelineskip \raggedleft \chaptitlefont ##1}
33558 \renewcommand*{\afterchaptertitle}{%
33559 \vskip\onelineskip \hrule\vskip \afterchapskip}
33560 \setlength{\beforechapskip}{3\baselineskip}
33561 \renewcommand*{\printchapternonum}{%
33562 \vphantom{\chapnumfont One}
33563 \afterchapternum%
33564 \vskip\topskip}
33565 \setlength{\beforechapskip}{2\onelineskip}
33566 }% end{demo2}
33567 \end{lcode}
33568 You may find it instructive to compare the code for the \cstyle{demo} and
33569 \cstyle{demo2} chapterstyles.
33570
33571 Thec \cstyle{demo} chapterstyle is still available in the class for
33572 backward compatibility reasons, but I strongly advise against anyone using it.
33573
33574 By chance I inadvertantly typest a chapterstyle that was a mixture
33575 of the \cstyle{pedersen} and \cstyle{demo2} styles. As a result there is
33576 now a \cstyle{demo3} chapterstyle as well. The only difference between the
33577 two styles is in the definition of \cs{chapnumfont} which in \cstyle{demo3}
33578 is:
33579 \begin{lcode}
33580 \renewcommand*{\chapnumfont}{\normalfont\HUGE\itshape}
33581 \end{lcode}
33582
33583 \subsection{Pedersen}
33584
33585 I have modified Troels Pedersen's original code to make it a little more
33586 efficient and flexible.
33587
33588 \begin{lcode}
33589 \newcommand*{\colorchapnum}{}
33590 \newcommand*{\colorchaptitle}{}
33591 \makechapterstyle{pedersen}{%
33592 \setlength{\beforechapskip}{-20pt}
33593 \setlength{\afterchapskip}{10pt}
33594 \renewcommand*{\chapnamefont}{\normalfont\LARGE\itshape}
33595 \renewcommand*{\chapnumfont}{\normalfont\HUGE\itshape\colorchapnum}
33596 \renewcommand*{\chaptitlefont}{\normalfont\huge\itshape\colorchaptitle}
33597 \renewcommand*{\afterchapternum}{}
33598 \renewcommand*{\printchaptername}{}
33599 \setlength{\midchapskip}{20mm}
33600 \renewcommand*{\chapternamenum}{}
33601 \renewcommand*{\printchapternum}{%
33602 \sidebar{\raisebox{0pt}[0pt][0pt]{\makebox[0pt][l]{%
33603 \resizebox{!}{\midchapskip}{\chapnumfont\thechapter}}}}}
33604 \renewcommand*{\printchaptertitle}[1]{\chaptitlefont ##1}
33605 }
33606 \end{lcode}
33607 The chapter number is scaled up from its normal size and set in a
33608 sidebar\index{sidebar}.
33609
33610 \begin{syntax}
33611 \cmd{\colorchapnum} \cmd{\colorchaptitle} \\
33612 \end{syntax}
33613 \glossary(colorchapnum)
33614 {\cs{colorchapnum}}%
33615 {Color for the number in the \Pcstyle{pedersen} chapterstyle.}
33616 \glossary(colorchaptitle)
33617 {\cs{colorchaptitle}}%
33618 {Color for the title in the \Pcstyle{pedersen} chapterstyle.}
33619 The title is set with \cmd{colorchaptitle} and the number with
33620 \cmd{colorchapnum}, both of which default to doing nothing.
33621 Lars Madsen\index{Madsen, Lars}
33622 has suggested an attractive red color for these:
33623 \begin{lcode}
33624 \usepackage{color}
33625 \definecolor{ared}{rgb}{.647,.129,.149}
33626 \renewcommand{\colorchapnum}{\color{ared}}
33627 \renewcommand{\colorchaptitle}{\color{ared}}
33628 \chapterstyle{pedersen}
33629 \end{lcode}
33630
33631 The uncolored version is used for the chaptersyle for this chapter;
33632 because of setting the number in a sidebar\index{sidebar} it does not
33633 display well anywhere other than as a real chapter head.
33634
33635 \subsection{Southall}
33636
33637 On 2006/01/08 Thomas Dye\index{Dye, Thomas} posted his \cstyle{southall}
33638 chapterstyle on \url{comp.text.tex} and kindly gave me permission to
33639 include it here. It is based on the headings in a Cambridge Press
33640 book\footnote{Which I haven't seen} by Aidan Southall.
33641 It produces a simple numbered heading with the title set as a block paragraph,
33642 and with a horizontal rule underneath. His original code called for lining
33643 figures for the number but I have commented out that bit. I also changed
33644 the code to eliminate the need for the two new lengths that Thomas used.
33645
33646 \begin{lcode}
33647 \makechapterstyle{southall}{%
33648 \setlength{\afterchapskip}{5\baselineskip}
33649 \setlength{\beforechapskip}{36pt}
33650 \setlength{\midchapskip}{\textwidth}
33651 \addtolength{\midchapskip}{-\beforechapskip}
33652 \renewcommand*{\chapterheadstart}{\vspace*{2\baselineskip}}
33653 \renewcommand*{\chaptitlefont}{\huge\rmfamily\raggedright}
33654 \renewcommand*{\chapnumfont}{\chaptitlefont}
33655 \renewcommand*{\printchaptername}{}
33656 \renewcommand*{\chapternamenum}{}
33657 \renewcommand*{\afterchapternum}{}
33658 \renewcommand*{\printchapternum}{%
33659 \begin{minipage}[t][\baselineskip][b]{\beforechapskip}
33660 {\vspace{0pt}\chapnumfont%%%\figureversion{lining}
33661 \thechapter}
33662 \end{minipage}}
33663 \renewcommand*{\printchaptertitle}[1]{%
33664 \hfill\begin{minipage}[t]{\midchapskip}
33665 {\vspace{0pt}\chaptitlefont ##1\par}\end{minipage}}
33666 \renewcommand*{\afterchaptertitle}{%
33667 \par\vspace{\baselineskip}%
33668 \hrulefill \par\nobreak\noindent \vskip\afterchapskip}}
33669 \end{lcode}
33670
33671 The resulting style is shown in \fref{dcsouthall}.
33672
33673
33674 \subsection{Veelo}
33675
33676 Bastiaan Veelo
33677 posted the code for a new chapter style to \pixctt\ on 2003/07/22 under the
33678 title \textit{[memoir] [contrib] New chapter style}. His code, which
33679 I have slightly modified and changed the name to \cstyle{veelo},
33680 is below. I have also exercised editorial privilege on his comments.
33681
33682 \begin{quote}
33683 I thought I'd share a new chapter style to be used with the memoir class.
33684 The style is tailored for documents that are to be trimmed to a smaller
33685 width. When the bound document is bent, black tabs will appear on the
33686 fore side at the places where new chapters start as a navigational aid.
33687 We are scaling the chapter number, which most DVI viewers
33688 will not display accurately. \\[0.5\onelineskip]
33689 Bastiaan.
33690 \end{quote}
33691
33692 In the style as I modified it, \lnc{\beforechapskip} is used as the
33693 height of the number and \lnc{\midchapskip} is used as the length of the
33694 black bar.
33695 \begin{lcode}
33696 \newlength{\numberheight}
33697 \newlength{\barlength}
33698 \makechapterstyle{veelo}{%
33699 \setlength{\afterchapskip}{40pt}
33700 \renewcommand*{\chapterheadstart}{\vspace*{40pt}}
33701 \renewcommand*{\afterchapternum}{\par\nobreak\vskip 25pt}
33702 \renewcommand*{\chapnamefont}{\normalfont\LARGE\flushright}
33703 \renewcommand*{\chapnumfont}{\normalfont\HUGE}
33704 \renewcommand*{\chaptitlefont}{\normalfont\HUGE\bfseries\flushright}
33705 \renewcommand*{\printchaptername}{%
33706 \chapnamefont\MakeUppercase{\@chapapp}}
33707 \renewcommand*{\chapternamenum}{}
33708 \setlength{\beforechapskip}{18mm}
33709 \setlength{\midchapskip}{\paperwidth}
33710 \addtolength{\midchapskip}{-\textwidth}
33711 \addtolength{\midchapskip}{-\spinemargin}
33712 \renewcommand*{\printchapternum}{%
33713 \makebox[0pt][l]{\hspace{.8em}%
33714 \resizebox{!}{\numberheight}{\chapnumfont \thechapter}%
33715 \hspace{.8em}%
33716 \rule{\midchapskip}{\beforechapskip}%
33717 }}%
33718 \makeoddfoot{plain}{}{}{\thepage}}
33719 \end{lcode}
33720
33721
33722 If you use this style you will also need to use the \Lpack{graphicx}
33723 package~\cite{GRAPHICX} because of the \cmd{\resizebox} macro.
33724 The \cstyle{veelo} style works best for chapters that start
33725 on recto pages.
33726
33727 \index{chapterstyle|)}
33728
33729 \endgroup
33730
33731
33732 %#% extend
33733 %#% extstart include sniplets.tex
33734
33735
33736 \svnidlong
33737 {$Ignore: $}
33738 {$LastChangedDate: 2025-09-18 17:21:36 +0200 (Thu, 18 Sep 2025) $}
33739 {$LastChangedRevision: 872 $}
33740 {$LastChangedBy: [email protected] $}
33741
33742
33743 \defaultlists
33744
33745
33746 \LMnote{2010/02/09}{Started the sniplet chapter}
33747 \chapter{Sniplets}
33748 \label{cha:sniplets}
33749
33750 \cftinserthook{toc}{start-sniplets}
33751
33752
33753 This chapter is (over time) meant to hold various pieces of code for
33754 \theclass\ that we have gathered over the years or others have
33755 contributed, and which we think might be useful for others. In some
33756 cases they will have been moved from the text to this place, in order
33757 to make the manual less cluttered.
33758
33759
33760 If you have some \theclass\ related code you would like to share, feel
33761 free to send it to \[email protected]?.
33762
33763
33764
33765 \sniplettoc
33766
33767
33768 % \begin{sniplet}[Mirroring the output]\label{snip:1}
33769 % The \theclass\ class is not quite compatible with the \Lpack{crop}
33770 % package. This is usually not a problem as we provide our own
33771 % crop marks. But \Lpack{crop} provide one feature that we do not:
33772 % mirroring of the output. The following sniplet was posted on
33773 % \textsc{ctt} by Heiko Oberdiek (2009/12/05, thread \textit{
33774 % Memoir and mirrored pdf output })\fxnote[author=dlf,vadj=0em]{This is probably not compatible with current kernel, needs testing}
33775 % \begin{lcode}
33776 % \usepackage{atbegshi}
33777 % \usepackage{graphicx}
33778 % \AtBeginShipout{%
33779 % \sbox\AtBeginShipoutBox{%
33780 % \kern-1in\relax
33781 % \reflectbox{%
33782 % \rlap{\kern1in\copy\AtBeginShipoutBox}%
33783 % \kern\stockwidth
33784 % }%
33785 % }%
33786 % }
33787 % \end{lcode}
33788 % \end{sniplet}
33789
33790 \begin{sniplet}[Remove pagenumber if only one page]\label{snip:2}
33791 Memoir counts all the pages used. You can use this information
33792 in various ways. For example, say you are preparing a setup to write
33793 small assignments in, these may or may not be just one page. How do
33794 we remove the footer automatically if there is only one page?
33795
33796 Easy, place the following in the preamble (compile at least twice):
33797 \begin{lcode}
33798 \AddToHook{begindocument/end}
33799 {\ifnum\value{lastsheet}=1\thispagestyle{empty}\fi}
33800 \end{lcode}
33801 This version does not crumble if the contents ends with
33802 \cs{clearpage} or \cs{newpage}.
33803 \end{sniplet}
33804
33805 \begin{sniplet}[A kind of draft note]\label{snip:veelo}
33806 Bastiaan Veelo\index{Veelo, Bastiaan} has kindly provided example code
33807 for another form of a side note, as follows.
33808 \begin{lcode}
33809 %% A new command that allows you to note down ideas or annotations in
33810 %% the margin of the draft. If you are printing on a stock that is wider
33811 %% than the final page width, we will go to some length to utilise the
33812 %% paper that would otherwise be trimmed away, assuming you will not be
33813 %% trimming the draft. These notes will not be printed when we are not
33814 %% in draft mode.
33815 \makeatletter
33816 \ifdraftdoc
33817 \newlength{\draftnotewidth}
33818 \newlength{\draftnotesignwidth}
33819 \newcommand{\draftnote}[1]{\@bsphack%
33820 {%% do not interfere with settings for other marginal notes
33821 \strictpagecheck%
33822 \checkoddpage%
33823 \setlength{\draftnotewidth}{\foremargin}%
33824 \addtolength{\draftnotewidth}{\trimedge}%
33825 \addtolength{\draftnotewidth}{-3\marginparsep}%
33826 \ifoddpage
33827 \setlength{\marginparwidth}{\draftnotewidth}%
33828 \marginpar{\flushleft\textbf{\textit{\HUGE !\ }}\small #1}%
33829 \else
33830 \settowidth{\draftnotesignwidth}{\textbf{\textit{\HUGE\ !}}}%
33831 \addtolength{\draftnotewidth}{-\draftnotesignwidth}%
33832 \marginpar{\raggedleft\makebox[0pt][r]{%% hack around
33833 \parbox[t]{\draftnotewidth}{%%%%%%%%% funny behaviour
33834 \raggedleft\small\hspace{0pt}#1%
33835 }}\textbf{\textit{\HUGE\ !}}%
33836 }%
33837 \fi
33838 }\@esphack}
33839 \else
33840 \newcommand{\draftnote}[1]{\@bsphack\@esphack}
33841 \fi
33842 \makeatother
33843 \end{lcode}
33844 Bastiaan also noted that it provided an example of using the
33845 \lnc{\foremargin} length. If you want to try it out, either put the
33846 code in your preamble, or put it into a package (i.e., \file{.sty}
33847 file) without the \cs{makeat...} commands.
33848 \end{sniplet}
33849
33850
33851 \LMnote{2010/03/12}{Added this sniplet inspired by a thread on ctt}
33852 \begin{sniplet}[Adding indentation to footnotes]
33853
33854 At times a document design calls for a footnote configuration equal to
33855 the default but everything indented more to the right. This can be
33856 achieved via
33857 \begin{lcode}
33858 \newlength\myextrafootnoteindent
33859 \setlength\myextrafootnoteindent{\parindent}
33860 \renewcommand\makefootmarkhook{%
33861 \addtolength{\leftskip}{\myextrafootnoteindent}}
33862 \end{lcode}
33863 In this example we indent the footnotes to match the overall paragraph
33864 indentation. We need to save the current value of \verb?\parindent?
33865 since it is reset in the footnotes.
33866
33867 \end{sniplet}
33868
33869
33870 % \LMnote{2010/03/12}{Added this sniplet inspired by a thread on ctt}
33871 % \begin{sniplet}[Background image and trimmarks]
33872 % This sniplet comes from another problem described in
33873 % \textsc{ctt}. If one use the \Lpack{eso-pic} package to add a
33874 % background image, this image ends up on top of the trim marks. To
33875 % get it \emph{under} the trim marks Rolf Niepraschk suggested the
33876 % following trick\fxnote[author=dlf,vadj=0em]{not sure if this is
33877 % relevant anyone, at least things are not using the output hooks
33878 % and can be reordered}
33879 % \begin{lcode}
33880 % \RequirePackage{atbegshi}\AtBeginShipoutInit
33881 % \documentclass[...,showtrims]{memoir}
33882 % ...
33883 % \usepackage{eso-pic}
33884 % ...
33885 % \end{lcode}
33886
33887 % \end{sniplet}
33888
33889
33890 \LMnote{2012/09/21}{Sniplet showcasing autoadjusting numwidths in the toc}
33891 \begin{sniplet}[Autoadjusted number widths in the ToC]
33892 \label{snip:autotoc}
33893
33894 When the \toc{} is typeset the chapter, section etc. number is
33895 typeset within a box of a certain fixed with (one width for each
33896 sectional type). If this width is too small for the current
33897 document, the user have to manually adjust this width.
33898
33899 In this sniplet we present a method where we automatically record
33900 the widest.
33901
33902 It a later \theclass\ version, we may add similar code to the core.
33903
33904 There are two ways to record the widest entries of the various
33905 types, either preprocess the entire \toc{} or measure it as a part
33906 of the \toc{} typesetting, store it in the \texttt{.aux} and reuse
33907 it on the next run. We will use the later approach. There is one
33908 caveat: The \texttt{.aux} file is read at \verb|\begin{document}|,
33909 so we need to postpone our adjustments via \verb|\AtBeginDocument|.
33910
33911 The following solution use some \toc{} related hooks within the
33912 class, plus the \Lpack{etoolbox} and \Lpack{calc} packages.
33913
33914 First we create some macros to store information within the
33915 \texttt{.aux} file, and retrieve it again.
33916
33917 \begin{lcode}
33918 \makeatletter
33919 \newcommand\mem@auxrestore[2]{\csgdef{stored@value@#1}{#2}}
33920 \newcommand\memstorevalue[2]{%
33921 \@bsphack%
33922 \immediate\write\@mainaux{\string\mem@auxrestore{#1}{#2}}%
33923 \@esphack}
33924 \newcommand\RetrieveStoredLength[1]{%
33925 \ifcsdef{stored@value@#1}{\csuse{stored@value@#1}}{0pt}}%
33926 \makeatletter
33927 \end{lcode}
33928 Here \cs{RetrieveStoredLength} can be used in most \cmd{\setlength}
33929 cases, at least when the \Lpack{calc} package is loaded. The
33930 argument will be the name of the variable one asked to be stored. If
33931 no corresponding value has been found for a given name, 0\,pt is returned.
33932
33933 Next we need to prepare the hooks. In this case we will show how to
33934 take care of \cmd{\chapter}, \cmd{\section} and \cmd{\subsection}.
33935 \cmd{\chapter} is relatively easy:\footnote{In some cases you may
33936 want to use \texttt{%
33937 \{%
33938 \cs{@chapapp@head}%
33939 \cs{@cftbsnum}
33940 \#1%
33941 \cs{@cftasnum}%
33942 \}%
33943 }}
33944 \begin{lcode}
33945 \newlength\tmplen % scratch length
33946 \newlength\widestchapter % guess, they are zero by default
33947 \renewcommand\chapternumberlinehook[1]{%
33948 \settowidth\tmplen{\hbox{\cftchapterfont#1}}%
33949 \ifdimgreater\tmplen\widestchapter{%
33950 \global\widestchapter=\tmplen}{}}
33951 \end{lcode}
33952 We use an alternative syntax to make the \cs{widestchapter} global.
33953
33954 Handling \cmd{\section} and \cmd{\subsection} is slightly more
33955 tricky, as they both use \cmd{numberline}. Instead we rely on the
33956 local value of the magic macro \cmd{\cftwhatismyname}.
33957 \begin{lcode}
33958 \newlength\widestsection
33959 \newlength\widestsubsection
33960 \renewcommand\numberlinehook[1]{%
33961 % use a loop handler to loop over a list of possible
33962 % types. \forcsvlist comes from etoolbox
33963 \forcsvlist{\ToCHookListHandler{#1}}{section,subsection,subsubsection,%
33964 paragraph,subparagraph,figure,table}}
33965 % the actual handler.
33966 \newcommand\ToCHookListHandler[2]{%
33967 \edef\tmpstr{#2}%
33968 \ifdefstrequal{\cftwhatismyname}{\tmpstr}{%
33969 \settowidth\tmplen{\hbox{\csuse{cft\cftwhatismyname font}#1}}%
33970 \ifcslength{widest#2}{% is this length defined?
33971 \ifdimgreater\tmplen{\csuse{widest#2}}{%
33972 \global\csuse{widest#2}=\tmplen}{}}{}}{}}
33973 \end{lcode}
33974 Even though the list mention more macros, we only use those we have
33975 added corresponding lengths for.
33976
33977 Next we need to store the values at the end of the document
33978 \begin{lcode}
33979 \AtBeginDocument{\AtEndDocument{
33980 \memstorevalue{widestchapter}{\the\widestchapter}
33981 \memstorevalue{widestsection}{\the\widestsection}
33982 \memstorevalue{widestsubsection}{\the\widestsubsection}
33983 }}
33984 \end{lcode}
33985
33986 Here is how to get the standard class setup for a three level
33987 TOC. We also add a little extra padding to the boxes. Remember that
33988 it may take a few compilations before the \toc{} settles down.
33989 \begin{lcode}
33990 \newlength\cftnumpad % padding
33991 \setlength\cftnumpad{0.5em}
33992 \AtBeginDocument{
33993 \cftsetindents{chapter}{0pt}{%
33994 \RetrieveStoredLength{widestchapter}+\cftnumpad}
33995 \cftsetindents{section}{%
33996 \cftchapterindent+\cftchapternumwidth}{%
33997 \RetrieveStoredLength{widestsection}+\cftnumpad}
33998 \cftsetindents{subsection}{%
33999 \cftsectionindent+\cftsectionnumwidth}{%
34000 \RetrieveStoredLength{widestsubsection}+\cftnumpad}
34001 }
34002 \end{lcode}
34003 \end{sniplet}
34004
34005
34006 \begin{sniplet}[Using class tools to make a chapter ToC]
34007 \label{snip:chaptertoc}
34008
34009 By using a few hooks, we will be able to create a simple chapter
34010 toc. First a few notes:\fxnote[author=dlf,vadj=0em]{this can probably be simplified using the kernel hooks}
34011 \begin{enumerate}[(a)]
34012 \setlength\itemsep{0.5em}
34013 \item In this class, the ToC data can be reused, thus we can load
34014 the ToC data as many times as we would like.
34015 \item Data in the ToC is stored as arguments the \cs{contentsline}
34016 macro, say (see also \fref{fig:tocloflotfiles} on
34017 page~\pageref{fig:tocloflotfiles})
34018 \begin{verbatim}
34019 \contentsline{chapter}{\chapternumberline {1}Test}{3}{...}
34020 \end{verbatim}
34021 where the first argument determins which macro is used to process
34022 the data. Each of these macros look at the value of the \Pcn{tocdepth}
34023 counter to know whether to typeset or not.
34024 \item Using some hooks we can insert local changes to \Pcn{tocdepth}
34025 in order to only typeset the sections from the current chapter.
34026 \end{enumerate}
34027
34028 The idea is to be able to add hooks at key points in the \toc{} data,
34029 and then use these hooks to enable and disable typesetting.
34030
34031 We will need to add hooks just after a chapter line (like the one
34032 above), and we will need to be able to insert hooks just before items
34033 that mark the end of a chapter, that is the next \cmd{\chapter},
34034 \cmd{\part}, \cmd{\book}, plus a macro like \cmd{\appendixpage} which
34035 also write to the \toc{}.
34036
34037
34038
34039
34040
34041
34042 First we define hooks that add hooks into the TOC. We use a counter
34043 to make each start and end hook unique. We add \emph{end markers}
34044 above the \toc{} entries for \cs{chapter}, \cs{part} and
34045 \cs{book}.
34046 \begin{lcode}
34047 \newcounter{tocmarker}
34048 \renewcommand\mempreaddchaptertotochook{\cftinserthook{toc}{end-\thetocmarker}}
34049 \renewcommand\mempreaddparttotochook {\cftinserthook{toc}{end-\thetocmarker}}
34050 \renewcommand\mempreaddbooktotochook {\cftinserthook{toc}{end-\thetocmarker}}
34051 \renewcommand\mempreaddapppagetotochook{\cftinserthook{toc}{end-\thetocmarker}}
34052 % start marker
34053 \renewcommand\mempostaddchaptertotochook{%
34054 \stepcounter{tocmarker}\cftinserthook{toc}{start-\thetocmarker}}
34055 \let\normalchangetocdepth\changetocdepth % for later
34056 \end{lcode}
34057 The hooks inserted into the TOC file, does nothing by default. You
34058 will notice that the line above will now look like:
34059 \begin{verbatim}
34060 \cftinsert {end-0}
34061 \contentsline{chapter}{\chapternumberline {1}Test}{3}
34062 \cftinsert {start-1}
34063 ...
34064 \cftinsert {end-1}
34065 \contentsline{chapter}{\chapternumberline {2}Test}{5}
34066 \end{verbatim}
34067 Thus to get a chapter toc command we need to make sure that (1) all
34068 entries are disabled, (2) at \texttt{start-1} we reenable TOC entries,
34069 and (3) at \texttt{end-1} disable TOC entries again. Here is the rest
34070 of the code, explained via comments.
34071 \begin{lcode}
34072 \makeatletter
34073 \newcommand\chaptertoc{
34074 % make changes local, remember counters a global
34075 \begingroup
34076 % store current value, to be restored later
34077 \setcounter{@memmarkcntra}{\value{tocdepth}}
34078 % when ever \settocdepth is used, it adds the new value to the
34079 % ToC data. This cause problems when we want to disable all
34080 % entries. Luckily the data is added via a special macro, we we
34081 % redefine it, remember we stored the original value earlier.
34082 \let\changetocdepth\@gobble
34083 % disable all entries (using our copy from above)
34084 \normalchangetocdepth{-10}
34085 % enable toc data within our block, we go as far as subsubsection
34086 \cftinsertcode{start-\thetocmarker}{\normalchangetocdepth{3}}
34087 % when the block is done, disable the remaining
34088 \cftinsertcode{end-\thetocmarker}{\normalchangetocdepth{-10}}
34089 % remove the spacing above the toc title
34090 \let\tocheadstart\relax
34091 % remove the toc title itself
34092 \let\printtoctitle\@gobble
34093 % remove space below title
34094 \let\aftertoctitle\relax
34095 % reformat TOC entries:
34096 \setlength{\cftsectionindent}{0pt}
34097 \setlength{\cftsubsectionindent}{\cftsectionnumwidth}
34098 \setlength{\cftsubsubsectionindent}{\cftsubsectionindent}
34099 \addtolength{\cftsubsubsectionindent}{\cftsubsectionnumwidth}
34100 \renewcommand\cftsectionfont{\small}
34101 \renewcommand\cftsectionpagefont{\small}
34102 \renewcommand\cftsubsectionfont{\small}
34103 \renewcommand\cftsubsectionpagefont{\small}
34104 \renewcommand\cftsubsubsectionfont{\small}
34105 \renewcommand\cftsubsubsectionpagefont{\small}
34106 % include the actual ToC data
34107 \tableofcontents*
34108 \endgroup
34109 % restore tocdepth
34110 \setcounter{tocdepth}{\value{@memmarkcntra}}
34111 % to indent or not after the chapter toc
34112 \m@mindentafterchapter
34113 % space between chapter toc and text
34114 \par\bigskip
34115 % handles indentation after the macro
34116 \@afterheading}
34117 \makeatother
34118 \end{lcode}
34119 \end{sniplet}
34120
34121 Note that if the \cmd{\chapterprecistoc} or \cmd{\chapterprecis} has
34122 been used then that data is also added to the \toc{} data, and we will
34123 need to locally disable it in the chapter \toc{}. This can be done by
34124 adding
34125 \begin{lcode}
34126 \let\precistoctext\@gobble
34127 \end{lcode}
34128 to the \cmd{\chaptertoc} definition above, just make sure it is added
34129 before calling
34130 before \cmd{\tableofcontents*}.
34131
34132
34133 %%%%%
34134 %% Appendix ToC
34135 %%%%
34136
34137
34138 \begin{sniplet}[An appendix ToC]
34139 \label{snip:apptoc}
34140 Here we assume a structure like
34141 \begin{verbatim}
34142 \tableofcontents*
34143 \chapter
34144 \chapter
34145 \chapter
34146 \appendix
34147 \appendixpage
34148 \appendixtableofcontents
34149 \chapter
34150 \chapter
34151 \chapter
34152 \end{verbatim}
34153 where the first \toc{} should just show until (and including)
34154 \cmd{\appendixpage}, and \cmd{\appendixtableofcontents} should only
34155 list the appendices.
34156
34157 We also assume that no \cmd{\settocdepth}'s have been issued after
34158 \cmd{\appendixpage}.
34159
34160
34161 We only need a single hook after \cmd{\appendixpage}.
34162 \begin{lcode}
34163 \renewcommand\mempostaddapppagetotochook{\cftinserthook{toc}{BREAK}}
34164 \cftinsertcode{BREAK}{\changetocdepth{-10}}
34165 \let\normalchangetocdepth\changetocdepth % needed for later
34166 \end{lcode}
34167 Then the definition of the actual appendix \toc{}:
34168 \begin{lcode}
34169 \makeatletter
34170 \newcommand\appendixtableofcontents{
34171 \begingroup
34172 \let\changetocdepth\@gobble
34173 \normalchangetocdepth{-10}
34174 \cftinsertcode{BREAK}{\normalchangetocdepth{3}}
34175 \renewcommand\contentsname{Appendices overview}
34176 \tableofcontents*
34177 \endgroup
34178 }
34179 \makeatother
34180 \end{lcode}
34181
34182
34183 \end{sniplet}
34184
34185
34186
34187
34188 \cftinserthook{toc}{end-sniplets}
34189
34190 %#% extend
34191 %#% extstart include pictures.tex
34192
34193 \svnidlong
34194 {$Ignore: $}
34195 {$LastChangedDate: 2025-08-07 16:33:42 +0200 (Thu, 07 Aug 2025) $}
34196 {$LastChangedRevision: 858 $}
34197 {$LastChangedBy: [email protected] $}
34198
34199 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
34200
34201 \LMnote{2010/02/08}{Added this entire chapter from PW sources}
34202
34203
34204 \chapter{Pictures} \label{chap:lpic}
34205 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
34206
34207 \LMnote{2010/02/08}{Added this intro to show the motivation for adding
34208 this}
34209 \LMnote{2010/02/17}{fixed typo from Adriano Pascoletti}
34210 There are many freely available \ltx\ introductions on \ctan\ and
34211 other places. One thing that these apparently are not covering is the
34212 traditional picture environment. It can be very handy in many
34213 applications, though for more complex drawings the reader might be
34214 better of with TiKz/pgf or PSTricks. For the benefit of the general
34215 reader we here provide a lesson in the standard picture environment.
34216
34217 \LMnote{2010/02/08}{Added a writers note as not to change the text too
34218 much, the most important thing about this note is the mentioning of
34219 the picture package by Heiko, which enables us to use something like
34220 \cs{put}(5mm, 5cm)}
34221 \emph{Writers comment:} There are many extensions to the stock picture
34222 environment provided by the \ltx\ kernel. We have chosen not to deal
34223 with them in this chapter but instead concentrate on what you get as
34224 is from the kernel. But there are a few handy packages that the reader
34225 might want to explore: picture (by Heiko Oberdiek) which extends the
34226 \cs{put} syntax to include arbitrary lengths, like 50mm; pict2e which
34227 is mentioned in \cite{GCOMPANION} but just recently was released;
34228 eepic. All packages are available from \ctan.
34229
34230
34231
34232 \fancybreak{}
34233
34234
34235 This chapter describes how to draw diagrams\index{diagram} and
34236 pictures\index{picture} using \ltx.
34237 Pictures are drawn in the \Ie{picture} environment. You can draw\index{draw}
34238 straight
34239 lines, arrows and circles; you can also put text into your pictures.
34240
34241 Most often pictures are drawn within a \Ie{figure}\index{figure}
34242 environment, but
34243 they may also be drawn as part of the normal text.
34244
34245
34246
34247
34248 \section{Basic principles}
34249
34250 The positions of picture elements are specified in terms of a
34251 two-dimensional cartesian coordinate\index{coordinate system} system.
34252 A \emph{coordinate}\index{coordinate} is a
34253 number, such as \texttt{7}, \texttt{-21} or \texttt{1.78}. In the cartesian coordinate
34254 system, a pair of coordinates (i.e., a pair of numbers) specifies a
34255 position relative to the position designated as \texttt{(0,0)}. This special
34256 position is called the \emph{origin}.
34257 The first of the coordinate pair\index{coordinate pair}
34258 gives the value of the horizontal distance from the origin to the position.
34259 A positive coordinate is an offset to the right and a negative number is
34260 an offset to the left. The first value of a coordinate pair is called the
34261 \emph{x coordinate}\index{coordinate}.
34262 The second value of a coordinate pair is called the
34263 \emph{y coordinate}\index{coordinate}
34264 and gives the vertical offset from the origin (positive
34265 upwards and negative downwards).
34266
34267 \begin{syntax}
34268 \lnc{\unitlength} \\
34269 \end{syntax}
34270 \glossary(unitlength)
34271 {\cs{unitlength}}{The unit of length in a picture environment. Default 1pt.}
34272 To draw a picture we also need to specify the units of measurement.
34273 By default, \ltx\ takes the printer's point (there are 72.27 points to
34274 an inch) as the measurement of length. The value of the unit of
34275 length\index{unit length} measurement
34276 within a \Ie{picture} environment is actually given by the value
34277 of the \lnc{\unitlength} length declaration.
34278 This can be changed
34279 to any length that you like via the \cmd{\setlength} command. For example, \\
34280 \verb?\setlength{\unitlength}{2mm}? \\
34281 will make the value of \lnc{\unitlength} to be two millimeters.
34282
34283 \fref{flpic:coords} shows the positions of some points and their
34284 coordinate values. Coordinate pairs are typed as a pair of numbers, separated
34285 by a comma, and enclosed in parentheses.
34286
34287 \begin{figure}
34288 \setlength{\unitlength}{1mm}
34289 \centering
34290 \begin{picture}(80,70)
34291 \thicklines
34292 % x axis
34293 \put(10,30){\begin{picture}(60,10)
34294 \thicklines \put(-5,0){\vector(1,0){65}}
34295 \thinlines \multiput(0,0)(10,0){6}{\line(0,1){3}}
34296 \put(0,-3){\makebox(0,0)[t]{-20}}
34297 \put(10,-3){\makebox(0,0)[t]{-10}}
34298 \put(23,-3){\makebox(0,0)[t]{0}}
34299 \put(30,-3){\makebox(0,0)[t]{10}}
34300 \put(40,-3){\makebox(0,0)[t]{20}}
34301 \put(50,-3){\makebox(0,0)[t]{30}}
34302 \put(63,0){\makebox(0,0){x}}
34303 \end{picture}}
34304 % y axis
34305 \put(30,10){\begin{picture}(10,60)
34306 \thicklines \put(0,-5){\vector(0,1){60}}
34307 \thinlines \multiput(0,0)(0,10){6}{\line(1,0){3}}
34308 \put(-3,0){\makebox(0,0)[r]{-20}}
34309 \put(-3,10){\makebox(0,0)[r]{-10}}
34310 \put(-3,30){\makebox(0,0)[r]{10}}
34311 \put(-3,40){\makebox(0,0)[r]{20}}
34312 \put(-3,50){\makebox(0,0)[r]{30}}
34313 \put(0,58){\makebox(0,0)[b]{y}}
34314 \end{picture}}
34315
34316 \put(50,50){\begin{picture}(10,10)
34317 \put(0,0){\circle*{1}}
34318 \put(2,2){\makebox(0,0)[bl]{\texttt{(20,20)}}}
34319 \end{picture}}
34320
34321 \put(15,45){\begin{picture}(10,10)
34322 \put(0,0){\circle*{1}}
34323 \put(-2,2){\makebox(0,0)[br]{\texttt{(-15,15)}}}
34324 \end{picture}}
34325
34326 \put(15,20){\begin{picture}(10,10)
34327 \put(0,0){\circle*{1}}
34328 \put(-2,-2){\makebox(0,0)[tr]{\texttt{(-15,-10)}}}
34329 \end{picture}}
34330
34331 \put(40,20){\begin{picture}(10,10)
34332 \put(0,0){\circle*{1}}
34333 \put(2,-2){\makebox(0,0)[tl]{\texttt{(10,-10)}}}
34334 \end{picture}}
34335
34336
34337 \end{picture}
34338 \setlength{\unitlength}{1pt}
34339 \caption{Some points in the cartesian coordinate system}
34340 \label{flpic:coords}
34341 \end{figure}
34342
34343
34344 \begin{syntax}
34345 \cmd{\thinlines} \\
34346 \cmd{\thicklines} \\
34347 \cmd{\linethickness}\marg{len} \\
34348 \end{syntax}
34349 \glossary(thinlines)
34350 {\cs{thinlines}}{Picture declaration for lines to be thin.}
34351 \glossary(thicklines)
34352 {\cs{thicklines}}{Picture declaration for lines to be thick.}
34353 \glossary(linethickness)
34354 {\cs{linethickness}\marg{len}}{Picture declaration for vertical and
34355 horizontal lines to be \meta{len} thick.}
34356
34357 In general, \ltx\ can draw lines of only two
34358 thicknesses\indextwo{thickness}{line},
34359 thin and thick. The required
34360 thickness is specified via either a \cmd{\thicklines} or a \cmd{\thinlines}
34361 declaration, with the latter being the default.
34362
34363 There is another declaration, \cmd{\linethickness}, which can be used
34364 to change the thickness of horizontal and vertical lines only.
34365 It sets the thickness of these lines to \meta{len}, but has no effect on
34366 any sloping lines.
34367
34368 A \Ie{picture} environment has a required size pair argument that
34369 specifies the width and height of the picture, in terms of the value
34370 of \cmd{\unitlength}.
34371 \begin{syntax}
34372 \senv{picture}\parg{width, height}
34373 \meta{contents}
34374 \eenv{picture} \\
34375 \senv{picture}\parg{width, height}\parg{llx, lly}
34376 \meta{contents}
34377 \eenv{picture} \\
34378 \end{syntax}
34379 \glossary(picture)
34380 {\senv{picture}\parg{width, height}}{Creates a box of \meta{width} times
34381 \meta{height} (in terms of \cs{unitlength}) in which you can use drawing
34382 commands. The origin is at (0,0).}
34383 \glossary(picturex)
34384 {\senv{picture}\parg{width, height}\parg{llx,lly}}{Creates a box of \meta{width} times
34385 \meta{height} (in terms of \cs{unitlength}) in which you can use drawing
34386 commands. The origin is at (\meta{llx},\meta{lly}).}
34387 The environment creates a box\indextwo{box}{picture}
34388 of size \meta{width} by \meta{height}, which will not be
34389 split\index{box!unbreakable} across pages. The default position of
34390 the origin in this environment is at the lower left hand corner of the box.
34391 For example,
34392 \begin{lcode}
34393 \begin{picture}(80,160)
34394 \end{lcode}
34395 creates a picture box of width 80 and height 160 whose lower left hand corner
34396 is at \texttt{(0,0)}. There is also an optional coordinate pair argument (which
34397 comes after the required argument) that specifies the coordinates of the
34398 lower left hand corner of the box if you do not want the default origin.
34399 \begin{lcode}
34400 \begin{picture}(80,160)(10,20)
34401 \end{lcode}
34402 specifies a picture box of width 80 and height 160, as before, but with
34403 the bottom left hand corner having coordinates of \texttt{(10,20)}. Thus, the
34404 top right hand corner will have coordinates \texttt{(90,180)}. Note that the
34405 optional argument is enclosed in parentheses not square brackets as is
34406 ordinarily the case. Typically, the optional argument is used when you
34407 want to shift everything in the picture. \ltx\ uses the required argument
34408 to determine the space required for typesetting the result.
34409
34410 You are not limited to drawing within the box, but if you do draw
34411 outside the box the result might run into other text on the page, or even
34412 run off the page altogether. \ltx\ only reserves the space you specify
34413 for the picture and does not know if anything protrudes. In particular
34414 \begin{lcode}
34415 \begin{picture}(0,0)
34416 \end{lcode}
34417 creates a zero-sized\index{picture!zero-sized} picture which takes no
34418 space at all. This can be very useful if you need to position
34419 things on the page.
34420
34421
34422 \LMnote{2010/02/17}{fixed typo from Adriano Pascoletti}
34423 Within the \Ie{picture} environment, \ltx\ is in a special \emph{picture}
34424 mode\indextwo{mode}{picture} (which is a restriced form of LR
34425 mode\indextwo{mode}{LR}).
34426 The only commands that can appear in picture mode are \cmd{\put},
34427 \cmd{\multiput} and \cmd{\qbezier} commands, and a few
34428 declarations such as the type style and the thickness declarations.
34429 By the way,
34430 you should only change the value of \cmd{\unitlength} outside
34431 picture mode\indextwo{mode}{picture}
34432 otherwise \ltx\ will get confused about its measurements.
34433
34434 \section{Picture objects}
34435
34436 In a picture everything is placed and drawn by the \cmd{\put} (or
34437 its \cmd{\multiput} variant) command.
34438 \begin{syntax}
34439 \cmd{\put}\parg{x, y}\marg{object} \\
34440 \end{syntax}
34441 \glossary(put)
34442 {\cs{put}\parg{x,y}\marg{object}}{Drawing command to place \meta{object}
34443 at coordinates (\meta{x,y}). In the simplest case \meta{object}
34444 is just text.}
34445 \cmd{\put} places \meta{object} in the picture with the
34446 object's \emph{reference point}\index{reference point}
34447 at position \parg{x, y}.
34448
34449 The following sections describe the various picture
34450 objects\index{picture object}.
34451
34452 \subsection{Text}
34453
34454 Text\index{picture object!text} is the simplest kind of picture object.
34455 This is typeset in LR mode\indextwo{mode}{LR} and the
34456 reference point\index{reference point!text} is at
34457 the lower left hand corner of the text.
34458 \begin{egsource}{eg:pic1}
34459 \setlength{\unitlength}{1mm} % measurements in millimeters
34460 \begin{picture}(30,10) % define size of picture
34461 \put(0,0){\framebox(30,10){}} % draw frame around picture
34462 \put(10,5){Some text} % place text
34463 \thicklines
34464 \put(10,5){\vector(1,1){0}} % mark reference point
34465 \end{picture}
34466 \setlength{\unitlength}{1pt} % reset measurements to default
34467 \end{egsource}
34468
34469 \begin{egresult}[Picture: text]{eg:pic1}
34470 \vspace*{0.5\onelineskip}
34471 \setlength{\unitlength}{1mm}
34472 \begin{picture}(30,10)
34473 \put(0,0){\framebox(30,10){}}
34474 \put(10,5){Some text}
34475 \thicklines
34476 \put(10,5){\vector(1,1){0}}
34477 \end{picture}
34478 \setlength{\unitlength}{1pt}
34479 \end{egresult}
34480
34481 In the diagram, and those following,
34482 the reference point is indicated by an arrow. Also, a
34483 box is drawn round the diagram at the same size as the \Ie{picture}
34484 environment.
34485
34486 \subsection{Boxes} \label{slpic:boxes}
34487
34488 A box\index{picture object!box} picture object is made with one of
34489 the box\index{box} commands. When used
34490 in picture mode\indextwo{mode}{picture}, the box commands have a slightly
34491 different form than when
34492 in normal text. The first argument of a box command is a size pair
34493 that specifies the width and height of the box. The last argument is the
34494 text to be placed in the box. The reference point\indextwo{reference point}{box}
34495 of a box is the lower left hand corner.
34496 \begin{syntax}
34497 \cmd{\framebox}\parg{width, height}\oarg{pos}\marg{text} \\
34498 \cmd{\makebox}\parg{width, height}\oarg{pos}\marg{text} \\
34499 \end{syntax}
34500 \glossary(framebox)
34501 {\cs{framebox}\parg{width,height}\oarg{pos}\marg{text}}{A picture
34502 object framing \meta{text} (at position \meta{pos}) in a box \meta{width}
34503 by \meta{height}.}
34504 \glossary(makebox)
34505 {\cs{makebox}\parg{width,height}\oarg{pos}\marg{text}}{A picture
34506 object putting \meta{text} (at position \meta{pos}) in a box \meta{width}
34507 by \meta{height}.}
34508 The \cmd{\framebox} command draws a
34509 framed box\indextwo{box}{framed}\index{picture object!framed box}
34510 of the specified \parg{width, height} dimensions around
34511 the text.
34512
34513 \begin{egsource}{eg:pic2}
34514 \setlength{\unitlength}{1pc}
34515 \begin{picture}(22,5)
34516 \put(0,0){\framebox(22,5){}} % empty box
34517 \thicklines
34518 \put(2,1){\framebox(5,2.5){center}} % centered text
34519 \put(2,1){\vector(1,1){0}} % ref point
34520 \put(9,1){\framebox(5,2)[b]{bottom}} % bottomed text
34521 \put(9,1){\vector(1,1){0}} % ref point
34522 \put(16,1){\framebox(5,3)[tl]{top left}} % cornered text
34523 \put(16,1){\vector(1,1){0}} % ref point
34524 \end{picture}
34525 \setlength{\unitlength}{1pt}
34526 \end{egsource}
34527
34528 \begin{egresult}[Picture: text in boxes]{eg:pic2}
34529 \vspace*{0.5\onelineskip}
34530 \setlength{\unitlength}{1pc}
34531 \begin{picture}(22,5)
34532 \put(0,0){\framebox(22,5){}}
34533 \thicklines
34534 \put(2,1){\framebox(5,2.5){center}}
34535 \put(2,1){\vector(1,1){0}}
34536 \put(9,1){\framebox(5,2)[b]{bottom}}
34537 \put(9,1){\vector(1,1){0}}
34538 \put(16,1){\framebox(5,3)[tl]{top left}}
34539 \put(16,1){\vector(1,1){0}}
34540 \end{picture}
34541 \setlength{\unitlength}{1pt}
34542 \end{egresult}
34543
34544 The default position\index{picture object!framed box!text position}
34545 of the \textit{text} is centered in the box.
34546 However, this can
34547 be changed via an optional argument (which is enclosed in square brackets),
34548 placed between the coordinate pair and the text argument. This argument
34549 consists of either one or two of the following letters.
34550 \begin{itemize}
34551 \item[\pixposarg{l}] (left) Places the contents at the left of the box.
34552 \item[\pixposarg{r}] (right) Places the contents at the right of the box.
34553 \item[\pixposarg{t}] (top) Places the contents at the top of the box.
34554 \item[\pixposarg{b}] (bottom) Places the contents at the bottom of the box.
34555 \end{itemize}
34556 These place the text in the corresponding position in the box. In a two-letter
34557 argument the order of the letters is immaterial. For example, \verb?[tr]?
34558 and \verb?[rt]? will both result in the text being placed at the top right
34559 hand corner of the box. Unlike the normal \cmd{\framebox} command, a
34560 \cmd{\framebox} in a \Ie{picture} environment does not add any extra space
34561 around the text.
34562
34563 Corresponding to the \cmd{\framebox} there is a \cmd{\makebox}
34564 command\index{picture object!unframed box} which
34565 does not draw a frame around its contents. The \cmd{\makebox} command takes the
34566 same arguments as the \cmd{\framebox}. Particularly interesting is when you
34567 specify a zero sized\index{picture object!unframed box!zero size}
34568 \cmd{\makebox}. A \verb?\makebox(0,0){text}?
34569 command will make the reference point the center of \texttt{text}. Similarly,
34570 the other positioning arguments\index{picture object!unframed box!text position}
34571 which will adjust the reference point with respect to
34572 the box contents. This can be used for fine-tuning the position of text
34573 in a picture.
34574
34575 \begin{egsource}{eg:pic3}
34576 \setlength{\unitlength}{1pc}
34577 \begin{picture}(16,2)
34578 \put(0,0){\framebox(16,2){}}
34579 \thicklines
34580 \put(3.5,1){\makebox(0,0){center}} % ref at text center
34581 \put(3.5,1){\vector(0,-1){0}}
34582 \put(7,1){\makebox(0,0)[b]{bottom}} % ref at text bottom
34583 \put(7,1){\vector(0,1){0}}
34584 \put(11,1){\makebox(0,0)[tl]{top left}} % ref at text top left
34585 \put(11,1){\vector(1,-1){0}}
34586 \end{picture}
34587 \setlength{\unitlength}{1pt}
34588 \end{egsource}
34589
34590 \begin{egresult}[Picture: positioning text]{eg:pic3}
34591 \vspace{0.5\onelineskip}
34592 \setlength{\unitlength}{1pc}
34593 \begin{picture}(16,2)
34594 \put(0,0){\framebox(16,2){}}
34595 \thicklines
34596 \put(3.5,1){\makebox(0,0){center}}
34597 \put(3.5,1){\vector(0,-1){0}}
34598 \put(7,1){\makebox(0,0)[b]{bottom}}
34599 \put(7,1){\vector(0,1){0}}
34600 \put(11,1){\makebox(0,0)[tl]{top left}}
34601 \put(11,1){\vector(1,-1){0}}
34602 \end{picture}
34603 \setlength{\unitlength}{1pt}
34604 \end{egresult}
34605
34606 You can draw a dashed box\index{picture object!dashed box}
34607 with the \cmd{\dashbox} command.
34608 \begin{syntax}
34609 \cmd{\dashbox}\marg{len}\parg{width, height}\oarg{pos}\marg{text} \\
34610 \end{syntax}
34611 \glossary(dashbox)
34612 {\cs{dashbox}\marg{len}\parg{width,height}\oarg{pos}\marg{text}}{A picture
34613 object framing \meta{text} (at position \meta{pos}) in a dashed box
34614 \meta{width} by \meta{height}. The dashes and spaces are each \meta{len} long.}
34615 The first argument
34616 of this command specifies the length of each dash. The following arguments
34617 are the same as for the other box commands.
34618
34619 \begin{egsource}{eg:pic4}
34620 \setlength{\unitlength}{4mm}
34621 \begin{picture}(7,4)
34622 \put(0,0){\framebox(7,4){}}
34623 \thicklines
34624 \put(1,1){\dashbox{0.5}(5,2)[tr]{top right}}
34625 \put(1,1){\vector(1,1){0}}
34626 \end{picture}
34627 \setlength{\unitlength}{1pt}
34628 \end{egsource}
34629
34630 \begin{egresult}[Picture: dashed box]{eg:pic4}
34631 \vspace{0.5\onelineskip}
34632 \setlength{\unitlength}{4mm}
34633 \begin{picture}(7,4)
34634 \put(0,0){\framebox(7,4){}}
34635 \thicklines
34636 \put(1,1){\dashbox{0.5}(5,2)[tr]{top right}}
34637 \put(1,1){\vector(1,1){0}}
34638 \end{picture}
34639 \setlength{\unitlength}{1pt}
34640 \end{egresult}
34641
34642 The appearance of the box is best when the width and height of the
34643 box are integer multiples of the dash length. In the example the dash length
34644 has been set to \texttt{0.5} with the width and height set as \texttt{(5,2)}; thus
34645 the width and height are respectively ten and four times the dash length.
34646
34647 The \cmd{\frame}\index{picture object!frame} command draws a
34648 frame around the contents of the
34649 box that exactly fits the contents.
34650 \begin{syntax}
34651 \cmd{\frame}\marg{contents} \\
34652 \end{syntax}
34653 \glossary(frame)
34654 {\cs{frame}\marg{contents}}{A picture object drawing a frame about \meta{contents}.}
34655 It takes a single required argument
34656 which is the contents.
34657
34658 \begin{egsource}{eg:pic6}
34659 \setlength{\unitlength}{1pc}
34660 \begin{picture}(10,3)
34661 \put(0,0){\framebox(10,3){}}
34662 \thicklines
34663 \put(0.5,2){\frame{$\mathcal{FRAME}$ text}}
34664 \put(0.5,2){\vector(1,1){0}}
34665 \end{picture}
34666 \setlength{\unitlength}{1pt}
34667 \end{egsource}
34668
34669 \begin{egresult}[Picture: framing]{eg:pic6}
34670 \vspace{0.5\onelineskip}
34671 \setlength{\unitlength}{1pc}
34672 \begin{picture}(10,3)
34673 \put(0,0){\framebox(10,3){}}
34674 \thicklines
34675 \put(0.5,2){\frame{$\mathcal{FRAME}$ text}}
34676 \put(0.5,2){\vector(1,1){0}}
34677 \end{picture}
34678 \setlength{\unitlength}{1pt}
34679 \end{egresult}
34680
34681
34682 The \cmd{\shortstack} command\index{picture object!stack}
34683 enables you to stack\index{stacking!text} text vertically. It
34684 produces a box with a single column of text. As with the other boxes, the
34685 reference point\indextwo{reference point}{stack} is at the lower left hand corner,
34686 although no frame is
34687 drawn around the stack. The \cmd{\shortstack} command is an ordinary
34688 box making command, but it is not often used outside picture
34689 mode\indextwo{mode}{picture}.
34690 \begin{syntax}
34691 \cmd{\shortstack}\oarg{pos}\marg{text} \\
34692 \end{syntax}
34693 \glossary(shortstack)
34694 {\cs{shortstack}\oarg{pos}\marg{text}}{Vertically stacks each line of
34695 \meta{text} into a column, normally centered but can be left or
34696 right aligned via \meta{pos}. Usually used as a picture object,
34697 but can be used outside the environment.}
34698 Each line of \meta{text}, except for the last, is
34699 ended\indextwo{end}{line} by a \cmd{\\} command.
34700 The default is to center each text line within the column. However, there
34701 is an optional positioning argument.
34702 A value of \pixposarg{l} for \meta{pos} will left align the
34703 text and a value of \pixposarg{r} will right align the text.
34704
34705 \begin{egsource}{eg:pic7}
34706 \setlength{\unitlength}{1mm}
34707 \begin{picture}(75,25)
34708 \put(0,0){\framebox(75,25){}}
34709 \put(3,3){\shortstack{Default \\ short \\ Stack}}
34710 \put(3,3){\vector(1,1){0}}
34711 \put(23,3){\shortstack[l]{Left\\aligned\\short\\Stack}}
34712 \put(23,3){\vector(1,1){0}}
34713 \put(43,3){\shortstack[r]{Right\\aligned\\short\\Stack}}
34714 \put(43,3){\vector(1,1){0}}
34715 \put(63,3){\shortstack{Extra \\[4ex] spaced \\[2ex] Stack}}
34716 \put(63,3){\vector(1,1){0}}
34717 \end{picture}
34718 \setlength{\unitlength}{1pt}
34719 \end{egsource}
34720
34721 \begin{egresult}[Picture: stacking]{eg:pic7}
34722 \vspace{0.5\onelineskip}
34723 \setlength{\unitlength}{1mm}
34724 \begin{picture}(75,25)
34725 \put(0,0){\framebox(75,25){}}
34726 \put(3,3){\shortstack{Default \\ short \\ Stack}}
34727 \put(3,3){\vector(1,1){0}}
34728
34729 \put(23,3){\shortstack[l]{Left\\aligned\\short\\Stack}}
34730 \put(23,3){\vector(1,1){0}}
34731
34732 \put(43,3){\shortstack[r]{Right\\aligned\\short\\Stack}}
34733 \put(43,3){\vector(1,1){0}}
34734
34735 \put(63,3){\shortstack{Extra \\[4ex] spaced \\[2ex] Stack}}
34736 \put(63,3){\vector(1,1){0}}
34737 \end{picture}
34738 \setlength{\unitlength}{1pt}
34739 \end{egresult}
34740
34741 The rows in a stack\index{stacking!text!vertical spacing}
34742 are not evenly spaced. The spacing between two
34743 rows can be changed in one of two ways.
34744 \begin{enumerate}
34745 \item Add a strut to a row. A strut\index{strut} is a vertical rule with
34746 no width.
34747 \item Use the optional argument to the \cmd{\\} command. This optional
34748 argument is a length value.
34749 \begin{syntax}
34750 \cmd{\\}\oarg{len} \\
34751 \end{syntax}
34752 It has the effect of adding additional \meta{len}
34753 vertical space between the two lines that the \cmd{\\} separates.
34754 \end{enumerate}
34755
34756 \begin{syntax}
34757 \cmd{\newsavebox}\marg{box} \\
34758 \cmd{\savebox}\marg{box}\parg{width, height}\oarg{pos}\marg{text} \\
34759 \cmd{\sbox}\marg{box}\marg{text} \\
34760 \cmd{\usebox}\marg{box} \\
34761 \end{syntax}
34762 \glossary(savebox)
34763 {\cs{savebox}\meta{box}\parg{width, height}\oarg{pos}\marg{text}}{Picture
34764 command to save
34765 \meta{text} in a (pre-existing) storage box \meta{box} making it
34766 size \meta{width} times \meta{height}. The optional
34767 argument controls the position of the \meta{text}.}
34768
34769 \LMnote{2010/02/17}{fixed typo from Adriano Pascoletti}
34770 Just as in normal text you can save and reuse boxes.
34771 The \cmd{\savebox}\index{box!saved object}
34772 macro in picture mode\indextwo{mode}{picture} is a variant of the normal
34773 text version, but the other three commands are the same in both
34774 picture\indextwo{mode}{picture} and paragraph\indextwo{mode}{paragraph} modes,
34775 and are described in \Cref{chap:boxes}. In picture mode you have to
34776 specify the size of the storage box when saving it, via the
34777 \parg{width, height} argument to \cmd{\savebox}.
34778
34779 A \cmd{\savebox} command can be used within a picture to store a picture
34780 object. The first argument of \cmd{\savebox} is the name of the
34781 storage bin to be used. The following arguments are the same as the
34782 \cmd{\makebox} command.
34783 The result is stored, not drawn. When you have saved
34784 something it can be drawn in either the same or other pictures via the
34785 \cmd{\usebox}\index{box!using saved object} command.
34786 This command takes one argument, which is the name
34787 of the storage bin.
34788
34789 \begin{egsource}{eg:pic8}
34790 \setlength{\unitlength}{1pc}
34791 \begin{picture}(18,5)
34792 \put(0,0){\framebox(18,5){}}
34793 \newsavebox{\Mybox}
34794 \savebox{\Mybox}(6,3)[tr]{$\mathcal{SAVED}$}
34795 \thicklines
34796 \put(1,1){\frame{\usebox{\Mybox}}}
34797 \put(11,1){\frame{\usebox{\Mybox}}}
34798 \put(1,1){\vector(1,1){0}}
34799 \put(11,1){\vector(1,1){0}}
34800 \end{picture}
34801 \setlength{\unitlength}{1pt}
34802 \end{egsource}
34803
34804 \begin{egresult}[Picture: saved boxes]{eg:pic8}
34805 \vspace{0.5\onelineskip}
34806 \setlength{\unitlength}{1pc}
34807 \begin{picture}(18,5)
34808 \put(0,0){\framebox(18,5){}}
34809 \newsavebox{\Mybox}
34810 \savebox{\Mybox}(6,3)[tr]{$\mathcal{SAVED}$}
34811 \thicklines
34812 \put(1,1){\frame{\usebox{\Mybox}}}
34813 \put(11,1){\frame{\usebox{\Mybox}}}
34814 \put(1,1){\vector(1,1){0}}
34815 \put(11,1){\vector(1,1){0}}
34816 \end{picture}
34817 \setlength{\unitlength}{1pt}
34818 \end{egresult}
34819
34820 It can take \ltx\ a long time to draw something. When a box is saved
34821 it actually contains the typeset contents, which then just get
34822 printed out when the box is
34823 used. It can save processing time if something which appears several times
34824 is saved and then used as and where required. On the other hand, a saved
34825 box can use up a significant amount of \ltx's internal storage space.
34826 The \cmd{\sbox} command with an empty text argument can be used to delete
34827 the contents of a bin. For example,
34828 \begin{lcode}
34829 \sbox{\Mybox}{}
34830 \end{lcode}
34831 will empty the \verb?\Mybox? box. Note that this does not delete the
34832 storage box itself.
34833
34834 \subsection{Lines}
34835
34836 \ltx\ can draw straight
34837 lines\index{picture object!line|seealso{line}}\index{line|seealso{picture object}},
34838 but the range of slopes\index{line!restricted slope} for lines is
34839 somewhat restricted. Further, very short lines\index{line!short} cannot
34840 be drawn.
34841 \begin{syntax}
34842 \cmd{\line}\parg{i, j}\marg{distance} \\
34843 \end{syntax}
34844 \glossary(line)
34845 {\cs{line}\parg{dx,dy}\marg{distance}}{Picture object of a line, slope
34846 \meta{dx,dy} and coordinate length \meta{distance}.}
34847 The pair \parg{i, j} specifies the
34848 \emph{slope}\index{slope}\indextwo{line}{slope} of the line, and \meta{distance}
34849 is a value that controls the length\index{line!length} of the line. The line
34850 starts at its reference point\indextwo{reference point}{line}
34851 (i.e., the place where it is \cmd{\put}).
34852 The slope\index{slope} of the line is such that if a point on the line is slid along the
34853 line, then for every $i$ units the point moves in the horizontal direction
34854 it will also have moved $j$ units in the vertical direction. Negative
34855 values for $i$ or $j$ have the expected meaning. A move of -3 units in $i$
34856 means a move of 3 units to the left, and similarly a move of -4 units in
34857 $j$ means a move of 4 units downwards. So, a line sloping up to the right
34858 will have positive values for $i$ and $j$, while a line sloping up to the
34859 left will have a negative value for $i$ and a positive value for~$j$.
34860
34861 The \meta{distance} argument specifies the length of the line in the
34862 $x$ (horizontal) direction. One problem with this may have occured to you:
34863 what if the line is vertical (i.e., $i=0$)? In this case only, \meta{distance}
34864 specifies the vertical length of the line. The \meta{distance} argument must
34865 be a non-negative value. For horizontal and vertical lines only, the actual
34866 length of the line is \meta{distance}. \fref{flpic:spec}, which is
34867 produced from the code below, diagrams the line
34868 specification arguments.
34869
34870 \begin{lcode}
34871 \begin{figure}
34872 \centering
34873 \setlength{\unitlength}{1mm}
34874 \begin{picture}(70,60)
34875 \thicklines % draw line and ref point
34876 \put(10,20){\line(2,1){40}}
34877 \put(10,20){\vector(1,-1){0}}
34878 \thinlines % draw axes
34879 \put(0,0){\vector(1,0){60}} \put(63,0){x}
34880 \put(0,0){\vector(0,1){50}} \put(0,53){y}
34881 % draw i and j vectors
34882 \put(20,25){\vector(1,0){20}}
34883 \put(30,22){\makebox(0,0)[t]{$i$}}
34884 \put(40,25){\vector(0,1){10}}
34885 \put(42,30){\makebox(0,0)[l]{$j$}}
34886 % draw distance vector
34887 \put(30,10){\vector(-1,0){20}}
34888 \put(30,10){\vector(1,0){20}}
34889 \put(30,8){\makebox(0,0)[t]{\textit{distance}}}
34890 \end{picture}
34891 \setlength{\unitlength}{1pt}
34892 \caption{Specification of a line or arrow}
34893 \label{flpic:spec}
34894 \end{figure}
34895 \end{lcode}
34896
34897 \begin{figure}
34898 \centering
34899 \setlength{\unitlength}{1mm}
34900 \begin{picture}(70,60)
34901 \thicklines
34902 \put(10,20){\line(2,1){40}}
34903 \put(10,20){\vector(1,-1){0}}
34904 \thinlines
34905 \put(0,0){\vector(1,0){60}} \put(63,0){x}
34906 \put(0,0){\vector(0,1){50}} \put(0,53){y}
34907
34908 \put(20,25){\vector(1,0){20}} \put(30,22){\makebox(0,0)[t]{$i$}}
34909 \put(40,25){\vector(0,1){10}} \put(42,30){\makebox(0,0)[l]{$j$}}
34910
34911 \put(30,10){\vector(-1,0){20}}
34912 \put(30,10){\vector(1,0){20}}
34913 \put(30,8){\makebox(0,0)[t]{\textit{distance}}}
34914
34915 \end{picture}
34916 \setlength{\unitlength}{1pt}
34917 \caption{Specification of a line or arrow}
34918 \label{flpic:spec}
34919 \end{figure}
34920
34921 Only a fixed number of slopes\index{line!restricted slope}
34922 are available. This is because \ltx\ uses
34923 a special font for drawing lines --- a line actually consists of little bits
34924 of angled rules joined together. Thus, there is only a limited number of
34925 values for $i$ and $j$. They must both be integers and in the range
34926 $-6 \leq i,j \leq 6$. Also, they must have no common divisor other than 1.
34927 In other words, the ratio between $i$ and $j$ must be in its simplest form.
34928 You cannot, for example, have $(3,6)$; instead it would have to be $(1,2)$.
34929 The shortest line that \ltx\ can draw is about ten points
34930 (1/7 inch approximately) in overall length. You can, though, draw lines that
34931 are too long to fit on the page.
34932
34933 \fref{flpic:lslope} shows the lines and arrows slanting
34934 upwards and to the right that can be drawn in \ltx. The slope $(i,j)$
34935 pair are shown to the right of the first set of lines and arrows, together
34936 with the $j/i$ ratio which gives the slope of the line as a decimal number.
34937
34938
34939 \subsection{Arrows}
34940
34941 As shown in \fref{flpic:lslope} you can also draw a line with an
34942 arrowhead\index{line!arrowhead|see{vector}}\index{arrow|see{vector}}
34943 on it. These are specified
34944 by the \cmd{\vector}\index{vector|seealso{picture object}}\index{picture object!vector|seealso{vector}}
34945 command.
34946 \begin{syntax}
34947 \cmd{\vector}\parg{i, j}\marg{distance} \\
34948 \end{syntax}
34949 \glossary(vector)
34950 {\cs{vector}\parg{dx,dy}\marg{distance}}{Picture object of a line with an
34951 arrowhead at the end, slope \meta{dx,dy} and coordinate
34952 length \meta{distance}.}
34953 This works exactly
34954 like the \cmd{\line} command and the arrowhead is put on the line at the
34955 end away from the reference point\indextwo{reference point}{vector}.
34956 That is, the arrow points away from the
34957 reference point. If the \meta{distance} argument is too small (zero,
34958 for instance) the arrowhead only is drawn, with its point at the position
34959 where it is \cmd{\put}.
34960
34961 \begin{figure}
34962 \centering
34963 \setlength{\unitlength}{1mm}
34964 \begin{picture}(70,70)
34965 % lines and arrows with slopes <= (1,1)
34966 \thicklines \put(0,0){\vector(1,0){50}}
34967 \thinlines \put(0,0){\line(6,1){50}}
34968 \put(0,0){\line(5,1){50}}
34969 \thicklines \put(0,0){\vector(4,1){50}}
34970 \put(0,0){\vector(3,1){50}}
34971 \thinlines \put(0,0){\line(5,2){50}}
34972 \thicklines \put(0,0){\vector(2,1){50}}
34973 \thinlines \put(0,0){\line(5,3){50}}
34974 \thicklines \put(0,0){\vector(3,2){50}}
34975 \put(0,0){\vector(4,3){50}}
34976 \thinlines \put(0,0){\line(5,4){50}}
34977 \put(0,0){\line(6,5){50}}
34978 \thicklines \put(0,0){\vector(1,1){50}}
34979 % label vertically
34980 \put(53,0){\begin{picture}(20,60)
34981 \begin{footnotesize}
34982 \put(0,0){$(1,0)=0$}
34983 \put(0,7.333){$(6,1)=0.167$}
34984 \put(0,10){$(5,1)=0.2$}
34985 \put(0,12.5){$(4,1)=0.25$}
34986 \put(0,16.667){$(3,1)=0.333$}
34987 \put(0,20){$(5,2)=0.4$}
34988 \put(0,25){$(2,1)= 0.5$}
34989 \put(0,30){$(5,3)= 0.6$}
34990 \put(0,33.333){$(3,2)=0.667$}
34991 \put(0,37.5){$(4,3)=0.75$}
34992 \put(0,40){$(5,4)=0.8$}
34993 \put(0,42.667){$(6,5)=0.833$}
34994 \put(0,50){$(1,1)=1$}
34995 \end{footnotesize}
34996 \end{picture}}
34997 % remaining lines and arrows
34998 \thinlines \put(0,0){\line(5,6){41.667}}
34999 \put(0,0){\line(4,5){40}}
35000 \thicklines \put(0,0){\vector(3,4){37.5}}
35001 \put(0,0){\vector(2,3){33.333}}
35002 \thinlines \put(0,0){\line(3,5){30}}
35003 \thicklines \put(0,0){\vector(1,2){25}}
35004 \thinlines \put(0,0){\line(2,5){20}}
35005 \thicklines \put(0,0){\vector(1,3){16.667}}
35006 \put(0,0){\vector(1,4){12.5}}
35007 \thinlines \put(0,0){\line(1,5){10}}
35008 \put(0,0){\line(1,6){8.333}}
35009 \thicklines \put(0,0){\vector(0,1){50}}
35010 % label horizontally
35011 \put(0,55){\begin{picture}(50,10)
35012 \begin{footnotesize}
35013 % \put(41.667,5){\makebox(0,0){$(5,6)=1.2$}}
35014 % \put(40,0){\makebox(0,0){$(4,5)=1.25$}}
35015 % \put(37.5,5){\makebox(0,0){$(3,4)=1.333$}}
35016 % \put(33.333,0){\makebox(0,0){$(2,3)=1.5$}}
35017 % \put(30,5){\makebox(0,0){$(3,5)=1.667$}}
35018 \put(25,0){\makebox(0,0){$(1,2)=2$}}
35019 % \put(20,5){\makebox(0,0){$(2,5)=2.5$}}
35020 % \put(16.667,0){\makebox(0,0){$(1,3)=3$}}
35021 % \put(12.5,5){\makebox(0,0){$(1,4)=4$}}
35022 % \put(10,0){\makebox(0,0){$(1,5)=5$}}
35023 % \put(8.333,5){\makebox(0,0){$(1,6)=6$}}
35024 \put(0,0){\makebox(0,0){$(0,1)= \infty$}}
35025 \end{footnotesize}
35026 \end{picture}}
35027 \end{picture}
35028 \setlength{\unitlength}{1pt}
35029 \caption{Sloping lines and arrows} \label{flpic:lslope}
35030 \end{figure}
35031
35032 \ltx\ is even more restrictive in the number of slopes that it can draw
35033 with arrows\index{vector!restricted slope}\indextwo{slope}{vector}
35034 than it is with lines.
35035 The $(i,j)$ slope specification pair
35036 must lie in the range $-4 \leq i,j \leq 4$. Also, as with the \cmd{\line}
35037 command, they must have no common divisor.
35038
35039
35040
35041 \subsection{Circles}
35042
35043 \ltx\ can draw two kinds of circles\index{picture object!circle|seealso{circle}}\index{circle|seealso{picture object}}.
35044 One is an open circle\index{circle!open} where only
35045 the perimeter is drawn, and the other is a solidly filled
35046 disk\index{circle!disk}\index{disk|see{circle}}.
35047 \begin{syntax}
35048 \cmd{\circle}\marg{diameter} \\
35049 \cmd{\circle*}\marg{diameter} \\
35050 \end{syntax}
35051 \glossary(circle)
35052 {\cs{circle}\marg{diam}}{Picture object of a open circle
35053 diameter \meta{diam}.}
35054 \glossary(circle*)
35055 {\cs{circle*}\marg{diam}}{Picture object of a black closed circle
35056 diameter \meta{diam}.}
35057
35058 The reference point\indextwo{reference point}{circle} for the open circle,
35059 drawn by the \cmd{\circle}
35060 command, and the disk, which is drawn by the \cmd{\circle*} command,
35061 is at the center
35062 of the circle. The argument to the commands is the \meta{diameter}
35063 of the circle.
35064
35065 \begin{egsource}{eg:pic10}
35066 \setlength{\unitlength}{1pt}
35067 \begin{picture}(200,60)
35068 \put(0,0){\framebox(200,60){}}
35069 \put(30,30){\circle{40}}
35070 \put(30,30){\vector(1,1){0}}
35071 \put(150,50){\circle*{20}}
35072 \end{picture}
35073 \setlength{\unitlength}{1pt}
35074 \end{egsource}
35075
35076 \begin{egresult}[Picture: circles]{eg:pic10}
35077 \vspace{0.5\onelineskip}
35078 \setlength{\unitlength}{1pt}
35079 \begin{picture}(200,60)
35080 \put(0,0){\framebox(200,60){}}
35081 \put(30,30){\circle{40}}
35082 \put(30,30){\vector(1,1){0}}
35083 \put(150,50){\circle*{20}}
35084 \end{picture}
35085 \setlength{\unitlength}{1pt}
35086 \end{egresult}
35087
35088 Just as with the \cmd{\line} and \cmd{\vector} commands, there is only a
35089 limited range of circles\index{circle!restricted diameter} that can be drawn.
35090 Typically, the maximum diamter of a \cmd{\circle} is about 40 points, while
35091 for a \cmd{\circle*} the maximum diameter is less, being about 15 points.
35092 \ltx\ will choose
35093 the nearest sized circle to the one that you specify. Either consult your
35094 local guru to find what sized circles you can draw on your system, or
35095 try some experiments by drawing a range of circles to see what happens.
35096
35097 \subsubsection{Quarter circles and boxes}
35098
35099 In \ltx\ an \cmd{\oval}\index{picture object!oval|seealso{box, rounded}}%
35100 \index{oval|seealso{picture object}} is a rectangular
35101 box\index{box!rounded|seealso{oval}} with rounded corners.
35102 \begin{syntax}
35103 \cmd{\oval}\parg{width, height}\oarg{portion} \\
35104 \end{syntax}
35105 \glossary(oval)
35106 {\cs{oval}\parg{width,height}\oarg{portion}}{Picture object of a rectangular
35107 box, size \meta{width} by \meta{height}, with rounded corners. The optional
35108 \meta{portion} argument controls whether and which a quarter or a half of
35109 the object will be drawn (default is everything).}
35110
35111 The \cmd{\oval} command has one required argument which specifies the
35112 width and height of the box. The normally sharp corners of the box are
35113 replaced by quarter circles of the maximum possible radius (which \ltx\
35114 figures out for itself). Unlike the boxes discussed earlier, the reference
35115 point\indextwo{reference point}{oval} is at the `center' of the oval.
35116
35117 \begin{egsource}{eg:pic11}
35118 \setlength{\unitlength}{1mm}
35119 \begin{picture}(75,20)
35120 \thicklines
35121 \put(0,0){\framebox(75,20){}}
35122 \put(15,10){\oval(15,10)} % complete oval
35123 \put(15,10){\vector(1,1){0}}
35124 \put(30,10){\oval(5,5)} % small oval
35125 \put(30,10){\vector(1,1){0}}
35126 \put(45,10){\oval(15,10)[l]} % left half
35127 \put(45,10){\vector(1,1){0}}
35128 \put(60,10){\oval(15,10)[bl]} % bottom left quarter
35129 \put(60,10){\vector(1,1){0}}
35130 \end{picture}
35131 \setlength{\unitlength}{1pt}
35132 \end{egsource}
35133
35134 \begin{egresult}[Picture: ovals]{eg:pic11}
35135 \vspace{0.5\onelineskip}
35136 \setlength{\unitlength}{1mm}
35137 \begin{picture}(75,20)
35138 \thicklines
35139 \put(0,0){\framebox(75,20){}}
35140 \put(15,10){\oval(15,10)}
35141 \put(15,10){\vector(1,1){0}}
35142
35143 \put(30,10){\oval(5,5)}
35144 \put(30,10){\vector(1,1){0}}
35145
35146 \put(45,10){\oval(15,10)[l]}
35147 \put(45,10){\vector(1,1){0}}
35148
35149 \put(60,10){\oval(15,10)[bl]}
35150 \put(60,10){\vector(1,1){0}}
35151 \end{picture}
35152 \setlength{\unitlength}{1pt}
35153 \end{egresult}
35154
35155 The \cmd{\oval} command also has one optional argument, \meta{portion},
35156 which comes after
35157 the required argument.
35158 Use of the optional argument enables either half\index{box!rounded!half} or
35159 a quarter\index{box!rounded!quarter} of the complete rounded box
35160 to be drawn. The argument is a one or two
35161 letter code drawn from the following.
35162 \begin{itemize}
35163 \item[\pixposarg{l}] (left) Draw the left of the oval.
35164 \item[\pixposarg{r}] (right) Draw the right of the oval.
35165 \item[\pixposarg{t}] (top) Draw the top of the oval.
35166 \item[\pixposarg{b}] (bottom) Draw the bottom of the oval.
35167 \end{itemize}
35168 These are similar to the optional positioning argument in the box commands.
35169 A one letter code will draw the designated half of the oval, while a two letter
35170 code results in the designated quarter of the oval being drawn. In all cases
35171 the reference point is at the center of the `complete' oval.
35172
35173
35174
35175 \begin{egsource}{eg:pic12}
35176 \setlength{\unitlength}{1mm}
35177 \begin{picture}(30,10)
35178 \thicklines
35179 \put(15,5){\oval(30,10)}
35180 \put(15,5){\makebox(0,0){Text in oval}}
35181 \end{picture}
35182 \setlength{\unitlength}{1pt}
35183 \end{egsource}
35184
35185 \begin{egresult}[Picture: text in oval]{eg:pic12}
35186 \vspace{0.5\onelineskip}
35187 \setlength{\unitlength}{1mm}
35188 \begin{picture}(30,10)
35189 \thicklines
35190 \put(15,5){\oval(30,10)}
35191 \put(15,5){\makebox(0,0){Text in oval}}
35192 \end{picture}
35193 \setlength{\unitlength}{1pt}
35194 \end{egresult}
35195
35196 Unlike the boxes described in \Sref{slpic:boxes} there is no \meta{text}
35197 argument for an \cmd{\oval}. If you want the rounded box to contain text,
35198 then you have to place the text inside the box yourself.
35199 The code in \eref{eg:pic12} shows
35200 one way of doing this; a zero-sized box is used to center the text at
35201 the center of the oval.
35202
35203
35204 \section{Repetitions}
35205
35206 The \cmd{\multiput} command is a convenient way to place regularly spaced
35207 copies of an object\index{picture object!regular pattern}
35208 in a picture.
35209 \begin{syntax}
35210 \cmd{\multiput}\parg{x, y}\parg{dx, dy}\marg{num}\marg{object} \\
35211 \end{syntax}
35212 \glossary(multiput)
35213 {\cs{multiput}\parg{x,y}\parg{dx,dy}\marg{num}\marg{object}}{Drawing
35214 command to place \meta{num} copies of \meta{object}, starting at coordinates
35215 \meta{x,y} and stepping \meta{dx,dy} for each copy after the first.}
35216 As you can see, this is similar to the syntax for the \cmd{\put} command,
35217 except that there are two more required arguments, namely \parg{dx, dy}
35218 and \textit{num}.
35219
35220 The \parg{dx, dy} argument is a pair of (decimal) numbers that
35221 specify the amount that the \meta{object} shall be moved at each repetition.
35222 The first of this pair specifies the horizontal movement and the second the
35223 vertical movement. Positive values shift to the right or up, and negative
35224 numbers shift to the left or down. The \meta{num} argument specifies how many
35225 times the \meta{object} is to be drawn.
35226
35227 The code below produces \fref{flpic:scales}.
35228 This example
35229 also shows that a \Ie{picture} can be placed
35230 inside\index{picture object!picture} another \Ie{picture}.
35231 Often it is useful to break a complex diagram up into pieces, with each
35232 piece being a separate \Ie{picture}. The pieces can then be individually
35233 positioned within the overall diagram.
35234
35235 \begin{figure}
35236 \setlength{\unitlength}{1pc}
35237 \centering
35238 %\begin{picture}(21,35)
35239 \begin{picture}(21,26)
35240 % Draw Pica scale
35241 %\put(2,2){\begin{picture}(5,33)
35242 \put(2,2){\begin{picture}(5,24)
35243 \put(0,-0.5){\makebox(0,0)[t]{\textbf{Picas}}}
35244 % \thicklines \put(0,0){\line(0,1){35}}
35245 \thicklines \put(0,0){\line(0,1){24.0}}
35246 % \thinlines \multiput(0,0)(0,1){36}{\line(1,0){1}}
35247 % \multiput(0,0)(0,10){4}{\line(1,0){2}}
35248 \thinlines \multiput(0,0)(0,1){25}{\line(1,0){1}}
35249 \multiput(0,0)(0,10){3}{\line(1,0){2}}
35250 \put(-1,0){\makebox(0,0)[br]{0}}
35251 \put(-1,10){\makebox(0,0)[br]{10}}
35252 \put(-1,20){\makebox(0,0)[br]{20}}
35253 % \put(-1,30){\makebox(0,0)[br]{30}}
35254 \end{picture}}
35255 % Draw Points scale
35256 %\put(7,2){\begin{picture}(5,33)
35257 \put(7,2){\begin{picture}(5,24)
35258 \put(0,-0.5){\makebox(0,0)[t]{\textbf{Points}}}
35259 % \thicklines \put(0,0){\line(0,1){35}}
35260 % \thinlines \multiput(0,0)(0,0.8333){42}{\line(1,0){1}}
35261 % \multiput(0,0)(0,8.333){5}{\line(1,0){2}}
35262 \thicklines \put(0,0){\line(0,1){24.2}}
35263 \thinlines \multiput(0,0)(0,0.8333){30}{\line(1,0){1}}
35264 \multiput(0,0)(0,8.333){3}{\line(1,0){2}}
35265 \put(-1,0){\makebox(0,0)[br]{0}}
35266 \put(-1,8.333){\makebox(0,0)[br]{100}}
35267 \put(-1,16.667){\makebox(0,0)[br]{200}}
35268 % \put(-1,25){\makebox(0,0)[br]{300}}
35269 % \put(-1,33.333){\makebox(0,0)[br]{400}}
35270 \end{picture}}
35271 % Draw Millimeter scale
35272 %\put(12,2){\begin{picture}(5,33)
35273 \put(12,2){\begin{picture}(5,24)
35274 \put(0,-0.5){\makebox(0,0)[t]{\textbf{Millimeters}}}
35275 % \thicklines \put(0,0){\line(0,1){35}}
35276 % \thinlines \multiput(0,0)(0,0.4742){74}{\line(1,0){1}}
35277 % \multiput(0,0)(0,2.3711){15}{\line(1,0){2}}
35278 \thicklines \put(0,0){\line(0,1){24.2}}
35279 \thinlines \multiput(0,0)(0,0.4742){52}{\line(1,0){1}}
35280 \multiput(0,0)(0,2.3711){11}{\line(1,0){2}}
35281 \put(-1,0){\makebox(0,0)[br]{0}}
35282 % \put(-1,2.371){\makebox(0,0)[br]{10}}
35283 \put(-1,4.742){\makebox(0,0)[br]{20}}
35284 % \put(-1,7.113){\makebox(0,0)[br]{30}}
35285 \put(-1,9.484){\makebox(0,0)[br]{40}}
35286 % \put(-1,11.855){\makebox(0,0)[br]{50}}
35287 \put(-1,14,226){\makebox(0,0)[br]{60}}
35288 % \put(-1,16.597){\makebox(0,0)[br]{70}}
35289 \put(-1,18.968){\makebox(0,0)[br]{80}}
35290 % \put(-1,21.339){\makebox(0,0)[br]{90}}
35291 \put(-1,23.71){\makebox(0,0)[br]{100}}
35292 % \put(-1,26.081){\makebox(0,0)[br]{110}}
35293 % \put(-1,28.452){\makebox(0,0)[br]{120}}
35294 % \put(-1,30.823){\makebox(0,0)[br]{130}}
35295 % \put(-1,33.194){\makebox(0,0)[br]{140}}
35296 \end{picture}}
35297 % Draw Inch scale
35298 %\put(17,2){\begin{picture}(5,33)
35299 \put(17,2){\begin{picture}(5,24)
35300 \put(0,-0.5){\makebox(0,0)[t]{\textbf{Inches}}}
35301 % \thicklines \put(0,0){\line(0,1){35}}
35302 % \thinlines \multiput(0,0)(0,0.60225){59}{\line(1,0){1}}
35303 % \multiput(0,0)(0,6.0225){6}{\line(1,0){2}}
35304 \thicklines \put(0,0){\line(0,1){24.1}}
35305 \thinlines \multiput(0,0)(0,0.60225){41}{\line(1,0){1}}
35306 \multiput(0,0)(0,6.0225){5}{\line(1,0){2}}
35307 \put(-1,0){\makebox(0,0)[br]{0}}
35308 \put(-1,6.0225){\makebox(0,0)[br]{1}}
35309 \put(-1,12.045){\makebox(0,0)[br]{2}}
35310 \put(-1,18.0675){\makebox(0,0)[br]{3}}
35311 \put(-1,24.09){\makebox(0,0)[br]{4}}
35312 % \put(-1,30.1125){\makebox(0,0)[br]{5}}
35313 \end{picture}}
35314
35315 \end{picture}
35316 \setlength{\unitlength}{1pt}
35317 \caption{Some measuring scales} \label{flpic:scales}
35318 \end{figure}
35319
35320 \begin{lcode}
35321 \begin{figure}
35322 \setlength{\unitlength}{1pc}
35323 \centering
35324 \begin{picture}(21,26)
35325 % Draw Pica scale
35326 \put(2,2){\begin{picture}(5,24)
35327 \put(0,-0.5){\makebox(0,0)[t]{\textbf{Picas}}}
35328 \thicklines \put(0,0){\line(0,1){24.0}}
35329 \thinlines \multiput(0,0)(0,1){25}{\line(1,0){1}}
35330 \multiput(0,0)(0,10){3}{\line(1,0){2}}
35331 \put(-1,0){\makebox(0,0)[br]{0}}
35332 \put(-1,10){\makebox(0,0)[br]{10}}
35333 \put(-1,20){\makebox(0,0)[br]{20}}
35334 \end{picture}}
35335 % Draw Points scale
35336 \put(7,2){\begin{picture}(5,24)
35337 \put(0,-0.5){\makebox(0,0)[t]{\textbf{Points}}}
35338 \thicklines \put(0,0){\line(0,1){24.2}}
35339 \thinlines \multiput(0,0)(0,0.8333){30}{\line(1,0){1}}
35340 \multiput(0,0)(0,8.333){3}{\line(1,0){2}}
35341 \put(-1,0){\makebox(0,0)[br]{0}}
35342 \put(-1,8.333){\makebox(0,0)[br]{100}}
35343 \put(-1,16.667){\makebox(0,0)[br]{200}}
35344 \end{picture}}
35345 % Draw Millimeter scale
35346 \put(12,2){\begin{picture}(5,24)
35347 \put(0,-0.5){\makebox(0,0)[t]{\textbf{Millimeters}}}
35348 \thicklines \put(0,0){\line(0,1){24.2}}
35349 \thinlines \multiput(0,0)(0,0.4742){15}{\line(1,0){1}}
35350 \multiput(0,0)(0,2.3711){11}{\line(1,0){2}}
35351 \put(-1,0){\makebox(0,0)[br]{0}}
35352 \put(-1,4.742){\makebox(0,0)[br]{20}}
35353 \put(-1,9.484){\makebox(0,0)[br]{40}}
35354 \put(-1,14,226){\makebox(0,0)[br]{60}}
35355 \put(-1,18.968){\makebox(0,0)[br]{80}}
35356 \put(-1,23.71){\makebox(0,0)[br]{100}}
35357 \end{picture}}
35358 % Draw Inch scale
35359 \put(17,2){\begin{picture}(5,24)
35360 \put(0,-0.5){\makebox(0,0)[t]{\textbf{Inches}}}
35361 \thicklines \put(0,0){\line(0,1){24.1}}
35362 \thinlines \multiput(0,0)(0,0.60225){41}{\line(1,0){1}}
35363 \multiput(0,0)(0,6.0225){5}{\line(1,0){2}}
35364 \put(-1,0){\makebox(0,0)[br]{0}}
35365 \put(-1,6.0225){\makebox(0,0)[br]{1}}
35366 \put(-1,12.045){\makebox(0,0)[br]{2}}
35367 \put(-1,18.0675){\makebox(0,0)[br]{3}}
35368 \put(-1,24.09){\makebox(0,0)[br]{4}}
35369 \end{picture}}
35370
35371 \end{picture}
35372 \setlength{\unitlength}{1pt}
35373 \caption{Some measuring scales} \label{flpic:scales}
35374 \end{figure}
35375 \end{lcode}
35376
35377
35378 You can also make regular
35379 two-dimensional\index{picture object!two-dimensional pattern} patterns
35380 by using a
35381 \cmd{\multiput} pattern inside another \cmd{\multiput}. As \ltx\ will
35382 process each \cmd{\multiput} every time it is repeated it is often more
35383 convenient to store the results of the first \cmd{\multiput} in a bin
35384 and then use this as the argument to the second \cmd{\multiput}.
35385
35386 \begin{egsource}{eg:pic14}
35387 \setlength{\unitlength}{1mm}
35388 \begin{picture}(32,14)
35389 \put(0,0){\framebox(32,14){}}
35390 \savebox{\Mybox}(8,8){\multiput(0,0)(4,4){3}{\circle*{1}}}
35391 \multiput(4,4)(6,0){4}{\usebox{\Mybox}}
35392 \sbox{\Mybox}{}
35393 \end{picture}
35394 \setlength{\unitlength}{1pt}
35395 \end{egsource}
35396
35397 \begin{egresult}[Picture: repetitions]{eg:pic14}
35398 \vspace{0.5\onelineskip}
35399 \setlength{\unitlength}{1mm}
35400 \begin{picture}(32,14)
35401 \put(0,0){\framebox(32,14){}}
35402 \savebox{\Mybox}(8,8){\multiput(0,0)(4,4){3}{\circle*{1}}}
35403 \multiput(4,4)(6,0){4}{\usebox{\Mybox}}
35404 \sbox{\Mybox}{}
35405 \end{picture}
35406 \setlength{\unitlength}{1pt}
35407 \end{egresult}
35408
35409 Remember that
35410 a storage bin must have been declared via a \cmd{\newsavebox} command before
35411 it can be used. I originally declared and used
35412 the \cs{Mybox} bin in \Sref{slpic:boxes}.
35413 As the above example shows, you can change the contents of a storage bin
35414 by utilising it in another \cmd{\savebox}. Storage bins can use up a
35415 lot of \ltx's memory. After
35416 you have finished with a storage bin empty it via the \cmd{\sbox}
35417 command with an empty last argument, as shown in the example.
35418
35419 \section{Bezier curves}
35420
35421 Standard \ltx\ provides one further drawing command ---
35422 the \cmd{\qbezier}\index{picture object!Bezier curve|seealso{Bezier curve}}
35423 command.
35424 This can be used for drawing fairly arbitrary curves.
35425 \begin{syntax}
35426 \cmd{\qbezier}\oarg{num}\parg{Xs, Ys}\parg{Xm, Ym}\parg{Xe, Ye} \\
35427 \end{syntax}
35428 \glossary(qbezier)
35429 {\cs{qbezier}\oarg{num}\parg{Xs,Ys}\parg{Xm,Ym}\parg{Xe,Ye}}{Picture
35430 command to draw a quadratic Bezier curve from \meta{Xs,Ys} to \meta{Xe,Ye}
35431 passing near \meta{Xm,Ym}. If the optional argument is present exactly
35432 \meta{num} segments will be used in drawing the curve.}
35433 The command will draw what geometers call a \emph{quadratic Bezier
35434 curve}\index{Bezier curve|seealso{picture object}} from the
35435 point \parg{Xs, Ys} to the point \parg{Xe, Ye}. The
35436 curve will pass somewhere near to the point \parg{Xm, Ym}.
35437
35438 Bezier curves are named after Pierre Bezier\index{Bezier, Pierre}
35439 who first used them in 1962. They are widely used in Computer Aided
35440 Design (CAD)
35441 programs and other graphics and font design systems. Descriptions, with
35442 varying degrees of mathematical complexity, can be found in many places:
35443 when I was a practicing geometer these included \cite{FAUX80},
35444 \cite{MORTENSON85} and \cite{FARIN90}; no doubt there are more recent
35445 sources available and there is a brief review in~\cite{BEZ123}.
35446
35447 \fref{lpicf:bez} shows two of these curves. The figure was
35448 produced by the code below.
35449
35450 %\begin{egsource}{eg11.15}
35451 \begin{lcode}
35452 \begin{figure}
35453 \setlength{\unitlength}{1mm}
35454 \centering
35455 \begin{picture}(100,100)
35456
35457 \thicklines % first curve
35458 \qbezier(10,50)(50,90)(50,50)
35459 \thinlines % draw lines joining control points
35460 \put(10,50){\line(1,1){40}}
35461 \put(50,90){\line(0,-1){40}}
35462 % label control points
35463 \put(10,45){\makebox(0,0)[t]{\texttt{(10,50)}}}
35464 \put(50,95){\makebox(0,0)[b]{\texttt{(50,90)}}}
35465 \put(55,50){\makebox(0,0)[l]{\texttt{(50,50)}}}
35466
35467 \thicklines % second curve
35468 \qbezier[25](50,50)(50,10)(90,50)
35469 \thinlines % draw lines joining control points
35470 % \put(50,50){\line(0,-1){40}}
35471 % \put(50,10){\line(1,1){40}}
35472 % label control points
35473 \put(50,5){\makebox(0,0)[t]{\texttt{(50,10)}}}
35474 \put(90,55){\makebox(0,0)[b]{\texttt{(90,50)}}}
35475
35476 \end{picture}
35477 \setlength{\unitlength}{1pt}
35478 \caption{Two Bezier curves}
35479 \label{lpicf:bez}
35480 \end{figure}
35481 \end{lcode}
35482 %\end{egsource}
35483
35484 \begin{figure}
35485 \setlength{\unitlength}{1mm}
35486 \centering
35487 \begin{picture}(100,100)
35488
35489 \thicklines % first curve
35490 \qbezier(10,50)(50,90)(50,50)
35491 \thinlines % draw lines joining control points
35492 \put(10,50){\line(1,1){40}}
35493 \put(50,90){\line(0,-1){40}}
35494 % label control points
35495 \put(10,45){\makebox(0,0)[t]{\texttt{(10,50)}}}
35496 \put(50,95){\makebox(0,0)[b]{\texttt{(50,90)}}}
35497 \put(55,50){\makebox(0,0)[l]{\texttt{(50,50)}}}
35498
35499 \thicklines % second curve
35500 \qbezier[25](50,50)(50,10)(90,50)
35501 \thinlines % draw lines joining control points
35502 % \put(50,50){\line(0,-1){40}}
35503 % \put(50,10){\line(1,1){40}}
35504 % label control points
35505 \put(50,5){\makebox(0,0)[t]{\texttt{(50,10)}}}
35506 \put(90,55){\makebox(0,0)[b]{\texttt{(90,50)}}}
35507
35508 \end{picture}
35509 \setlength{\unitlength}{1pt}
35510 \caption{Two Bezier curves}
35511 \label{lpicf:bez}
35512 \end{figure}
35513
35514 The three points used to specify the position and shape of the
35515 Bezier curve are called
35516 \emph{control points}\index{Bezier curve!control points}.
35517 The curve starts at
35518 the first control point and is tangent to the line joining the first
35519 and second control points. The curve stops at the last control point
35520 and is tangent to the line joining the last two control points.
35521
35522 In \fref{lpicf:bez} the lines joining the control points for the
35523 first curve have been drawn in. The locations of all the control points
35524 for the two curves are labeled.
35525
35526 The second Bezier curve is the same shape
35527 as the first one, but rotated 180 degrees. The first control point
35528 of this curve is the same as the last control point of the first curve.
35529 This means that the two curves are joind at this point. The line,
35530 although it is not drawn,
35531 connecting the first two control points of the second curve is in the
35532 same direction as the line joining the last two control points of the
35533 first curve. This means that the two curves are also tangent at the
35534 point where they join. By stringing together several Bezier curves
35535 you can draw quite complex curved shapes.
35536
35537 \begin{syntax}
35538 \cmd{\qbeziermax} \\
35539 \end{syntax}
35540 \glossary(qbeziermax)
35541 {\cs{qbeziermax}}{The maximum number of segments for drawing a Bezier curve.}
35542 The Bezier curves are actually drawn as a
35543 linearized\index{Bezier curve!linearized rendition} form
35544 using a series of rectangular
35545 blobs of ink. Left to itself, \ltx\ will attempt to pick the number
35546 of blobs to give the smoothest looking curve, up to a maximum number.
35547 (Each blob takes up space in \ltx 's internal memory, and it may run
35548 out of space if too many are used in one picture.) The maximum number
35549 of blobs per Bezier curve is set by the \cmd{\qbeziermax} command. This
35550 can be adjusted with the \cmd{\renewcommand} command. For example:
35551 \begin{lcode}
35552 \renewcommand{\qbeziermax}{250}
35553 \end{lcode}
35554 will set the maximum number of blobs to be 250.
35555
35556 Another method of controlling the number of blobs is by
35557 the optional \meta{num} argument to the \cmd{\qbezier} command.
35558 If used, it must be a positive integer number which tells \ltx\
35559 exactly how many blobs to use for the curve.
35560
35561
35562 %#% extend
35563 %#% extstart include latex-and-tex.tex
35564
35565 \svnidlong
35566 {$Ignore: $}
35567 {$LastChangedDate: 2025-09-19 16:06:27 +0200 (Fri, 19 Sep 2025) $}
35568 {$LastChangedRevision: 873 $}
35569 {$LastChangedBy: [email protected] $}
35570
35571
35572 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
35573 \chapter{\ltx\ and \tx} \label{appendix:alltex}
35574
35575 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
35576
35577
35578 \begin{note}
35579 This appendix will probably disappear in the future or at least be
35580 heavily rewritten, as the contents is not really within the scope of
35581 this manual
35582
35583 Users are referred to materials such as \cite{USRGUIDE},
35584 \cite{CLSGUIDE}, \cite{TEXBYTOPIC} and \cite{TLC3}. And for the
35585 adventurous \cite{EXPL3}.\fxnote[author=dlf,vadj=0em]{finish cleaning this}
35586 \sourceatright{/maintainer}
35587 \end{note}
35588
35589
35590
35591 \noindent
35592 Strictly speaking, \ltx\ is a set of macros built on top of
35593 the \tx\ program originally developed by
35594 Donald Knuth~\cite{TEXPROGRAM,TEXBOOK}
35595 in the early
35596 1980's. \tx\ is undoubtedly one of the most robust computer programs
35597 to date.
35598
35599 Leslie Lamport says that most \tx\ commands can be used with
35600 \ltx\ and lists those that cannot be used~\cite[Appendix E]{LAMPORT94}.
35601 Apart from this he says nothing about any \tx\ commands. I have used
35602 some \tx\ macros in the code examples and so I need to talk a little
35603 bit about these.
35604
35605 I like to think of the commands and
35606 macros as falling into one of several groups.
35607 \begin{itemize}
35608
35609 \item \tx\ primitives. These are the basic constructs of the \tx\ language.
35610
35611 \item \tx\ commands or macros. These are part of the plain \tx\ system
35612 and are
35613 constructed from the \tx\ primitives.
35614
35615 \item \ltx\ kernel commands or macros. These are defined in the \ltx\ kernel
35616 and are based on plain \tx\ primitives or commands. In turn, some
35617 higher level kernel macros are constructed from more basic aspects
35618 of the kernel. The kernel does redefine some of the plain \tx\ commands.
35619
35620
35621 \item Class command. These are mainly built up on the kernel commands but
35622 may use some basic \tx.
35623
35624 \item Package commands. These are similar to the class commands but are
35625 less likely to directly use \tx\ macros.
35626
35627 \item User commands. Typically these are limited to the commands
35628 provided by the class and any packages that might be called for,
35629 but more experienced users will employ some kernel commands,
35630 like \cmd{\newcommand}, to make their authoring more efficient.
35631 \end{itemize}
35632
35633 Although \tx\ is designed as a language for typesetting it is
35634 also a `Turing complete'
35635 language\index{Turing complete language}\index{Turing, Alan}
35636 which means that it can perform any function that can be programmed in
35637 any familiar programming language. For example, an interpreter for the
35638 BASIC language has been written in \tx, but writing this kind of program
35639 using \tx\ is something that only an expert\footnote{Probably also a masochist
35640 with plenty of time.} might consider.
35641
35642 Nevertheless, you may have to, or wish to, write a typesetting function
35643 of your own. This chapter presents a few of the programming aspects that
35644 you may need for this, such as performing some simple arithmetic or comparing
35645 two lengths. For anything else you will have to read one or more of the
35646 \tx\ books or tutorials.
35647
35648
35649
35650 In England witnesses at a trial have to swear to `Tell the truth, the
35651 whole truth, and nothing but the truth'. I will try and tell the truth
35652 about \tx\ but, to misquote Hamlet \linenumberfrequency{0}
35653 \settowidth{\versewidth}{There are more things in heaven and TeX, Horatio}
35654 \begin{verse}[\versewidth]
35655 There are more things in heaven and \tx, Horatio, \\
35656 Than are dreamt of in your philosophy.
35657 \end{verse}
35658
35659 \section{The \tx\ process}
35660
35661 As we are delving deeper than normal and because at the bottom
35662 it is the \tx\ language that does all the work, it is useful to
35663 have an idea of how \tx\ processes a source file to produce a
35664 \pixfile{dvi} file. It is all explained in detail by
35665 Knuth~\cite{TEXBOOK} and also perhaps more accessibly by
35666 Eijkhout~\cite{TEXBYTOPIC};
35667 the following is a simplified description.
35668 Basically there are four processes involved and the output from one
35669 process is the input to the following one.
35670
35671 \begin{description}
35672 \item[Input] The input process, which Knuth terms the `eyes', reads
35673 the source file and converts what it sees into \emph{tokens}\index{token}.
35674 There are essentially two kinds of token. A token is either a single
35675 character such as a letter or a digit or a punctuation mark, or
35676 a token is a control sequence.
35677 A \emph{control sequence}\index{control sequence} consists of a backslash
35678 and either all the alphabetic characters immediately following it, or
35679 the single non-alphabetic following it. Control sequence is the general
35680 term for what I have been calling a macro or a command.
35681
35682 \item[Expansion] The expansion processor is what Knuth calls `\tx's mouth'.
35683 In this process some of the tokens from the input processor are expanded.
35684 Expansion replaces a token by other tokens or sometimes by no token.
35685 The expandible tokens include macros, conditionals, and a number of
35686 \tx\ primitives.
35687
35688 \item[Execution] The execution process is \tx's `stomach'. This handles
35689 all the tokens output by the expansion processor. Control sequences
35690 that are not expandible are termed \emph{executable}, and the execution
35691 processor executes the executable tokens. Character tokens are
35692 neither expandible nor executable. It handles any macro defintions
35693 and also builds horizontal, vertical and mathematical lists.
35694
35695 \item[Layout] The layout processor (\tx's `bowels') breaks horizontal
35696 lists into paragraphs, mathematical lists into formulae, and
35697 vertical lists into pages. The final output is the \pixfile{dvi} file.
35698
35699 \end{description}
35700
35701 In spite of the sequential nature implied by this description the
35702 overall process includes some feedback from a later process to an
35703 earlier one which may affect what that does.
35704
35705 It is probably the expansion processor that needs to be best understood.
35706 Its input is a sequence of tokens from the input processor and its output
35707 is a sequence of different tokens.
35708
35709 In outline, the expansion processor takes each input token in turn
35710 and sees if it is expandible; if it is not it simply passes it on to the
35711 output. If the token is expandible then it is replaced by its expansion.
35712 The most common expandible tokens are control sequences that have been
35713 defined as macros. If the macro takes no arguments then the macro's name
35714 is replaced by its definition. If the macro takes arguments, sufficient
35715 tokens are collected to get the values of the arguments, and then the
35716 macro name is replaced by the definition. The expansion processor then
35717 looks at the first token in the replacement, and if that is expandible
35718 it expands that, and so on.
35719
35720 Nominally, the eventual output from the expansion
35721 processor is a stream of non-expandible tokens. There are ways,
35722 however of controlling whether or not the expansion processor will actually
35723 expand an expandible token, and to control the order in which things
35724 get expanded, but that is where things get rapidly complicated.
35725
35726 The layout processor works something like this. Ignoring maths,
35727 \tx\ stores what you type in two kinds of lists, vertical and horizontal.
35728 As it reads your words it puts them one after another in a horizontal list.
35729 At the end of a paragraph it stops the horizontal list and adds it to the
35730 vertical list. At the beginning of the next paragraph it starts a new
35731 horizontal list and adds the paragraph's words to it. And so on. This
35732 results in a vertical list of horizontal lists of words, where each
35733 horizontal list contains the words of a paragraph.
35734
35735 It then goes through each horizontal list in turn, breaking it up into
35736 shorter horizontal lists, one for each line in the paragraph. These are
35737 put into another vertical list, so conceptually there is a vertical list
35738 of paragraphs, and each paragraph is a vertical list of lines, and each
35739 line is a horizontal list of words, or alternatively one vertical list
35740 of lines. Lastly it chops up the vertical list of lines into page sized
35741 chunks and outputs them a page at a time.
35742
35743 \tx\ is designed to handle arbitrary sized inserts, like those for
35744 maths, tables, sectional divisions and so forth, in an elegant manner.
35745 It does this by allowing
35746 vertical spaces on a page to stretch and shrink a little so that the
35747 actual height of the typeblock is constant. If a page consists only of
35748 text with no widow or orphan then the vertical spacing is regular, otherwise
35749 it is likely to vary to some extent. Generally speaking, \tx\ is not
35750 designed to typeset on a fixed grid, but against this
35751 other systems are not designed
35752 to produce high quality typeset mathematics. Attempts have been made
35753 to tweak \ltx\ to typeset on a fixed grid but as far as I know nobody
35754 has been completely successful.
35755
35756
35757 \tx\ works somewhat more efficiently than I have described. Instead
35758 of reading the whole document before breaking paragraphs into lines, it
35759 does the line breaking at the end of each paragraph. After each paragraph
35760 it checks to see if it has enough material for a page, and outputs a page
35761 whenever it is full. However, \tx\ is also a bit lazy. Once it has broken
35762 a paragraph into lines it never looks at the paragraph again, except perhaps
35763 to split it at a page break. If you want to change, say, the width of the
35764 typeblock on a particular page, any paragraph that spills over from a
35765 previous page will not be reset to match the new measure. This asynchronous
35766 page breaking\index{page break!asynchronous} also has an unfortunate effect
35767 if you are trying to put a note in say, the outside margin, as the outside
35768 is unknown until after the paragraph has been set, and so the note may end
35769 up in the wrong margin.
35770
35771 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
35772
35773 \section{\ltx\ files} \label{sec:latexfiles}
35774
35775 The \pixfile{aux} file is the way \ltx\ transfers information from one
35776 run to the next and the process works roughly like this.
35777 \begin{itemize}
35778 \item The \pixfile{aux} file is read at the start of the \Ie{document}
35779 environment. If \cmd{\nofiles} has not been specified a
35780 new empty \pixfile{aux} file is then created which has the side
35781 effect of destroying the original \pixfile{aux} file.
35782 \item Within the \Ie{document} environment there may be macros that write
35783 information to the \pixfile{aux} file, such as the sectioning or
35784 captioning commands. However, these macros will not write their
35785 information if \cmd{\nofiles} has been specified.
35786 \item At the end of the \Ie{document} environment the contents
35787 of the \pixfile{aux} file are read.
35788 \end{itemize}
35789 Under normal circumstances new output files are produced each time \ltx\
35790 is run, but when \cmd{\nofiles} is specified only the \pixfile{pdf} and
35791 \pixfile{log} files will be new --- any other files are unchanged.
35792
35793 In the case of the sectioning commands these write macros into the
35794 \pixfile{aux} file that in turn write information into a \pixfile{toc}
35795 file, and the \cmd{\tableofcontents} command reads the \pixfile{toc}
35796 file which contains the information for the Table of Contents. To make this
35797 a bit more concrete, as \ltx\ processes a new document through the
35798 first two runs, the following events occur.
35799 \begin{enumerate}
35800 \item Initially there is neither an \pixfile{aux} nor a \pixfile{toc} file.
35801 At the start of the \Ie{document} environment a new empty \pixfile{aux}
35802 file is created.
35803 \item During the first run the \cmd{\tableofcontents} typesets the
35804 Contents heading and creates a new empty \pixfile{toc}
35805 file.
35806
35807 During
35808 the run sectional commands write information into the new
35809 \pixfile{aux} file. At the end of the \Ie{document} environment
35810 the \pixfile{aux} file
35811 is read. Contents information in the \pixfile{aux} file is written
35812 to the \pixfile{toc} file. Lastly all the output files are closed.
35813
35814 \item For the second run the \pixfile{aux} file from the previous run is
35815 read at the start of the \Ie{document} environment; no information can
35816 be written to a \pixfile{toc} file because the \pixfile{toc} file
35817 is only made available by the \cmd{\tableofcontents} command.
35818 The \pixfile{aux} file from the previous run is closed and the new
35819 one for this run is created.
35820
35821 This time the \cmd{\tableofcontents} reads \pixfile{toc} file
35822 that was created during the previous run which contains the typesetting
35823 instructions for the contents, and then starts a
35824 new \pixfile{toc} file.
35825
35826 And so the process repeats itself.
35827 \end{enumerate}
35828
35829 The \pixfile{aux} file mechanism means that, except for the simplest
35830 of documents, \ltx\ has to be run at least
35831 twice in order to have all the information to hand for typesetting.
35832 If sections are added or deleted, two runs are necessary afterwards
35833 to ensure that everything is up to date. Sometimes three, or even more,
35834 runs are necessary to guarantee that things are settled.
35835
35836
35837
35838 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
35839
35840 % \fancybreak{}
35841
35842
35843 % \begin{Changed}[March 2025]
35844 % The rest of this chapter has been removed. It contained some low
35845 % level explanation about TeX programming, which is not really inside
35846 % the scope of this manual. Plus if was so low level that it should
35847 % not be used by \ltx\ users.
35848
35849 % If one really want to do some \ltx\ programming these days it
35850 % is probably better to use more high level tools.
35851 % \begin{itemize}
35852 % \item For some slightly advanced coding for user commands see the
35853 % manual (\cite{ETOOLBOX}) for \Lpack{etoolbox} (the package is
35854 % autoloaded by \theclass).
35855 % \item If you want to use the really impressive programming tools
35856 % contained in the modern \ltx\ kernel see \cite{EXPL3}, aka the
35857 % fabeled \ltx3 interfaces.\footnotemark\ Nowadays just referred to
35858 % as Expl3. It can be a bit daunting to get started with, but once
35859 % you understand it, there are a lot of build in tools that can
35860 % handle tasks that are hard to do in standard \ltx. A personal
35861 % favorite is \verb|\str_case_e:nn| which enables us to do
35862 % \setverbatimfont{\footnotesize\ttfamily}
35863 % \begin{verbatim}
35864 % \newcommand\settypeoutlayoutunit[1]{
35865 % \def\mem@tl@unit{#1}
35866 % \str_case_e:nnF{#1}{
35867 % {pt}{ \def\mem@tl@unitperpt{1.0} }
35868 % {pc}{ \def\mem@tl@unitperpt{0.083333} }
35869 % {in}{ \def\mem@tl@unitperpt{0.013837} }
35870 % {mm}{ \def\mem@tl@unitperpt{0.351459} }
35871 % {cm}{ \def\mem@tl@unitperpt{0.0351459} }
35872 % {bp}{ \def\mem@tl@unitperpt{0.996264} }
35873 % {dd}{ \def\mem@tl@unitperpt{0.9345718} }
35874 % {cc}{ \def\mem@tl@unitperpt{0.0778809} }
35875 % }{ % or error
35876 % \@memerror{Unknown~unit~'#1'~not~suitable~for~layout\MessageBreak listing}{}
35877 % }
35878 % }
35879 % \end{verbatim}
35880 % The original memoir version was 50+ lines of tests. Expl3 also
35881 % include tools to create data structures and loop through them etc.
35882 % \end{itemize}
35883 % \end{Changed}
35884 % \footnotetext{It was once the plan to do a version 3 of the \ltx\
35885 % format. As it would be hard to make users switch to a totally new
35886 % setup, the interface has instead been moved to the \ltx\ kernel.}
35887
35888
35889
35890
35891
35892
35893
35894 \section{Syntax}
35895
35896 The \ltx\ syntax that you normally see is pretty regular.
35897 Mandatory arguments are enclosed in curly braces and optional
35898 arguments are enclosed in square brackets. One exception to this
35899 rule is in the \Ie{picture} environment where coordinate and direction
35900 pairs are enclosed in parentheses.
35901
35902 The \tx\ syntax is not regular in the above sense. For example, if in
35903 \ltx\ you said
35904 \begin{lcode}
35905 \newcommand*{\cmd}[2]{#1 is no. #2 of}
35906 \cmd{M}{13} the alphabet. % prints: M is no. 13 of the alphabet
35907 \end{lcode}
35908 Then in \tx\ you would say
35909 \begin{lcode}
35910 \def\cmd#1#2{#1 is no. #2 of}
35911 \end{lcode}
35912 and you could then use either of the following calls:
35913 \begin{lcode}
35914 \cmd M{13} the alphabet. % prints: M is no. 13 of the alphabet
35915 \cmd{M}{13} the alphabet. % prints: M is no. 13 of the alphabet
35916 \end{lcode}
35917
35918 A simplistic explanation of the first \tx\ call of \verb?\cmd? is as
35919 follows. A control sequence starts with a backslash, followed by either
35920 a single character, or one or more of what \tx\ thinks of as letters
35921 (normally the 52 lower- and upper-case alphabetic characters);
35922 a space or any non-letter, therefore, ends a multiletter control
35923 sequence. \tx\ and \ltx\ discard any spaces after a macro name.
35924 If the macro takes any arguments, and \verb?\cmd? takes two, \tx\ will
35925 then start looking for the first argument. An argument is either
35926 something enclosed in braces or a single token. In the example the first
35927 token is the character `M', so that is the value of the first argument.
35928 \tx\ then looks for the second argument, which is the `13' enclosed
35929 in the braces. In the second example, both arguments are enclosed in braces.
35930
35931 Here are some \tx\ variations.
35932 \begin{lcode}
35933 \cmd B{2} the alphabet. % prints: B is no. 2 of the alphabet.
35934 \cmd B2 the alphabet. % prints: B is no. 2 of the alphabet.
35935 \cmd N14 the alphabet. % prints: N is no. 1 of4 the alphabet.
35936 \end{lcode}
35937 The result of \verb?\cmd B{2}? is as expected. The results of \verb?\cmd B2?
35938 and \verb?\cmd N14? should also be expected, and if not take a moment to
35939 ponder why. The `B' and 'N' are the first arguments to \verb?\cmd? in the
35940 two cases because a single character is a token. Having found the first
35941 argument \tx\ looks for the second one, which again will be a token as
35942 there are no braces. It will find `2' and `1' as the second arguments
35943 and will then expand the \verb?\cmd? macro. In the case of \verb?\cmd B2? this
35944 gives a reasonable result. In the case of \verb?\cmd N14?, \tx\ expands
35945 \verb?\cmd N1? to produce `N is in position 1 of', then continues printing
35946 the rest of the text, which is `4 the alphabet', hence the odd looking
35947 result.
35948
35949
35950 \section{\alltx{} commands} \label{sec:alltexcommands}
35951
35952 I have used some \tx\ commands in the example code and it is now time
35953 to describe these. Only enough explanation is given to cover my use of
35954 them. Full explanations would require a doubling in the size of the book
35955 and a concomitant increase in the price, so for full details consult
35956 the \textit{\txbook} which is the definitive source, or one of the \tx\
35957 manuals listed in the Bibliography. I find \textit{\tx\ by Topic}
35958 particularly helpful.
35959
35960 I have also used \ltx\ commands that are not mentioned by
35961 Lamport. \ltx\ uses a convention for command names; any name that
35962 includes the \texttt{@} character is an `internal' command and may be
35963 subject to change, or even deletion. Normal commands are meant to be
35964 stable --- the code implementing them may change but their effect will
35965 remain unaltered. In the \ltx\ kernel, and in class and package files
35966 the character \texttt{@} is automatically
35967 treated as a letter so it may be used as part of a command name.
35968 Anywhere else you have to use
35969 \cmd{\makeatletter} to make \texttt{@} be treated as a letter and
35970 \cmd{\makeatother} to make \texttt{@} revert to its other meaning.
35971 So, if you are defining or modifying or directly using any command
35972 that includes an \texttt{@}\idxatincode\
35973 sign then this must be done in either a \file{.sty} file or if in the
35974 document itself it must be surrounded by \cmd{\makeatletter} and
35975 \cmd{\makeatother}.
35976
35977 The implication is `don't use internal commands as they may be dangerous'.
35978 Climbing rocks is also dangerous but there are rock climbers; the live ones
35979 though don't try climbing Half Dome in Yosemite or the North Face of the
35980 Eiger without having first gained experience on friendlier rocks.
35981
35982 The \ltx\ kernel is full of internal commands and a few are mentioned
35983 in Lamport. There is no place where you can go to get explanations of all
35984 the \ltx\ commands, but if you run \ltx\ on the \pixfile{source2e.tex}
35985 file which is in the standard \ltx\ distribution you will get the commented
35986 kernel code. The index of the commands runs to about 40 double column pages.
35987 Each class and package introduce new commands over and above those in the
35988 kernel.
35989
35990
35991 \ltx\ includes \cmd{\newcommand}, \cmd{\providecommand} and
35992 \cmd{\renewcommand} as means of (re-)defining a command, but \tx\
35993 provides only one method.
35994 \begin{syntax}
35995 \cmd{\def}\meta{cmd}\meta{arg-spec}\marg{text} \\
35996 \end{syntax}
35997 \cmd{\def} specifies that within the local group\index{group}
35998 the command \verb?\cmd? is defined as \meta{text}, and any previous definitions
35999 of \meta{cmd} within the group are overwritten. Neither the
36000 \meta{text} nor any arguments can include an end-of-paragraph.
36001 The \ltx\ equivalent to \cmd{\def} is the pair of commands
36002 \cmd{\providecommand*} followed by \cmd{\renewcommand*}.
36003
36004 The \meta{arg-spec} is a list of the argument numbers
36005 (e.g., \verb?#1#2?)
36006 in sequential
36007 order, the list ending at the `\{' starting the \meta{text}. Any
36008 spaces or other characters in the argument list are significant. These
36009 must appear in the actual argument list when the macro is used.
36010
36011 \begin{syntax}
36012 \cmd{\long} \cmd{\global} \\
36013 \cmd{\gdef}\meta{cmd}\meta{arg-spec}\marg{text} \\
36014 \cmd{\edef}\meta{cmd}\meta{arg-spec}\marg{text} \\
36015 \cmd{\xdef}\meta{cmd}\meta{arg-spec}\marg{text} \\
36016 \end{syntax}
36017 If you use the \cmd{\long} qualifier before \cmd{\def} (as \verb?\long\def...?)
36018 then the \meta{text} and arguments may include paragraphs.
36019 The \ltx\ version of this is the unstarred \cmd{\providecommand}
36020 followed by \cmd{\renewcommand}.
36021
36022 To make a command global instead of local to the current group,
36023 the \cmd{\global} qualifier can be used with \cmd{\def}
36024 (as \verb?\global\def...?) when defining it;
36025 \cmd{\gdef} is provided as a shorthand for this common case.
36026
36027 Normally any macros within the replacement \meta{text} of a command
36028 defined by \cmd{\def} are expanded when the command is called.
36029 The macro \cmd{\edef} also defines a command but in this case any macros
36030 in the replacement \meta{text} are expanded when the command is defined.
36031 Both \cmd{\long} and \cmd{\global} may be used to qualify \cmd{\edef},
36032 and like \cmd{\gdef} being shorthand for \verb?\global\def?, \cmd{\xdef}
36033 is short for \verb?\global\edef?.
36034
36035 There is much more to the \cmd{\def} family of commands than I have
36036 given; consult elsewhere for all the gory details.
36037
36038 \begin{syntax}
36039 \cmd{\let}\meta{cmda}=\meta{cmdb} \\
36040 \end{syntax}
36041 The \cmd{\let} macro gives \meta{cmda} the same definition as \meta{cmdb}
36042 \emph{at the time the \cmd{\let} is called}. The \Itt{=} sign is optional.
36043 \cmd{\let} is often used when you want to save the definition of a
36044 command.
36045
36046 Here is a short example of how some of \cmd{\def} and \cmd{\let} work.
36047 \begin{lcode}
36048 \def\name{Alf}
36049 \let\fred = \name
36050 \name, \fred. % prints Alf, Alf.
36051 \def\name{Fred}
36052 \name, \fred. % prints Fred, Alf.
36053 \def\name{\fred red}
36054 \name, \fred. % prints Alfred, Alf.
36055 \end{lcode}
36056
36057 \begin{syntax}
36058 \cmd{\csname} \meta{string}\cmd{\endcsname} \\
36059 \end{syntax}
36060 If you have ever tried to define commands like \verb?\cmd1?, \verb?\cmd2? you will
36061 have found that it does not work. \tx\ command names consists of either
36062 a single character or a name composed solely of what \tx\ thinks
36063 of as alphabetic characters. However, the \cmd{\csname} \cmd{\endcsname}
36064 pair turn the enclosed \meta{string} into the control sequence \verb?\string?,
36065 which means that you can create \verb?\cmd1? by
36066 \begin{lcode}
36067 \csname cmd1\endcsname
36068 \end{lcode}
36069 Note that the resulting \verb?\cmd1? is not defined (as a macro).
36070
36071 \begin{syntax}
36072 \cmd{\@namedef}\marg{string} \\
36073 \cmd{\@nameuse}\marg{string} \\
36074 \end{syntax}
36075 The kernel \cmd{\@namedef} macro expands to \verb?\def\<string>?, where
36076 \meta{string} can contain any characters. You can use this to
36077 define commands that include non-alphabetic characters. There is
36078 the matching \cmd{\@nameuse} macro which expands to \verb?\<string>?
36079 which then lets you use command names that include non-alphabetic
36080 characters. For example:
36081 \begin{lcode}
36082 \@namedef{fred2}{Frederick~II}
36083 ...
36084 \makeatletter\@nameuse{fred2}\makeatother reigned from ...
36085 \end{lcode}
36086
36087 % \begin{comment}
36088
36089 % \ltx\ lets you create lengths via \cmd{\newlength}.
36090 % \begin{syntax}
36091 % \cmd{\newdimen}\meta{cmd} \\
36092 % \cmd{\newskip}\meta{cmd} \\
36093 % \end{syntax}
36094 % \tx\ has two kinds of lengths, called \emph{dimension}\index{dimension}
36095 % and \emph{glue}\index{glue}. In \ltx\ these are called
36096 % \emph{fixed length}\index{fixed length}\index{length!fixed}
36097 % and
36098 % \emph{rubber length}\index{rubber length}\index{length!rubber}
36099 % respectively. A new dimension is created by \cmd{\newdimen} and a new
36100 % glue by \cmd{\newskip}. It so happens that \ltx's \cmd{\newlength}
36101 % always creates a new skip --- all lengths are created as rubber lengths.
36102
36103 % To set a length in \ltx\ you can use any of
36104 % several commands, but \tx\ is more parsimonious.
36105 % \begin{syntax}
36106 % \meta{dimen} = \meta{length} \\
36107 % \meta{skip} = \meta{length} plus \meta{length} minus \meta{length} \\
36108 % \end{syntax}
36109 % A dimension is set by giving it a length, as in
36110 % \begin{lcode}
36111 % \mydimen = 20pt % or as the = is optional
36112 % \mydimen 20pt
36113 % \end{lcode}
36114 % A glue is also set by giving it a length, which is possibly followed
36115 % by \Itt{plus} a length optionally followed by \Itt{minus} a length.
36116 % \begin{lcode}
36117 % \myskip = 20pt plus 5pt minus 2pt
36118 % \end{lcode}
36119 % The actual length will normally be the first specified length, but
36120 % the value is allowed to be no shorter than the given length less
36121 % the \Itt{minus} length. The value is allowed, but only very reluctantly,
36122 % to be greater than the given length plus the \Itt{plus} length.
36123 % As in setting a dimension value the \Itt{=} sign is optional. In the example,
36124 % \verb?\myskip? can vary anywhere between 18pt and 25pt, but may possibly be
36125 % strained to be greater than 25pt.
36126
36127 % \begin{syntax}
36128 % \cmd{\@plus} \cmd{\@minus} \\
36129 % \end{syntax}
36130 % \ltx\ supplies \cmd{\@plus} and \cmd{\@minus} which expand to \Itt{plus}
36131 % and \Itt{minus} respectively. Writing \cmd{\@plus} instead of \Itt{plus}
36132 % uses one instead of four tokens, saving three tokens,
36133 % and \cmd{\@minus} in place of \Itt{minus}
36134 % saves four tokens --- remember that a \tx\ token is either a control
36135 % sequence (e.g. \cmd{\@minus}) or a single character (e.g., \verb?m?).
36136 % \tx's memory is not infinite --- it can only hold so many tokens --- and
36137 % it makes sense for kernel and class or package writers to use fewer
36138 % rather than more to leave sufficient space for any that authors might want
36139 % to create.
36140
36141 % \begin{syntax}
36142 % \cmd{\z@} \\
36143 % \Itt{fil} \Itt{fill} \Itt{filll} \\
36144 % \end{syntax}
36145 % \cmd{\z@} is a very useful \ltx\ command when specifying lengths.
36146 % Depending on the context it either stands for the number 0 (zero)
36147 % or 0pt (zero length). \tx\ has three kinds of infinitely stretchy
36148 % length units that can be used in the \Itt{plus} or \Itt{minus}
36149 % parts of a skip.
36150 % \Itt{fil} is infinitely more flexible than any fixed amount, but
36151 % \Itt{fill} is infitely more flexible than \Itt{fil} and \Itt{filll}
36152 % is infinitely more flexible than anything else at all. These infinite
36153 % glues can be used to push things around.
36154
36155 % \begin{syntax}
36156 % \cmd{\hskip}\meta{skip} \\
36157 % \cmd{\vskip}\meta{skip} \\
36158 % \end{syntax}
36159 % The \tx\ command \cmd{\hskip} inserts \meta{skip} horizontal space
36160 % and likewise \cmd{\vskip} inserts \meta{skip} vertical space.
36161
36162 % \begin{syntax}
36163 % \cmd{\hfil} \cmd{\hfill} \cmd{\hfilneg} \cmd{\hss} \\
36164 % \end{syntax}
36165 % These commands are all \tx\ primitives and are equivalent to horizontal
36166 % skips with some kind of infinite glue, as indicated below (note the use
36167 % of \Itt{fil} as a length unit, it being preceeded by a number):
36168 % \begin{lcode}
36169 % \hfil -> \hskip 0pt plus 1fil
36170 % \hfill -> \hskip 0pt plus 1fill
36171 % \hfilneg -> \hskip 0pt minus 1fil
36172 % \hss -> \hskip 0pt plus 1fil minus 1fil
36173 % \end{lcode}
36174
36175 % \begin{syntax}
36176 % \cmd{\vfil} \cmd{\vfill} \cmd{\vfilneg} \cmd{\vss} \\
36177 % \end{syntax}
36178 % These commands are all \tx\ primitives and are equivalent to vertical
36179 % skips with some kind of infinite glue, as indicated below:
36180 % \begin{lcode}
36181 % \vfil -> \vskip 0pt plus 1fil
36182 % \vfill -> \vskip 0pt plus 1fill
36183 % \vfilneg -> \vskip 0pt minus 1fil
36184 % \vss -> \vskip 0pt plus 1fil minus 1fil
36185 % \end{lcode}
36186
36187 % \end{comment}
36188
36189 At any point in its processing \tx\ is in one of six
36190 \emph{modes}\index{mode} which can be categorized into three groups:
36191 \begin{enumerate}
36192 \item horizontal and restricted
36193 horizontal;\index{horizontal mode}\index{mode!horizontal}\index{mode!restricted horizontal}
36194 \item vertical and internal
36195 vertical;\index{vertical mode}\index{mode!vertical}\index{mode!internal vertical}
36196 \item math and display
36197 math.\index{math mode}\index{mode!math}\index{mode!display math}
36198 \end{enumerate}
36199 More simply, \tx\ is in either horizontal, or vertical, or math mode.
36200 In horizontal mode \tx\ is typically building lines of text while in
36201 vertical mode it is typically stacking things on top of each other,
36202 like the lines making up a paragraph.
36203 Math gets complicated, and who can do with more complications
36204 at this stage of the game?
36205
36206 \begin{syntax}
36207 \cmd{\hbox} to \meta{dimen}\marg{text} \cmd{\hb@xt@}\meta{dimen}\marg{text} \\
36208 \cmd{\vbox} to \meta{dimen}\marg{text} \\
36209 \end{syntax}
36210 With \cmd{\hbox}, \meta{text} is put into a horizontal box, and similarly
36211 \cmd{\vbox} puts \meta{text} into a vertical box. The sizes of the boxes
36212 depend on the size of the \meta{text}. The optional
36213 \Itt{to}~\meta{dimen} phrase sets the size of the box to the fixed
36214 \meta{dimen} value. If the
36215 \meta{text} does not fit neatly inside a fixed size box then \tx\
36216 will report \Itt{overfull} or \Itt{underfull} warnings. \ltx\ supplies
36217 the \cmd{\hb@xt@} command as a shorthand for \cmd{\hbox}~\Itt{to}.
36218
36219 Inside a horizontal box \tx\ is in restricted horizontal
36220 mode\index{mode!horizontal}
36221 which means that everything in the box is aligned horizontally.
36222 Inside a vertical box \tx\ is in internal vertical
36223 mode\index{mode!vertical} and the contents are stacked up
36224 and aligned vertically.
36225
36226 \begin{syntax}
36227 \cmd{\dp}\meta{box} \cmd{\ht}\meta{box} \cmd{\wd}\meta{box} \\
36228 \end{syntax}
36229 The depth, height and width of a box are returned by the macros
36230 \cmd{\dp}, \cmd{\ht} and \cmd{\wd} respectively.
36231
36232 \begin{syntax}
36233 \cmd{\leavevmode} \\
36234 \end{syntax}
36235 \tx\ may be in either vertical or horizontal mode and there are
36236 things that can be done in one mode while \tx\ reports an eror if they
36237 are attempted in the other mode. When typesetting a paragraph \tx\
36238 is in horizontal mode. If \tx\ is in vertical mode, \cmd{\leavevmode}
36239 makes it switch to horizontal mode, but does nothing if \tx\ is already
36240 in horizontal mode. It is often used to make sure that \tx\ is in horizontal
36241 mode when it is unclear what state it might be in.
36242
36243 % \begin{comment}
36244
36245 % \tx\ has various \emph{conditional}\index{conditional}
36246 % constructs of the form:
36247 % \begin{lcode}
36248 % \if something-is-true
36249 % do-true-stuff
36250 % \else % something is not true (i.e. it is false)
36251 % do-false-stuff
36252 % \fi
36253 % \end{lcode}
36254 % In any of these constructs the \verb?\else do-false-stuff? phrase is
36255 % optional, and so is the \verb?do-true-stuff?.
36256
36257 % \begin{syntax}
36258 % \piif{ifodd} \meta{number} ... \piif{else} ... \piif{fi} \\
36259 % \end{syntax}
36260 % The command \piif{ifodd} tests whether \meta{number} is an odd number (true)
36261 % or an even number (false).
36262
36263 % \begin{syntax}
36264 % \piif{ifnum} \meta{numbera} \Itt{>} \meta{numberb} ... \piif{else} ... \piif{fi} \\
36265 % \piif{ifnum} \meta{numbera} \Itt{=} \meta{numberb} ... \piif{else} ... \piif{fi} \\
36266 % \piif{ifnum} \meta{numbera} \Itt{<} \meta{numberb} ... \piif{else} ... \piif{fi} \\
36267 % \end{syntax}
36268 % \piif{ifnum} tests if \meta{numbera} is greater than \Itt{>}, equal to
36269 % \Itt{=} or less than \Itt{<} \meta{numberb}.
36270 % There is a similar command, \piif{ifdim}, for comparing two lengths.
36271
36272 % \begin{syntax}
36273 % \cmd{\newif}\meta{ifcmd} \\
36274 % \end{syntax}
36275 % \cmd{\newif} creates a new conditional\index{conditional}, \meta{ifcmd}.
36276 % The \meta{ifcmd} must start with the three
36277 % characters \verb?\if?. Two other declarations are created at the same time.
36278 % These are called \verb?\cmdtrue? and \verb?\cmdfalse?.
36279 % Using \verb?\cmdtrue? sets the result of \verb?\ifcmd? to be true and
36280 % using \verb?\cmdfalse? sets the result of \verb?\ifcmd? to be false.
36281 % At creation time, \verb?\cmdfalse? is declared
36282 % so \verb?\ifcmd? is initially false. Here is an example.
36283 % \begin{lcode}
36284 % \newif\ifpeter
36285 % ...
36286 % \ifpeter
36287 % My name is Peter.
36288 % \else
36289 % Call me Ishmael.
36290 % \fi
36291 % \end{lcode}
36292
36293 % \end{comment}
36294
36295 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
36296 %%\input{program} % programming chapter \label{chap:program}
36297
36298 %% program.tex (La)TeX programming
36299
36300
36301 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
36302 %%\chapter{Calculation and programming} \label{chap:program}
36303 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
36304
36305 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
36306 \makeatletter
36307 \newcount\fib
36308 \newcount\fibprev
36309 \newcount\fibprevprev
36310 \newcount\fibtogo
36311
36312 \newcommand*{\fibseries}[1]{%
36313 \fibprevprev=1\relax
36314 \fibprev=1\relax
36315 \ifnum #1>0\relax
36316 \@fibseries{#1}%
36317 \fi}
36318
36319 \newcommand*{\gfibseries}[3]{%
36320 \fibprevprev=#1\relax
36321 \fibprev=#2\relax
36322 \ifnum #3>0\relax
36323 \@fibseries{#3}%
36324 \fi}
36325
36326 \newcommand*{\@fibseries}[1]{%
36327 \fibtogo=#1\relax
36328 \ifnum \fibtogo=1\relax
36329 \the\fibprevprev
36330 \else
36331 \ifnum \fibtogo=2\relax
36332 \the\fibprevprev{} and \the\fibprev
36333 \else
36334 \advance\fibtogo by -2\relax
36335 \the\fibprevprev, \the\fibprev
36336 \loop
36337 \@fibnext
36338 \ifnum \fibtogo>0\relax
36339 \repeat
36340 \fi
36341 \fi}
36342
36343 \newcommand*{\@fibnext}{%
36344 \fib=\fibprev
36345 \advance\fib by \fibprevprev
36346 \fibprevprev=\fibprev
36347 \fibprev=\fib
36348 \printfibterm
36349 \advance\fibtogo by -1\relax}
36350
36351 \newcommand*{\printfibterm}{%
36352 \ifnum \fibtogo=1\relax
36353 \space and \else , \fi
36354 \the\fib}
36355
36356 \renewcommand*{\@fibseries}[1]{%
36357 \fibtogo=#1\relax
36358 \ifcase \fibtogo % ignore 0
36359 \or % \fibtogo=1
36360 \the\fibprevprev
36361 \or % \fibtogo=2
36362 \the\fibprevprev{} and \the\fibprev
36363 \else % fibtogo > 2
36364 \advance\fibtogo by -\tw@
36365 \the\fibprevprev, \the\fibprev
36366 \@whilenum \fibtogo > 0\do {% % !!! must kill space after the {
36367 \@fibnext}%
36368 \fi}
36369
36370 \makeatother
36371 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%
36372
36373
36374 \section{Calculation}
36375
36376 \ltx\ provides some methods for manipulating numbers and these, of course,
36377 are composed from \tx's more basic methods. Sometimes it is
36378 useful to know what \tx\ itself provides. We have met most, if not all,
36379 of \ltx's macros earlier but I'll collect them all here for ease of reference.
36380
36381 \subsection{Numbers}
36382
36383 In \ltx\ a counter\index{counter} is used for storing an integer number.
36384 \begin{syntax}
36385 \cmd{\newcounter}\marg{counter} \\
36386 \cmd{\setcounter}\marg{counter}\marg{number} \\
36387 \cmd{\stepcounter}\marg{counter} \cmd{\refstepcounter}\marg{counter} \\
36388 \end{syntax}
36389 A new counter called \meta{counter}, without a backslash, is created using
36390 \cmd{\newcounter}. Its value can be set to a \meta{number} by the
36391 \cmd{\setcounter} command and \cmd{\stepcounter} increases its value by one.
36392 If the counter is to be used as the basis for a \cmd{\label}, its
36393 value must be set using \cmd{\refstepcounter}, neither \cmd{\stepcounter}
36394 nor \cmd{\setcounter} will work as expected in this case.
36395
36396 Internally, a \ltx\ \emph{counter} is represented by a \tx\
36397 \emph{count}\index{count} --- the \cmd{\newcounter} macro creates a
36398 \tx\ count named \cs{c@}\meta{counter}, and the other \cs{...counter}
36399 macros similarly operate on the \cs{c@}\meta{counter} count.
36400
36401
36402 \begin{syntax}
36403 \cmd{\newcount}\meta{count} \\
36404 \end{syntax}
36405 The \tx\ \cmd{\newcount} command creates a new count, \meta{count}, which
36406 \emph{does} include an initial backslash. For example
36407 \begin{lcode}
36408 \newcount\mycount
36409 \end{lcode}
36410 \tx's method of assigning a number to a count uses nothing like
36411 \cmd{\setcounter}.
36412 \begin{syntax}
36413 \meta{count} [ \texttt{=} ] \meta{number} \\
36414 \end{syntax}
36415 The [ and ] enclosing the \texttt{=} sign are there only
36416 to indicate that the \texttt{=} sign is optional. For example:
36417 \begin{lcode}
36418 \mycount = -24\relax % \mycount has the value -24
36419 \mycount 36\relax % now \mycount has the value 36
36420 \end{lcode}
36421 I have added \cmd{\relax} after the digits forming the number for safety
36422 and efficiency. When \tx\ is reading a number it keeps on looking until
36423 it comes across something that is not part of a number. There are things
36424 that \tx\ will treat as part of a number which you might not think of,
36425 but \cmd{\relax} is definitely not part of a number. See, for example,
36426 \cite[chapter 7]{TEXBYTOPIC} for all the intricate details if you need them.
36427
36428 There are some numbers that are used many times in the \ltx\ kernel
36429 and class codes. To save having to use \cmd{\relax} after such numbers,
36430 and for other reasons of efficiency, there are commands that can be used
36431 instead of typing the digits. These are listed in \tref{tab:intmacnum}.
36432 The command \cmd{\z@} can be used both for the number zero and for a
36433 length of 0pt. Do not use the commands to print a number.
36434
36435 \newcolumntype{A}{>{\makeatletter}r<{\makeatother}}
36436 \begin{table}
36437 \centering
36438 \caption{Some internal macros for numbers} \label{tab:intmacnum}
36439 \begin{tabular}{lrclrclr} \toprule
36440 \cmd{\m@ne} & \makeatletter\the\m@ne\makeatother & &
36441 %\cmd{\z@} & \makeatletter\strip@pt\the\z@\makeatother & &
36442 \cmd{\z@} & 0 & &
36443 \cmd{\@ne} & \makeatletter\the\@ne\makeatother \\
36444 \cmd{\tw@} & \makeatletter\the\tw@\makeatother & &
36445 \cmd{\thr@@} & \makeatletter\the\thr@@\makeatother & &
36446 \cmd{\sixt@@n} & \makeatletter\the\sixt@@n\makeatother \\
36447 \cmd{\@xxxii} & \makeatletter\the\@xxxii\makeatother & &
36448 \cmd{\@cclv} & \makeatletter\the\@cclv\makeatother & &
36449 \cmd{\@cclvi} & \makeatletter\the\@cclvi\makeatother \\
36450 \cmd{\@m} & \makeatletter\the\@m\makeatother & &
36451 \cmd{\@Mi} & \makeatletter\the\@Mi\makeatother & &
36452 \cmd{\@Mii} & \makeatletter\the\@Mii\makeatother \\
36453 \cmd{\@Miii} & \makeatletter\the\@Miii\makeatother & &
36454 \cmd{\@Miv} & \makeatletter\the\@Miv\makeatother & &
36455 \cmd{\@MM} & \makeatletter\the\@MM\makeatother \\
36456 \bottomrule
36457 \end{tabular}
36458 \end{table}
36459
36460
36461 \tx\ has a limited vocabulary for arithmetic. It can add to a count,
36462 and can multiply and divide a count, but only by integers. The result
36463 is always an integer. This may be disconcerting after a division where
36464 any remainder is discarded.
36465 The syntax for these operations is:
36466 \begin{syntax}
36467 \cmd{\advance}\meta{count} [ \pixkey{by} ] \meta{number} \\
36468 \cmd{\multiply}\meta{count} [ \pixkey{by} ] \meta{number} \\
36469 \cmd{\divide}\meta{count} [ \pixkey{by} ] \meta{number} \\
36470 \end{syntax}
36471 The \pixkey{by} is a \tx\ keyword and the brackets are
36472 just there
36473 to indicate that it can be missed out. Some examples:
36474 \begin{lcode}
36475 \advance\mycount by -\mycount % \mycount is now 0
36476 \mycount = 15\relax % \mycount is now 15
36477 \divide\mycount by 4\relax % \mycount is now 3
36478 \multiply\mycount 4\relax % \mycount is now 12
36479 \advance\mycount by \yourcount % \mycount is now \yourcount + 12
36480 \end{lcode}
36481
36482 The value of a count can be typeset by prepending the count by the \cmd{\the}
36483 command, e.g., \verb?\the\mycount?.
36484
36485
36486 \subsection{Lengths}
36487
36488 Every length\index{length} has an associated unit. For convenience I'll use
36489 `\textit{dimension}'\index{dimension} as shorthand for a number and a length
36490 unit.
36491 \begin{syntax}
36492 \textit{dimension}: \meta{number}\meta{length-unit} \\
36493 \end{syntax}
36494 For example, a \textit{dimension} may be \texttt{10pt}, or \texttt{23mm},
36495 or \texttt{1.3pc}.
36496
36497 Unlike \ltx, \tx\ distinguishes two kinds of lengths. A \tx\
36498 \cmd{\dimen} is a length that is fixed; in \ltx's terms it is a
36499 \emph{rigid}\index{length!rigid} length. On the other hand a \tx\ \cmd{\skip}
36500 is a length that may stretch or shrink a little; it is what \ltx\ calls
36501 a \emph{rubber}\index{length!rubber} length.
36502 \begin{syntax}
36503 \cmd{\newdimen}\meta{dimen} \cmd{\newskip}\meta{skip} \\
36504 \end{syntax}
36505 The \tx\ macros \cmd{\newdimen} and \cmd{\newskip} are used for creating
36506 a new \meta{dimen} or a new \meta{skip}. For instance:
36507 \begin{lcode}
36508 \newdimen\mydimen
36509 \newskip\myskip
36510 \end{lcode}
36511 The value of a \cmd{\dimen} is a \textit{dimension} and the value of a
36512 \cmd{\skip} is what \tx\ calls \textit{glue}\index{glue}. It
36513 so happens that \ltx's \cmd{\newlength} always creates a new skip ---
36514 all \ltx\ lengths are created as rubber\index{length!rubber} lengths. Glue
36515 has at least one and possibly as many as three parts.
36516 \begin{syntax}
36517 glue: \textit{dimension} [ \pixkey{plus} \textit{dimension} ] [ \pixkey{minus} \textit{dimension} ] \\
36518 \end{syntax}
36519 The optional \pixkey{plus} part is the amount that the glue can
36520 stretch from its normal size and the optional \pixkey{minus} part
36521 is the amount the glue can shrink below its normal size.
36522 Both \pixkey{plus} and \pixkey{minus} are \tx\ keywords.
36523 Glue can never shrink more than the \pixkey{minus}
36524 \textit{dimension} and it normally does not stretch more than the
36525 \pixkey{plus} \textit{dimension}.
36526
36527 \begin{syntax}
36528 \cmd{\@plus} \cmd{\@minus} \\
36529 \end{syntax}
36530 \ltx\ supplies \cmd{\@plus} and \cmd{\@minus} which expand to \Itt{plus}
36531 and \Itt{minus} respectively. Writing \cmd{\@plus} instead of \Itt{plus}
36532 uses one instead of four tokens, saving three tokens,
36533 and \cmd{\@minus} in place of \Itt{minus}
36534 saves four tokens --- remember that a \tx\ token is either a control
36535 sequence (e.g. \cmd{\@minus}) or a single character (e.g., \verb?m?).
36536 \tx's memory is not infinite --- it can only hold so many tokens --- and
36537 it makes sense for kernel and class or package writers to use fewer
36538 rather than more to leave sufficient space for any that authors might want
36539 to create.
36540
36541 In \tx, assigning a value to a length (\cmd{\dimen} or \cmd{\skip}) is
36542 rather different from the way it would be done in \ltx.
36543 \begin{syntax}
36544 \meta{dimen} [ \texttt{=} ] \meta{dimension} \\
36545 \meta{skip} [ \texttt{=} ] \meta{glue} \\
36546 \end{syntax}
36547 The [ and ] enclosing the \texttt{=} sign are there only
36548 to indicate that the \texttt{=} sign is optional. For example:
36549 \begin{lcode}
36550 \newdimen\mydimen
36551 \mydimen = 3pt % \mydimen has the value 3pt
36552 \mydimen -13pt % now \mydimen has the value -13pt
36553 \myskip = 10pt plus 3pt minus 2pt % \myskip can vary between
36554 % 8pt and 13pt (or more)
36555 \myskip = 10pt plus 3pt % \myskip can vary between
36556 % 10pt and 13pt (or more)
36557 \myskip = 10pt minus 2pt % \myskip can vary between
36558 % 8pt and 10pt
36559 \myskip = 10pt % \myskip is fixed at 10pt
36560 \end{lcode}
36561
36562 Like counts, the value of a length can be typeset by prepending the
36563 length by the \cmd{\the} command, e.g., \verb?\the\myskip?.
36564
36565 \tx's lengths can be manipulated in the same way as a count, using the
36566 \cmd{\advance}, \cmd{\multiply} and \cmd{\divide} macros. Ignoring some
36567 details, lengths can be added together but may only be multiplied or divided
36568 by an integer number.
36569
36570
36571 \newdimen\Wdimen \newskip\Wskip
36572
36573 \begin{center}
36574 \begin{tabular}{l}
36575 $\rhd$ \verb?\Wdimen = 10pt? $\Rightarrow$ \\
36576 \multicolumn{1}{r}{\global\Wdimen = 10pt \texttt{Wdimen} = \the\Wdimen} \\
36577 $\rhd$ \verb?\Wskip = 15pt plus 5pt minus 3pt? $\Rightarrow$ \\
36578 \multicolumn{1}{r}{ \global\Wskip = 15pt plus 5pt minus 3pt \texttt{Wskip} = \the\Wskip} \\
36579 $\rhd$ \verb?\advance\Wskip by \Wskip? $\Rightarrow$ \\
36580 \multicolumn{1}{r}{\global\advance\Wskip by \Wskip \texttt{Wskip} = \the\Wskip} \\
36581 $\rhd$ \verb?\multiply\Wskip by 3? $\Rightarrow$ \\
36582 \multicolumn{1}{r}{\global\multiply\Wskip by 3 \texttt{Wskip} = \the\Wskip} \\
36583 $\rhd$ \verb?\divide\Wskip by 17? $\Rightarrow$ \\
36584 \multicolumn{1}{r}{\global\divide\Wskip by 17 \texttt{Wskip} = \the\Wskip} \\
36585 $\rhd$ \verb?\advance\Wskip by \Wdimen? $\Rightarrow$ \\
36586 \multicolumn{1}{r}{\global\advance\Wskip by \Wdimen \texttt{Wskip} = \the\Wskip} \\
36587 $\rhd$ \verb?\advance\Wdimen by \Wskip? $\Rightarrow$ \\
36588 \multicolumn{1}{r}{\global\advance\Wdimen by \Wskip \texttt{Wdimen} = \the\Wdimen} \\
36589 \end{tabular}
36590 \end{center}
36591
36592 A length can be multiplied by a fractional number by prepending the
36593 length with the number. For example:
36594
36595 \begin{center}
36596 \begin{tabular}{l}
36597 $\rhd$ \verb?\Wdimen = 0.5\Wdimen? $\Rightarrow$ \\
36598 \multicolumn{1}{r}{\Wdimen = 0.5\Wdimen \texttt{Wdimen} = \the\Wdimen } \\
36599 $\rhd$ \verb?\Wskip = 0.5\Wskip? $\Rightarrow$ \\
36600 \multicolumn{1}{r}{\Wskip = 0.5\Wskip \texttt{Wskip} = \the\Wskip} \\
36601 \end{tabular}
36602 \end{center}
36603
36604 When \cmd{\multiply} or \cmd{\divide} is applied to a \cmd{\skip}
36605 all its parts are modified, both the fixed part and any elastic components.
36606 However, if a \cmd{\skip} is multiplied by a fractional number then it
36607 loses any elasticity it might have had. In the same vein,
36608 if a \cmd{\skip} is added to a \cmd{\dimen} any elasticity is lost.
36609 A \cmd{\skip} can be coerced into behaving like a \cmd{\dimen} but a
36610 \cmd{\dimen} is always rigid. For example, typing \\
36611 `\verb?\Wdimen = 10pt plus 2pt minus 1pt?' results in:
36612 `\Wdimen = 10pt plus 2pt minus 1pt'.
36613
36614 \begin{syntax}
36615 \cmd{\newlength}\marg{len} \\
36616 \end{syntax}
36617 \ltx's \cmd{\newlength} macro creates a new
36618 rubber length\index{length!rubber} (internally it uses \cmd{\newskip});
36619 there is no \ltx\ specific macro to create a rigid length\index{length!rigid}
36620 (i.e., a \cmd{\dimen}).
36621
36622 \ltx\ has a variety of macros for setting or changing its length values.
36623 \begin{syntax}
36624 \cmd{\setlength}\marg{len}\marg{glue} \\
36625 \end{syntax}
36626 The \ltx\ \cmd{\setlength} macro assigns the value \meta{glue} to the
36627 rubber length \meta{len}.
36628 Some examples of this are: \newlength{\Wlen}
36629
36630 \begin{center}
36631 \begin{tabular}{l}
36632 $\rhd$ \verb?\setlength{\Wlen}{10pt}? $\Rightarrow$ \\
36633 \multicolumn{1}{r}{\setlength{\Wlen}{10pt} \texttt{Wlen} = \the\Wlen} \\
36634 $\rhd$ \verb?\setlength{\Wlen}{10pt plus 2pt}? $ \Rightarrow $ \\
36635 \multicolumn{1}{r}{\setlength{\Wlen}{10pt plus 2pt} \texttt{Wlen} = \the\Wlen} \\
36636 $\rhd$ \verb?\setlength{\Wlen}{10pt minus 1pt}? $ \Rightarrow $ \\
36637 \multicolumn{1}{r}{\setlength{\Wlen}{10pt minus 1pt} \texttt{Wlen} = \the\Wlen} \\
36638 $\rhd$ \verb?\setlength{\Wlen}{10mm plus 2pt minus 1pt}? $ \Rightarrow $ \\
36639 \multicolumn{1}{r}{\setlength{\Wlen}{10mm plus 2pt minus 1pt} \texttt{Wlen} = \the\Wlen} \\
36640 \end{tabular}
36641 \end{center}
36642
36643 As shown in the last example above where both mm and pt are used as a
36644 length unit, the \cmd{\the} applied to a length always prints the value
36645 in pt units.
36646
36647 \begin{syntax}
36648 \cmd{\settowidth}\marg{len}\marg{text} \\
36649 \cmd{\settoheight}\marg{len}\marg{text} \\
36650 \cmd{\settodepth}\marg{len}\marg{text} \\
36651 \end{syntax}
36652 These put the \meta{text} into a box and then set the \meta{len} to the
36653 width, height and depth respectively of the box.
36654
36655 \begin{syntax}
36656 \cmd{\addtolength}\marg{len}\marg{glue} \\
36657 \end{syntax}
36658 \ltx's \cmd{\addtolength} macro is the equivalent of \tx's \cmd{\advance}
36659 command. There are no equivalents to \tx's \cmd{\multiply} or \cmd{\divide}
36660 but in any case a length can still be multiplied by prepending it with
36661 a fractional number.
36662
36663
36664 \begin{syntax}
36665 \cmd{\z@} \\
36666 \Itt{fil} \Itt{fill} \Itt{filll} \\
36667 \end{syntax}
36668 \cmd{\z@} is a very useful \ltx\ command when specifying lengths.
36669 Depending on the context it either stands for the number 0 (zero)
36670 or 0pt (zero length). \tx\ has three kinds of infinitely stretchy
36671 length units that can be used in the \Itt{plus} or \Itt{minus}
36672 parts of a skip.
36673 \Itt{fil} is infinitely more flexible than any fixed amount, but
36674 \Itt{fill} is infitely more flexible than \Itt{fil} and \Itt{filll}
36675 is infinitely more flexible than anything else at all. These infinite
36676 glues can be used to push things around.
36677
36678 \begin{syntax}
36679 \cmd{\hskip}\meta{skip} \\
36680 \cmd{\vskip}\meta{skip} \\
36681 \end{syntax}
36682 The \tx\ command \cmd{\hskip} inserts \meta{skip} horizontal space
36683 and likewise \cmd{\vskip} inserts \meta{skip} vertical space.
36684
36685 \begin{syntax}
36686 \cmd{\hfil} \cmd{\hfill} \cmd{\hfilneg} \cmd{\hss} \\
36687 \end{syntax}
36688 These commands are all \tx\ primitives and are equivalent to horizontal
36689 skips with some kind of infinite glue, as indicated below (note the use
36690 of \Itt{fil} as a length unit, it being preceeded by a number):
36691 \begin{lcode}
36692 \hfil -> \hskip 0pt plus 1fil
36693 \hfill -> \hskip 0pt plus 1fill
36694 \hfilneg -> \hskip 0pt minus 1fil
36695 \hss -> \hskip 0pt plus 1fil minus 1fil
36696 \end{lcode}
36697
36698 \begin{syntax}
36699 \cmd{\vfil} \cmd{\vfill} \cmd{\vfilneg} \cmd{\vss} \\
36700 \end{syntax}
36701 These commands are all \tx\ primitives and are equivalent to vertical
36702 skips with some kind of infinite glue, as indicated below:
36703 \begin{lcode}
36704 \vfil -> \vskip 0pt plus 1fil
36705 \vfill -> \vskip 0pt plus 1fill
36706 \vfilneg -> \vskip 0pt minus 1fil
36707 \vss -> \vskip 0pt plus 1fil minus 1fil
36708 \end{lcode}
36709
36710
36711
36712 \section{Programming}
36713
36714
36715
36716 One of the commonest programming operations is to possibly do one thing if
36717 something is true and to possibly do another thing if it is not true. Generally
36718 speaking, this is called an `if-then-else'\index{if-then-else} or
36719 \emph{conditional}\index{conditional} statement.
36720
36721 \begin{syntax}
36722 \cs{if...} \meta{test} \meta{true-text} [ \piif{else} \meta{false-text} ] \piif{fi} \\
36723 \end{syntax}
36724 \tx\ has several kinds of `if-then-else' statements which have the general
36725 form shown above. The statement starts with an \cs{if...} and is finished
36726 by a matching \piif{fi}. As usual, the brackets enclose optional elements,
36727 so there need be no \cs{else} portion. The \meta{true-text}, it it exists,
36728 is processed if the \meta{test} is \ptrue\ otherwise the
36729 \meta{false-text}, if both the \piif{else} clause and \meta{false-text}
36730 are present, is processed.
36731
36732 The simplest kind of \cs{if...}
36733 is defined by the \cmd{\newif} macro.
36734 \begin{syntax}
36735 \cmd{\newif}\verb?\if?\meta{name} \\
36736 \end{syntax}
36737 \cmd{\newif} creates three new commands, the \cs{ifname} and the
36738 two declarations, \cs{nametrue} and \cs{namefalse}, for setting the value
36739 of \cs{ifname} to \ptrue\ or \pfalse\ respectively.
36740 In this case the \meta{test} is embedded in the \cs{if...}.
36741 For example:
36742 \begin{lcode}
36743 \newif\ifpeter
36744 ...
36745 \ifpeter
36746 My name is Peter.
36747 \else
36748 Call me Ishmael.
36749 \fi
36750 \end{lcode}
36751 or a more likely scenario is
36752 \begin{lcode}
36753 \newif\ifmine
36754 \minetrue % or \minefalse
36755 \newcommand{\whose}{%
36756 \ifmine It's mine. \else I don't know whose it is. \fi}
36757 \end{lcode}
36758
36759 Here are some of the other more commonly used kinds of ifs.
36760 \begin{syntax}
36761 \piif{ifdim} \meta{dimen1} \meta{rel} \meta{dimen2} \\
36762 \piif{ifnum} \meta{number1} \meta{rel} \meta{number2} \\
36763 \piif{ifodd} \meta{number} \\
36764 \end{syntax}
36765 The \meta{rel} in \piif{ifnum} and \piif{ifdim} is one of the three characters:
36766 \texttt{<} (less than), \texttt{=} (equals), or \texttt{>} (greater than).
36767 \piif{ifdim} results in \ptrue\ if the two lengths are in the stated
36768 relationship otherwise it results in \pfalse. Similarly \piif{ifnum}
36769 is for the comparison of two integers. The \piif{ifodd} test is \ptrue\
36770 if the integer \meta{number} is an odd number, otherwise it results
36771 in \pfalse.
36772
36773 Among other things, the \ltx\ class code that organizes the page layout
36774 checks if the length values are sensible. The following code is a snippet
36775 from the layout algorithm. It checks that the sum of the margins and the
36776 width of the typeblock is the same as the width of the page after trimming.
36777 \cmd{\@tempdima} and \cmd{\@tempdimb} are two `scratch' lengths used in many
36778 calculations.
36779 \begin{lcode}
36780 \@tempdimb= -1pt % allow a difference of 1pt
36781 \@tempdima=\paperwidth % paperwidth
36782 \advance\@tempdima by -\foremargin % minus the foremargin
36783 \advance\@tempdima -\textwidth % minus the textwidth
36784 \advance\@tempdima -\spinemargin % minus the spinemargin
36785 \ifdim\@tempdima < \@tempdimb % should be close to zero
36786 %% error % otherwise a problem
36787 \fi
36788 \end{lcode}
36789
36790 Changing the subject, on the offchance that you might want to see
36791 how the Fibonacci sequence
36792 progresses, the first thirty numbers in the sequence are:
36793 \fibseries{30}.
36794 I got \ltx\ to calculate those numbers for me, and it could have
36795 calculated many more. They were produced by just saying \verb?\fibseries{30}?.
36796 The French mathematician
36797 \'{E}douard Lucas\index{Lucas, Edouard?Lucas, \'{E}douard}
36798 (1842--1891) studied sequences
36799 like this and was the one to give it the name Fibonacci. Lucas also
36800 invented the game called the Tower of Hanoi with
36801 Henri de Parville\protect\index{Parville, Henri?de Parville, Henri} (1838--1909),
36802 supplying the accompanying fable~\cite{PARVILLE84,ROUSEBALL}:
36803 \begin{quotation}
36804 In the great temple at Benares beneath the dome that marks the center of
36805 the world, rests a brass plate in which are fixed three diamond needles,
36806 each a cubit high and as thick as the body of a bee. On one of these
36807 needles, at the creation, God placed sixty-four discs of pure gold, the
36808 largest disc resting on the brass plate, and the others getting smaller
36809 and smaller up to the top one. This is the tower of Bramah. Day and night
36810 unceasingly the priests transfer the discs from one diamond needle to
36811 another according to the fixed and immutable laws of Bramah, which require
36812 that the priest on duty must not move more than one disc at a time and
36813 that he must place this disc on a needle so that there is no smaller disc
36814 below. When the sixty-four discs shall have been thus transferred from the
36815 needle which at creation God placed them, to one of the other needles,
36816 tower, temple, and Brahmins alike will crumble into dust and with a
36817 thunderclap the world will vanish.
36818 \end{quotation}
36819
36820 The number of separate transfers of single discs is $2^{64} - 1$
36821 or just under eighteen and a half million million moves, give or take a few,
36822 to move the pile. At the rate of one disc per second, with no mistakes,
36823 it would take more than 58 million million years before we would have to
36824 start being concerned.
36825
36826 In his turn, Lucas has a number sequence named after him. There are many
36827 relationships between the Fibonacci
36828 numbers $F_{n}$ and the Lucas numbers $L_{n}$, the simplest, perhaps, being
36829 \begin{eqnarray}
36830 L_{n} & = & F_{n-1} + F_{n+1} \\
36831 5F_{n} & = & L_{n-1} + L_{n+1}
36832 \end{eqnarray}
36833 The first 15 numbers in the Lucas sequence are:
36834 \gfibseries{2}{1}{15}. These were produced by saying
36835 \verb?\gfibseries{2}{1}{15}?. The Lucas numbers are produced in the same manner
36836 as the Fibonacci numbers, it's just the starting pairs that differ.
36837
36838 However, it is the definition of the \cmd{\fibseries} and \cmd{\gfibseries}
36839 macros that might be more interesting in this context.
36840
36841 First, create four new counts. \cs{fibtogo} is the number of terms to be
36842 calculated, \cs{fib} is the current term, and \cs{fibprev} and \cs{fibprevprev}
36843 are the two prior terms.
36844 \begin{lcode}
36845 \newcount\fib
36846 \newcount\fibprev
36847 \newcount\fibprevprev
36848 \newcount\fibtogo
36849 \end{lcode}
36850 The argument to \cmd{\fibseries} is the number of terms. The counts
36851 \cs{fibprevprev} and \cs{fibprev} are set to the starting pair in the sequence.
36852 Provided the number of terms requested is one or more the macro
36853 \cmd{\@fibseries} is called to do the work.
36854 \begin{lcode}
36855 \newcommand*{\fibseries}[1]{%
36856 \fibprevprev=1\relax
36857 \fibprev=1\relax
36858 \ifnum #1>0\relax
36859 \@fibseries{#1}%
36860 \fi}
36861 \end{lcode}
36862
36863 The macro \cmd{\@fibseries} calculates and prints the terms.
36864 \begin{lcode}
36865 \newcommand*{\@fibseries}[1]{%
36866 \fibtogo=#1\relax
36867 \end{lcode}
36868 It's simple if no more than two terms have been asked for --- just print
36869 them out.
36870 \begin{lcode}
36871 \ifnum \fibtogo=\@ne
36872 \the\fibprevprev
36873 \else
36874 \ifnum \fibtogo=\tw@
36875 \the\fibprevprev{} and \the\fibprev
36876 \else
36877 \end{lcode}
36878 Three or more terms have to be calculated. We reduce the number to be
36879 calculated by 2, and print the first two terms.
36880 \begin{lcode}
36881 \advance\fibtogo by -\tw@
36882 \the\fibprevprev, \the\fibprev
36883 \end{lcode}
36884 We now have to calculate the rest of the terms, where each term is the sum of
36885 the two previous terms.
36886 The macro \cmd{\@fibnext} calculates the next term, prints it out and reduces
36887 the number of terms left to be calculated (\cmd{\fibtogo}) by one.
36888 If there are terms left to be done then the process is repeated until
36889 they have all been printed.
36890 \begin{lcode}
36891 \loop
36892 \@fibnext
36893 \ifnum \fibtogo>\z@
36894 \repeat
36895 \fi
36896 \fi}
36897 \end{lcode}
36898
36899 The \cmd{\@fibnext} macro calculates a term in the series, uses
36900 \cmd{\printfibterm} to print it, and decrements the \cmd{\fibtogo} count.
36901 \begin{lcode}
36902 \newcommand*{\@fibnext}{%
36903 \fib=\fibprev
36904 \advance\fib by \fibprevprev
36905 \fibprevprev=\fibprev
36906 \fibprev=\fib
36907 \printfibterm
36908 \advance\fibtogo \m@ne}
36909 \end{lcode}
36910
36911 The last of the macros, \cmd{\printfibterm}, typesets a term in the sequence.
36912 If the term is the last one print an `and' otherwise print a `,',
36913 then a space and the term.
36914 \begin{lcode}
36915 \newcommand*{\printfibterm}{%
36916 \ifnum \fibtogo=\@ne \space and \else , \fi
36917 \the\fib}
36918 \end{lcode}
36919
36920 You have met all of the macros used in this code except for \tx's
36921 \piif{loop} construct. I find the syntax for this a little unusual.
36922 \begin{syntax}
36923 \piif{loop} \meta{text1} \cs{if...} \meta{text2} \piif{repeat} \\
36924 \end{syntax}
36925 The construct starts with \piif{loop} and is ended by \piif{repeat};
36926 the \cs{if...} is any conditional test, but without the closing \piif{fi}.
36927 \tx\ processes \meta{text1}, then if the \cs{if...} is \ptrue\
36928 it processes \meta{text2} and repeats the sequence again starting
36929 with \meta{text1}. On the other hand, as soon as the result of the
36930 \cs{if...} is
36931 \pfalse\ the loop stops (i.e., \tx\ jumps over \meta{text2}
36932 and goes on to do whatever is after the \piif{repeat}).
36933
36934 The \cmd{\gfibseries} macro that I used for the Lucas numbers is a
36935 generalisation of \cmd{\fibseries}, where the first two arguments are the
36936 starting pair for the sequence and the third argument is the number
36937 of terms; so \verb?\gfibseries{1}{1}{...}? is equivalent to
36938 \verb?\fibseries{...}?.
36939 \begin{lcode}
36940 \newcommand*{\gfibseries}[3]{%
36941 \fibprevprev=#1\relax
36942 \fibprev=#2\relax
36943 \ifnum #3>0\relax
36944 \@fibseries{#3}%
36945 \fi}
36946 \end{lcode}
36947 The calculation of the terms in the Fibonacci and in the generalised
36948 sequences is the same so \cmd{\@fibseries} can be used again.
36949
36950 I used the \tx\ \piif{loop} construct in the \cmd{\@fibseries} macro
36951 but \ltx\ has a similar construct.
36952 \begin{syntax}
36953 \cmd{\@whilenum} \meta{ifnum test} \cmd{\do} \marg{body} \\
36954 \cmd{\@whiledim} \meta{ifdim test} \cmd{\do} \marg{body} \\
36955 \end{syntax}
36956 As long as the appropriate \meta{test} is \ptrue\ the \meta{body} is processed.
36957
36958 In \cmd{\@fibseries} I used \cs{ifnum}s to check for 3 possible values.
36959 There is another \cs{if...} form that can be used for this type of work.
36960 \begin{syntax}
36961 \piif{ifcase} \meta{number} \meta{text for 0} \piif{or} \meta{text for 1}
36962 \piif{or} \meta{text for 2} \\
36963 ... \\
36964 \piif{or} \meta{text for N} [ \piif{else} \meta{text for anything else} ] \piif{fi} \\
36965 \end{syntax}
36966 If the \meta{number} is 0 then \meta{text for 0} is processed, but if
36967 \meta{number} is 1 then \meta{text for 1} is processed, but if \meta{number}
36968 is \ldots Each \meta{text for ...} is separated by an \piif{or}. If \meta{number}
36969 is anything other than the specified cases (i.e., less than zero or greater
36970 than N) then if the \piif{else} is present \meta{text for anything else} is
36971 processed.
36972
36973 Here's another version of the \cmd{\@fibseries} macro using \piif{ifcase}
36974 and \cmd{\@whilenum}.
36975 \begin{lcode}
36976 \renewcommand*{\@fibseries}[1]{%
36977 \fibtogo=#1\relax
36978 \ifcase \fibtogo % ignore 0
36979 \or % \fibtogo=1
36980 \the\fibprevprev
36981 \or % \fibtogo=2
36982 \the\fibprevprev{} and \the\fibprev
36983 \else % fibtogo > 2
36984 \advance\fibtogo by -\tw@
36985 \the\fibprevprev, \the\fibprev
36986 \@whilenum \fibtogo > \z@ \do {% must kill space after the {
36987 \@fibnext}%
36988 \fi}
36989 \end{lcode}
36990
36991 \tx\ has more programing constructs than I have shown here and these
36992 will be explained in any good \tx\ book. \ltx\ also has more than I have shown
36993 but in this case the best place to look for further information is in the
36994 \ltx\ kernel code, for example in \file{ltcntrl.dtx}.
36995
36996 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
36997 %%%%%%%\endinput
36998 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
36999
37000
37001 %#% extend
37002 %#% extstart include the-terrors-of-errors.tex
37003
37004 \svnidlong
37005 {$Ignore: $}
37006 {$LastChangedDate: 2025-03-06 13:42:47 +0100 (Thu, 06 Mar 2025) $}
37007 {$LastChangedRevision: 834 $}
37008 {$LastChangedBy: [email protected] $}
37009
37010
37011 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
37012
37013 %%\input{merrors} % errors chapter \label{chap:errors}
37014
37015 % merrors.tex Chapter on (La)TeX errors/warnings
37016
37017
37018 \chapter{The terrors of errors} \label{chap:errors}
37019
37020 No matter how conscientious you are a mistake or two will occasionally
37021 creep into your document source. The good news is that whatever happens
37022 \tx\ will not destroy your files --- it may produce some odd looking output,
37023 or even no output at all, but your work is safe. The bad news is that you
37024 have to correct any errors that \tx\ finds. To assist you in this \tx\ stops
37025 whenever it comes across what it thinks is an error\index{error}
37026 and tells you about it.
37027 If you're not sure what to do it will also provide some possibly helpful
37028 advice.
37029
37030 \tx\ underlies \ltx\ which underlies classes and packages. You may get
37031 messages than originate from \tx, or from \ltx, or from the class and any
37032 packages you may be using. I'll describe the \tx, \ltx, and class messages
37033 below.
37034
37035 In general, you will see a message\index{error message!response}
37036 on your terminal and \ltx\ will
37037 stop and wait for you to respond. It prints a question mark and is
37038 expecting you to type one of the following:
37039 \begin{itemize}
37040 \item \meta{return} (or \meta{enter} or what is the equivalent on your
37041 keyboard): \ltx\ will continue\index{error message!response!continue}
37042 processing the document.
37043 \item \texttt{H} (help): the help\index{error message!response!help}
37044 message is output and \ltx\
37045 waits for you to respond again.
37046 \item \texttt{S} (scroll): Continue\index{error message!response!scroll}
37047 processing, outputting any
37048 further error messages, but not stopping.
37049 \item \texttt{Q} (quiet): Continue\index{error message!response!quiet}
37050 processing without stopping
37051 and with no further messages.
37052 \item \texttt{R} (run): Like\index{error message!response!run}
37053 the \texttt{Q} option but not even
37054 stopping if your document requires some user input.
37055 \item \texttt{I} (insert): To insert\index{error message!response!insert}
37056 some material for \tx\ to
37057 read but no changes are made to the source file.
37058 \item \texttt{E} (edit): This\index{error message!response!edit}
37059 may return you to an editor so you can
37060 change the file. What actually happens is system dependent.
37061 \item \texttt{X} (exit): Stop\index{error message!response!exit}
37062 this \ltx\ run.
37063 \end{itemize}
37064 On the system I am used to the case of the characters does not matter.
37065 I must admit that the only ones I have used are \meta{return}, \texttt{q},
37066 \texttt{h} and \texttt{x}, in approximately that order of frequency.
37067
37068 All messages are output to the \pixfile{log} file so you can study
37069 them later if you need to.
37070
37071 \section{\tx\ messages}
37072
37073 \index{error!TeX?\tx|(}
37074 \index{TeX?\tx!error|(}
37075 \index{warning!TeX?\tx|(}
37076 \index{TeX?\tx!warning|(}
37077
37078 The following is an alphabetical list of some of \tx's messages,
37079 abbreviated in some cases, together
37080 with their corresponding remarks. As an example of how these appear on your
37081 terminal, if you had a line in your source that read: \\
37082 \verb?resulting in $x^3^4$.?\\
37083 then \tx\ would output this:
37084 \begin{lcode}
37085 ! Double superscript
37086 l.102 resulting in $x^3^
37087 4^$.
37088 ?
37089 \end{lcode}
37090 If you typed \texttt{h} in response to this you would then see:
37091 \begin{lcode}
37092 I treat `x^1^2' essentially like `x^1{}^2'.
37093 \end{lcode}
37094
37095 \tx's messages start with \verb?!? followed by the particular message
37096 text. The second line starts \verb?l.?
37097 and a number, which is the number of the line in your file where the error
37098 is. This is followed by the text of the line itself up to the point where
37099 the error was detected, and the next line in the report shows the rest of
37100 the erroneous line. The last line of the report is a \verb+?+ and \tx\
37101 awaits your response.
37102
37103
37104 %% List of TeX messages
37105 \newcommand{\textmess}[1]{\texttt{#1}}
37106 \newcommand{\texthelp}[1]{\textit{#1}}
37107
37108 In the listing I have used \textmess{this font for the error message}
37109 and \texthelp{this font for the comment message}.
37110 \vspace{\onelineskip}
37111
37112 \begin{plainlist}
37113 %1084
37114 \item[\textmess{!}]\index{A box was supposed to be here}
37115 \textmess{A box was supposed to be here.} \\
37116 \texthelp{I was expecting to see \cmd{\hbox}{} or \cmd{\vbox}{} or
37117 \cmd{\copy}{} or \cmd{\box}{} or something like that.
37118 So you might find
37119 something missing in your output. But keep trying; you can
37120 fix this later.}
37121
37122 %395
37123 \item[\textmess{!}]\index{Argument of ... has an extra \rb}
37124 \textmess{Argument of ... has an extra \}.} \\
37125 \texthelp{I've run across a `\}' that doesn't seem to match anything.
37126 For example,} \verb?`\def\a#1{...}'? \texthelp{and} \verb?`\a}'?
37127 \texthelp{would produce this error. If you simply proceed now,
37128 the \piif{par} that I've just inserted will cause me to report
37129 a runaway argument that might be the root of the problem. But if
37130 your `\}' was spurious, just type `2' and it will go away.}
37131
37132 In \ltx\ terms, the example can be translated into \\
37133 \verb?`\newcommand{\a}[1]{...}'? and \verb?`\a}'?.
37134
37135 If you can't find the extra \} it might be that you have used a fragile
37136 command\index{fragile} in a moving\index{moving argument} argument.
37137 Footnotes\index{footnote!in heading}\index{footnote!in caption}
37138 or math\index{math!in caption or title} in division titles
37139 or captions
37140 are a fruitful source for this kind of error. You shouldn't be putting
37141 footnotes into titles that will get listed in the \toc. For maths, put
37142 \cmd{\protect} before each fragile command.
37143
37144 %1236
37145 \item[\textmess{!}]\index{Arithmetic overflow}
37146 \textmess{Arithmetic overflow.} \\
37147 \texthelp{I can't carry out that multiplication or division,
37148 since the result is out of range.}
37149
37150 The maximum\index{maximum number} number that \tx\
37151 can deal with is 2,147,483,647 and it balks at
37152 dividing\index{divide by zero} by zero.
37153
37154
37155 %168 \texttt{AVAIL list clobbered at \ldots}
37156
37157 %293/4 \texttt{BAD.}
37158
37159 %961 \texttt{Bad \cmd{\patterns}}
37160 % \texttt{(See Appendix H.)}
37161
37162 %1244
37163 %\item[\textmess{!}] \textmess{Bad \cmd{\prevgraf}.} \\
37164 % \texthelp{I allow only nonnegative values here.}
37165
37166 %432
37167 %\item[\textmess{!}] \textmess{Bad character code} \\
37168 % \texthelp{The numeric code for a character must be between 0 and 127.
37169 % I changed this one to zero.}
37170
37171 %435
37172 %\item[\textmess{!}] \textmess{Bad character code} \\
37173 % \texthelp{A character number must be between 0 and 255.
37174 % I changed this one to zero.}
37175
37176 %437
37177 %\item[\textmess{!}] \textmess{Bad delimter code} \\
37178 % \texthelp{A numeric delimeter code must be between 0 and} \verb?2^{27}-1.?
37179 % \texthelp{I changed this one to zero.}
37180
37181 %170 \texttt{Bad flag at}
37182
37183 %170 \texttt{Bad link, display aborted.}
37184
37185 %436
37186 %\item[\textmess{!}] \textmess{Bad math code} \\
37187 % \texthelp{A numeric math code must be between 0 and 32767.
37188 % I changed this one to zero.}
37189
37190 %434
37191 %\item[\textmess{!}] \textmess{Bad number.} \\
37192 % \texthelp{Since I expected to read a number between 0 and 15,
37193 % I changed this one to zero.}
37194
37195 %433
37196 %\item[\textmess{!}] \textmess{Bad register code} \\
37197 % \texthelp{A register number must be between 0 and 255.
37198 % I changed this one to zero.}
37199
37200 %1243
37201 %\item[\textmess{!}] \textmess{Bad space factor} \\
37202 % \texthelp{I allow only values in the range 1..32767 here.}
37203
37204 %1328 \texttt{Beginning to dump on file \ldots}
37205
37206 %484 \texttt{*** (cannot \cmd{\read} from terminal in nonstop modes)} fatal error
37207
37208 %638 \texttt{Completed box being shipped out}
37209
37210 %639 \texttt{Memory usage before: }
37211
37212 %460
37213 \item[\textmess{!}]\index{Dimension too large}
37214 \textmess{Dimension too large.} \\
37215 \texthelp{I can't work with sizes\index{maximum length} bigger
37216 than about 19 feet.
37217 Continue and I'll use the largest value I can.}
37218
37219 %1120
37220 %\item[\textmess{!}] \textmess{Discretionary list is too long.} \\
37221 % \texthelp{Wow---I never thought anyone would tweak me here.
37222 % You can't seriously need such a huge discretionary list?}
37223
37224
37225
37226 %1197
37227 \item[\textmess{!}]\index{Display math should end with \$\$}
37228 \textmess{Display math should end with \$\$.} \\
37229 \texthelp{The `\$' that I just saw supposedly matches a previous `\$\$'.
37230 So I shall assume that you typed `\$\$' both times.}
37231
37232 Although \$\$ is one of \tx's methods for starting and ending
37233 display math, do \emph{not} use it in \ltx.
37234
37235 %1177
37236 \item[\textmess{!}]\index{Double subscript}
37237 \textmess{Double subscript.} \\
37238 \texthelp{I treat} \verb?`x_1_2'? \texthelp{essentially like}
37239 \verb?`x_1{}_2'.?
37240
37241 This would produce $x_1{}_2$. If you were after
37242 say, $x_{2_{3}}$ instead, type \verb?x_{2_{3}}?.
37243
37244 %1177
37245 \item[\textmess{!}]\index{Double superscript}
37246 \textmess{Double superscript.} \\
37247 \texthelp{I treat} \verb?`x^1^2'? \texthelp{essentially like}
37248 \verb?`x^1{}^2'.?
37249
37250 This would produce $x^1{}^2$. If you were after
37251 say, $x^{2^{3}}$ instead, type \verb?x^{2^{3}}?.
37252
37253 %169 \texttt{Double-AVAIL list clobbered at \ldots}
37254
37255 %169 \texttt{Doubly free location at ldots}
37256
37257 %1335
37258 \item[\textmess{!}]\index{end occurred inside?\cs{end} occurred inside a group ...}
37259 \textmess{(\cmd{\end} occurred inside a group at level ...).}
37260
37261 This is message is output at the end of a run. It means that you have not
37262 ended all the groups that you started; a group can be started by
37263 a simple open brace (\{), but there are other starting mechanisms as well,
37264 such as \senv{...}. If the problem is a missing \eenv{...}, \ltx\ is kind
37265 enough to tell you what the mismatch is.
37266
37267 %1335
37268 \item[\textmess{!}]\index{end occurred when?\cs{end} occurred when ...}
37269 \textmess{(\cmd{\end} occurred when ... was incomplete).}
37270
37271 %1335 \texttt{(\cmd{\dump} is performed only by INITEX)}
37272
37273 %963 \texttt{Duplicate pattern}
37274 % \texttt{(See Appendix H.)}
37275
37276 %93 \texttt{Emergency stop}
37277
37278 %183 \texttt{Unknown node type!}
37279
37280 %292 \texttt{\cs{ETC}.}
37281
37282 %293 \texttt{\cs{CLOBBERED}.}
37283
37284 %293/4 \texttt{\cs{BAD}.}
37285
37286 %510
37287 \item[\textmess{!}]\index{Extra fi?Extra \cs{fi}}%
37288 \index{Extra else?Extra \cs{else}}%
37289 \index{Extra or?Extra \cs{or}}
37290 \textmess{Extra \cs{fi}.} or \textmess{Extra \cs{else}.} or \textmess{Extra \cs{or}.} \\
37291 \texthelp{I'm ignoring this; it doesn't match any \cs{if}.}
37292
37293 %1135
37294 \item[\textmess{!}]\index{Extra endcsname?Extra \cs{endcsname}}
37295 \textmess{Extra \cmd{\endcsname}.} \\
37296 \texthelp{I'm ignoring this, since I wasn't doing a \cmd{\csname}.}
37297
37298 %1192
37299 \item[\textmess{!}]\index{Extra right?Extra \cs{right}}
37300 \textmess{Extra \cmd{\right}.} \\
37301 \texthelp{I'm ignoring a \cmd{\right} that had no matching \cmd{\left}.}
37302
37303 %1069
37304 \item[\textmess{!}]\index{Extra ... or forgotten ...}
37305 \textmess{Extra \}, or forgotten \cmd{\endgroup}, \$, or \cmd{\right}.} \\
37306 \texthelp{I've deleted a group closing symbol because it seems to be
37307 spurious, as in `\$x\}\$'. But perhas the \} is legitimate and
37308 you forgot something else, as in} \verb?`\hbox{$x}'.? %$
37309 \texthelp{In such cases the way to recover is to insert both the
37310 forgotten and the deleted material, e.g., by typing `I\$\}'.}
37311
37312 The braces or math mode delimeters didn't match. You might have
37313 forgotten a \texttt{\{}, \cmd{\[}, \cmd{\(} or \texttt{\$}.
37314
37315 %1066
37316 \item[\textmess{!}]\index{Extra ...}
37317 \textmess{Extra ...} \\
37318 \texthelp{Things are pretty mixed up, but I think the worst is over.}
37319
37320 %792
37321 \item[\textmess{!}]\index{Extra alignment tab ...}
37322 \textmess{Extra alignment tab has been changed to \cmd{\cr}.} \\
37323 \texthelp{You have given more \cmd{\span} or \& marks than there were
37324 in the preamble to the \cmd{\halign} or \cmd{\valign} now in progress.
37325 So I'll asume that you meant to type \cmd{\cr} instead.}
37326
37327 Internally, \ltx\ uses
37328 \cmd{\halign} for its \Ie{array}\index{array} and
37329 \Ie{tabular}\index{tabular} environments.
37330 The message means that you have too many column entries in a row
37331 (i.e., too many \texttt{\&} before the end of the row). Perhaps
37332 you have forgotten to put \cmd{\\} at the end of the preceding row.
37333
37334 %789
37335 %\item[\textmess{!}] \textmess{(interwoven alignment preambles are not allowed).} (fatal error)
37336
37337 %1303
37338 %\item[\textmess{!}] \textmess{(Fatal format file error; I'm stymied).}
37339
37340 %338
37341 \item[\textmess{!}]\index{File ended while scanning ...}%
37342 \index{Forbidden control sequence found ...}
37343 \textmess{File ended while scanning \ldots .} or
37344 \textmess{Forbidden control sequence found while scanning \ldots .} \\
37345 \texthelp{I suspect you have forgotten a `\}', causing me
37346 to read past where you wanted me to stop. I'll try to recover;
37347 but if the error is serious you'd better type `E' or `X' now
37348 and fix your file.}
37349
37350
37351 %579
37352 %\item[\textmess{!}] \textmess{Font \ldots has only \ldots fontdimen parameters.} \\
37353 % \texthelp{To increase the number of font parameters, you must use
37354 % \cmd{\fontdimen} immediately after the \cmd{\font} is loaded.}
37355
37356 %561
37357 \item[\textmess{!}]\index{Font ... not loadable ...}
37358 \textmess{Font \ldots not loadable: Metric (TFM) file not found.} \\
37359 \item[\textmess{!}]\index{Font ... not loadable ...}
37360 \textmess{Font \ldots not loadable: Bad metric (TFM) file.} \\
37361 \texthelp{I wasn't able to read the size data for this font, so I will
37362 ignore the font specification.
37363 [Wizards can fix TFM files using TFtoPL/PLtoTF.]
37364 You might try inserting a different font spec;
37365 e.g., type}
37366 \verb?`I\font<same font id>=<substitute font name>'.?
37367
37368 \ltx\ can't find a font you have asked for.
37369
37370 %567
37371 %\item[\textmess{!}] \textmess{Font \ldots not loaded: Not enough room left.} \\
37372 % \texthelp{I'm afraid I won't be able to make use of this font,
37373 % because my memory for character-size data is too small.
37374 % If you're really stuck, ask a izard to enlarge me.
37375 % Or maybe try}
37376 % \verb?`I\font<same font id>=<name of loaded font>'.?
37377
37378 %641
37379 \item[\textmess{!}]\index{Huge page cannot be shipped out}
37380 \textmess{Huge page cannot be shipped out.} \\
37381 \texthelp{The page just created is more than 18 feet tall or
37382 more than 18 feet wide, so I suspect something went wrong.}
37383
37384 %530
37385 \item[\textmess{!}]\index{I can't find file ...}
37386 \textmess{I can't find file `\ldots', please type another.} \\
37387
37388 \tx\ couldn't find the file you asked it to read. You can also
37389 get this message with \ltx\ if you have missed the braces around
37390 the argument to \cmd{\input}.
37391
37392 %95
37393 \item[\textmess{!}]\index{I can't go on meeting you like this}
37394 \textmess{I can't go on meeting you like this.} \\
37395 \texthelp{One of your faux pas seems to have wounded me deeply...
37396 in fact, I'm barely conscious. Plase fix it and try again.}
37397
37398
37399 %530
37400 \item[\textmess{!}]\index{I can't write on file ...}
37401 \textmess{I can't write on file `\ldots', please type another.} \\
37402
37403 \tx\ couldn't write on a file, you might have mispelled the name
37404 or not have permission to use it.
37405
37406 %535
37407 %\item[\textmess{!}] \textmess{I can't write on file `\ldots'.} (fatal error?)
37408
37409 %51 \texttt{! I can't read TEX.POOL}
37410
37411 %288/1258
37412 %\item[\textmess{!}] \textmess{Illegal magnification has been changed to 1000.} \\
37413 % \texthelp{The magnification ratio must be between 1 and 32768.}
37414
37415 %1120
37416 %\item[\textmess{!}] \textmess{Illegal math \cmd{\discretionary}.} \\
37417 % \texthelp{Sorry: The third part of a discretionary break must be empty,
37418 % in math formulas. I had to delete your third part.}
37419
37420 %479
37421 \item[\textmess{!}]\index{Illegal parameter number ...}
37422 \textmess{Illegal parameter number in definition of \ldots .} \\
37423 \texthelp{You meant to type \#\# instead of \#, right?
37424 Or maybe a \} was forgotten somewhere earlier, and things are
37425 all screwed up? I'm going to assume that you meant \#\#.}
37426
37427 This is probably due to a command defining command like \cmd{\newcommand}
37428 or \cmd{\renewcommand} or \cmd{\providecommand}, or an environment
37429 defining command like \cmd{\newenvironment} or \cmd{\renewenvironment}, where
37430 a \verb?#? has been used incorrectly. Apart from the command \cmd{\#},
37431 a \verb?#? can only be used to indicate an argument parameter, like \verb?#3?
37432 which denotes the third argument. You cannot use an argument parameter,
37433 like the \verb?#3? in the last argument of either the \cmd{\newenvironment}
37434 or the \cmd{\renewenvironment} commands.
37435
37436 You get the same error if you try to include any of the above defining
37437 commands inside another one.
37438
37439
37440 %454
37441 \item[\textmess{!}]\index{Illegal unit of measure ...}
37442 \textmess{Illegal unit of measure (replaced by filll).} \\
37443 \texthelp{I dddon't go any higher than filll.}
37444
37445 You have tried to use a \texttt{filll} with more than 3 `l's.
37446
37447 %456
37448 \item[\textmess{!}]\index{Illegal unit of measure ...}
37449 \textmess{Illegal unit of measure (mu inserted).} \\
37450 \texthelp{The unit of measurement in math glue must be mu.
37451 To recover gracefully from this error it's best to delete
37452 the erroneous units; e.g., type `2' to delete two letters.
37453 (See Chapter 27 of The TeXbook.)}
37454
37455 \tx\ was in math mode
37456 and expecting a length, which must be in \texttt{mu} units.
37457
37458 %459
37459 \item[\textmess{!}]\index{Illegal unit of measure ...}
37460 \textmess{Illegal unit of measure (pt inserted).} \\
37461 \texthelp{Dimensions can be in units of em, ex, in, pt, pc, cm, mm, dd,
37462 cc, bp, or sp; but yours is a new one!
37463 I'll assume you meant to say pt, for printers' points.
37464 To recover gracefully from this error it's best to delete
37465 the erroneous units; e.g., type `2' to delete two letters.
37466 (See Chapter 27 of The TeXbook.)}
37467
37468 \tx\ was expecting a length
37469 but it found just a number without a known length unit. For example
37470 you wrote \verb?2ib? instead of \verb?2in?.
37471
37472 %1121
37473 %\item[\textmess{!}] \textmess{Improper discretionary list.} \\
37474 % \texthelp{Discretionary lists must contain only boxes and kerns.
37475 % The following discretionary sublist has been deleted: \ldots}
37476
37477 %935
37478 \item[\textmess{!}]\index{Improper \cs{hyphenation} ...}
37479 \textmess{Improper \cmd{\hyphenation} will be flushed.} \\
37480 \texthelp{Hyphenation exceptions must contain only letters
37481 and hyphens. But continue; I'll forgive and forget.}
37482
37483 %288
37484 %\item[\textmess{!}] \textmess{Incompatible magnification (\ldots); the previous value will
37485 % be retained.} \\
37486 % \texthelp{I can handle only one magnification ratio per job. So I've
37487 % reverted to the magnification you used earlier on this run.}
37488
37489 %336
37490 \item[\textmess{!}]\index{Incomplete ...}
37491 \textmess{Incomplete \ldots all text was ignored after line \ldots.} \\
37492 \texthelp{A forbidden control sequence occurred in skipped text.
37493 This kind of error happens when you say `\cs{if}...' and forget
37494 the matching `\cs{fi}'. I've inserted a `\cs{fi}'; this might work.}
37495
37496 %993
37497 %\item[\textmess{!}] \textmess{Insertions can only be aded to a vbox.} \\
37498 % \texthelp{Tut tut: You're trying to insert into a
37499 % box register that now contains an \cmd{\hbox}.
37500 % Proceed, and I'll discard its present contents.}
37501
37502 %826
37503 \item[\textmess{!}]\index{Infinite glue shrinkage ...}
37504 \textmess{Infinite glue shrinkage found in a paragraph.} \\
37505 \texthelp{The paragraph just ended includes some glue that has
37506 infinite shrinkability, e.g.,} \verb?`\hskip 0pt minus 1fil'.?
37507 \texthelp{Such glue doesn't belong there---it allows a paragraph
37508 of any length to fit on one line. But it's safe to proceed,
37509 since the offensive shrinkability has been made finite.}
37510
37511 %1232
37512 %\item[\textmess{!}] \textmess{Invalid code (\ldots) should be in the range 0 to \ldots.}
37513 %or \textmess{Invalid code (\ldots) should be at most \ldots} \\
37514 % \texthelp{I'm going to use 0 instead of that illegal code value.}
37515
37516 %1159
37517 \item[\textmess{!}]\index{Limit controls ...}
37518 \textmess{Limit controls must follow a math operator.} \\
37519 \texthelp{I'm ignoring this misplaced \cmd{\limits} or \cmd{\nolimits}
37520 command.}
37521
37522 %660
37523 %\item[\textmess{!}] \textmess{Loose \cmd{\hbox} (badness \ldots).}
37524
37525 %674
37526 %\item[\textmess{!}] \textmess{Loose \cmd{\vbox} (badness \ldots).}
37527
37528
37529 %1195
37530 %\item[\textmess{!}]\textmess{Math formula deleted: Insufficient extension fonts.} \\
37531 % \texthelp{Sorry, but I can't typeset math unless \cmd{\textfont} 3
37532 % and \cmd{\scriptfont} 3 and \cmd{\scriptscriptfont} 3
37533 % have all the \cmd{\fontdimen} values needed in math extension fonts.}
37534
37535 %1195
37536 %\item[\textmess{!}] \textmess{Math formula deleted: Insufficient symbol fonts.} \\
37537 % \texthelp{Sorry, but I can't typeset math unless \cmd{\textfont} 2
37538 % and \cmd{\scriptfont} 2 and \cmd{\scriptscriptfont} 2
37539 % have all the \cmd{\fontdimen} values needed in math symbol fonts.}
37540
37541 %1128
37542 \item[\textmess{!}]\index{Misplaced \&}\index{Misplaced \cs{cr}}\index{Misplaced \cs{span}}
37543 \textmess{Misplaced \&.} or \textmess{Misplaced \cmd{\cr}.} or \textmess{Misplaced \cmd{\span}.} \\
37544 \texthelp{I can't figure out why you would want to use a tab mark
37545 or \cmd{\cr} or \cmd{\span} here.
37546 If you just want an ampersand the remedy is simple: Just type}
37547 \verb?`I\&'?
37548 \texthelp{now. But if some right brace
37549 up above has ended a previous alignment prematurely,
37550 you're probably due for more error messages, and you
37551 might try typing `S' now just to see what is salvageable.}
37552
37553 In \ltx\ the most likely of these messages is the
37554 \textmess{Misplaced \&}. You can only use a naked \texttt{\&} in
37555 environments like \Ie{array} and \Ie{tabular} as column separators.
37556 Anywhere else you have to use \cmd{\&}.
37557
37558
37559 %1129
37560 \item[\textmess{!}]\index{Misplaced \cs{noalign}}
37561 \textmess{Misplaced \cmd{\noalign}.} \\
37562 \texthelp{I expect to see \cmd{\noalign} only after the \cmd{\cr} of
37563 an alignment. Proceed, and I'll ignore this case.}
37564
37565 %1129
37566 \item[\textmess{!}]\index{Misplaced \cs{omit}}
37567 \textmess{Misplaced \cmd{\omit}.} \\
37568 \texthelp{I expect to see \cmd{\omit} only after the tab marks or
37569 the \cmd{\cr} of an alignment. Proceed, and I'll ignore this case.}
37570
37571 %1132
37572 \item[\textmess{!}]\index{Missing \cs{cr} inserted}
37573 \textmess{Missing \cmd{\cr} inserted.} \\
37574 \texthelp{I'm guessing that you meant to end an alignment here.}
37575
37576 You might have missed a \cmd{\\} at the end of the last row
37577 of a \Ie{tabular} or \Ie{array}.
37578
37579 %503
37580 \item[\textmess{!}]\index{Missing = inserted ...}
37581 \textmess{Missing = inserted for \ldots .} \\
37582 \texthelp{I was expecting to see `$<$', `$=$', or `$>$'. Didn't.}
37583
37584 %783
37585 \item[\textmess{!}]\index{Missing \# inserted ...}
37586 \textmess{Missing \# inserted in alignment preamble.} \\
37587 \texthelp{There should be exactly one \# between \&'s, when an
37588 \cmd{\halign} or \cmd{\valign} is being set up. In this case you had
37589 none, so I've put one in; maybe that will work.}
37590
37591 If you get this in \ltx\ then there are problems with the argument
37592 to an \Ie{array} or \Ie{tabular}.
37593
37594 \item[\textmess{!}]\index{Missing \$ inserted}%
37595 \index{Missing \cs{endgroup} inserted}%
37596 \index{Missing \cs{right} inserted}%
37597 \index{Missing \rb inserted}
37598 \textmess{Missing \$ inserted.} or
37599 \textmess{Missing \cmd{\endgroup} inserted.} or
37600 \textmess{Missing \cmd{\right} inserted.} or
37601 \textmess{Missing \} inserted.} \\
37602 \texthelp{I've inserted something that you may have forgotten.
37603 (See the $<$inserted text$>$ above.)
37604 With luck, this will get me unwedged, But if you
37605 really didn't forget anything, try typing `2' now; then
37606 my insertion and my current dilemma will both disappear.}
37607
37608 This is a general response to the above messages. There is also a
37609 more specific response for each of the messages, as listed below.
37610
37611
37612 %1047
37613 \item[\textmess{!}]\index{Missing \$ inserted}
37614 \textmess{Missing \$ inserted.} \\
37615 \texthelp{I've inserted a begin-math/end-math symbol since I think
37616 you left one out. Proceed with fingers crossed.}
37617
37618 Certain commands can only be executed in math mode and there are
37619 others that cannot be used in math mode. \tx\ has come across a command that
37620 cannot be used in the current mode, so it switches into, or out of, math
37621 mode on the assumption that that was what you had forgotten to do.
37622
37623 %1065
37624 %373
37625 \item[\textmess{!}]\index{Missing \cs{endcsname} inserted}
37626 \textmess{Missing \cmd{\endcsname} inserted.} \\
37627 \texthelp{The control sequence marked $<$to be read again$>$ should
37628 not appear between \cmd{\csname} and \cmd{\endcsname}.}
37629
37630 %403
37631 \item[\textmess{!}]\index{Missing \lb{} inserted}
37632 \textmess{Missing \{ inserted.} \\
37633 \texthelp{A left brace was mandatory here, so I've put one in.
37634 You might want to delete and/or insert some corrections
37635 so that I will find a matching right brace soon.
37636 If you're confused by all this, try typing `I\}' now.}
37637
37638 %475
37639 \item[\textmess{!}]\index{Missing \lb{} inserted}
37640 \textmess{Missing \{ inserted.} \\
37641 \texthelp{Where was the left brace? You said something like}
37642 \verb?\def\a}',?
37643 \texthelp{which I'm going to interpret as}
37644 \verb?\def\a{}'.?
37645
37646 In \ltx\ terms, the example wrongdoing would be \verb?\newcommand{\a}}?
37647
37648 %1127
37649 \item[\textmess{!}]\index{Missing \lb{} inserted}
37650 \textmess{Missing \{ inserted.} \\
37651 \texthelp{I've put in what seems becessary to fix
37652 the current column of the current alignment.
37653 Try to go on, since this might almost work.}
37654
37655 It seems that a \texttt{\{} might have been missing in a \Ie{tabular}
37656 or \Ie{array} entry.
37657
37658 %1082
37659 %\item[\textmess{!}] \textmess{Missing `to' inserted.} \\
37660 % \texthelp{I'm working on} \verb?`\vsplit<box number> to <dimen>';?
37661 % \texthelp{will look for the $<$dimen$>$ next.}
37662
37663 %1207
37664 %\item[\textmess{!}] \textmess{Missing \$\$ inserted.} \\
37665 % \texthelp{Displays can use special alignments (like \cmd{eqalignno})
37666 % only if nothing but the alignment itself is between \$\$'s.}
37667
37668 %581
37669 %\item[\textmess{!}] \textmess{Missing character: there is no \ldots in font \ldots.}
37670
37671 %1215
37672 \item[\textmess{!}]\index{Missing control sequence inserted}
37673 \textmess{Missing control sequence inserted.} \\
37674 \texthelp{Please don't say} \verb?`\def cs{...}',? \texthelp{say}
37675 \verb?`\def\cs{...}'.?
37676 \texthelp{I've inserted an inaccessible control sequence so that your
37677 definition will be completed without mixing me up too badly.
37678 You can recover graciously from this error, if you're
37679 careful; see exercise 27.2 in The TeXbook.}
37680
37681 %1161
37682 \item[\textmess{!}]\index{Missing delimeter(. inserted).}
37683 \textmess{Missing delimeter(. inserted).} \\
37684 \texthelp{I was expecting to see something like}
37685 \verb?`('?
37686 \texthelp{or}
37687 \verb?`\{'?
37688 \texthelp{or}
37689 \verb?`\}'?
37690 \texthelp{here. If you typed, e.g.,}
37691 \verb?`{'?
37692 \texthelp{instead of}
37693 \verb?`\{'?
37694 \texthelp{you should probably delete the}
37695 \verb?`{'?
37696 \texthelp{by typing `1' now, so that braces don't get unbalanced.
37697 Otherwise just proceed.
37698 Acceptable delimeters are characters whose \cmd{\delcode} is
37699 nonnegative, or you can use `\cmd{\delimeter} $<$delimeter code$>$'.}
37700
37701 %577
37702 %\item[\textmess{!}] \textmess{Missing font identifier.} \\
37703 % \texthelp{I was looking for a control sequence whose
37704 % current meaning has been defined by \cmd{\font}.}
37705
37706 %415/446
37707 \item[\textmess{!}]\index{Missing number ...}
37708 \textmess{Missing number, treated as zero.} \\
37709 \texthelp{A number should have been here; I inserted `0'.
37710 (If you can't figure out why I needed to see a number,
37711 look up `weird error' in the index to The TeXbook.)}
37712
37713 In \ltx\ this is often caused by a command expecting a number or a length
37714 argument but not finding it. You might have forgotten the argument or
37715 an opening square bracket in the text might have been taken as the start
37716 of an optional argument. For example, the \cmd{\\} (newline) command takes
37717 an optional length argument, so the following will produce this error:
37718 \begin{lcode}
37719 ... next line\\
37720 [Horatio:] ...
37721 \end{lcode}
37722
37723 %937
37724 \item[\textmess{!}]\index{Not a letter}
37725 \textmess{Not a letter.} \\
37726 \texthelp{Letters in \cmd{\hyphenation} words must have \cmd{\lccode}>0.}
37727
37728 One or more characters in the argument to the \cmd{\hyphenation} command
37729 should not be there.
37730
37731
37732 %962
37733 %\item[\textmess{!}] \textmess{Nonletter.} \\
37734 % \texthelp{(See Appendix H.)}
37735
37736 %445
37737 \item[\textmess{!}]\index{Number too big}
37738 \textmess{Number too big.} \\
37739 \texthelp{I can only go up to 2147483647 = '17777777777 = "7FFFFFFF,
37740 so I'm using that number instead of yours.}
37741
37742 These all represent the
37743 same value, firstly in decimal, secondly in octal, and lastly in
37744 hexadecimal notations.
37745
37746 %1024
37747 \item[\textmess{!}]\index{Output loop ...}
37748 \textmess{Output loop--- \ldots consecutive dead cycles.} \\
37749 \texthelp{I've concluded that your \cmd{\output} is awry; it never does a
37750 \cs{shipout}, so I'm shipping \cmd{\box255} out myself. Next time
37751 increase \cmd{\maxdeadcycles} if you want me to be more patient!}
37752
37753 \tx\ appears to be spinning its wheels, doing nothing.
37754
37755 %1024
37756 %\item[\textmess{!}] \textmess{Output routine didn't use all of \cmd{\box255}.} \\
37757 % \texthelp{Your \cmd{\output} commands should empty \cmd{\box255},
37758 % e.g., by saying `\cs{shipout}\cmd{\box255}'.
37759 % Proceed; I'll discard its present contents.}
37760
37761 %666
37762 \item[\textmess{!}]\index{Overfull \cs{hbox} ...}
37763 \textmess{Overfull \cmd{\hbox} (\ldots pt too wide).}
37764
37765 This is a warning that \tx\ couldn't cram some text into the alloted
37766 horizontal space.
37767
37768 %677
37769 \item[\textmess{!}]\index{Overfull \cs{vbox} ...}
37770 \textmess{Overfull \cmd{\vbox} (\ldots pt too high).}
37771
37772 This is a warning that \tx\ couldn't find a good place for a
37773 pagebreak, so it has put too much onto the current page.
37774
37775
37776 %396
37777 \item[\textmess{!}]\index{Paragraph ended before ...}
37778 \textmess{Paragraph ended before \ldots was complete.} \\
37779 \texthelp{I suspect you've forgotten a `\}', causing me to apply this
37780 control sequence to too much text. How can we recover?
37781 My plan is to forget the whole thing and hope for the best.}
37782
37783 Either a blank line or a \piif{par} command appeared in the
37784 argument to a macro that cannot handle paragraphs (e.g.,
37785 a macro that was defined using \cmd{\newcommand*}).
37786
37787 %476
37788 %\item[\textmess{!}] \textmess{Parameters must be numbered consecutively.} \\
37789 % \texthelp{I've inserted the digit you should have used after the \#.
37790 % Type `1' to delete what you did use.}
37791
37792 %1252 \texttt{Patterns can only be loaded by INITEX}
37793
37794 %360
37795 \item[\textmess{!}]\index{Please type a command ...}
37796 \textmess{Please type a command or say `\cmd{\end}'.}
37797
37798 This is the message that causes me the most trouble. My computer
37799 always ignores whatever I say to it and even typing \cmd{\end} has
37800 no effect. What I usually do, after having tried a few variations
37801 like \eenv{document}, is to kill the program by whatever means the operating
37802 system provides. Some other possible responses include:
37803 \begin{itemize}
37804 \item Type \cmd{\stop}
37805 \item Type \verb?\csname @@end\endcsname? (\ltx\ stores \tx's version of
37806 \cmd{\end} as \cmd{\@@end})
37807 \item Type some macro that you think is unknown, perhaps \cs{qwertyuiod},
37808 then respond to the error message: \textmess{Undefined control sequence.}
37809 \item Sometimes nothing works except killing the program. If you are are sure you
37810 know how to kill a program, try the following highly contrived code:
37811 \begin{lcode}
37812 \documentclass{article}
37813 \newif\ifland
37814 \newif\ifprint
37815 \newcommand{\Xor}[2]{\ifx #1 #2}
37816 \begin{document}
37817 % \Xor{\ifland}{\ifprint}% try uncommenting this
37818 \iffalse
37819 \end{document}
37820 \end{lcode}
37821 \end{itemize}
37822
37823
37824
37825 %1166
37826 %\item[\textmess{!}] \textmess{Please use \cmd{\mathaccent} for accents in math mode.} \\
37827 % \texthelp{I'm changing \cmd{\accent} to \cmd{\mathaccent} here; wish
37828 % me luck. Accents are not the same in formulas as they are in text.}
37829
37830 %306
37831 \item[\textmess{!}]\index{Runaway argument}%
37832 \index{Runaway definition}%
37833 \index{Runaway preamble}%
37834 \index{Runaway text}
37835 \textmess{Runaway argument.} or
37836 \textmess{Runaway definition.} or
37837 \textmess{Runaway preamble.} or
37838 \textmess{Runaway text.}
37839
37840 %524
37841 %\item[\textmess{!}] \textmess{Sorry, I can't find that format; will try PLAIN.}
37842
37843 %1050
37844 \item[\textmess{!}]\index{Sorry, but I'm not ...}
37845 \textmess{Sorry, but I'm not programmed to handle this case.} \\
37846 \texthelp{I'll just pretend that you didn't ask for it.
37847 If you're in the wrong mode, you might be able to
37848 return to the right one by typing `I\}' or `I\$' or
37849 `I\cs{par}'.}
37850
37851
37852 %94
37853 \item[\textmess{!}]\index{TeX capacity exceeded ...}
37854 \textmess{TeX capacity exceeded, sorry [\ldots].} \\
37855 \texthelp{If you absolutely need more capacity, you can ask a wizard
37856 to enlarge me.}
37857
37858 This is dealt with in more detail below.
37859
37860 %346
37861 \item[\textmess{!}]\index{Text line contains ...}
37862 \textmess{Text line contains an invalid character.} \\
37863 \texthelp{A funny symbol that I can't read has just been input.
37864 Continue, and I'll forget that it ever happened.}
37865
37866 The input file contains a nonprinting (control) character; only
37867 printing characters should be in the file. Some programs,
37868 like word processors, insert invisible characters into their output file. If
37869 you have used one of these to prepare your input file, make sure you
37870 save it as a plain text file (also known as an ASCII file).
37871
37872
37873 %82
37874 \item[\textmess{!}]\index{That makes 100 errors ...}
37875 \textmess{That makes 100 errors; please try again.}
37876
37877 %95
37878 \item[\textmess{!}]\index{This can't happen ...}
37879 \textmess{This can't happen (\ldots).} \\
37880 \texthelp{I'm broken. Please show this to someone who can fix can fix}
37881
37882 This is the message you should never see!
37883
37884 %667
37885 %\item[\textmess{!}] \textmess{Tight \cmd{\hbox} (badness \ldots).}
37886
37887 %678
37888 %\item[\textmess{!}] \textmess{Tight \cmd{\vbox} (badness \ldots).}
37889
37890
37891 %1068
37892 \item[\textmess{!}]\index{Too many \rb's}
37893 \textmess{Too many \}'s.} \\
37894 \texthelp{You've closed more groups than you opened.
37895 Such booboos are generally harmless, so keep going.}
37896
37897 There are more closing braces (\}) than there are opening braces (\{).
37898
37899 %1027
37900 \item[\textmess{!}]\index{Unbalanced output routine}
37901 \textmess{Unbalanced output routine.} \\
37902 \texthelp{Your sneaky output routine has fewer real \{'s than \}'s.
37903 I can't handle that very well; good luck.}
37904
37905 A package or class has done nasty things to one of \ltx's most
37906 delicate parts --- the output routine.
37907
37908 %1372
37909 \item[\textmess{!}]\index{Unbalanced write command}
37910 \textmess{Unbalanced write command.} \\
37911 \texthelp{On this page there's a \cmd{\write} with fewer real \{'s
37912 than \}'s. I can't handle that very well; good luck.}
37913
37914 %370
37915 \item[\textmess{!}]\index{Undefined control sequence}
37916 \textmess{Undefined control sequence.} \\
37917 \texthelp{The control sequence at the end of the top line
37918 of your error message was never \cmd{\def}'ed. If you have
37919 misspelled it (e.g., `\cs{hobx}'), type `I' and the correct
37920 spelling (e.g., `I\cs{hbox}'). Otherwise just continue,
37921 and I'll forget whatever was undefined.}
37922
37923 \tx\ has come across a macro name that it does not know about.
37924 Perhaps you mispelled it, or it is defined in a package you did not include.
37925 Another possibility is that you used a macro name that included the
37926 \texttt{@} character without enclosing it between \cmd{\makeatletter}
37927 and \cmd{\makeother} (\seeatincode)\idxatincode.
37928 In this case \tx\ would think that the name was
37929 just the portion up to the \texttt{@}.
37930
37931
37932 %660
37933 \item[\textmess{!}]\index{Underfull \cs{hbox} ...}
37934 \textmess{Underfull \cmd{\hbox} (badness \ldots).}
37935
37936 This is a warning. There might be some extra horizontal space. It could
37937 be caused by trying to use two \cmd{\newline} or \cmd{\\} commands
37938 in succession with nothing intervening, or by using a \cmd{\linebreak}
37939 command or typesetting with the \cmd{\sloppy} declaration.
37940
37941 %674
37942 \item[\textmess{!}]\index{Underfull \cs{vbox} ...}
37943 \textmess{Underfull \cmd{\vbox} (badness \ldots).}
37944
37945 This is a warning that \tx\ couldn't find a good place for a
37946 pagebreak, so it produced a page with too much whitespace on it.
37947
37948 %398
37949 \item[\textmess{!}]\index{Use of ... doesn't match ...}
37950 \textmess{Use of \ldots doesn't match its definition.} \\
37951 \texthelp{If you say, e.g.,}
37952 \verb?`\def\a1{...}',?
37953 \texthelp{then you must always put `1' after `\cs{a}', since the control
37954 sequence names are made up of letters only.
37955 The macro here has not been followed by the required stuff,
37956 so I'm ignoring it.}
37957
37958
37959 %476
37960 %\item[\textmess{!}] \textmess{You already have nine parameters.} \\
37961 % \texthelp{I'm going to ignore the \# sign you just used.}
37962
37963
37964
37965 %1304 \texttt{You can't dump inside a group}
37966 % \texttt{`\{...\cmd{\dump}\}' is a no-no.}
37967
37968 %1099
37969 %\item[\textmess{!}] \textmess{You can't \cs{insert255}.} \\
37970 % \texthelp{I'm changing to \cs{insert0}; box 255 is special.}
37971
37972 %1095
37973 %\item[\textmess{!}] \textmess{You can't use `\cmd{\hrule}' here without leaders.} \\
37974 % \texthelp{To put a horizontal rule in an hbox or an alignment,
37975 % you should use \cmd{\leaders} or \cmd{\hrulefill}
37976 % (see The TeXbook).}
37977
37978 %1213
37979 %\item[\textmess{!}] \textmess{You can't use `\cmd{\long}' or `\cmd{\outer}' with \ldots} \\
37980 % \texthelp{I'll pretend you didn't say \cmd{\long} or \cmd{\outer} here.}
37981
37982 %1212
37983 %\item[\textmess{!}] \textmess{You can't use a prefix with \ldots} \\
37984 % \texthelp{I'll pretend you didn't say \cmd{\long} or \cmd{\outer}
37985 % or \cmd{\global}.}
37986
37987 %428
37988 %\item[\textmess{!}] \textmess{You can't use `\ldots' after \cmd{\the}.} \\
37989 % \texthelp{I'm forgetting what you said and using zero instead.}
37990
37991 %428
37992 %\item[\textmess{!}] \textmess{You can't use `\ldots' after `\ldots'.} \\
37993 % \texthelp{I'm forgetting what you said and not changing anything.}
37994
37995 %1049
37996 \item[\textmess{!}]\index{You can't use ... in ...}
37997 \textmess{You can't use `\ldots' in `\ldots'.} \\
37998
37999 This often manifests itself in the form \\
38000 \textmess{You can't use `\cmd{\spacefactor}' in vertical
38001 mode}\index{You can't use `\cs{spacefactor}' in vertical mode} \\
38002 the cause
38003 is usually trying to use a macro with \texttt{@} in its name, typically
38004 in the preamble (\seeatincode)\idxatincode.
38005 The solution is to enclose the macro within
38006 \cmd{\makeatletter} and \cmd{\makeatother}.
38007
38008 Another version is \\
38009 \textmess{You can't use `macro parameter character \#' in ...
38010 mode.}\index{You can't use `macro parameter character \#' in ... mode} \\
38011 In this case you have used a naked \texttt{\#} in ordinary text; it can only
38012 be used in the definition of a macro. In ordinary text you have to use
38013 \cmd{\#}.
38014
38015 %486
38016 %\item[\textmess{!}] \textmess{File ended within \cmd{\read}.} \\
38017 % \texthelp{This \cmd{\read} has unbalanced braces.}
38018
38019 \end{plainlist}
38020
38021 \index{TeX?\tx!warning|)}
38022 \index{warning!TeX?\tx|)}
38023
38024 \subsection{\tx\ capacity exceeded}
38025
38026 \index{TeX capacity exceeded ...|(}
38027 \tx\ has run out of computer space before it finished processing your
38028 document. The most likely cause is an error in the input file rather than
38029 there really not being enough space --- I have processed documents consisting
38030 of more than 1400 pages without any capacity problems.
38031
38032 You can very easily make \tx\ run out of space. Try inputting this:
38033 \begin{lcode}
38034 \documentclass{article}
38035 \newcommand*{\fred}{Fred} % should print `Fred'
38036 % try to make it print `Frederick' instead
38037 \renewcommand{\fred}{\fred erick}
38038 \begin{document}
38039 His name is \fred.
38040 \end{document}
38041 \end{lcode}
38042 and \tx\ will tell you that it has run out of stack space:
38043 \begin{lcode}
38044 ! TeX capacity exceeded, sorry [input stack size=15000].
38045 \fred ->\fred
38046 erick
38047 l.5 His name is \fred
38048 .
38049 No pages of output.
38050 Transcript written on errors.log.
38051 \end{lcode}
38052
38053 The offending code above
38054 tries to define \cs{fred} in terms of itself, and \tx\ just keeps chasing
38055 round and round trying to pin down \cs{fred} until it is exhausted.
38056
38057 At the end of the \file{log} file for a run, \tx\ prints the memory space
38058 it has used. For example:
38059 \begin{lcode}
38060 Here is how much of TeX's memory you used:
38061 2432 strings out of 60985
38062 29447 string characters out of 4940048
38063 106416 words of memory out of 8000001
38064 5453 multiletter control sequences out of 10000+65535
38065 8933 words of font info for 31 fonts out of 1000000 for 1000
38066 276 hyphenation exceptions out of 1000
38067 26i,11n,21p,210b,380s stack positions out of
38068 15000i,4000n,6000p,200000b,40000s
38069 \end{lcode}
38070
38071 The error message says what kind of space it exhausted (input stack size
38072 in the example above). The most common are:
38073 \begin{plainlist}
38074
38075 \item[\texttt{buffer size}\index{buffer size}]
38076 Can be caused by too long a section or caption title appearing
38077 in the \toc, \lof, etc. Use the optional argument to produce a
38078 shorter entry.
38079
38080 \item[\texttt{exception dictionary}\index{exception dictionary}] There
38081 are too many words listed in \cmd{\hyphenation} commands. Remove any
38082 that are not actually used and if that doesn't work, remove the less
38083 common ones and insert \cmd{\-} in the words in the text.
38084
38085 \item[\texttt{hash size}\index{hash size}]
38086 The document defines too many command names and/or uses too many
38087 cross-referencing \cmd{\label}s.
38088
38089 \item[\texttt{input stack size}\index{input stack size}]
38090 Typically caused by a self-referencing macro definition.
38091
38092
38093 \item[\texttt{main memory size}\index{main memory size}]
38094 There are three main things that cause \tx\ to run out of main memory:
38095 \begin{itemize}
38096 \item Defining a lot of very long complicated macros.
38097 \item Having too many \cmd{\index} or \cmd{\glossary} commands on a page.
38098 \item Creating such a complicated page that \tx\ cannot hold all it needs
38099 to process it.
38100 \end{itemize}
38101 The solution to the first two problems is to simplify and eliminate. The
38102 third is more problematic.
38103
38104 Large \Ie{tabular}s, \Ie{array}s and \Ie{picture}s (the \cmd{\qbezier}
38105 command is a memory hog) can gobble up memory. A queue of floats also demands
38106 memory space. Try putting a \cmd{\clearpage} just before the place where the
38107 error occurs and if it still runs out of room then there may be an error in
38108 your file, otherwise you did exceed the capacity.
38109
38110 If you have a long paragraph or a long \Ie{verbatim} environment try
38111 breaking it up, as \tx\ keeps these in memory until it is ready to
38112 typeset them. If you have a queue of floats make sure that you have done
38113 your best to help \ltx\ find a way to output them (see \Sref{sec:floatplace})
38114 and try adding \cmd{\clearpage} at appropriate places to flush the queue.
38115
38116
38117 \item[\texttt{pool size}\index{pool size}]
38118 Typically caused by having too many characters in command names
38119 and label names.
38120
38121 It can also be caused by omitting the right brace that ends the
38122 argument of a counter command (\cmd{\setcounter} or \cmd{\addtocounter})
38123 or of a \cmd{\newenvironment} or \cmd{\newtheorem} command.
38124
38125 \item[\texttt{save stack size}\index{save stack size}]
38126 This happens if commands or environments are nested too deeply.
38127 For instance a \Ie{picture} that contains a \Ie{picture} that includes
38128 a \cmd{\multiput} that includes a \Ie{picture} that includes a \ldots
38129
38130
38131 \index{TeX capacity exceeded ...|)}
38132
38133 \end{plainlist}
38134
38135 \index{TeX?\tx!error|)}
38136 \index{error!TeX?\tx|)}
38137
38138
38139 \section{\ltx\ errors}
38140
38141 \index{LaTeX?\ltx!error|(}
38142 \index{error!LaTeX?\ltx|(}
38143
38144 \ltx\ errors introduce themselves differently from those
38145 that \tx\ finds. For example, if you ever happended to
38146 use the \cmd{\caption} command outside a float, like:
38147 \begin{lcode}
38148 \caption{Naked}
38149 \end{lcode}
38150 you would get the message:
38151 \begin{lcode}
38152 ! LaTeX Error: \caption outside float.
38153
38154 See the LaTeX manual or LaTeX Companion for explanation.
38155 Type H <return> for immediate help.
38156 ...
38157
38158 l.624 \caption
38159 {Naked}
38160 ?
38161 \end{lcode}
38162 If you then typed \texttt{H} in response you would get the following
38163 helpful message:
38164 \begin{lcode}
38165 You're in trouble here. Try typing <return> to proceed.
38166 If that doesn't work, type X <return> to quit.
38167 ?
38168 \end{lcode}
38169 The majority of \ltx's help messages follow this formula, so I have
38170 not noted them in the alphabetical listing below.
38171
38172
38173 %%%%\subsection{Errors}
38174
38175 \begin{plainlist}
38176
38177 %LTTAB
38178 \item[]\index{\cs{<} in mid line}
38179 \textmess{\cs{<} in mid line}
38180
38181 A \cmd{\<} appears in the middle of a line in a \Ie{tabbing} environment;
38182 it should only come at the start of a line.
38183
38184 %LTFSSDCL
38185 \item[]\index{... allowed only in math mode}
38186 \textmess{... allowed only in math mode}
38187
38188 You have tried to use a math command in a non-math mode.
38189
38190
38191 %%%% BBBBBBBBBBBBBBBBBB
38192
38193 %LTERROR
38194 \item[]\index{Bad \cs{line} or \cs{vector} argument}
38195 \textmess{Bad \cmd{\line} or \cmd{\vector} argument}
38196
38197 A \cmd{\line} or \cmd{\vector} has a negative length argument or
38198 the slope is not within the allowed range.
38199
38200 %LTERROR
38201 \item[]\index{Bad math environment delimeter}
38202 \textmess{Bad math environment delimeter}
38203
38204 If in math mode there is a start math mode command like \cmd{\(}
38205 or \cmd{\[} or if in LR or paragraph mode there is an end math mode
38206 command like \cmd{\)}or \cmd{\]}. The basic problem is unmatched math
38207 mode delimeters or unbalanced braces.
38208
38209 %LTERROR
38210 \item[]\index{begin{...} ended by end{...}?\senv{...} ended by \eenv{...}}
38211 \textmess{\senv{...} ended by \eenv{...}}
38212
38213 The name of the \cmd{\begin} argument is not the same as the
38214 name of the \cmd{\end} argument. This could be caused by a typo or a missing
38215 \cmd{\end}.
38216
38217 %%%% CCCCCCCCCCCCCCCC
38218
38219 %LTERROR
38220 \item[]\index{Can only be used in the preamble}
38221 \textmess{Can only be used in the preamble}
38222
38223 Some commands can only be used in the preamble\index{preamble}, such
38224 as \cmd{\usepackage}, but
38225 there was one of these after the \senv{document}.
38226
38227
38228 %LTFLOAT
38229 \item[]\index{caption outside float?\cs{caption} outside float}
38230 \textmess{\cmd{\caption} outside float}
38231
38232 You have used the \cmd{\caption} command outside a float, such as
38233 a \Ie{figure} or \Ie{table} environment.
38234
38235
38236 %LTERROR
38237 \item[]\index{Command \cs{...} already defined ...}
38238 \textmess{Command \cs{...} already defined or name \cs{end}... illegal}
38239
38240 This is normally because you have used one of the \cs{new...}
38241 commands to define a command or environment or counter name that has
38242 already been used; remember also that defining an environment \verb?foo?
38243 automatically defines the macro \cs{foo}. Either choose a new name or
38244 use the appropriate \cs{renew...}; also, see \Sref{sec:nameclash}.
38245 In the unlikely event that you have
38246 tried to define something beginning with \cs{end...}, choose another name.
38247 \label{alreadydefined}
38248
38249
38250
38251 %LTERROR %LTFSSINI
38252 \item[]\index{Command ... invalid ...}
38253 \textmess{Command ... invalid in math mode}
38254
38255 You have used a non-math command in math mode.
38256
38257 %LTFSSDCL
38258 %\item[]\index{Command \cs{..} not defined as a math alphabet}
38259 % \textmess{Command \cs{..} not defined as a math alphabet}
38260 % (use \cmd{\DeclareMathAlphabet} to define it)
38261
38262 %LTFSSINI
38263 \item[]\index{Command ... not provided ...}
38264 \textmess{Command ... not provided in base LaTeX2e}
38265
38266 You have tried to use a symbol that is not part of basic \ltx.
38267 Try loading the \Lpack{latexsym} or \Lpack{amsfonts} package which
38268 might define the symbol.
38269
38270 %LTOUTENC
38271 %\item[] \textmess{Command ... unavailable in encoding ...}
38272
38273 %LTFSSBAS
38274 %\item[] \textmess{Corrupted NFSS tables}
38275
38276
38277 %LTERROR
38278 \item[]\index{Counter too large}
38279 \textmess{Counter too large}
38280
38281 You are using a non-numeric counter representation, such as letters
38282 or footnote symbols, and the counter has exceeded the allowed number
38283 (for example there are only 26 alphabetic characters).
38284
38285
38286 %%%% EEEEEEEEEEEEEEEEEEEE
38287
38288 %LTFSSBAS
38289 %\item[] \textmess{Encoding scheme `...' unknown}
38290
38291 %LTOUTENC
38292 %\item[] \textmess{Encoding file ... not found. You might have misspelt the
38293 % name of the encoding.}
38294
38295
38296 %LTDEFNS %LTERROR %LTMISCEN
38297 \item[]\index{Environment ... undefined}
38298 \textmess{Environment ... undefined}
38299
38300 \ltx\ does not know the name of the argument of a \cmd{\begin}.
38301 You have probably misspelled it.
38302
38303
38304 %%%% FFFFFFFFFFFFFFFFFFFFF
38305
38306 %LTFILES
38307 \item[]\index{File not found ...}
38308 \textmess{File not found. Type X to quit or <RETURN> to proceed
38309 or enter new name (Default extension: ...)}
38310
38311 \ltx\ cannot find the file you requested. The extension \file{tex}
38312 results from a problematic \cmd{\input} or \cmd{\include}; the extension
38313 \file{sty} from a \cmd{\usepackage} and an extension \file{cls}
38314 from a \cmd{\documentclass}.
38315
38316 %LTERROR %LTOUTPUT
38317 \item[]\index{Float(s) lost}
38318 \textmess{Float(s) lost}
38319
38320 Usually caused by having too many \cmd{\marginpar}s on a page.
38321
38322 %LTFSSBAS
38323 %\item[] \textmess{Font family `..+..' unknown}
38324
38325 %LTFSSTRC
38326 %\item[] \textmess{Font ... not found}
38327
38328
38329
38330 %%%% IIIIIIIIIIIIIIIIII
38331
38332 %LTERROR
38333 \item[]\index{Illegal character ...}
38334 \textmess{Illegal character in array argument}
38335
38336 There is an illegal character in the argument of an \Ie{array} or
38337 \Ie{tabular} environment, or in the second argument of a
38338 \cmd{\multicolumn} command.
38339
38340 %LTFILES
38341 \item[]\index{\cs{include} cannot be nested}
38342 \textmess{\cmd{\include} cannot be nested}
38343
38344 A file that is \cmd{\include}d cannot \cmd{\include} any other files.
38345
38346
38347 %%%%% LLLLLLLLLLLLLLLL
38348
38349 %LTCLASS
38350 \item[]\index{\cs{LoadClass} in package file}
38351 \textmess{\cmd{\LoadClass} in package file}
38352
38353 This is an error in a package file you are using
38354 (you can only use \cmd{\LoadClass} in a class file). Complain to the author.
38355
38356 %LTLISTS
38357 \item[]\index{Lonely \cs{item} ...}
38358 \textmess{Lonely \cmd{\item} --- perhaps a missing list environment}
38359
38360 An \cmd{\item} command appears to be outside any list environment.
38361
38362
38363 %%%% MMMMMMMMMMMMMMMM
38364
38365 %LTFSSBAS
38366 %\item[] \textmess{Math alphabet identifier ...is undefined in math version `...'}
38367 % (Check the spelling or use the \cmd{\SetMathAlphabet} command)
38368
38369 %LTFSSBAS %LTFSSDCL
38370 %\item[] \textmess{Math version `..' is not defined} (misspelled or need a package)
38371
38372
38373 %LTERROR
38374 \item[]\index{Missing \senv{document}}
38375 \textmess{Missing \cs{begin}\{document\}}
38376
38377 If you haven't forgotten \senv{document} then there is something
38378 wrong in the preamble as \ltx\ is trying to typeset something before
38379 the document starts. This is often caused by missing the backslash from
38380 a command, misplaced braces round an argument, a stray character, or
38381 suchlike.
38382
38383 \item[]\index{Missing @-exp ...}
38384 \textmess{Missing @-exp in array argument}
38385
38386 The \texttt{@} character is not followed by an \pixatexp{}
38387 in the argument of an \Ie{array} or
38388 \Ie{tabular} environment, or in the second argument of a
38389 \cmd{\multicolumn} command.
38390
38391 \item[]\index{Missing p-arg ...}
38392 \textmess{Missing p-arg in array argument}
38393
38394 There is a \texttt{p} not followed by braces
38395 in the argument of an \Ie{array} or
38396 \Ie{tabular} environment, or in the second argument of a
38397 \cmd{\multicolumn} command.
38398
38399 %%%% NNNNNNNNNNNNNNNN
38400
38401 %LTERROR
38402 \item[]\index{No counter ... defined}
38403 \textmess{No counter ... defined}
38404
38405 The argument to a \cmd{\setcounter} or \cmd{\addtocounter}
38406 command, or in the optional argument to \cmd{\newcounter}
38407 or \cmd{\newtheorem} is not the name of a counter. Perhaps you
38408 misspelled the name.
38409 However, if the error occured while an \file{aux} file was being read
38410 then you might well have used a \cmd{\newcounter} in an \cmd{\include}d file.
38411
38412
38413 %LTFSSDCL
38414 %\item[] \textmess{Not a command name: \cs{...}}
38415
38416 %LTFSSTRC
38417 %\item[] \textmess{No declaration for shape ...}
38418
38419 %LTPLAIN
38420 \item[]\index{No room for a new ...}
38421 \textmess{No room for a new ...}
38422
38423 \tx\ is limited in the numbers of different things it can handle. You
38424 might not recognize the thing that the message mentions as some of them are
38425 hidden in \ltx. The \ltx\ \texttt{counter} uses a \tx\ \cmd{\count} for
38426 example, and a length is a \tx\ \cmd{\skip}. Most things are limited to a
38427 maximum of 256 but there can be no more than 16 files open for reading
38428 and 16 for writing.
38429
38430 %LTSECT
38431 \item[]\index{No title given?No \cs{title} given}
38432 \textmess{No \cmd{\title} given}
38433
38434 You did not put a \cmd{\title} command before using \cmd{\maketitle}.
38435
38436
38437 %LTERROR
38438 \item[]\index{Not in outer par mode}
38439 \textmess{Not in outer par mode}
38440
38441 There is a float (e.g., a \Ie{figure} or a \cmd{\marginpar})
38442 in math mode or in a parbox (e.g., in another float).
38443
38444
38445 %%%% OOOOOOOOOOOOOOOO
38446
38447 %LTHYPHEN
38448 %\item[] \textmess{OOPS! I can't find any hyphenation patterns for US English.
38449 % Think of getting some otherwise latex2e setup will never succeed.}
38450
38451
38452 %LTCLASS
38453 \item[]\index{Option clash for ...}
38454 \textmess{Option clash for ...}
38455
38456 The same package was used twice but with different options. It is possible
38457 for one package to use another package which might be the cause if you
38458 can't see anything obvious.
38459
38460 %%%% PPPPPPPPPPPPPPPPPP
38461
38462 %LTOUTPUT
38463 \item[]\index{Page height already too large}
38464 \textmess{Page height already too large}
38465
38466 You are trying to use \cmd{\enlargethispage} when the page is already
38467 too large.
38468
38469
38470 %LTERROR
38471 \item[]\index{pushtabs and poptabs don't match?\cs{pushtabs} and \cs{poptabs} don't match}
38472 \textmess{\cmd{\pushtabs} and \cmd{\poptabs} don't match}
38473
38474 There are unmatched \cmd{\pushtabs} and \cmd{\poptabs} in a
38475 \Ie{tabbing} environment.
38476
38477
38478 %%%% RRRRRRRRRRRRRRRR
38479
38480 %LTCLASS
38481 \item[]\index{RequirePackage or LoadClass in Options Section?\cs{RequirePackage} or \cs{LoadClass} in Options Section}
38482 \textmess{\cmd{\RequirePackage} or \cmd{\LoadClass} in Options Section}
38483
38484 This is a problem in a class or package file. Complain to the author.
38485
38486 %%%% SSSSSSSSSSSSSSSS
38487
38488 %LTERROR
38489 \item[]\index{Something's wrong ...}
38490 \textmess{Something's wrong --- perhaps a missing \cmd{\item}}
38491
38492 This can be caused by not starting a list environment, such as \Ie{itemize}
38493 with a \cmd{\item} command, or by omitting the argument to the
38494 \Ie{thebibliography} environment. There are many other non-obvious
38495 causes, such as calling some macro that ends up using \cmd{\addvspace}
38496 or \cmd{\addpenalty} when not in \texttt{vmode}.
38497
38498 %LTOUTPUT
38499 \item[]\index{Suggested extra height ...}
38500 \textmess{Suggested extra height (...) dangerously large}
38501
38502 \ltx\ is concerned that you a trying to increase the page size
38503 too much with the \cmd{\enlargthispage} command.
38504
38505
38506 %LTFSSDCL
38507 %\item[] \textmess{Symbol font ... not defined}
38508
38509 %%%% TTTTTTTTTTTTTTTT
38510
38511 %LTERROR %LTTAB
38512 \item[]\index{Tab overflow}
38513 \textmess{Tab overflow}
38514
38515 In the \Ie{tabbing} environment a \cmd{\=} has exceeded \ltx's maximum
38516 number of tab stops.
38517
38518
38519 %LTCLASS
38520 \item[]\index{The file needs format ...}
38521 \textmess{The file needs format ... but this is ...}
38522
38523 The document uses a document class or package that is not compatible
38524 with the version of \ltx\ you are using. If you are using only standard
38525 files then there is a problem with your \ltx\ installation.
38526
38527 %LTFNTCMD
38528 %\item[] \textmess{The font size command \cmd{\normalsize} is not defined:
38529 % there is probably something wrong with the class file}
38530
38531 %LTERROR
38532 \item[]\index{There's no line to end here}
38533 \textmess{There's no line to end here}
38534
38535 A \cmd{\newline} or \cmd{\\} appears in vertical mode, for example
38536 between paragraphs. Or perhaps you have tried to put \cmd{\\} immediately
38537 after an \cmd{\item} to start the text on a new line. If this is the case,
38538 then try this:
38539 \begin{lcode}
38540 \item \mbox{} \\
38541 ...
38542 \end{lcode}
38543
38544 %LTERROR
38545 \item[]\index{This may be a LaTeX bug}
38546 \textmess{This may be a LaTeX bug} % (in output routine)
38547
38548 This is a message you don't want to see as it is produced by the
38549 output routine --- perhaps the most obscure part of \ltx. It is probably
38550 due to an earlier error. If it is the first error, though, and you can't
38551 see anything wrong, ask for somebody's help.
38552
38553 %LTFSSDCL
38554 %\item[] \textmess{This NFSS system isn't set up properly} (For encoding scheme ...
38555 % .../.../... do not form a valid font shape)
38556
38557 %LTFSSDCL
38558 %5\item[] \textmess{This NFSS system isn't set up properly}
38559 % (The system manitainer forgot
38560 % to specify a suitable substitution font shape using the
38561 % \cmd{\DeclareErrorFont} command)
38562
38563 %LTERROR
38564 \item[]\index{Too deeply nested}
38565 \textmess{Too deeply nested}
38566
38567 There are too many list environments nested within each other. At least
38568 four levels are usually available but some list environments are not obvious
38569 (for example the \Ie{quotation} environment is actually a list).
38570
38571 %LTMATH
38572 \item[]\index{Too many columns ...}
38573 \textmess{Too many columns in eqnarray environment}
38574
38575 An \Ie{eqnarray} environment has three \texttt{\&} column separators
38576 with no \cmd{\\} between.
38577
38578 %LTFSSDCL
38579 %\item[] \textmess{Too many math alphabets used in version ...}
38580
38581 %LTERROR
38582 \item[]\index{Too many unprocessed floats}
38583 \textmess{Too many unprocessed floats}
38584
38585 There may be too many \cmd{\marginpar}s to fit on a page, but it's more
38586 likely that \ltx\ hasn't been able to find locations for printing all the
38587 figures or tables. If one float cannot be placed, all later ones are saved
38588 until \ltx\ runs out of storage space. See \Sref{sec:floatplace} for
38589 details on how \ltx\ decides to place a float.
38590
38591 %LTCLASS
38592 \item[]\index{Two documentclass commands?Two \cs{documentclass} commands}
38593 \textmess{Two \cmd{\documentclass} commands}
38594
38595 Your document has two \cmd{\documentclass} commands; only one is
38596 permitted.
38597
38598
38599 %LTCLASS
38600 \item[]\index{Two LoadClass commands?Two \cmd{\LoadClass} commands}
38601 \textmess{Two \cmd{\LoadClass} commands}% (only one allowed)
38602
38603 This is an error in the class file. Complain to the author.
38604
38605 %%%% UUUUUUUUUUUUUUUUUUUUUUUUUUU
38606
38607 %LTFSSTRC
38608 %\item[] \textmess{Undefined font size function ...}
38609
38610 %LTERROR
38611 \item[]\index{Undefined tab position}
38612 \textmess{Undefined tab position}
38613
38614 A \cmd{\>}, \cmd{\+}, \cmd{\-}, or \cmd{\<} tabbing command
38615 is trying to move to a tab position that has not been defined by a
38616 \cmd{\=} command.
38617
38618 %LTCLASS
38619 \item[]\index{Unknown option ...}
38620 \textmess{Unknown option ... for class/package ...}
38621
38622 You have asked for an option that the class or package does not know about.
38623 Perhaps you have mispelled something, or omitted a comma.
38624
38625 %LTFSSDCL
38626 %\item[] \textmess{Unknown symbol font ...}
38627
38628 %LTCLASS
38629 \item[]\index{usepackage before documentclass?\cs{usepackage} before \cs{documentclass}}
38630 \textmess{\cmd{\usepackage} before \cmd{\documentclass}}
38631
38632 In general, the \cmd{\usepackage} command can only be used in the
38633 preamble\index{preamble}.
38634
38635 %%%% VVVVVVVVVVVVVVVVVVVVVVVVVVVVV
38636
38637 %LTMISCEN
38638 \item[]\index{verb ended by end of line?\cs{verb} ended by end of line}
38639 \textmess{\cs{verb} ended by end of line}
38640
38641 The argument of a \piif{verb} command runs past the end of the line.
38642 Perhaps you forgot to put in the correct ending character.
38643
38644 %LTMISCEN
38645 \item[]\index{verb illegal in command argument?\cs{verb} illegal in command argument}
38646 \textmess{\cs{verb} illegal in command argument}
38647
38648 A \piif{verb} cannot be part of the argument to another command.
38649
38650
38651 %%%%%%%%%%%%%%%%%%%%% TBD
38652
38653
38654
38655 %LTVERS
38656 %\textmess{LaTeX source files more than 1 year old!}
38657
38658
38659
38660 %LTFSSCMP
38661 %\textmess{*** What's this? NFSS release 0? ***}
38662
38663 %LTFSSCMP
38664 %\textmess{*** NFSS release 1 command ... found
38665 % *** Recovery not possible. Use ...}
38666
38667 %LTFSSCMP
38668 %\textmess{*** NFSS release 1 command \cmd{\newmathalphabet} found
38669 % *** Automatic recovery not possible}
38670
38671 \end{plainlist}
38672
38673 \index{error!LaTeX?\ltx|)}
38674 \index{LaTeX?\ltx!error|)}
38675
38676
38677 \section{\ltx\ warnings}
38678
38679 \index{warning!LaTeX?\ltx|(}
38680 \index{LaTeX?\ltx!warning|(}
38681
38682 Most warnings are given at the point in the document where
38683 a potential problem is discovered, while others are output
38684 after the document has been processed.
38685
38686 For example, the following code
38687 \begin{lcode}
38688 ... \ref{joe}... \cite{FRED96} ...
38689 \end{lcode}
38690 may produce warnings like
38691 \begin{lcode}
38692 Latex Warning: Reference `joe' on page 12 undefined
38693 on input line 881.
38694 Latex Warning: Citation `FRED96' on page 12 undefined
38695 at lines 890--897.
38696 \end{lcode}
38697 during the document processing, and then at the end there will also
38698 be the warning:
38699 \begin{lcode}
38700 LaTeX Warning: There were undefined references.
38701 \end{lcode}
38702
38703 Some warning messages pinpoint where a problem might lie, as in the citation
38704 warning above, while others make no attempt to do so. In the alphabetical
38705 listing that follows I have not included such information, even if it is
38706 supplied.
38707
38708 \begin{plainlist}
38709 %%%% AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
38710
38711 %LTOUTPUT
38712 %\item[] \textmess{Active ... character found while output routine is active.
38713 % This may be a bug in a package you are using}
38714
38715
38716 %%%% BBBBBBBBBBBBBBBBBBBBBB
38717
38718
38719 %%%% CCCCCCCCCCCCCCCCCCCCCCC
38720
38721 %LTBIBL
38722 \item[]\index{Citation ... on page ...}
38723 \textmess{Citation ... on page ... undefined}
38724
38725 The key in a \cmd{\cite} command was not defined by any \cmd{\bibitem}.
38726
38727 %LTBIBL
38728 \item[]\index{Citation ... undefined}
38729 \textmess{Citation ... undefined}
38730
38731 The key in a \cmd{\cite} command was not defined by any \cmd{\bibitem}.
38732
38733 %LTDEFNS
38734 %\item[] \textmess{Command ... has changed. Check if current package is valid}
38735 % (from \cmd{\CheckCommand})
38736
38737 %LTFSSBAS
38738 \item[]\index{Command ... invalid ...}
38739 \textmess{Command ... invalid in math mode}
38740
38741 The command is not permitted in math mode but was used there anyway.
38742 Remember that font size commands and \cmd{\boldmath} or \cmd{\unboldmath}
38743 cannot be used in math mode.
38744
38745
38746 %LTFSSTRC
38747 %\item[] \textmess{Command \cmd{\tracingfonts} not provided. Use the 'tracefnt'
38748 % package. Command found: ...}
38749
38750 %%%% EEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEE
38751
38752 %LTFSSDCL
38753 %\item[] \textmess{Encoding ... has changed to ... for symbol font ...
38754 % in the math version ...}
38755
38756
38757 %%%% FFFFFFFFFFFFFFFFFFFFFFFFFFFF
38758
38759 %LTCLASS
38760 %\item[] \textmess{File ... already exits on the system. Not generating it from this source}
38761
38762 %LTFLOAT
38763 \item[]\index{Float too large ...}
38764 \textmess{Float too large for page by ...}
38765
38766 A float (table or figure) is too tall to fit properly on a page by
38767 the given amount. It is put on a page by itself.
38768
38769
38770 %LTFSSTRC
38771 \item[]\index{Font shape ...}
38772 \textmess{Font shape ... in size ... not available size ... substituted}
38773
38774 You asked for a font size that was not available. The message also
38775 says what font is being used instead.
38776
38777 %LTFSSBAS
38778 \item[]\index{Font shape ...}
38779 \textmess{Font shape ... undefined using ... instead}
38780
38781 You asked for a font shape that was not available. The message also
38782 says what font is being used instead.
38783
38784 %%%% HHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHH
38785
38786 %LTOUTPUT
38787 \item[]\index{h float specifier ...}\index{"!h float specifier ...}
38788 \textmess{h float specifier changed to ht} or
38789 \textmess{!h float specifier changed to !ht}
38790
38791 A float has an optional \texttt{h} or \texttt{!h} argument but
38792 as it wouldn't fit on the curent page it has been moved to the top
38793 pf the next page.
38794
38795
38796 %%%% IIIIIIIIIIIIIIIIIIIIIIIIII
38797
38798 %LTFILES
38799 %\item[] \textmess{Inputting ... instead of obsolete ...}
38800
38801 %%%% LLLLLLLLLLLLLLLLLLLLLLLLLLL
38802
38803 %LTXREF
38804 \item[]\index{Label ... multiply defined}
38805 \textmess{Label ... multiply defined}
38806
38807 Two \cmd{\label} or \cmd{\bibitem} commands have the same argument
38808 (at least during the previous \ltx\ run).
38809
38810 %LTMISCEN
38811 \item[]\index{Label(s) may have changed ...}
38812 \textmess{Label(s) may have changed. Rerun to get cross-references right}
38813
38814 This is only output at the end of the run.
38815
38816 One of the numbers printed by \cmd{\cite}, \cmd{\ref}
38817 or \cmd{\pageref} commands might be incorrect because the correct values
38818 have changed since the preceding \ltx\ run.
38819
38820
38821 %%%% MMMMMMMMMMMMMMMMMMMMMMMMMMMMM
38822
38823 %LTOUTPUT
38824 \item[]\index{Marginpar on page ...}
38825 \textmess{Marginpar on page ... moved}
38826
38827 A \cmd{\marginpar} was moved down the page to avoid overwriting an earlier
38828 one. The result will not be aligned with the \cmd{\marginpar} call.
38829
38830 %%%% NNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNN
38831
38832 %LTSECT
38833 \item[]\index{No author given?No \cs{author} given}
38834 \textmess{No \cmd{\author} given}
38835
38836 There is no \cmd{\author} command before calling \cmd{\maketitle}.
38837
38838 %LTOUTPUT
38839 \item[]\index{No positions in optional float specifier ...}
38840 \textmess{No positions in optional float specifier.
38841 Default added (so using `tbp')}
38842
38843 You have used an empty optional argument to a float, for example: \\
38844 \verb?\begin{figure}[]? \\
38845 so it has used \\
38846 \verb?\begin{figure}[tbp]? \\
38847 instead.
38848
38849 %%%% OOOOOOOOOOOOOOOOOOOOO
38850
38851 %LTOUTPUT
38852 \item[]\index{Optional argument of twocolumn ...?Optional argument of \cs{twocolumn} ...}
38853 \textmess{Optional argument of \cmd{\twocolumn} too tall on page ...}
38854
38855 The contents of the optional argument to \cmd{\twocolumn} was too
38856 long to fit on the page.
38857
38858 %LTPICTUR
38859 \item[]\index{oval, circle, or line size unavailable?\cs{oval}, \cs{circle}, or \cs{line} size unavailable}
38860 \textmess{\cmd{\oval}, \cmd{\circle}, or \cmd{\line} size unavailable}
38861
38862 You have asked for too large (or too small) an oval or circle,
38863 or too short a line, in a \Ie{picture}.
38864
38865 %%%% RRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRR
38866
38867 %LTXREF
38868 \item[]\index{Reference ... on page ...}
38869 \textmess{Reference ... on page ... undefined}
38870
38871 The argument of a \cmd{\ref} or \cmd{\pageref} has not been defined
38872 on the preceding run by a \cmd{\label} command.
38873
38874 %%%% SSSSSSSSSSSSSSSSSSSSSS
38875
38876 %LTFINAL
38877 \item[]\index{Size substitutions ....}
38878 \textmess{Size substitutions with differences up to ... have occured.
38879 Please check the transcript file carefully and redo the
38880 format generation if necessary!}
38881
38882 This is only output at the end of the run.
38883
38884 Some fonts have had to be used as substitutes for requested ones and
38885 they are a different size.
38886
38887 %LTFSSBAS
38888 \item[]\index{Some shapes ...}
38889 \textmess{Some shapes were not available, defaults substituted}
38890
38891 This is only output at the end of the run.
38892
38893 At least one font had to be substituted.
38894
38895 %%%% TTTTTTTTTTTTTTTTTTTTTTTTTTTTTTT
38896
38897 %LTOUTPUT
38898 \item[]\index{Text page ... contains only floats}
38899 \textmess{Text page ... contains only floats}
38900
38901 The page should have included some textual material but there was
38902 no room for it.
38903
38904 %LTXREF
38905 \item[]\index{There were multiply defined labels}
38906 \textmess{There were multiply defined labels}
38907
38908 This is only output at the end of the run.
38909
38910 Two or more \cmd{\label} or \cmd{\cite} commands had the same argument.
38911
38912 %LTXREF
38913 \item[]\index{There were undefined references}
38914 \textmess{There were undefined references}
38915
38916 This is only output at the end of the run.
38917
38918 There was at least one \cmd{\ref} or \cmd{\pageref} or \cmd{\cite}
38919 whose argument had not been defined
38920 on the preceding run by a \cmd{\label} or \cmd{\biblabel} command.
38921
38922 %%%% UUUUUUUUUUUUUUUUUUUUUUUUUUUU
38923
38924 %LTFILES
38925 \item[]\index{Unused global option(s) ...}
38926 \textmess{Unused global option(s) [...]}
38927
38928 The listed options were not known to the document class or any packages
38929 you used.
38930
38931 %%%% WWWWWWWWWWWWWWWWWWWWWWWWWWWWWWW
38932
38933 %LTCLASS
38934 %\item[] \textmess{Writing text ... before \cs{end}\{...\} as last line of ...}
38935
38936
38937 %%%% YYYYYYYYYYYYYYYYYYYYYYYYYYYYYY
38938
38939 %LTCLASS
38940 %\item[] \textmess{You have requested class/package ... but the class/package provides ...}
38941
38942 %LTCLASS
38943 \item[]\index{You have requested release ...}
38944 \textmess{You have requested release ... of LaTeX but only release ... is available}
38945
38946 You are using a class or package that requires a later release of \ltx\
38947 than the one you are using. You should get the latest release.
38948
38949 %LTCLASS
38950 \item[]\index{You have requested version ...}
38951 \textmess{You have requested version ... of class/package ... but only version
38952 ... is available}
38953
38954 You (or the class or one of the packages you are using) needs a later
38955 release of a class or package than the one you are using. You should get
38956 the latest release.
38957
38958 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
38959
38960 %%LTCLASS
38961 %\textmess{... has been converted to Blank ...3e}
38962
38963
38964 %%LTFSSCMP
38965 %\textmess{*** NFSS release 1 command ... found
38966 % *** Update by using release 2 command ...}
38967
38968
38969 \end{plainlist}
38970
38971 \index{LaTeX?\ltx!warning|)}
38972 \index{warning!LaTeX?\ltx|)}
38973
38974 \section{Class errors}
38975
38976 %%\index{memoir class!error|(}
38977 \Iclasssub{memoir}{error|(}
38978 \index{error!memoir class|(}
38979
38980 The class errors introduce themselves differently from those
38981 that \ltx\ finds. Instead of starting with \\
38982 \verb?! LaTeX Error:? \\
38983 the class errors start with \\
38984 \verb?! Class memoir Error:? \\
38985 After that, it is indistinguishable from a \ltx\ error.
38986 For example, if you ever happened to input the
38987 next line as line 954 in your document you would get the error message
38988 that follows \\
38989 \verb?\sidecapmargin{either}?
38990 \begin{verbatim}
38991 ! Class memoir Error: Unrecognized argument for \sidecapmargin.
38992
38993 See the memoir class documentation for explanation.
38994 Type H <return> for immediate help.
38995 ...
38996
38997 l.954 \sidecapmargin{either}
38998 ?
38999 \end{verbatim}
39000 If you then typed \texttt{H} (or \texttt{h}) in response you would
39001 get the following helpful message:
39002 \begin{lcode}
39003 Try typing <return> to proceed.
39004 If that doesn't work, type X <return> to quit.
39005 ?
39006 \end{lcode}
39007 The majority of the help messages follow this formula, so I have
39008 not noted them in the alphabetical listing below.
39009
39010
39011 %%%%%\subsection{Errors}
39012
39013 \begin{plainlist}
39014
39015 \item[]\index{... is negative}
39016 \textmess{... is negative}
39017
39018 The value is negative. It should be at least zero.
39019
39020 \item[]\index{... is not a counter}
39021 \textmess{... is not a counter}
39022
39023 An argument that should be the name of a counter is not.
39024
39025 \item[]\index{... is zero or negative}
39026 \textmess{... is zero or negative}
39027
39028 The value must be greater than zero.
39029
39030
39031 \item[]\index{>\lb...\rb at wrong position ...}
39032 \textmess{>\{...\} at wrong position: token ignored}
39033
39034 A \verb?>{...}? in the argument to an \Ie{array} or \Ie{tabular}
39035 is incorrectly placed and is being ignored.
39036
39037 \item[]\index{<\lb...\rb at wrong position ...}
39038 \textmess{<\{...\} at wrong position: changed to !\{...\}}
39039
39040 A \verb?<{...}? in the argument to an \Ie{array} or \Ie{tabular}
39041 is incorrectly placed. It has been changed to \verb?!{...}? instead.
39042
39043 \item[]\index{A pattern has not been specified}
39044 \textmess{A pattern has not been specified}% (\cmd{\getstar@vsindent}
39045
39046 You are trying to use the \Ie{patverse} or \Ie{patverse*} environment
39047 without having first defined a pattern.
39048
39049 \item[]\index{Argument to \cs{setsidecappos} is not ...}
39050 \textmess{Argument to \cmd{\setsidecappos} is not t or c or b}
39051
39052 The argument will be assumed to be \texttt{c}.
39053
39054 \item[]\index{Argument to \cs{overridesidecapmargin} neither ...}
39055 \textmess{Argument to \cmd{\overridesidecapmargin} neither left nor right}
39056
39057 The argument to \cmd{\overridesidecapmargin} must be either
39058 \texttt{left} or \texttt{right}. The attempted override will be ignored.
39059
39060
39061 \item[]\index{Cannot change a macro that has delimited arguments}
39062 \textmess{Cannot change a macro that has delimited arguments}
39063
39064 You are using \cmd{patchcmd} on a macro that has delimted arguments.
39065
39066 \item[]\index{Empty preamble: `l' used}
39067 \textmess{Empty preamble: `l' used} % (array/tabular)
39068
39069 The argument to an \Ie{array} or \Ie{tabular} is empty. The
39070 specification \verb?{l}? is being used instead.
39071
39072 \item[]\index{Font command ... is not supported}
39073 \textmess{Font command ... is not supported}
39074
39075 You have tried to use a deprecated font command. Either replace
39076 it with the current font command or declaration or use
39077 the \Lopt{oldfontcommands} class option.
39078
39079 \item[]\index{footskip is too large ...?\cs{footskip} is too large ...}
39080 \textmess{\lnc{\footskip} is too large for \lnc{\lowermargin} by ...}
39081
39082 The \lnc{\footskip} is too large for the \lnc{\lowermargin}. Either
39083 increase the \lnc{\lowermargin} or decrease the \lnc{\footskip}.
39084
39085
39086 \item[]\index{headheight and/or headsep are too large ...?\cs{headheight} and/or \cs{headsep} are too large ...}
39087 \textmess{\lnc{\headheight} and/or \lnc{\headsep} are too large for
39088 \lnc{\uppermargin} by ...}
39089
39090 The sum of the \lnc{\headheight} and the \lnc{\headsep} is
39091 larger than the \lnc{\uppermargin}. Either increase the \lnc{\uppermargin}
39092 or reduce the others.
39093
39094
39095 \item[]\index{Illegal pream-token ...}
39096 \textmess{Illegal pream-token (...): `c' used}
39097
39098 An illegal character is used in the argument to an \Ie{array}
39099 or \Ie{tabular}. The `c' specifier is being used instead
39100 (which centers the column).
39101
39102
39103 \item[]\index{Index ... outside limits ...}
39104 \textmess{Index ... outside limits for array ...} % (\cmd{\checkarrayindex}
39105
39106 Trying to access an index for the array data structure that is not between
39107 the low and high indices.
39108
39109
39110 \item[]\index{Limits for array ... }
39111 \textmess{Limits for array ... are in reverse order}
39112
39113 The low index is not less than the high index in \cmd{\newarray}.
39114
39115
39116 \item[]\index{Missing arg: token ignored}
39117 \textmess{Missing arg: token ignored} % (array/tabular)
39118
39119 The argument to a column specifier for a \Ie{array} or \Ie{tabular}
39120 is missing.
39121
39122
39123
39124 \item[]\index{No array called ...}
39125 \textmess{No array called ...} % (\cmd{\checkarrayindex}
39126
39127 You have tried to access an unknown array data structure.
39128
39129
39130 \item[]\index{Not defined: ...}
39131 \textmess{Not defined: ...}
39132
39133 You are using \cmd{\patchcmd} on a macro that is not defined.
39134
39135 \item[]\index{Not redefinable: ...}
39136 \textmess{Not redefinable: ...}
39137
39138 You are using \cmd{\patchcmd} on a macro that it is unable to
39139 modify.
39140
39141
39142
39143 \item[]\index{Only one column-spec. allowed}
39144 \textmess{Only one column-spec. allowed}% (array/tabular)
39145
39146 There can only be one column specifier in a \cmd{\multicolumn}.
39147
39148 \item[]\index{Optional argument is not one of: ...}
39149 \textmess{Optional argument is not one of: classic, fixed, lines,
39150 or nearest. I will assume the default.}
39151
39152 You have provided an unknown name for the optional argument to
39153 \cmd{\checkthelayout}. The default \texttt{classic} will be used instead.
39154
39155
39156 \item[]\index{paperheight and/or trimtop are too large ...?\cs{paperheight} and/or \cs{trimtop} are too large ...}
39157 \textmess{\lnc{\paperheight} and/or \lnc{\trimtop} are too large for
39158 \lnc{\stockheight} by ...}
39159
39160 The sum of the \lnc{\paperheight} and the \lnc{\trimtop} is
39161 larger than the \lnc{\stockheight}. Either increase the \lnc{\stockheight}
39162 or reduce the others.
39163
39164 \item[]\index{paperwidth and/or trimedge are too large ...?\cs{paperwidth} and/or \cs{trimedge} are too large ...}
39165 \textmess{\lnc{\paperwidth} and/or \lnc{\trimedge} are too large for
39166 \lnc{\stockwidth} by ...}
39167
39168 The sum of the \lnc{\paperwidth} and the \lnc{\trimedge} is
39169 larger than the \lnc{\stockwidth}. Either increase the \lnc{\stockwidth}
39170 or reduce the others.
39171
39172 \item[]\index{spinemargin and/or textwidth and/or foremargin are too large ...?\cs{spinemargin} and/or \cs{textwidth} and/or \cs{foremargin} are too large ...}
39173 \textmess{\lnc{\spinemargin} and/or \lnc{\textwidth} and/or \lnc{\foremargin}
39174 are too large for \lnc{\paperwidth} by ...}
39175
39176 The sum of the \lnc{\spinemargin} and the \lnc{\textwidth}
39177 and the \lnc{\foremargin} is
39178 larger than the \lnc{\paperwidth}. Either increase the \lnc{\paperwidth}
39179 or reduce the others.
39180
39181
39182 \item[]\index{The combination of argument values ...}
39183 \textmess{The combination of argument values is ambiguous.
39184 The lengths will be set to zero}
39185 % (\cmd{\setrectanglesize}, \cmd{\setfillsize})
39186
39187 The combination of values in the arguments to one of the commands
39188 for page layout does not make sense.
39189
39190 \item[]\index{The `extrafontsizes' option ...}
39191 \textmess{The `extrafontsizes' option is required to use the `...pt' option}
39192
39193 If you want to use a `...pt' class option greater than \Lopt{25pt}
39194 you also have to use the \Lopt{extrafontsizes} option. The class will
39195 use the \Lopt{17pt} option.
39196
39197
39198 \item[]\index{Unknown document division ...}
39199 \textmess{Unknown document division name (...)}
39200
39201 You have used an unknown division name in the argument to
39202 \cmd{\settocdepth} or \cmd{\setsecnumdepth} and friends. If you haven't
39203 mistyped it you will have to use \cmd{\setcounter} instead.
39204
39205 \item[]\index{Unknown mark setting type ...}
39206 \textmess{Unknown mark setting type `...' for ...mark}
39207
39208 In \cmd{\createmark} or \cmd{\createplainmark} the mark setting
39209 type should have been \texttt{left} or \texttt{both}
39210 or \texttt{right}. The class will use \texttt{both}.
39211
39212 \item[]\index{Unknown numbering type ...}
39213 \textmess{Unknown numbering type ... for ...mark}
39214
39215 In \cmd{\createmark} the class expected either \texttt{shownumber} or
39216 \texttt{nonumber} for displaying the number. It will use
39217 \texttt{shownumber}.
39218
39219 \item[]\index{Unrecognized argument for \cs{sidecapmargin}}
39220 \textmess{Unrecognized argument for \cmd{\sidecapmargin}}
39221
39222 The argument to \cmd{\sidecaption} should be \texttt{left} or
39223 \texttt{right} or \texttt{inner} or \texttt{outer}.
39224
39225 \item[]\index{uppermargin and/or textheight and/or lowermargin are too large ...?\cs{uppermargin} and/or \cs{textheight} and/or \cs{lowermargin} are too large ...}
39226 \textmess{\lnc{\uppermargin} and/or \lnc{\textheight} and/or
39227 \lnc{\lowermargin} are too large for \lnc{\paperheight} by ...}
39228
39229 The sum of the \lnc{\uppermargin} and the \lnc{\textheight}
39230 and the \lnc{\lowermargin} is
39231 larger than the \lnc{\paperheight}. Either increase the \lnc{\paperheight}
39232 or reduce the others.
39233
39234 \item[]\index{You have used the `*pt' option but file ...}
39235 \textmess{You have used the `*pt' option but file ... can't be found}
39236
39237 You have used the \Lopt{*pt} option but the corresponding
39238 \pixfile{clo} file can't be found. Check your definitions of
39239 \cmd{\anyptfilebase} and \cmd{\anyptsize}. The \pixfile{mem10.clo}
39240 file will be used instead.
39241
39242 \item[]\index{XeTeX is required to process this document}
39243 \textmess{XeTeX is required to process this document}
39244
39245 The document needs to be processed via \pixxetx. Try using
39246 \texttt{xelatex} instead of \texttt{(pdf)latex}, or try removing
39247 any \pixxetx\ packages from the document.
39248
39249
39250
39251 \end{plainlist}
39252
39253
39254 \index{error!memoir class|)}
39255 %%\index{memoir class!error|)}
39256 \Iclasssub{memoir}{error|)}
39257
39258 \section{Class warnings}
39259
39260 %%\index{memoir class!warning|(}
39261 \Iclasssub{memoir}{warning|(}
39262 \index{warning!memoir class|(}
39263
39264 These are introduced by \verb?Class memoir Warning:?
39265
39266 For example
39267 \verb?\addtodef{alf}{\joe}{fred}? will produce a message along the lines of:
39268 \begin{verbatim}
39269 Class memoir Warning: `alf' is not a macro on input line 91.
39270 \end{verbatim}
39271 while
39272 \verb?\addtodef{\joe}{alf}{fred}? might produce:
39273 \begin{verbatim}
39274 Class memoir Warning: `\joe' is not a macro on input line 97.
39275 \end{verbatim}
39276
39277 The following is an alphabeticised list of the class warnings.
39278
39279 \begin{plainlist}
39280
39281 %%%%%%%%%%%%%%%%%%%%%%%
39282
39283 \item[]\index{... at index ... in pattern ...}
39284 \textmess{... at index ... in pattern ... is not a digit}% (\cmd{\get@vsindent}
39285
39286 The character at the given position in the verse pattern is not a digit.
39287
39288 \item[]\index{... is not a macro}
39289 \textmess{... is not a macro}
39290
39291 Using \cmd{\addtodef} or \cmd{\addtoiargdef} you have tried to extend
39292 the definition of an unknown macro.
39293
39294 \item[]\index{... is not an input stream}
39295 \textmess{... is not an input stream}
39296
39297 You are trying to access a non-existent input stream.
39298
39299 \item[]\index{... is not an output stream}
39300 \textmess{... is not an output stream}% (\cmd{\outstre@mandopen}, \cmd{\outstre@mandclosed}
39301
39302 You are trying to access a non-existent output stream.
39303
39304 \item[]\index{Bad \cs{sidebarmargin} argument}
39305 \textmess{Bad \cs{sidebarmargin} argument}
39306
39307 The argument to \cs{sidebarmargin} is not recognized. The class
39308 will use \texttt{right}.
39309
39310
39311 \item[]\index{Characters dropped after \eenv{...}}
39312 \textmess{Characters dropped after \eenv{...}} % (\cmd{\verbatim@rescan}
39313
39314 At the end of a \Ie{verbatim} environment there should be no characters
39315 after the \eenv{...} on the same line.
39316
39317 \item[]\index{Column ... is already defined}
39318 \textmess{Column ... is already defined} % (tabulars
39319
39320 The column type has been defined by a previous \cmd{\newcolumntype}.
39321
39322
39323 \item[]\index{Counter ... already defined}
39324 \textmess{Counter ... already defined}
39325
39326 For information only, the counter in \cmd{\providecounter}
39327 is already defined.
39328
39329 \item[]\index{Do not use footnote ...?Do not use \cs{footnote} ...}
39330 \textmess{Do not use \cmd{\footnote} in \cmd{\maketitle}. Use \cmd{\thanks} instead}
39331
39332 You cannot use \cmd{\footnote} in any of the \cmd{\maketitle} elements
39333 (i.e., \cmd{\title} or \cmd{\author} or \cmd{\date}) but you can use
39334 \cmd{\thanks}.
39335
39336 \item[]\index{Empty `thebibliography' environment}
39337 \textmess{Empty `thebibliography' environment}
39338
39339 There are no \cmd{\bibitem}s in the \Ie{thebibliography} environment.
39340
39341 \item[]\index{Environment ... already defined}
39342 \textmess{Environment ... already defined}% (\cmd{\m@mprovenv}
39343
39344 For information only, the environment in \cmd{\provideenvironment}
39345 is already defined.
39346
39347
39348 \item[]\index{Index ... for pattern ...}
39349 \textmess{Index ... for pattern ... is out of bounds}% (\cmd{\get@vsindent}
39350
39351 The index for the verse pattern is either too low or too high.
39352
39353 \item[]\index{Input stream ... is already defined}
39354 \textmess{Input stream ... is already defined}
39355
39356 You are trying to use \cmd{\newinputstream} to create an already existing
39357 input stream.
39358
39359 \item[]\index{Input stream ... is not open}
39360 \textmess{Input stream ... is not open}% (\cmd{\instre@mandopen}
39361
39362 You are trying to access or close an input stream that is closed.
39363
39364 \item[]\index{Input stream ... is open}
39365 \textmess{Input stream ... is open}% (\cmd{\instre@mandclosed}
39366
39367 You are trying to open an input stream that is already open.
39368
39369 \item[]\index{Length ... already defined}
39370 \textmess{Length ... already defined}
39371
39372 For information only, the length in \cmd{\providelength}
39373 is already defined.
39374
39375
39376
39377 \item[]\index{Marginpar on page ...}
39378 \textmess{Marginpar on page ... moved by ...}
39379
39380 A marginal note has been lowered by the given amount to avoid overwriting
39381 a previous note; the moved note will not be aligned with its \cmd{\marginpar}.
39382 (This is a more informative message than the normal \ltx\ one.)
39383
39384 \item[]\index{No more to read from stream ...}
39385 \textmess{No more to read from stream ...}% (\cmd{\readaline})
39386
39387 There is nothing left in the stream to be read.
39388
39389 \item[]\index{Optional argument of twocolumn ...?Optional argument of \cs{twocolumn} ...}
39390 \textmess{Optional argument of \cmd{\twocolumn} too tall on page ...}% (\cmd{\@topnewpage}
39391
39392 The contents of the optional argument to \cmd{\twocolumn} was too
39393 long to fit on the page.
39394
39395 \item[]\index{Output stream ... is already defined}
39396 \textmess{Output stream ... is already defined}
39397
39398 You are trying to use \cmd{\newoutputstream} to create an already existing
39399 output stream.
39400
39401 \item[]\index{Output stream ... is not open}
39402 \textmess{Output stream ... is not open}% (\cmd{\outstre@mandopen}
39403
39404 You are trying to access or close an output stream that is closed.
39405
39406 \item[]\index{Output stream ... is open}
39407 \textmess{Output stream ... is open}% (\cmd{\outstre@mandclosed}
39408
39409 You are trying to open an output stream that already open.
39410
39411 \item[]\index{Redefining primitive column ...}
39412 \textmess{Redefining primitive column ...} % (tabulars
39413
39414 The argument to \cmd{\newcolumntype} is one of the basic column types.
39415
39416
39417
39418 \item[]\index{Stream ... is not open}
39419 \textmess{Stream ... is not open}% (\cmd{stre@mverb@input} \cmd{\stre@mbvin}
39420
39421 You are trying to access a stream, either input or output, that is closed.
39422
39423
39424 \item[]\index{The ... font command is deprecated ...}
39425 \textmess{The ... font command is deprecated. Use ... or ... instead}
39426
39427 You are using a deprecated font command. Consider using one of the
39428 alternatives.
39429
39430 \item[]\index{The counter will not be printed ...}
39431 \textmess{The counter will not be printed. The label is: ...}% (\cmd{\@@enum@}
39432
39433 The optional \meta{style} argument to the \Ie{enumerate} environment
39434 does not include one of the special characters.
39435
39436 \item[]\index{Undefined index file ...}
39437 \textmess{Undefined index file ...}% (\cmd{\@index}, \cmd{\@spindex}
39438
39439 You are trying to add an index entry to an unknown \file{idx} file.
39440
39441
39442 \item[]\index{Unknown toclevel for ...}
39443 \textmess{Unknown toclevel for ...}
39444
39445 The division name you have used for \cmd{\settocdepth} is not
39446 recognized.
39447
39448
39449
39450 \item[]\index{verb may be unreliable ...?\cs{verb} may be unreliable ...}
39451 \textmess{\cs{verb} may be unreliable inside tabularx}
39452
39453 A \cs{verb} in a \Ie{tabularx} may work, but may not.
39454
39455 \item[]\index{X columns too narrow ...}
39456 \textmess{X columns too narrow (table too wide)} % (tabulars
39457
39458 The width of the X columns in a \Ie{tabularx} had to be made too narrow.
39459
39460 \end{plainlist}
39461
39462 \index{warning!memoir class|)}
39463 %%\index{memoir class!warning|)}
39464 \Iclasssub{memoir}{warning|)}
39465
39466 %#% extend
39467 %#% extstart include comments.tex
39468
39469 \svnidlong
39470 {$Ignore: $}
39471 {$LastChangedDate: 2025-08-06 18:23:54 +0200 (Wed, 06 Aug 2025) $}
39472 {$LastChangedRevision: 857 $}
39473 {$LastChangedBy: [email protected] $}
39474
39475 \chapter{Comments}
39476 \label{cha:comments}
39477
39478 \section{Algorithms}
39479 \label{sec:algorithms}
39480
39481 Over time we may use this section to explain, or list some of the
39482 algorithms for some of the macros in the class. The information may be
39483 useful to some.
39484
39485 \subsection{Autoadjusting
39486 \texorpdfstring{\cs{marginparwidth}}{\textbackslash marginparwidth}}
39487 \label{sec:auto-csmarg}
39488
39489 This algorithm is used within \cmd{\fixthelayout} unless the user have
39490 used \cmd{\setmarginnotes}.
39491
39492 \noindent
39493 \begin{framed}
39494 \vskip-2\baselineskip
39495 \begin{small}
39496 \begin{verbatim}
39497 IF twocolumn THEN:
39498 marginparwidth = min{inner margin,outer margin}
39499 ELSE
39500 IF twoside THEN:
39501 IF marginpar always left or always right THEN:
39502 marginparwidth = min{inner margin,outer margin}
39503 ELSE IF marginpar in outer margin THEN:
39504 marginparwidth = outer margin
39505 ELSE IF marginpar in inner margin THEN:
39506 marginparmargin = inner margin
39507 END IF
39508 ELSE
39509 IF marginpar in left margin THEN:
39510 marginparwidth = inner margin
39511 ELSE
39512 marginparwidth = outer margin
39513 END IF
39514 END IF
39515 END IF
39516 marginparwidth = marginparwidth - 2marginparsep
39517 IF marginparwidth < 1pt THEN:
39518 marginparwidth = 1pt
39519 END IF
39520 \end{verbatim}
39521 \end{small}
39522 \end{framed}
39523
39524
39525 %#% extend
39526
39527 %#% extstart input backend.tex
39528
39529
39530 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
39531 %%\endinput
39532 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
39533
39534 %%%%%%%%% end mbooka
39535 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
39536
39537 % back end
39538 \backmatter
39539
39540 \PWnote{2009/07/08}{Changed \cs{toclevel@section} so that Notes
39541 divisions appear in the bookmarks}
39542 \makeatletter\renewcommand*{\toclevel@chapter}{-1}\makeatother
39543 \makeatletter\renewcommand*{\toclevel@section}{0}\makeatother
39544 \clearpage
39545 \printpagenotes
39546 \clearpage
39547 \pagestyle{plainmarkruled}
39548 %%\chapterstyle{section}
39549
39550 \renewcommand*{\begintheglossaryhook}{\small}
39551 %%%\glossaryintoc
39552 \printglossary
39553
39554 \renewcommand{\prebibhook}{%
39555 \ctan\ is the \cTeXan. Information on how to
39556 access CTAN is available at \url{http://www.tug.org}.
39557 \par\vspace{\onelineskip}}
39558
39559
39560
39561 % bibliopgraphy
39562 \bibliography{memrefs}
39563
39564
39565 \clearpage
39566 \twocolindex
39567 \pagestyle{index}
39568 %\renewcommand{\chaptermark}[1]{}
39569 \renewcommand{\preindexhook}{%
39570 The first page number is usually, but not always, the primary reference to
39571 the indexed topic.\vskip\onelineskip}
39572 \indexintoc
39573
39574 %%%\raggedright does nasty things to index entries
39575 \printindex
39576
39577 \onecolindex
39578 \renewcommand*{\preindexhook}{}
39579 \renewcommand*{\indexname}{Index of first lines}
39580 %%% \indexintoc
39581
39582
39583 \makeatletter
39584 \renewcommand{\doidxbookmark}[1]{{\def\@tempa{Symbols}\def\@tempb{#1}%
39585 \centering\bfseries \ifx\@tempa\@tempb %
39586 Analphabetics
39587 % \phantomsection%
39588 % \pdfbookmark[0]{Analphabetics}{Analphabetics-idx}%
39589 % \label{AnalphabeticsAnalphabeticsAnalphabetics-idx}%
39590 \else
39591 #1%
39592 % \phantomsection%
39593 % \pdfbookmark[0]{#1}{#1-idx}%
39594 % \label{#1#1#1-idx}%
39595 \fi%
39596 \vskip\onelineskip\par}}
39597 \makeatother
39598
39599
39600 \printindex[lines]
39601
39602 \cleardoublepage
39603 \pagestyle{empty}
39604 \null\vfil
39605
39606 \begin{adjustwidth}{1in}{1in}
39607 \begin{center}
39608 {\Large\textsf{Colophon}}
39609 \end{center}
39610 \begin{center}
39611 This manual was typeset using the \ltx\ typesetting system
39612 created by Leslie Lamport and the \Mname\ class.
39613 The body text is set 10/12pt on a
39614 33pc measure with Palatino designed by Hermann Zapf, which includes
39615 italics and small caps. Other fonts include
39616 Sans, Slanted and Typewriter from Donald Knuth's
39617 Computer Modern family.
39618
39619 \end{center}
39620
39621
39622 \end{adjustwidth}
39623
39624
39625
39626
39627
39628 \vfil
39629
39630 %#% extend
39631
39632
39633 \end{document}
39634
39635 \endinput
39636
39637
39638 %%% Local Variables:
39639 %%% mode: latex
39640 %%% TeX-master: t
39641 %%% TeX-source-specials-mode: t
39642 %%% TeX-PDF-mode: t
39643 %%% End: