diff options
author | Karl Berry <karl@freefriends.org> | 2006-01-09 00:49:07 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2006-01-09 00:49:07 +0000 |
commit | 007f67a693e4d031fd3d792df8e4d5f43e2cb2e7 (patch) | |
tree | 90d17e00e572ecb1e24764b6f29c80e098b08d29 /Master/texmf-dist/doc/latex/memoir/memman.tex | |
parent | 950209b26f70aa87ed07c54f82a95b6f03b7c3a0 (diff) |
doc/latex
git-svn-id: svn://tug.org/texlive/trunk@84 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/latex/memoir/memman.tex')
-rw-r--r-- | Master/texmf-dist/doc/latex/memoir/memman.tex | 17911 |
1 files changed, 17911 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/latex/memoir/memman.tex b/Master/texmf-dist/doc/latex/memoir/memman.tex new file mode 100644 index 00000000000..2a8b26a5708 --- /dev/null +++ b/Master/texmf-dist/doc/latex/memoir/memman.tex @@ -0,0 +1,17911 @@ +% memman.tex edition 6, Memoir class user manual +% Author: Peter Wilson +% Copyright 2001, 2002, 2003, 2004 Peter R. wilson + +\documentclass[10pt,letterpaper]{memoir} +%%%%\usepackage{memfixa} +%%%%\usepackage{memfixc} +%%\usepackage{makeidx} +\usepackage{layouts}[2001/04/29] +%%\usepackage{verbatim} +\usepackage{url} +\usepackage{fixltx2e} +\usepackage{alltt} +\usepackage{graphicx} +\makeindex + +%%%%%%\usepackage{amsmath} + +\ifpdf + \pdfoutput=1 + \usepackage[plainpages=false,pdfpagelabels,bookmarksnumbered]{hyperref} + \usepackage{memhfixc} +\fi + +%\showindexmarktrue + +\newcommand{\theclass}{memoir} + +\providecommand{\tx}{TeX} +\providecommand{\ltx}{LaTeX} + + +\makeatletter + +%%% Print and Index macros +\newcommand{\Ppstyle}[1]{\textsl{#1}} +\newcommand{\pstyle}[1]{\Ppstyle{#1}% + \index{#1 pages?\Ppstyle{#1} (pagestyle)}% + \index{pagestyle!#1?\Ppstyle{#1}}} % pagestyle +\newcommand{\Pcstyle}[1]{\textsl{#1}} +\newcommand{\cstyle}[1]{\Pcstyle{#1}% + \index{#1 chaps?\Pcstyle{#1} (chapterstyle)}% + \index{chapterstyle!#1?\Pcstyle{#1}}} % chapterstyle +\newcommand{\Pclass}[1]{\textsf{#1}} +\newcommand{\Lclass}[1]{\Pclass{#1}% + \index{#1 class?\Pclass{#1} (class)}% + \index{class!#1?\Pclass{#1}}} % class name +\newcommand{\Ppack}[1]{\textsf{#1}} +\newcommand{\Lpack}[1]{\Ppack{#1}% + \index{#1 pack?\Ppack{#1} (package)}% + \index{package!#1?\Ppack{#1}}} % package name +\newcommand{\Popt}[1]{\textsf{#1}} +\newcommand{\Lopt}[1]{\Popt{#1}% + \index{#1 opt?\Popt{#1} (option)}% + \index{option!#1?\Popt{#1}}} % option name +\newcommand{\Ie}[1]{\texttt{#1}\index{#1 env?\texttt{#1} (environment)}% + \index{environment!#1?\texttt{#1}}} +\newcommand{\Icn}[1]{\texttt{#1}\index{#1 cou?\texttt{#1} (counter)}% + \index{counter!#1?\texttt{#1}}} +\newcommand{\Itt}[1]{\texttt{#1}\index{#1tt?\texttt{#1}}} + +% print and index an \if... \piif{if...} or friend (e.g., \else) +\newcommand{\piif}[1]{\cs{#1}\index{#1?\cs{#1}}} + +%%%\newcommand{\seealso}[2]{\emph{see also} #1} + +\newcommand{\listofx}{`List of\ldots'} + +% print a begin environment +\newcommand{\senv}[1]{\texttt{\bs begin\{#1\}}} + +% print an end environment +\newcommand{\eenv}[1]{\texttt{\bs end\{#1\}}} + +% print a file name +\newcommand{\file}[1]{\texttt{#1}} + +% print and index a file name +\newcommand{\ixfile}[1]{\file{#1}% + \index{#1 file?\file{#1} (file)}% + \index{file!#1?\file{#1}}} + +% print & index CTT +\newcommand{\ctt}{\textsc{ctt}} +\newcommand{\pictt}{\ctt\index{CTT?\ctt}} + +% index marking +\newcommand{\idxmark}[1]{#1\markboth{#1}{#1}} + +\newcommand{\foredge}{foredge} +\newlength{\pwlayi}\setlength{\pwlayi}{0.45\textwidth} % +\newlength{\pwlayii}\setlength{\pwlayii}{0.45\pwlayi} + +%% definition of \meta is taken from doc.dtx +\begingroup +\obeyspaces% +\catcode`\^^M\active% +\gdef\meta{\begingroup\obeyspaces\catcode`\^^M\active% +\let^^M\do@space\let \do@space% +\def\-{\egroup\discretionary{-}{}{}\hbox\bgroup\itshape}% +\m@ta}% +\endgroup +\def\m@ta#1{\leavevmode\hbox\bgroup$\langle$\itshape#1\/$\rangle$\egroup + \endgroup} +\def\do@space{\egroup\space + \hbox\bgroup\itshape\futurelet\next\sp@ce} +\def\sp@ce{\ifx\next\do@space\expandafter\sp@@ce\fi} +\def\sp@@ce#1{\futurelet\next\sp@ce} +%% end of \meta and supports + + +%% The definition of \MakeShortVerb & \DeleteShortVerb +%% are now in the memoir class. + +%% The macros \cmd, \cs, \marg, \oarg, \parg are taken from ltxdoc.dtx +% \cmd{\fred} typesets \fred +\def\cmd#1{\cs{\expandafter\cmd@to@cs\string#1}} +\def\cmd@to@cs#1#2{\char\number`#2\relax} +% \cs{fred} typesets \fred +\DeclareRobustCommand{\cs}[1]{\texttt{\char`\\#1}} +% \marg{arg} typesets {<arg>} +\providecommand{\marg}[1]{% + {\ttfamily\char`\{}\meta{#1}{\ttfamily\char`\}}} +% \oarg{arg} typesets [<arg>] +\providecommand{\oarg}[1]{% + {\ttfamily\char`\[}\meta{#1}{\ttfamily\char`\]}} +% \parg{x,y} typesets (<x,y>) +\providecommand{\parg}[1]{% + {\ttfamily\char`\(}\meta{#1}{\ttfamily\char`\)}} + +\def\bs{\texttt{\char`\\}} + +%%% macro \cmd from Heiko Oberdiek CTT 2001/05/26 (prints and indexes a command) +\newcommand*{\cmdprint}[1]{\texttt{\string#1}} +\def\cmd#1{\cmdprint{#1}% + \index{\expandafter\@gobble\string#1?\string\cmdprint{\string#1}}} + +% print and index \\! +\newcommand{\pixslashbang}{\cmdprint{\\!}\index{"\"\"!?\string\cmdprint{\\}\texttt{"!}}} + +% print and index \! +\newcommand{\pixabang}{\cmdprint{\!}\index{"!?\string\cs{}\texttt{"!}}} + + +\newcommand{\lnc}[1]{\cmdprint{#1}% + \index{\expandafter\@gobble\string#1len?\string\cmdprint{\string#1} (length)}% + \index{length!\expandafter\@gobble\string#1len?\string\cmdprint{\string#1}}} + +%%%%%% stuff for new LaTeX code environment + +% \zeroseps sets list before/after skips to minimum values +\newcommand{\@zeroseps}{\setlength{\topsep}{\z@} + \setlength{\partopsep}{\z@} + \setlength{\parskip}{\z@}} +\newlength{\gparindent} \setlength{\gparindent}{\parindent} +% now we can do the new environment. This has no extra before/after spacing. +\newenvironment{lcode}{\@zeroseps + \renewcommand{\verbatim@startline}{\verbatim@line{\hskip\gparindent}} + \small\setlength{\baselineskip}{\onelineskip}\verbatim}% + {\endverbatim + \vspace{-\baselineskip}% + \noindent +} + +%%%%% LaTeX syntax +\newenvironment{syntax}{\begin{center} + \begin{tabular}{|p{0.9\linewidth}|} \hline}% + {\hline + \end{tabular} + \end{center}} + +\providecommand{\Note}{\textbf{NOTE:}} + + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +% Save file as: DROP.STY Source: FILESERV@SHSU.BITNET +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% DROP.DOC <February 17, 1988> +% Macro for dropping and enlarging the first letter(s) of a paragraph. +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% +% Macro written by David G. Cantor, and published Fri, 12 Feb 88, in +% TeXhax, 1988 #16. +% Internet: dgc@math.ucla.edu +% UUCP: ...!{ihnp4, randvax, sdcrdcf, ucbvax}!ucla-cs!dgc +% +% Modified for use with LaTeX by Dominik Wujastyk, February 17, 1988 +% Internet: dow@wjh12.harvard.edu +% Bitnet: dow@harvunxw.bitnet +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% +% This LaTeX macro is for dropping and enlarging the first letter(s) of a +% paragraph. The argument may be one or more letters. +% +% Here is an example of its usage: +% +% \documentstyle[drop]{article} +% \begin{document} +% \drop{IN} THE beginning God created the heaven and the earth. Now the +% earth was unformed and void, and darkness was upon the face of the +% deep; and the spirit of God hovered over the face of the waters. +% \end{document} +% +% Which will produce something along these lines: +% +% I I\ I THE beginning God created the heaven and the earth. +% I I \ I Now the earth was unformed and void, and darkness was +% I I \I upon the face of the deep; and the spirit of God hov- +% ered over the face of the waters. +% +% In the first instance the macro will pause during LaTeX processing and +% ask you for the font you wish to use for you drop capital. When you +% have something that looks good, then comment out box one in DROP.STY, +% and comment in box two, replacing "cmr10 scaled \magstep5" with the font +% of your choice. +% +% In my opinion (DW) there are no fonts available in the standard +% TeX/LaTeX set that are ideal for this use, unless you go down to 9pt or +% 8pt for your text face, and this is too small. If you have Metafont you +% should consider generating a cmr17 font at a magstep of two (about 25pt) +% or three (about 30pt), or even more, depending on the point size of your +% main text. Why not go the whole hog and design some really fancy +% capitals from scratch! +% +%%%%%%%%%%%%%%%%%%%%% BOX ONE %%%%%%%%%%%%%%%%%%%%%%%%% +%\typein[\dropinitialfont]{Font for Dropped initial:} % +%\font\largefont \dropinitialfont % +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% +%%%%%%%%%%%%%%%%%%%%% BOX TWO %%%%%%%%%%%%%%%%%%%%%%%%% +%\font\largefont= cmr10 scaled \magstep5 % +%\font\largefont= cmbx10 scaled \magstep5 % +%\font\largefont= cmbx17 scaled \magstep3 % +\font\largefont= cmr17 scaled \magstep5 % +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\def\drop#1#2{{\noindent + \setbox0\hbox{\largefont #1}\setbox1\hbox{#2}\setbox2\hbox{(}% + \count0=\ht0\advance\count0 by\dp0\count1\baselineskip + \advance\count0 by-\ht1\advance\count0by\ht2 + \dimen1=.5ex\advance\count0by\dimen1\divide\count0 by\count1 + \advance\count0 by1\dimen0\wd0 + \advance\dimen0 by.25em\dimen1=\ht0\advance\dimen1 by-\ht1 + \global\hangindent\dimen0\global\hangafter-\count0 + \hskip-\dimen0\setbox0\hbox to\dimen0{\raise-\dimen1\box0\hss}% + \dp0=0in\ht0=0in\box0}#2} + +% end of DROP.STY +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\newcommand{\versal}[1]{{\noindent + \setbox0\hbox{\largefont #1}% + \count0=\ht0 % height of versal + \count1=\baselineskip % baselineskip + \divide\count0 by \count1 % versal height/baselineskip + \dimen1 = \count0\baselineskip % distance to drop versal + \advance\count0 by 1\relax % no of indented lines + \dimen0=\wd0 % width of versal + \global\hangindent\dimen0 % set indentation distance + \global\hangafter-\count0 % set no of indented lines + \hskip-\dimen0\setbox0\hbox to\dimen0{\raise-\dimen1\box0\hss}% + \dp0=0in\ht0=0in\box0}} + +\makeatother + +\MakeShortVerb{\|} +% \DeleteShortVerb{\|} + + +%%% need more space for ToC page numbers +\setpnumwidth{2.55em} +\setrmarg{3.55em} + +%%% need more space for ToC section numbers +\cftsetindents{section}{1.5em}{3.0em} +\cftsetindents{subsection}{4.5em}{3.9em} +\cftsetindents{subsubsection}{8.4em}{4.8em} +\cftsetindents{paragraph}{10.7em}{5.7em} +\cftsetindents{subparagraph}{12.7em}{6.7em} + +%%% need more space for LoF numbers +\cftsetindents{figure}{0em}{3.0em} + +%%% and do the same for the LoT +\cftsetindents{table}{0em}{3.0em} + +%%% set up the page layout +\settrimmedsize{11in}{210mm}{*} +\setlength{\trimtop}{0pt} +\setlength{\trimedge}{\stockwidth} +\addtolength{\trimedge}{-\paperwidth} +\settypeblocksize{7.75in}{33pc}{*} +\setulmargins{4cm}{*}{*} +\setlrmargins{1.25in}{*}{*} +\setmarginnotes{17pt}{51pt}{\onelineskip} +\setheadfoot{\onelineskip}{2\onelineskip} +\setheaderspaces{*}{2\onelineskip}{*} +\checkandfixthelayout + + +\bibliographystyle{alpha} + +\newcommand{\prtoc}{ToC} % print ToC +\newcommand{\prlof}{LoF} +\newcommand{\prlot}{LoT} +\newcommand{\ixtoc}{\index{ToC}} % index ToC +\newcommand{\ixlof}{\index{LoF}} +\newcommand{\ixlot}{\index{LoT}} +\newcommand{\toc}{\prtoc\ixtoc} % print & index ToC +\newcommand{\lof}{\prlof\index{LoF}} +\newcommand{\lot}{\prlot\index{LoT}} + +\newcommand{\noidxnum}[1]{} + +%%% subfigures and subtables +\newsubfloat{figure} +\newsubfloat{table} + +%% end preamble +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\begin{document} +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +%% list subfigures +\setcounter{lofdepth}{2} + +\index{table of contents|see{ToC}} +\index{list!of figures|see{LoF}} +\index{figure!list of|see{LoF}} +\index{list!of tables|see{LoT}} +\index{table!list of|see{LoT}} +\index{marginal note|see{marginalia}} +\index{footnote!in title|see{thanks}} +\index{counter|noidxnum} +\index{environment|noidxnum} +\index{length|noidxnum} +\index{list|noidxnum} +\index{illustration|seealso{float, figure}} +\index{figure|seealso{float}} +\index{file|noidxnum} +\index{table|seealso{float}} +\index{chapter!style|see{chapterstyle}} +\index{chapter!heading|see{heading}} +\index{page!style|see{pagestyle}} +\index{part!heading|see{heading}} +\index{subfloat|noidxnum} + +%%% ToC down to subsections +\settocdepth{subsection} +\frontmatter +\pagestyle{empty} + + +% half-title page +\vspace*{\fill} +\begin{adjustwidth}{1in}{1in} +\begin{flushleft} +\HUGE\sffamily The +\end{flushleft} +\begin{center} +\HUGE\sffamily Memoir +\end{center} +\begin{flushright} +\HUGE\sffamily Class +\end{flushright} +\end{adjustwidth} +\vspace*{\fill} +\cleardoublepage + +% title page +\vspace*{\fill} +\begin{center} +\HUGE\textsf{The Memoir Class}\par +\end{center} +\begin{center} +\LARGE\textsf{for}\par +\end{center} +\begin{center} +\HUGE\textsf{Configurable Typesetting}\par +\end{center} + +\begin{center} +\Huge\textsf{User Guide}\par +\end{center} +\begin{center} +\LARGE\textsf{Peter Wilson}\par +\end{center} +\vspace*{\fill} +\begin{center} +\textrm{\normalsize T\kern-0.2em H\kern-0.4em P} \\ +\textsf{The Herries Press} +\end{center} +\clearpage + +% copyright page +\begingroup +\footnotesize +\setlength{\parindent}{0pt} +\setlength{\parskip}{\baselineskip} +%%\ttfamily +\textcopyright{} 2001, 2002, 2003, 2004 Peter R. Wilson \\ +All rights reserved + +The Herries Press, Normandy Park, WA. + +Printed in the World + +The paper used in this publication may meet the minimum requirements +of the American National Standard for Information +Sciences --- Permanence of Paper for Printed Library Materials, +ANSI Z39.48--1984. + +\begin{center} +10 09 08 07 06 05 04 03 02 01\hspace{2em}15 14 13 12 11 10 9 +\end{center} +\begin{center} +\begin{tabular}{ll} +First edition: & 3 June 2001 \\ +Second impression, with corrections: & 2 July 2001 \\ +Second edition: & 14 July 2001 \\ +Second impression, with corrections: & 3 August 2001 \\ +Third impression, with minor additions: & 31 August 2001 \\ +Third edition: & 17 November 2001 \\ +Fourth edition: & 16 March 2002 \\ +Fifth edition: & 10 August 2002 \\ +Sixth edition: & 31 January 2004 \\ +\end{tabular} +\end{center} + +\endgroup + +\clearpage +\vspace*{\fill} +\begin{quote} +\textbf{memoir,} \textit{n.} a written record set down as material + for a history or biography: + a biographical sketch: + a record of some study investigated by the writer: + (in \textit{pl.}) the transactions of a society. + [Fr. \textit{m\'{e}moire} --- L. \textit{memoria,} memory --- + \textit{memor}, mindful.] \\[0.5\baselineskip] + \hspace*{\fill} + \textit{Chambers Twentieth Century Dictionary, New Edition}, 1972. +\end{quote} + +\vspace{2\baselineskip} + +\begin{quote} +\textbf{memoir,} \textit{n.} [Fr. \textit{m\'{e}moire,} masc., a memorandum, + memoir, fem., memory $<$ L. \textit{memoria,} \textsc{memory}] + \hspace{1ex} \textbf{1.} a biography or biographical notice, + usually written by a relative or personal friend of the subject + \hspace{1ex} \textbf{2.} [\textit{pl.}] an autobiography, + usually a full or highly personal account + \hspace{1ex} \textbf{3.} [\textit{pl.}] a report or record of + important events based on the writer's personal observation, + special knowledge, etc. + \hspace{1ex} \textbf{4.} a report or record of a scholarly + investigation, scientific study, etc. + \hspace{1ex} \textbf{5.} [\textit{pl.}] the record of the proceedings + of a learned society \\[0.5\baselineskip] + \hspace*{\fill} \textit{Webster's New World Dictionary, Second College Edition}. +\end{quote} + +%\vspace{2\baselineskip} +% +%\begin{quote} +%\textbf{memoir,} \textit{n.} a fiction designed to flatter the subject +% and to impress the reader. \\[0.5\baselineskip] +%\hspace*{\fill} With apologies to Reuben Thomas and Ambrose Bierce +%\end{quote} + +\vspace*{\fill} + +\cleardoublepage + +% ToC, etc +\pagenumbering{roman} +\pagestyle{headings} +%%%%\pagestyle{Ruled} + +\tableofcontents +\clearpage +\listoffigures +\clearpage +\listoftables + +%\chapter{Foreword} +\chapter{Preface} + + From personal experience and also from lurking on the \url{comp.text.tex} +newsgroup the major problems with using LaTeX are related to document +design. Some years ago most questions on \texttt{ctt} were answered by +someone providing a piece of code that solved a particular problem, and +again and again. More recently these questions are answered along the +lines of `Use the ---------{} package', and again and again. + + I have used many of the more common of these packages but my filing system +is not always well ordered and I tend to mislay the various user manuals, +even for the packages I have written. The \Pclass{memoir} class is an attempt +to integrate some of the more design-related packages with the LaTeX +\Pclass{book} class. I chose the \Pclass{book} class as the \Pclass{report} class +is virtually identical to \Pclass{book}, except that \Pclass{book} does +not have an \Ie{abstract} environment while \Pclass{report} does; however it is +easy to fake an \Ie{abstract} if it is needed. With a little bit of tweaking, +\Pclass{book} class documents can be made to look just like \Pclass{article} +class documents, and the \Pclass{memoir} class is designed with tweaking very +much in mind. + + The \Pclass{memoir} class effectively incorporates the facilties that +are usually accessed by using external packages. In most cases the class +code is new code reimplementing package functionalities. The exceptions +tend to be where I have cut and pasted code from some of my packages. +I could not have written the \Pclass{memoir} class without the excellent +work presented by the implementors of LaTeX and its many packages. + + Apart from packages that I happen to have written I have gained many +ideas from the other packages listed in the \bibname. One way or another +their authors have all contributed, albeit unknowingly. +The participants in the +\url{comp.text.tex} newsgroup have also provided valuable input, partly +by questioning how to do something in LaTeX, and partly by providing +answers. It is a friendly and educational forum. + +{\raggedleft{\scshape Peter Wilson} \\ Seattle, WA \\ June 2001\par} + +\chapter{Introduction to the first edition} + + This is not a guide to the general use of LaTeX but rather concentrates +on where the \index{class}\Lclass{memoir} class differs from the standard LaTeX +\Lclass{book} and \Lclass{report} classes. There are other sources that deal with LaTeX in +general, some of which are listed in the \bibname. Lamport~\cite{LAMPORT94} +is of course the original user manual for LaTeX, while the Companion +series, for example~\cite{GOOSSENS94}, go into further details and auxiliary +programs. The Comprehensive TeX Archive Network (CTAN) is a valuable source +of free information and the LaTeX system itself. For general questions see +the FAQ~\cite{FAQ} which also has pointers to information sources. Among +these are \textit{The Not So Short Introduction to LaTeX2e}~\cite{LSHORT}, +Keith Reckdahl's \textit{Using imported graphics in LaTeX2e}~\cite{EPSLATEX} +and Piet van Oostrum's \textit{Page layout in LaTeX}~\cite{FANCYHDR}. +The question of how to use different fonts with LaTeX is left strictly alone; +Alan Hoenig's book~\cite{HOENIG98} is the best guide to this that I know of. + + + The first part of the manual discusses briefly some aspects of book +design and typography, independently of the means of typesetting. Among +the several books on the subject listed in the \bibname{} I prefer +Bringhurst's \textit{The Elements of Typographic Style}~\cite{BRINGHURST92}. +I have used the LaTeX \Lclass{book} design, which is the default +\Lclass{memoir} class style, in typesetting Part~\ref{part:art}. + + The second part then goes into some detail on how the \Lclass{memoir} +class can be used to implement a particular design. + + With two exceptions, the \Lclass{memoir} class has all the capabilities +of the standard LaTeX \Lclass{book} class. These exceptions are: +\begin{itemize} +\item The old LaTeX v2.09 font commands --- + \cmd{\rm} (roman), + \cmd{\tt} (\texttt{typewriter}), + \cmd{\sf} (\textsf{sans}), + \cmd{\bf} (\textbf{bold}), + \cmd{\sl} (\textsl{slanted}), + \cmd{\it} (\textit{italic}), + and \cmd{\sc} (\textsc{small caps}) --- + are not supported and will give error messages if used. + + The \cmd{\em} (\emph{emphasis}) command is supported but gives +a warning message if used. + +\item There are no commands for making titles. This is because title pages are + usually designed individually for each book. The + \index{package}\Lpack{titling} + package~\cite{TITLING} can be used if you want the titling commands. + The package + provides extended titling facilities when compared to those in the + standard LaTeX classes. + +\end{itemize} +I hope that, apart from these, the class supports everything that the +\Lclass{book} class provides. + + The major extra functions provided by the class include: +\begin{itemize} +\item Font sizes for the main text of 9, 10, 11, 12 and 14pt. +\item A reasonably intuitive means of setting the page, text and margin sizes. +\item Page trimming marks. +\item If really required, typesetting as though in the olden typewriter days + (double spaced, raggedright, no hyphenation, typewriter font). +\item Configurable sectional headings, with several predefined styles for + chapter headings and simple methods for defining new ones. +\item `Anonymous' section breaks (e.g., a blank or decorated line or two). +\item Configurable page headers and footers, with several predefined styles + and simple methods for defining new ones. +\item Configurable captions, with several predefined captioning styles and + methods for defining new ones. +\item Ability to define new `List of...' and new floats with their accompanying + captions and `List of...'. +\item Control over whether the `List of...', bibliography, index, etc., appear + in the Table of Contents. +\item Support for epigraphs. +\end{itemize} +Also, along the way you will find other more minor but still useful things. + + As Part~\ref{part:practice} progresses I demonstrate some of the changes +that the \Lclass{memoir} class lets you easily make to the normal LaTeX +page and titling style. + +\section{Type conventions} + + The following conventions are used in the manual: +\begin{itemize} +\item \Pclass{The names of LaTeX classes\index{class} and + packages\index{package} are typeset in this font.} +\item \Popt{Class options\index{option} are typeset in this font.} +\item \Ppstyle{The names of chapterstyles\index{chapterstyle} and + pagestyles\index{pagestyle} are typeset in this font.} +\item \texttt{LaTeX code is typeset in this font.} +\end{itemize} + +\section{Caveats} + + At the moment both this manual and the class code are in a beta state. +That is, they hopefully serve the purposes they are intended for, but +it is probable that there are errors, poor explanations and missing +elements. So, be warned that I'm sure that there will be further releases +and these may not be entirely compatible with the current release. + + That said, I will be grateful for any constructive comments that +anyone\footnote{I have received valuable comments from +Javier Bezos (\url{jbezos@wanadoo.es}), +Sven Bovin (\url{sven.bovin@chem.kuleuven.ac.be}), +Scott Pakin (\url{pakin@uiuc.edu}), +and +Paul Stanley (\url{pstanley@essexcourt-chambers.co.uk}) +.} +may have, especially regarding errors, mispeaking, and desireable +enhancements. I can be reached either by posting to \url{comp.text.tex} +or more directly at \url{peter.r.wilson@boeing.com}. + + TeX was designed principally for typesetting documents containing a +lot of mathematics. In such works the mathematics breaks up the flow +of the text on the page, and the vertical space required for displayed +mathematics is arbitrary. Most non-technical books are typeset on a fixed +grid as they do not have arbitrary insertions into the text. + + TeX is designed to handle arbitrary sized inserts in an elegant manner, +and does this by allowing vertical spaces to stretch and shrink a little +so that the actual height of the typeblock is constant. Therefore LaTeX, being +built on top of TeX, does not typeset on a fixed grid, and it would be a +very major task to try and make it do so; this has been tried but as far as +I know nobody has been successful. + + The manual includes many unbreakable names of LaTeX commands, +some of which stick out into the margin. The way of getting rid of these +is to rewrite the text so that they don't come at the end of a typeset +line. This is tedious and I haven't done it because I expect the manual +to be revised and that would throw off any hand tweaking done now. + +\chapter{Introduction to the second edition} + + Since the first edition of the manual was published the \Lclass{memoir} +class has undergone some changes and extensions. The changes, to remove +some unfortunate errors, are upwards compatible. The extensions, by +their nature, are not upward compatible. + + The main extensions and changes include: +\begin{itemize} +\item A \index{option}\Lopt{subfigure} option to counteract an unfortunate + interplay\footnote{Discovered by Ignasi Furi\'{o} Caldentey + (\url{ignasi@ipc4.uib.es}).} + if the \Lpack{subfigure} package is used with the class. + +\item An \Lopt{article} option so that \Lclass{article} class typesetting + may be simulated. + +\item Incorporation of the essential code from the \Lpack{titling} + package~\cite{TITLING} (to support the \Lopt{article} option). + +\item Incorporation of the essential code from the \Lpack{abstract} + package~\cite{ABSTRACT} (to support the \Lopt{article} option). + +\end{itemize} + + The description of how to modify the \prtoc, \prlof{} and \prlot{} headings +in the first edition was completely wrong, as was the corresponding +description of the \cmd{\newlistof} macro. No noticeable +changes have been made to the class code but the descriptions now +reflect reality. I must have been a few bricks short of a full load when +I wrote the original. + + There are other more minor changes and extensions\footnote{With thanks +to, among others, Kevin Lin (\url{kevinlin@runtop.com.tw}) and +Adriano Pascoletti (\url{pascolet@dimi.uniud.it}).} +which you may find if you recall the first edition. + + There was no mention of typesetting verse in the first edition, +although the class does provide the normal LaTeX \Ie{verse} +environment. A poem +is usually individually typeset as the appearance often has an +effect on the emotional response when reading it. The \Lpack{verse} +package~\cite{VERSE} may be useful when typesetting poetry. + +\chapter{Introduction to the third edition} + + Since the second edition of the manual was published the \Lclass{memoir} +class has been upgraded from beta code to a production release. Extensions +have been made to both the class and this manual. + + The main extensions and changes include: +\begin{itemize} +\item An \Lopt{openleft} option to enable chapters to start + on verso pages. + +\item Incorporation of the essential code from the \Lpack{verse} + package~\cite{VERSE} for more flexibility when typesetting + poetry. + +\item Replacement of the macro called \cmd{\makepshook} by + \cmd{\makepsmarks}. Note that this is a non-upward compatible + change. + +\item The first part of the manual has been reorganised and + extended, principally + by providing more typesetting examples. + +\item As usual, minor glitches have been removed from both the code + and the manual; each revision, of course, eliminates the gap between + advertisement and reality. + +\end{itemize} + + + There are other more minor changes and extensions\footnote{With thanks +to, among others, Ignasi Furi\'{o} Caldentey (\url{ignasi@ipc4.uib.es}), +Daniel Richard G. (\url{skunk@mit.edu}) and +Vladimir Ivanovic (\url{vladimir@acm.org}).} +which you may find if you recall the second edition. + +\chapter{Introduction to the fourth edition} + + Since the third edition of the manual was published the \Lclass{memoir} +class has been upgraded from version~1.0 to version~1.1. Modifications +have been made to both the class and this manual. + + The main extensions and changes include: +\begin{itemize} +\item The \Lopt{subfigure} option is no longer required. + +\item Subfloats have been added to the class. Steve Cochran kindly gave + permission for me to use some of his \Lpack{subfigure} package + code for this. + +\item Some packages still use the old, deprecated LaTeX version~2.09 + font commands. I have reluctantly introduced an option + to enable the old, deprecated font commands to be used. + +\item The class now works harmoniously with the \Lpack{natbib} + package~\cite{NATBIB}. + +\item As usual, minor glitches have been removed from both the code + and the manual; each revision hopefully eliminates the gap between + advertisement and reality. + +\end{itemize} + + + There are other more minor changes and extensions\footnote{With thanks +to, among others, +William Adams (\url{WillAdams@aol.com}) +Ignasi Furi\'{o} Caldentey (\url{ignasi@ipc4.uib.es}), +Steven Douglas Cochran (\url{sdc+@cs.cmu.edu}), +Henrik Holm (\url{henrik@tele.ntnu.no}), +and Rolf Niepraschk (\url{niepraschk@ptb.de}). +} +which you may find if you have used earlier editions. + +\chapter{Introduction to the fifth edition} + + Since the fourth edition of the manual was published the \Lclass{memoir} +class has been upgraded from version~1.1 to version~1.2. Modifications +have been made to both the class and this manual. + + The main extensions and changes include: +\begin{itemize} +\item The size options have been extended\footnote{At the + request of Vittorio De Martino whose children use LaTeX + for their school projects.} + to include a \Lopt{17pt} option. + +\item A few font sizes corresponding to the font size commands (e.g., \verb?\Large?) + have been changed to give regular steps between sizes. + +\item Boxes that can break over pages and/or contain verbatim text. + +\item Several ways of dealing with verbatim text, including footnotes + that can contain verbatim text. + +\item Some control over the typesetting of footnotes. Unfortunately + this necessitated some changes in the methods for styling + thanks notes. + +\item Comment environments. + +\item Convenient methods for file input and output. + +\item Additional \verb?\provide...? commands. + +\item The \Ie{description} environment has been modified to match + the appearance of the standard environment. The original + \Lclass{memoir} form is still available as the \Ie{blockdescription} + environment. + +\item A new optional argument has been added to the \cmd{\chapter} and + \cmd{\chapter*} commands for setting header texts. + +\end{itemize} + + As usual, minor glitches have been removed from both the code +and the manual. Hopefully, new ones have not been introduced. + +\chapter{Introduction to the sixth edition} + + Since the fifth edition of the manual was published the \Lclass{memoir} +class has been upgraded from version~1.2 to version~1.6. +Many new functions have +been added to the class and this manual has been updated to reflect all +the additions. + + The main extensions and changes include: +\begin{itemize} + +\item Major extensions for typesetting arrays and tabulars, including + continuous tabulars and automatic tabulation. + +\item Major extensions to footnote styles and the ability to have + multiple series of footnotes. + +\item Major extensions for indexing, including one column and multiple indexes. + +\item Major extensions to crop marks. + +\item \verb?\tableofcontents? and friends can be used multiple times. + +\item Section titles (as well as numbers) can be referenced. + +\item Sheet numbers and access to the numbers of the last sheet and last page. + +\item Various methods for formatting numbers. + +\item Better cooperation with the \Lpack{chapterbib} and \Lpack{natbib} packages. + +\end{itemize} + + There are many more minor additions. + As usual, glitches have been removed from both the code +and the manual. Hopefully, new ones have not been introduced. + + + Many people have contributed to the \Lclass{memoir} class and this manual +in the forms of code, solutions to problems, suggestions for new functions, +bringing my attention to errors and infelicities in the code +and manual, and last but not least in simply being encouraging. +I am very grateful to the following for all they have done, whether they +knew it or not: +Paul Abrahams, +William Adams, +Donald Arseneau, +Jens Berger, +Karl Berry, +Javier Bezos, +Sven Bovin, +Alan Budden, +Ignasi Furi\'{o} Caldenty, +Ezequiel Mart\'{\i}n C\'{a}mara, +David Carlisle, +Steven Douglas Cochran, +Michael Downes, +Victor Eijkhout, +Danie Els, +Robin Fairbairns, +Simon Fear, +Kai von Fintel, +Daniel Richard G, +Romano Giannetti, +Kathryn Hargreaves, +Sven Hartrumpf, +Florence Henry, +Cartsten Heinz, +Peter Heslin, +Morton H\o{}gholm, +Henrik Holm, +Vladimir Ivanovich, +Stefan Kahrs, +J\o{}gen Larsen, +Kevin Lin, +Matthew Lovell, +Daniel Luecking, +Lars Madsen, +Vittorio De Martino, +Frank Mittelbach, +Rolf Niepraschk, +Patrik Nyman, +Heiko Oberdiek, +Scott Pakin, +Adriano Pascoletti, +Robert, +Chris Rowley, +Bernd Raichle, +Doug Schenck, +Rainer Sch\"{o}pf, +Paul Stanley, +Reuben Thomas, +Bastiaan Niels Veelo, +Emanuele Vicentini, +J\"{u}rgen Vollmer, +and others. + +If I have inadvertently left anyone off the list I apologise, +and please let me know so that I can correct the omisssion. + + Of course, none of this would have been possible without Donald Knuth's +TeX system and the subsequent development of LaTeX by Leslie Lamport. + + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\chapter{Terminology} +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + + Like all professions and trades, typographers and printers have their +specialised vocabulary. + + First there is the question of pages, leaves and sheets. +The trimmed sheets of paper\index{paper} that make up a book are called +\emph{leaves}\index{leaf}, +and I will call the untrimmed sheets the \emph{stock}\index{stock} material. +A leaf +has two sides, and a \emph{page}\index{page} is one side of a leaf. +If you think of a book +being opened flat, then you can see two leaves. The front of the righthand +leaf, is called the \emph{recto}\index{recto} page of that leaf, +and the side of the +lefthand leaf that you see is called the \emph{verso}\index{verso} page +of that leaf. +So, a leaf has a recto and a verso page. Recto pages are the odd-numbered +pages and verso pages are even-numbered. + + Then there is the question of folios. The typographical term for +the number of a page is \emph{folio}\index{folio}. +This is not to be confused with +the same term as used in `Shakespeare's First Folio' where the reference is +to the height and width of the book, nor to its use in the phrase +`\emph{folio} signature'\index{signature} where the term refers to the +number of times a printed sheet is folded. +Not every page in a book has a printed +folio, and there may be pages that do not have a folio at all. Pages with +folios, whether printed or not, form the \emph{pagination}\index{pagination} +of the book. Pages +that are not counted in the pagination have no folios. + + A \emph{font}\index{font} is a set of characters. In the days of +metal type and hot lead a font meant a complete alphabet and auxiliary +characters in a given size. More recently it is taken to mean a complete +set of characters regardless of size. A font of roman type normally +consists of CAPITAL LETTERS, \textsc{small capitals}, lowercase letters, +numbers, punctuation marks, ligatures (such as `fi' and `ffi'), and a +few special symbols like \&. + A \emph{font family}\index{font!family} is a set of fonts designed to +work harmoniously together, such as a pair of roman and italic fonts. + + The size of a font\index{font} is expressed in points\index{point} +(72.27 points equals 1 inch +equals 25.4 millimeters). The size is a rough indication of the height +of the tallest character, but different fonts with the same size may have +very different actual heights. + + The typographers' and printers' term for the vertical space between +the lines of normal text is \emph{leading}\index{leading}, which is also +usually expressed in points and is usually larger than the font size. +A convention for describing the font and leading is give the font size +and leading separated by a slash; for instance $10/12$ for a +10pt font set with a 12pt leading, or $12/14$ for a 12pt font set with a +14pt leading. + + The normal length of a line of text is often called the +\emph{measure}\index{measure} and is normally specified in terms of +picas\index{pica} where 1 pica equals 12 points (1pc = 12pt). + + Documents may be described as being typeset with a particular font +with a particular size and a particular leading on a particular measure; +this is normally given in a shorthand form. +A 10pt font with 11pt leading on a 20pc measure is described as +$10/11 \times 20$, and $14/16 \times 22$ describes a 14pt font +with 16pt leading set on a a 22pc measure. + +\section{Units of measurement} + + Typographers and printers use a mixed system of units, some of which +we met above. The fundamental unit is the point; \tref{tab:units} lists +the most common units employed. + +\begin{table} +\centering +\caption{Printers units} \label{tab:units} +\begin{tabular}{ll} \hline +Name (abbreviation) & Value \\ \hline +point (pt)\index{point}\index{pt} & \\ +pica (pc)\index{pica}\index{pc} & 1pc = 12pt \\ +inch (in)\index{inch}\index{in} & 1in = 72.27pt \\ +centimetre (cm)\index{centimetre}\index{cm} & 2.54cm = 1in \\ +millimetre (mm)\index{millimetre}\index{mm} & 10mm = 1cm \\ +big point (bp)\index{big point}\index{bp} & 72bp = 72.27pt \\ +didot point (dd)\index{didot point}\index{dd} & 1157dd = 1238pt \\ +cicero (cc)\index{cicero}\index{cc} & 1cc = 12dd \\ +\hline +\end{tabular} +\end{table} + + Points\index{point} and picas\index{pica} +are the traditional printers units used in English-speaking countries. +The didot point\index{didot point} and cicero\index{cicero} are the +corresponding units used in continental Europe. In Japan `kyus'\index{kyus} +(a quarter of a millimetre) may be used as the unit of measurement. +Inches\index{inch} and centimetres\index{centimetre} are the units that we +are all, or should be, familiar with. + + The point system was invented by Pierre Fournier le jeune in 1737 with +a length of 0.349mm. Later in the same century Fran\c{c}ois-Ambroise Didot +introduced his point system with a length of 0.3759mm. This is the value +still used in Europe. Much later, in 1886, the American Type Founders +Association settled on 0.013837in as the standard size for the point, and +the British followed in 1898. Conveniently for those who are not entirely +metric in their thinking this means that +six picas are approximately equal to one inch. + + The big point\index{big point} +is somewhat of an anomaly in that is a recent +invention. It tends to be used +in page markup languages, like PostScript\footnote{PostScript is a +registered trademark of Adobe Systems Incorporated.\label{fn:ps}}, +in order to make to make calculations quicker and easier. + + The above units are all constant in value. There are also some units +whose value depends on the particular font\index{font} being used. +The \textit{em}\index{em} +is the nominal height of the current font; it is used as a width measure. +An \textit{en}\index{en} is half an em. +The \textit{ex}\index{ex} is +nominally the height of the letter `x' in the current font. You may also +come across the term \textit{quad}\index{quad}, often as in a phrase +like `starts with a quad space'. It is a length defined in terms of +an em, often a quad is 1em. + + +\cleardoublepage +\pagenumbering{arabic} + +% body +\mainmatter + +\part{Art and Theory} \label{part:art} + +\chapter{The Parts of a Book} + +\section{Introduction} + + This chapter describes the various parts of a book, the +ordering of the parts, and the typical page numbering scheme used +in books. + + + +\section{Front matter} + + + There are three major divisions in a book: +the front matter\index{front matter} or preliminaries\index{preliminaries}, +the main matter\index{main matter} or text, +and the back matter\index{back matter} or references. +The main differences as +far as appearance goes is that in the front matter the folios\index{folio} are +expressed as roman numerals and sectional divisions are not numbered. The +folios\index{folio} are expressed as arabic numerals in the main and back matter. Sectional +divisions are numbered in the main matter but not in the back matter. + + The front matter\index{front matter} consists of such elements as the title +of the book, a table of contents\ixtoc, and similar items. The first few pages +in the front matter are not paginated\index{pagination} and so do not have folios\index{folio}. The remainder +are paginated and the folios\index{folio} are usually expressed as roman numerals. Not all +books have all the elements described below. + + The first page is a recto \emph{half title}\index{half title page} +page with no folio\index{folio}. +The page is very simple and displays just the main title of the book --- +no subtitle, author, or other information. One purported purpose of this +page is to protect the main title page. + + The first verso page, the back of the half-title page, may contain the +series title, if the book is one in a series, a list of contributors, +a frontispiece, or may be blank. The series title may instead be put on the +half-title page or on the copyright page. + + The \emph{title page}\index{title page} is recto and contains the full +title of the work, the names of the author(s) or editor(s), and often at the +bottom of the page the name of the publisher, together with the publisher's +logo if it has one. + + The title page(s) may be laid out in a simple manner or can have various +fol-de-rols, depending on the impression the designer wants to give. In +any event the style of this page should give an indication of the style +used in the main body of the work. + + The verso of the title page is the copyright page\index{copyright page}. +This contains the copyright notice, the publishing/printing history, +the country where printed, ISBN and/or CIP information. The page is usually +typeset in a smaller font\index{font!change} than the normal text. + + Following the copyright page may come a dedication or an epigraph\index{epigraph}, +on a recto page, with the following verso page blank. + + This essentially completes the unpaginated pages. + + The headings\index{heading} and textual forms for the paginated +pages should be the same as those for the main matter, except that +headings\index{heading} are usually unnumbered. + + The first paginated page, +usually with roman numerals (e.g., this is folio i), +is recto with the Table of Contents (\toc). If the book contains +figures\index{figure} (illustrations\index{illustration}) +and/or tables\index{table}, the List of Figures (\lof) and/or List of Tables (\lot) come +after the \toc, with no blank pages separating them. The \toc{} should contain +an entry for each following major element. If there is a \lot, say, this +should be listed in the \toc. The main chapters\index{chapter} must be listed, of course, and +so should elements like a preface\index{preface}, bibliography\index{bibliography} or an index\index{index}. + + There may be a foreword\index{foreword} after the listings, with no blank +separator. A foreword is usually written by someone other than the author, +preferably an eminent person, and is signed by the writer. The writer's +signature is often typeset in small caps after the end of the piece. + + A preface\index{preface} is normally written by the author, in which he +includes reasons why he wrote the work in the first place, and perhaps to +provide some more personal comments than would be justified in the body. +A preface starts on the page immediately following a foreword, or the lists. + + If any acknowledgements are required that have not already appeared in the +preface, these may come next in sequence. + + Following may be an introduction if this is not part of the main text. +The last elements in the front material may be a list of abbreviations, list +of symbols, a chronology of events, a family tree, or other information of +a like sort depending on the particular work. + + Table~\ref{tab:front} summarises the potential elements in the front +matter. + +\begin{table} +\centering +\caption{Front matter}\label{tab:front} +\begin{tabular}{llcc} \hline +Element & Page & Paginated & Leaf \\ \hline +Half-title page & recto & no & 1 \\ +Frontispiece, etc., or blank & verso & no & 1 \\ +Title page & recto & no & 2 \\ +Copyright page & verso & no & 2 \\ +Dedication & recto & no & 3 \\ +Blank & verso & no & 3 \\ +Table of Contents\ixtoc & recto & yes & 3 or 4 \\ +List of Figures\ixlof & recto or verso & yes & 3 or 4 \\ +List of Tables\ixlot & recto or verso & yes & etc. \\ +Foreword & recto or verso & yes & etc. \\ +Preface & recto or verso & yes & etc. \\ +Acknowledgements & recto or verso & yes & etc. \\ +Introduction & recto or verso & yes & etc. \\ +Abbreviations, etc & recto or verso & yes & etc. \\ +\hline +\end{tabular} +\end{table} + + + Note that the titles Foreword, Preface and Introduction are somewhat +interchangeable. In some books the title Introduction may be used for what +is described here as the preface, and similar changes may be made among the +other terms and titles in other books. + +\subsection{Copyright page} + + Most people are familiar with titles, \toc, prefaces, etc., but like +me are probably +less familiar with the contents of the copyright page\index{copyright page|(}. +In any event this is +usually laid out by the publishing house, but some authors may like to be, +or are forced into being, their own publisher. + + The main point of the copyright page is to display the +copyright\index{copyright} notice. +The Berne Convention does not require that published works carry a copyright +notice in order to secure copyright protection but most play it on the safe +side and include a copyright\index{copyright} notice. +This usually comes in three parts: the word \textit{Copyright} or more usually +the symbol \textcopyright, +the year of publication, +and the name of the copyright owner. +The copyright symbol matches the requirements of the Universal Copyright +Convention to which the USA, the majority of European and many Asian +countries belong. +The phrase `All rights reserved' is often added to ensure protection under the +Buenos Aires Convention, to which most of the Americas belong. A typical +copyright notice may look like: \\ +{\footnotesize \textcopyright{} 2035 by Frederick Jones. All rights reserved.} + + Somewhere on the page, but often near the copyright notice, is the name +and location(s) of the publisher. + + Also on the copyright page is the publishing history, denoting the edition +or editions\footnote{A second edition should be more valuable than a first +edition as there are many fewer of them.} and their dates, +and often where the book has been printed. One thing that has puzzled me in +the past is the mysterious row of numbers you often see, looking like: \\ +\centerline{\footnotesize\texttt{02 01 00 99 98 97\hspace{2em}10 9 8 7 6 5}} +The set on the left, reading from right to left, are the last two digits +of years starting with the original year of publication. +The set on the right, and again reading from right to left, represents the +potential number of new impressions (print runs). The lowest number in each +group indicates the edition date and the current impression. So, the example +indicates the fifth impression of a book first published in 1997. + + In the USA, the page often includes the Library of Congress +Cataloging-in-Publication (CIP)\index{CIP} data, +which has to be obtained from the +Library of Congress. This provides some keywords about the book. + + The copyright page is also the place for the ISBN\index{ISBN} +(International +Standard Book Number) number. This uniquely identifies the book. For example: +ISBN 0-NNN-NNNNN-2. The initial 0 means that the book was published in an +English-speaking country, the next group of digits identify the publisher, +the third group identifies the particular book by the publisher, and the final +digit, 2 in the example, is a check digit. + + It is left as an exercise for the reader to garner more information about +obtaining CIP and ISBN data.\index{copyright page|)} + +\section{Main matter} + + The main matter\index{main matter|(} forms the heart of the book. + + All pages within the main matter are paginated, even though some folios\index{folio} may +not be expressed. The folios\index{folio} are normally presented as arabic numerals, with +the numbering starting at 1 on the first recto page of the main matter. + + The main matter is at least divided into \emph{chapters}\index{chapter}, +unless it is something like a +young child's book which consists of a single short story. The chapters +may be grouped within \emph{parts}\index{part} which would then be the highest level +of division within the book. Typically both parts\index{part!number} and chapters\index{chapter!number} are numbered. +Obviously, part numbering should be continuous throughout the book, but even +with parts the chapter numbering is also continuous throughout the book. + + The title of a part\index{heading!part} is usually on a recto page which just contains the +part title, and number if there is one. Chapters\index{chapter} also start on recto pages +but in this case the text of the chapter\index{chapter} starts on the same page as the chapter +title. + + Chapters\index{chapter} may be divided into sections, either numbered or unnumbered, with +the numbering scheme starting afresh within each chapter. Similarly sections +may be partitioned into subsections but except for more technical works this +is usually as fine as the subdivisions need go to. Normally there are no +required page +breaks before the start of any subdivisions within a chapter\index{chapter}. + + The title page of a part\index{part} + or chapter\index{chapter} need not have the folio\index{folio} expressed, nor +a possibly textless verso page before the start of a chapter\index{chapter}, but all other +pages should display their folios\index{folio}. + + There may be a final chapter\index{chapter} in the main matter called Conclusions, +or similar, which may be a lengthy summary of the work presented, untouched +areas, ideas for future work, and so on. + + If there are any numbered appendices\index{appendix} +they logically come at the end of +the front matter. Appendices are often `numbered' alphabetically rather +than numerically, so the first might be Appendix A, the second Appendix B, +and so on. + + An epilogue\index{epilogue} or an afterword\index{afterword} is a +relatively short piece that the author may +include. These are not normally treated as prominently as the preceding +chapters\index{chapter}, and may well be put into the back matter if they are +unnumbered.\index{main matter|)} + +\section{Back matter} + + The back matter\index{back matter|(} +is optional but if present conveys information ancilliary +to that in the main matter. + + An unnumbered appendix\index{appendix} +would normally come in the back matter. + + Other elements include Notes, a Glossary\index{glossary} + and/or lists of symbols\index{symbol} or +abbreviations\index{abbreviation}, which could be in the +front matter\index{front matter} +instead. These elements +are normally unnumbered, as is any list of contributors\index{contributor}, +Bibliography\index{bibliography} or Index\index{index}. + + In some instances appendices\index{appendix} +and notes may be given at the end of each +chapter\index{chapter} instead of being lumped at the back. + + The first element in the back matter starts on a recto page but the +remainder may start on either recto or verso pages. + + In older books it was often the custom to have a colophon\index{colophon} +as the final element in a book. This is an inscription which includes +information about the production and design of the book and nearly +always indicates which fonts\index{font} were used.\index{back matter|)} + + +\section{Signatures and casting off} +\index{signature|(} + + Professionally printed books have many pages printed per sheet of (large) +paper\index{paper}, which is then folded and cut where necessary to produce a +\emph{signature} of several smaller sheets. An +unfolded sheet is called a \emph{broadside}\index{broadside}. +Folding a sheet in half produces a one sheet +\emph{folio}\index{folio} signature with two leaves and four pages. +Folding it in half again and cutting along the original fold gives a +two sheet \emph{quarto}\index{quarto} signature with four leaves +and eight pages. +Folding in half again, +results in a four sheet \emph{octavo}\index{octavo} signature with eight +leaves and 16 pages, and so on as listed in \tref{tab:signatures}. + +\begin{table} +\centering +\caption{Common signatures} \label{tab:signatures} +\begin{tabular}{lcccrccrccrc} \hline +Name & Folds & Size & \multicolumn{3}{c}{Sheets} & +\multicolumn{3}{c}{Leaves} & \multicolumn{3}{c}{Pages} \\ \hline +Broadside & 0 & $a \times b$ & & 1 & & & 1 & & & 2 & \\ +Folio & 1 & $b/2 \times a$ & & 1 & & & 2 & & & 4 & \\ +Quarto, \emph{4to} & 2 & $a/2 \times b/2$ & & 2 & & & 4 & & & 8 & \\ +Octavo, \emph{8vo} & 3 & $b/4 \times a/2$ & & 4 & & & 8 & & & 16 & \\ +\emph{16mo} & 4 & $a/4 \times b/4$ & & 8 & & & 16 & & & 32 & \\ +\emph{32mo} & 5 & $b/8 \times a/4$ & & 16 & & & 32 & & & 64 & \\ +\emph{64mo} & 6 & $a/8 \times b/8$ & & 32 & & & 64 & & & 128 & \\ \hline +\end{tabular}% +\index{broadside}\index{folio}\index{quarto}\index{4to}\index{octavo}% +\index{8vo}\index{16mo}\index{32mo}\index{64mo}% +\end{table} + + In \tref{tab:signatures} the Size column is the untrimmed size of a +leaf\index{leaf} in +the signature +with respect to the size of the broadside. When made up into a book the +leaves will trimmed to a slightly smaller size, at the discretion of the +designer and publisher; typically a minimum of 1/8 inch or 3 millimetres +would be trimmed from the top, bottom and foredge of a leaf. + + Other folds can produce other signatures. For example a +\emph{sexto}\index{sexto}, +obtained by folding in thirds and then folding in half, is a three sheet +signature with six leaves and 12 pages. + + In making up the book, the pages in each signature are first fastened +together, usually by sewing through the folds. The signatures are then bound +together and the covers, end papers\index{paper!end} and spine are attached to form +the completed whole. + + + Publishers like the final typeset book to be of a length that just fits +within an integral number of signatures\index{signature}, +with few if any blank pages required +to make up the final signature. Casting off\index{casting off} is the +process of determining how many lines a given text will make in a given +size of type, and hence how many pages will be required. + + To cast off you need to know how many characters there will be in +a line, and how many characters there are, or will be, in the text. +For the purposes of casting off, `characters' includes punctuation as well +as letters and digits. The +first number can be easily obtained, either from copy fitting tables or +by measurement; this is described in more detail in \S\ref{sec:tblock}. +The second is more problematic, especially when the manuscript has yet +to be written. A useful rule of thumb is that words in an English text +average five letters plus one space (i.e., six characters); +word length in technical texts might be greater than this. + + To determine the number of words it is probably easiest to type a +representative portion of the manuscript, hand count the words and then +divide that result by the proportion of the complete text that you have +typed. For example, if you have typed 1/20\,th of the whole, then divide +by 1/20, which is equivalent to multiplying by 20. To fully estimate +the number of pages required it is also necessary to make allowance for +chapter\index{chapter} titles, illustrations\index{illustration}, and so forth. + + If it turns out, say, that your work will require 3 signatures plus 2 +pages then it will be more convenient to make it fit into 3 signatures, +or 4 signatures minus a page or two. This can be done by expanding or cutting +the text and/or by changing the font\index{font!change} +and/or by changing the number or width +of lines on a page. + + When I was editing a technical journal the authors were given a word +limit. The primary reason was not that we were interested in the actual +word count but rather so that we could estimate, and possibly limit, +the number of pages allotted +to each article; we used \emph{octavo}\index{octavo} +signatures\index{signature} and no blank pages. +I suspect that it is +the same with most publishers --- it is the page count not the word count +that is important to them. + + In some special cases, extra pages may be `tipped in'\index{tip in} to +the body of the book. This is most likely to occur for +illustrations\index{illustration} which +require special paper\index{paper} for printing and it would be too costly to use +that paper\index{paper} for the whole work. Another example is for a fold-out of some sort, +a large map, say, or a triple spread illustration\index{illustration}. The tipped in pages +are glued into place in the book and may or may not be paginated. For +tipped in illustrations\index{illustration}, a List of Illustrations may well start with +a phrase like: `Between pages 52 and 53'. + +\index{signature|)} + +%%%\clearpage +%%%\raggedbottom +\chapter{The page} \label{chap:lpage} + + Authors usually want their works to be read by others than themselves, +and this implies that their manuscript will be reproduced in some manner. +It is to be hoped that the published version of their work will attract +readers and there are two aspects to this. The major is the actual content +of the work --- the thoughts of the author couched in an interesting +manner --- if something is boring, then there are too many other interesting +things for the reader to do than to plow on until the bitter end, +assuming that he +even started to read seriously after an initial scan. The other aspect is +the manner in which the content is displayed. Or, in other words, +the \emph{typography} +of the book, which is the subject of this chapter. + + The essence of good typography is that it is not noticeable at first, +or even second or later, glances to any without a trained eye. If your +initial reaction when glancing through a book is to exclaim about its layout +then it is most probably badly designed, if it was designed at all. Good +typography is subtle, not strident. + + With the advent of desktop publishing +many authors are tempted to design their own books. It is seemingly all +too easy to do. Just pick a few of the thousands of fonts\index{font} that are available, +use this one for headings\index{heading}, +that one for the main text, another one for +captions, decide how big the typeblock\index{typeblock} is to be, and there you are. + + However, just as writing is a skill that has to be learned, typography +is also an art that has to be learned and practised. There are hundreds +of years of experience embodied in the good design of a book. These are +not to be cast aside lightly and many authors who design their own books +do not know what some of the hard-earned lessons are, let alone that what +they are doing may be the very antithesis of these. An expert can break +the rules, but then he is aware that he has good reasons for breaking them. + + The author supplies the message and the typographer supplies the medium. +Contrary to Marshall McLuhan, the medium is \emph{not} the message, +and the typographer's job is not to +intrude between the message and the audience, but to subtly increase the +reader's enjoyment and involvement. If a book shouts `look at me!' then it +is an advertisement, and a bad one at that, for the designer. + + +\section{The shape of a book} + + Books come in many shapes and sizes, but over the centuries certain +shapes have been found to be more pleasurable and convenient than others. +Thus books, except for a very very few, are rectangular in shape. The +exceptions on the whole are books for young children, although I do +have a book edited by Fritz Spiegl and published by Pan Books entitled +\textit{A Small Book of Grave Humour}, which is in the shape of a tombstone +--- this is an anthology of epitaphs. Normally the height of a book, when +closed, is greater than the width. Apart from any aesthetic reasons, +a book of this shape is physically more comfortable to hold than one which +is wider than it is high. + + It might appear that the designer has great freedom in choosing the +size of the work, but for economic reasons this is not normally the case. +Much typographical design is based upon the availabilty of certain +standard industrial sizes of sheets of paper\index{paper!size}. A page size of $12 \times 8$ +inches will be much more expensive than one which fits on a standard +US letter sheet\index{paper!size!letterpaper} of $11 \times 8 \; 1/2$ inches. Similarly, +one of the standard sizes +for a business envelope is $4 \; 1/8 \times 9 \; 1/2$ inches. +Brochures for mailing +should be designed so that they can be inserted into the envelope with +minimal folding. Thus a brochure size of $5 \times 10$ inches will be +highly inconvenient, no matter how good it looks visually. + + Over the years books have been produced in an almost infinite variety +of proportions, +where by \emph{proportion}\index{proportion} +I mean the ratio of the height to the width of a +rectangle. However, certain proportions\index{proportion} occur time after time throughout +the centuries and across many different countries and +civilizations. This is because some proportions\index{proportion} are inherently +more pleasing to the eye than others are. These pleasing proportions\index{proportion} are +also commonly found in nature --- in physical, biological, and chemical +systems and constructs. + + Some examples of pleasing proportions\index{proportion} can be +seen in Japanese wood block prints, such as the \textit{Hoso-ye} size +($2 : 1$) which is a double square, the \textit{Oban} ($3 : 2$), +the \textit{Chuban} ($11 : 8$) and the \textit{Koban} size +($\sqrt{2} : 1$). Sometimes these prints were made up into books, but +were often published as stand-alone art work. Similarly Indian paintings, +at least in the 16th to the 18th century, +often come in the range $1.701 : 1$ to $13 : 9$, thus being around +$3 : 2$ in proportion\index{proportion}. + + In medieval Europe page proportions\index{proportion} were generally in the range +$1.25 : 1$ to $1.5 : 1$. Sheets of paper\index{paper} were typically +produced in the +proportion\index{proportion} $4 : 3$ ($1.33 : 1$) or $3 : 2$ ($1.5 : 1$). +These proportions\index{proportion} +have the property that they are reproduced with each alternate +folding of the sheet. +For example, if a sheet starts at a size of $60 \times 40$ +(i.e., $3 : 2$), +then the first fold will make a double sheet of size $30 \times 40$ +(i.e., $3 : 4$). The next fold will produce a quadrupled sheet of size +$30 \times 20$, which is again $3 : 2$, and so on. +It is an interesting fact, +though, that it is impossible to fold a sheet of paper\index{paper}, no matter how large +and thin, more than six times altogether. The Renaissance typographers +tended to like taller books, and their proportions\index{proportion} would go up +to $1.87 : 1$ +or so. The style nowadays has tended to go back towards the medieval +proportions\index{proportion}. + + The standard ISO page proportions\index{proportion} are $\sqrt{2} : 1$ +($1.414 : 1$). These +have a similar property to those of medieval times. However, in this case +each fold reproduces the page proportion\index{proportion}. Thus halving an A0 sheet +(size $1189 \times 841$ mm) produces an A1 size sheet ($594 \times 841$), +which in turn being halved produces the A2 sheet ($420 \times 594$), down +through the A3, A4 ($210 \times 297$ mm), and A5 sheets. + + There is no one perfect proportion\index{proportion} for a page, although some are +clearly better +than others. For ordinary books both publishers and readers tend to prefer +books whose proportions\index{proportion} range from the light $9 : 5$ ($1.8 : 1$) +to the heavy +$5 : 4$ ($1.25 : 1$). Some examples are shown in \fref{flpage:prop}. + Wider pages, those with proportions\index{proportion} less than +$\sqrt{2} : 1$ ($1.414 : 1$), +are principally useful for documents that need +extra width for tables\index{table} +, marginal notes\index{marginalia}, or where multi-column\index{column!multiple} printing +is preferred. + +\begin{figure} +\centering +\setlength{\unitlength}{1pc} +\begin{picture}(24,38) +\put(0,4){\begin{picture}(24,34) + \put(0,0){\framebox(24,34){}} + \thicklines \put(19.78,0){\line(0,1){34}} + \thinlines + \put(16,0){\line(0,1){34}} + \put(17.78,0){\line(0,1){34}} + \put(18.48,0){\line(0,1){34}} + \put(19.2,0){\line(0,1){34}} + \put(20.81,0){\line(0,1){34}} + \put(21.33,0){\line(0,1){34}} + \put(22.63,0){\line(0,1){34}} + \put(0,-0.5){\begin{picture}(24,2) + \put(16,0){\makebox(0,0){\textsc{a}}} + \put(17.78,0){\makebox(0,0){\textsc{b}}} + \put(18.48,0){\makebox(0,0){\textsc{c}}} + \put(19.2,0){\makebox(0,0){\textsc{d}}} + \put(19.78,0){\makebox(0,0){{$\varphi$}}} + \put(20.81,0){\makebox(0,0){\textsc{e}}} + \put(21.33,0){\makebox(0,0){\textsc{f}}} + \put(22.63,0){\makebox(0,0){\textsc{g}}} + \put(24,0){\makebox(0,0){\textsc{h}}} + \end{picture}} + \end{picture}} + \put(0,0){\begin{picture}(24,4) + \put(0,0){\begin{picture}(8,4) + \put(0,2){\textsc{a} $2 : 1$} + \put(0,1){\textsc{b} $9 : 5$} + \put(0,0){\textsc{c} $1.732 : 1$ ($\sqrt{3}{} : 1$)} + \end{picture}} + \put(8,0){\begin{picture}(8,4) + \put(0,2){\textsc{d} $5 : 3$} + \put(0,1){{$\varphi$} $1.618 : 1$ ($\varphi{} : 1$)} + \put(0,0){\textsc{e} $1.538 : 1$} + \end{picture}} + \put(16,0){\begin{picture}(8,4) + \put(0,2){\textsc{f} $3 : 2$} + \put(0,1){\textsc{g} $1.414 : 1$ ($\sqrt{2}{} : 1$)} + \put(0,0){\textsc{h} $4 : 3$} + \end{picture}} + \end{picture}} +\end{picture} +\setlength{\unitlength}{1pt} +\caption{Some page proportions} \label{flpage:prop} +\end{figure} + + + + In books where the illustrations\index{illustration} are the primary concern, the shape of +the illustrations\index{illustration} is generally the major influence on the page proportion\index{proportion}. +The page size should be somewhat higher than that of the average +illustration\index{illustration}. +The extra height is required for the insertion of captions\index{caption} describing the +illustration\index{illustration}. A proportion\index{proportion} of $\pi{} : e$ ($1.156 : 1$), +which is slightly higher +than a perfect square, is good for square illustrations.\footnote{Both $e$ +and $\pi$ are well known mathematical numbers. $e$ ($= 2.718 \ldots$) +is the base of natural logarithms and $\pi$ ($= 3.141 \ldots$) is the +ratio of the circumference of a circle to its diameter.} +The $e : \pi$ +($0.864 : 1$) proportion\index{proportion} is useful for landscape photographs taken with +a $4 \times 5$ +format camera, while those from a 35mm camera (which produces a negative +with a $2 : 3$ proportion\index{proportion}) are better accomodated on +a $0.83 : 1$ page. + +\subsection{The golden section and Fibonacci series} + +\index{golden section|(} + Typographers need a modicum of mathematical ability, but no more +than an average teenager can do --- basically simple arithmetic. You can +skip this section if you wish as it just provides some background +mathematical material which might be of interest. + + Since ancient Greek times or even before, the golden section, which +is denoted by the Greek letter $\varphi$ (phi), has been considered to be +a particularly harmonious proportion\index{proportion}. It should come as no surprise, then, +that this also has applications in typography. + + The Greeks were interested in geometry (think of Euclid). They discovered +that if you divide a straight line into two unequal parts then a certain +division appeared to have an especially appealing aesthetic quality about it. +Call the length of the line $l$ and the length of the two parts $a$ and $b$, +where $a$ is the smaller and $b$ is the larger. The division in question +is when the ratio of the larger to the smaller division ($b/a$) is the same +as the ratio of the whole line to the larger division ($l/b$). +More formally, two elements embody the golden section, symbolised by +$\varphi$, when the ratio of the larger +to the smaller is the same as the ratio of the sum of the two to the larger. +If the two elements are $a$ and $b$, with $a < b$, then +\begin{equation} +\varphi = \frac{b}{a} = \frac{a+b}{b} = (1+\sqrt{5})/2 +\end{equation} + + The golden section has been called by a number of different names +during its history. Euclid\index{Euclid} + called it the `extreme and mean ratio' while +Renaissance writers called it the `divine proportion\index{proportion}'; now it is +called either the `golden section' or the `golden ratio'. The symbol +$\varphi$ is said to come from the name of the Greek artist +Phidias\index{Phidias} +(C5th \textsc{bc}) who often used the golden section in his sculpture. +A rectangle whose sides are in the same proportion\index{proportion} as the golden section +is often called a `golden rectangle'. +The front of the Parthenon on the Acropolis in Athens is a golden rectangle, +and such rectangles appear often in Greek architecture. +The symbol of the Pythagoran school was the star pentagram, +%%%%shown in \fref{flpage:spent}, +where each line is divided in the golden section. + + + The approximate decimal value for $\varphi$ is $1.61803$. +The number has some unusual properties. If you add one to $\varphi$ +you get its square, while subtracting one from $\varphi$ gives its +reciprocal. +\begin{eqnarray} + \varphi + 1 & = & \varphi^{2} \\ + \varphi - 1 & = & 1/\varphi +\end{eqnarray} +It also has a very simple definition as the continued fraction +\begin{equation} +\varphi = 1 + \frac{1}{\displaystyle 1 + \frac{1}{\displaystyle 1 + \frac{1}{\displaystyle 1 + \frac{1}{1 + \cdots}}}} +\end{equation} + + + In 1202 Leonardo Pisano, +also known as Leonardo Fibonacci, wrote a +book called \textit{Liber Abbaci.}\footnote{Book of the Abacus.} One of the +topics he was interested in was population growth. The book included +this exercise: \index{Fibonacci series|(} +\begin{quote} +How many pairs of rabbits\index{rabbit} can be produced from a single +pair in a year? +Assume that each pair produces a new pair of offspring every month, +a rabbit becomes fertile at age one month, and no rabbits die during the +year. +\end{quote} +After a month there will be two pairs. At the end of the next month the +first pair will have produced another pair, so now there are three pairs. +At the end of the following month the original pair will have produced a +third pair of offspring and their firstborn will also have produced a pair, +to make five pairs in all. And so on. +If, like the rabbits, you are not too exhausted +to continue, you can get the following series of +numbers\footnote{The numbers at the start of the series +depend on whether you consider the initial pair of rabbits to be adults or +babies.\label{fn:rabbits}}: +\begin{displaymath} +0,1,1,2,3,5,8,13,21,34, 55, 89 \ldots +\end{displaymath} +After the first two terms, each term in the series is the sum of the two +preceding terms. Also, as one progresses along the series, the ratio of +any adjacent pair of terms oscillates around $\varphi$ ($= 1.618 \ldots$), +approaching it ever more closely. +\begin{eqnarray*} + 8/5 & = & 1.6 \\ + 13/8 & = & 1.625 \\ + 21/13 & = & 1.615 \\ + 34/21 & = & 1.619 \\ + 55/34 & = & 1.6176 \\ + 89/55 & = & 1.6182 +\end{eqnarray*} + + For the mathematically inclined there is another, to me, striking +relationship between $\varphi$ and the Fibonacci series. Define the +Fibonacci numbers as $F_{n}$, where +\begin{equation} +\begin{array}{cccc} +F_{0} = 0;\ \ & F_{1}=1;\ \ & F_{n+2}=F_{n+1} + F_{n}, & n \geq 0. +\end{array} +\end{equation} +Then +\begin{equation} + F_{n} = \frac{1}{\sqrt{5}}(\varphi^{n} - (- \varphi)^{-n}) +\end{equation} + + Both the Fibonacci series and the golden section appear in nature. +The arrangement of seeds in a sunflower, the pattern on the surface of a +pinecone, and the spacing of leaves around a stalk all exhibit Fibonacci +paterns (for example see~\cite{CONWAY96}). Martin Gardener~\cite{GARDNER66} +reports on studies that claimed that the average ratio of a person's height +to the height of the navel is $1.618+$ --- suspiciously close to $\varphi$. + +\index{Fibonacci series|)} +\index{golden section|)} + +%%%%%%%%%%%%%%%%%%%%%%%%%%% +%%%%%%\endinput +%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\section{The spread} \label{sec:spread} +\index{spread|(} + + The typeblock\index{typeblock} is that part of the page which is normally covered with +type. The same proportions\index{proportion} that are useful for the shape of a page are also +useful for the shape of the typeblock\index{typeblock}. This does not mean, though, that the +proportions\index{proportion} of the page and the typeblock\index{typeblock} should be the same. For instance, +a square typeblock\index{typeblock} on a square page is inherently dull. + + When we first start to learn to read we scan horizontally along each line +of text. As our skills improve we tend to scan vertically rather than +horizontally. A tall column\index{column} of text helps in this process, provided that +the column\index{column} is not too wide. + + A page in a book will typically contain several elements. Principal +among these is the typeblock\index{typeblock}, but there are also items like the folio\index{folio} +(that is, the page number), a running head and/or foot which carries the +chapter\index{chapter} and/or book title, and possibly marginalia\index{marginalia} and footnotes\index{footnote}. These latter +elements, although essential to the content of the book, are minor visual +elements compared to the typeblock\index{typeblock}. But even minor decoration can obscure +or kill an otherwise good design. + + The major concern is the positioning of the typeblock\index{typeblock} on the page. +The mere +fact of positioning the typeblock\index{typeblock} also has the result of producing margins\index{margin} +onto the page. Page design is a question of balancing the page proportions\index{proportion} +with the proportions\index{proportion} of the typeblock\index{typeblock} and the proportions\index{proportion} of the margins\index{margin} to +create an interesting yet harmonious composition. A single page, except +for a title page, is never the subject of a design but rather the design +is in terms of the two pages that are on view when a book is opened --- the +left and right hand pages are considered as a whole. More technically, the +design is in terms of a \emph{double spread}. + + + +\begin{table} +\caption{Some page designs} \label{tlpage:allp} +\centering +\DeleteShortVerb{\|} +%\begin{tabular}{|l|l|l|c|} \hline +\begin{tabular}{|r|r|rrrrr|l|} \hline +\multicolumn{1}{|c|}{$P$} & \multicolumn{1}{c|}{$T$} & \multicolumn{5}{c|}{Margins \& Columns} & +\multicolumn{1}{c|}{Figure} \\ + & & \multicolumn{1}{c|}{$s$} & \multicolumn{1}{c|}{$t$} & \multicolumn{1}{c|}{$e$} & + \multicolumn{1}{c|}{$f$} & \multicolumn{1}{c|}{$g$} & \\ \hline +$\sqrt{3}$ & $2$ & $w/13$ & $8s/5$ & $16s/5$ & $16s/5$ & & \ref{fb:1} left \\ %Bringhurst +$\sqrt{3}$ & $e/\varphi$ & $w/10$ & $2s$ & $2s$ & $3s$ & & \ref{fb:1} right \\ % Machie +$12/7$ & $1.701$ & $w/7$ & $8s/5$ & $8s/5$ & $14s/5$ & & \ref{fb:2} left \\ % Grenfell +$e/\varphi$ & $7/4$ & $w/10$ & $5s/4$ & $5s/3$ & $11s/8$ & & \ref{fb:2} right \\ % JKJ +$\varphi$ & $1.866$ & $w/9$ & $s$ & $2s$ & $7s/3$ & & \ref{fb:3} left \\ %Paris +$\varphi$ & $\varphi$ & $w/12$ & $2s$ & $5s/2$ & $4s$ & & \ref{fb:3} right \\ %Dowding +$8/5$ & $1.634$ & $2w/15$ & $7s/5$ & $9s/5$ & $13s/5$ & & \ref{fb:4} left \\ %Rogers +$19/12$ & $7/4$ & $2w/15$ & $s$ & $9s/8$ & $11s/8$ & & \ref{fb:4} right \\ %Anatomy +$19/12$ & $\sqrt{3}$ & $w/7$ & $s$ & $5s/4$ & $1.84s$ & & \ref{fb:5} left \\ % Cornford +$19/12$ & $8/5$ & $w/12$ & $7s/5$ & $8s/5$ & $2s$ & & \ref{fb:5} right \\ %Abeced +$\pi/2$ & $9/5$ & $w/9$ & $3s/2$ & $5s/2$ & $3s$ & & \ref{fb:6} left \\ %Dwiggins +$e/\sqrt{3}$ & $1.71$ & $w/10$ & $11s/8$ & $24s/11$ & $8s/3$ & & \ref{fb:6} right \\ %Two Men +$1.553$ & $1.658$ & $w/11$ & $\varphi s$ & $\varphi s$ & $\varphi s$ & & \ref{fb:7} left \\ %Express +$1.538$ & $\sqrt{7}$ & $w/10$ & $s$ & $23s/6$ & $3s/2$ & & \ref{fb:7} right \\ %T&H +$3/2$ & $2$ & $w/5$ & $s/2$ & $s$ & $s$ & & \ref{fb:8} left \\ %Rome +$3/2$ & $1.701$ & $w/9$ & $s$ & $2s$ & $7s/3$ & & \ref{fb:8} right \\ %Venice +$3/2$ & $\pi/2$ & $w/13$ & $2s$ & $10s/3$ & $30s/7$ & & \ref{fb:9} left \\ %Magellan +$3/2$ & $3/2$ & $w/9$ & $3s/2$ & $2s$ & $3s$ & & \ref{fb:9} right \\ %Gutenberg +$3/2$ & $1.68$ & $w/23$ & $2s$ & $5s$ & $2s$ & & \ref{fb:10} left \\ % Pers Mss +$3/2$ & $3/2$ & $w/10$ & $2s$ & $5s/2$ & $2.85s$ & & \ref{fb:10} right \\ % Pers Bk +$1.48$ & $1.376$ & $w/12$ & $7s/4$ & $2s$ & $7s/2$ & & \ref{fb:11} left \\ %Goudy +$13/9$ & $\sqrt{2}$ & $w/30$ & $2s$ & $9s/2$ & $4s$ & $s/2$ & \ref{fb:11} right \\ %Doomsday +$\sqrt{2}$ & $\varphi$ & $w/9$ & $s$ & $2s$ & $2s$ & & \ref{fb:12} left \\ %Orig A4 +$\sqrt{2}$ & $\varphi$ & $w/8$ & $s$ & $5s/3$ & $5s/3$ & & \ref{fb:12} right \\ %Mod A4 +$7/5$ & $1.641$ & $w/7$ & $s$ & $8s/5$ & $8s/5$ & & \ref{fb:13} left \\ %Emery Walker +$1.294$ & $\varphi$ & $0.176w$ & $1.03s$ & $1.685s$ & $13s/9$ & & \ref{fb:13} right \\ %LaTeX +$1.294$ & $13/9$ & $w/12$ & $s$ & $2s$ & $10s/7$ & $s/2$ & \ref{fb:14} left \\ %Wilson +$9/7$ & $19/9$ & $2w/5$ & $5s/8$ & $5s/8$ & $5s/6$ & & \ref{fb:14} right \\ %Kuniyoshi +$5/4$ & $13/11$ & $w/10$ & $3s/2$ & $2s$ & $8s/3$ & & \ref{fb:15} left \\ %Fens +$7/6$ & $17/15$ & $w/13$ & $s$ & $s$ & $7s/5$ & $.382$ & \ref{fb:15} right \\ %Durer +%$1.176$ & $1.46$ & $0.107w$ & $5s/6$ & $2.41s$ & $3s/2$ & & \ref{fb:12} left \\ %Art +$e/\pi$ & $0.951$ & $w/9$ & $s$ & $2s$ & $3s/2$ & & \ref{fb:16} left \\ %Hammer & Hand +$5/7$ & $2/3$ & $w/9$ & $s/2$ & $2s/3$ & $s$ & $s/3$ & \ref{fb:16} right \\ \hline %Hokusai +\end{tabular} +\MakeShortVerb{\|} +\end{table} + + Table~\ref{tlpage:allp} gives some examples of +page designs. These are arranged in increasing order of +fatness. In this table, and afterwards, I have just used a single number +to represent the ratio of the page height to the width; that is, for example, +$1.5$ instead of $1.5 : 1$ or $12/7$ instead of $12 : 7$. +The following symbols are used in the table: +\begin{description} +\item[Proportions]: + \begin{itemize} + \item[$P$] = page proportion = $h/w$ + \item[$T$] = typeblock proportion = $d/m$ + \end{itemize} +\item[Page size]: + \begin{itemize} + \item[$w$] = width of page + \item[$h$] = height of page + \end{itemize} +\item[Typeblock]: + \begin{itemize} + \item[$m$] = measure (i.e., width) of primary typeblock + \item[$d$] = depth (excluding folios, running heads, etc.) +%% \item[$n$] = measure of secondary column +%% \item[$c$] = column width, when there are two columns + \end{itemize} +\item[Margins]: + \begin{itemize} + \item[$s$] = spine margin (back margin) + \item[$t$] = top margin (head margin) + \item[$e$] = fore-edge (front margin) + \item[$f$] = foot margin (bottom margin) + \item[$g$] = internal gutter (on a multi-column page) + \end{itemize} +\end{description} + The designs are also shown in \figurerefname s~\ref{fb:1} +to~\ref{fb:16}. Each of these shows a double page spread; the +page width has been kept constant throughout the series to enable easier +visual comparison --- it is the relative proportions\index{proportion}, not the absolute size, +that are important. I have only shown the pages and the typeblocks\index{typeblock} to avoid +confusing the diagrams with headers\index{header}, footers\index{footer} +or folios\index{folio}. + + +\begin{figure} +\centering +\begin{minipage}[b]{\pwlayi} +\drawaspread{\pwlayii}{1.732}{2}{.0769}{1.6}{3.2}{0} % Bringhurst +\end{minipage} +\hfill +\begin{minipage}[b]{\pwlayi} +\drawaspread{\pwlayii}{1.732}{1.684}{.1}{2}{2}{0} % Machiavelli +\end{minipage} +\caption[Two spreads: Canada, 1992 and England, 1970]% + {Two spreads: (Left) Canada, 1992. % Bringhurst. + (Right) England, 1970.} \label{fb:1} +\end{figure} + + Shown in \fref{fb:1} are two modern books. On the left is the layout +for Robert Bringhurst's \textit{The Elements of Typographical Style} published +by Hartley \& Marks in 1992, and designed by Bringhurst. The text face is +Minion set with $12$pt leading on a $21$pc measure. The captions are +set in Syntax. The original +size is $227 \times 132$mm. I highly recommend this book if you are +interested in typography. The layout on the right is The Folio Society's +1970 edition of \textit{The Prince} by Niccol\`{o} Machiavelli. The original +size is $216 \times 125$mm and is set in $12/13 \times 22$ Centaur. + + + +\begin{figure} +\centering +\begin{minipage}[b]{\pwlayi} +\drawaspread{\pwlayii}{1.714}{1.701}{.143}{1.6}{1.6}{0} % Grenfell +\end{minipage} +\hfill +\begin{minipage}[b]{\pwlayi} +\drawaspread{\pwlayii}{1.68}{1.75}{.1}{1.25}{1.667}{0} % JKJ +\end{minipage} +\caption[Two spreads: USA, 1909 and England, 1964.]% + {Two spreads: (Left) USA, 1909. + (Right) England, 1964.} \label{fb:2} +\end{figure} + + Figure~\ref{fb:2} (left) illustrates a small book by Wilfred T.~Grenfell +entitled \textit{Adrift on an Ice-Pan} published in 1909 by the Riverside +Press of Boston. The text is set with a leading of $16$pt on a $16$pc measure. +The large leading and small measure combine to give a very open appearance. +The original +size is $184 \times 107$mm. On the right is another book from the +Folio Society --- \textit{Three Men in a Boat} by Jerome K.~Jerome printed +in 1964. The original size is $215 \times 128$mm and is typeset with +Ehrhardt at $11/12 \times 22$. + +\begin{figure} +\centering +\begin{minipage}[b]{\pwlayi} +\drawaspread{\pwlayii}{1.618}{1.87}{.111}{1}{2}{0} % Paris +\end{minipage} +\hfill +\begin{minipage}[b]{\pwlayi} +\drawaspread{\pwlayii}{1.618}{1.618}{.0833}{2}{2.5}{0} % Dowding +\end{minipage} +\caption[Two spreads: France, 1559 and Canada, 1995]% + {Two spreads: (Left) France, 1559. + (Right) Canada, 1995.} \label{fb:3} +\end{figure} + + Jean de Tourmes, a Parisian publisher, printed \textit{Histoire et Chronique} +by Jean Froissart in 1559. This is a history book with the main text in +roman and sidenotes in italic at roughly 80\% of the size of the main text. +The layout is shown in \fref{fb:3} (left). The gutter (not shown) between the main +text and the sidenote column\index{column} is very small, but the change in fonts and sizes +enables the book to be read with no confusion. Another Hartley \& Marks +typography book --- \textit{Finer Points in the Spacing \& Arrangement +of Type} by Geoffrey Dowding --- is shown at the right of \fref{fb:3}. +This is typeset in Ehrhardt at $10.5/14 \times 23$ on a page size of +$231 \times 143$mm. + + + +\begin{figure} +\centering +\begin{minipage}[b]{\pwlayi} +\drawaspread{\pwlayii}{1.6}{1.634}{.1333}{1.4}{1.8}{0} % Rogers +\end{minipage} +\hfill +\begin{minipage}[b]{\pwlayi} +\drawaspread{\pwlayii}{1.583}{1.75}{.1333}{1}{1.125}{0} % Anatonomy +\end{minipage} +\caption[Two spreads: USA, 1949 and 1990]% + {Two spreads: (Left) USA, 1949. + (Right) USA, 1990.} \label{fb:4} +\end{figure} + + Bruce Rogers (1870--1957) described how he came to design his +Centaur typeface in +\textit{Centaur Types}, a privately published book by his studio October +House in 1949. The layout of this book, which of course was typeset in +Centaur, is shown at the left of \fref{fb:4}. Centaur is an upright +seriffed type based on Nicolas Jenson's type as used in \textit{Eusebius} +published in 1470. \textit{Centaur Types} demonstrates typefaces other than +Centaur, and also includes exact size reproductions of the engraver's +patterns. It is set at $14/16 \times 22$ on a page size of $240 \times 150$mm. +Figure~\ref{fb:4} (right) is the layout of another book on typefaces. +It is \textit{The Anatomy of a Typeface} by Alexander Lawson published by +David R.~Godine in 1990. +This is set in Galliard with $13$pt leading and a measure of $24$pc on +a page size of $227.5 \times 150$mm. + + +\begin{figure} +\centering +\begin{minipage}[b]{\pwlayi} +\drawaspread{\pwlayii}{1.583}{1.731}{.143}{1}{1.25}{0} % Cornford +\end{minipage} +\hfill +\begin{minipage}[b]{\pwlayi} +\drawaspread{\pwlayii}{1.583}{1.6}{.0833}{1.4}{1.6}{0} % Abcedarium +\end{minipage} +\caption[Two spreads: England, 1908 and USA, 1993]% + {Two spreads: (Left) England, 1908. + (Right) USA, 1993.} \label{fb:5} +\end{figure} + + \textit{Microcosmographica Academia} by F. M. Cornford is shown in +\fref{fb:5}. Despite its title, it is written in English and was published +by Bowes \& Bowes, London, in 1908. It is a dryly humourous look at academic +politics as practised in Cambridge University at the turn of the nineteenth +century (possibly the twentieth as well). It is set with $14$pt leading +on $22$pc. The original page size is $216 \times 136$mm. +The right of this figure illustrates a book with another unusual title --- +\textit{The Alphabet Abcedarium} by Richard A.~Firmage and published by +David R.~Godine in 1993. It is set in Adobe Garamond on a $27$pc measure +with $14$pt leading. The original page size is $227.5 \times 150$mm. The +book gives a history of each letter of the latin alphabet. One +unusual feature is that there is a deep footer\index{footer} on each page +showing many examples of typefaces of the letter being described. + + +\begin{figure} +\centering +\begin{minipage}[b]{\pwlayi} +\drawaspread{\pwlayii}{1.571}{1.8}{.111}{1.5}{2.5}{0} % Dwiggins +\end{minipage} +\hfill +\begin{minipage}[b]{\pwlayi} +\drawaspread{\pwlayii}{1.562}{1.709}{.1}{1.375}{2.182}{0} % Two Men +\end{minipage} +\caption[Two spreads: USA, 1931 and England, 1968]% + {Two spreads: (Left) USA, 1931. + (Right) England, 1968.} \label{fb:6} +\end{figure} + + + W.~A.~Dwiggins was, among many other things, an American book designer. +Figure~\ref{fb:6} (left) shows his layout of H.~G.~Wells' \textit{The Time +Machine} for Random House in 1931. The page size is $231 \times 147$mm. +The right of the figure illustrates the layout of a book called +\textit{Two Men --- Walter Lewis and Stanley Morrison at Cambridge} +by Brooke Crutchley and published by Cambridge University Press in 1968. +Crutchley was the Cambridge University Printer and each year would produce +a limited edition of a book about Cambridge or typography, and preferably +both together. This is typeset in Monotype Barbon with $17.5$ leading on +a $26$pc measure on a $253 \times 162$mm page. + + + +\begin{figure} +\centering +\begin{minipage}[b]{\pwlayi} +\drawaspread{\pwlayii}{1.553}{1.685}{.0909}{1.618}{1.618}{0} % Express +\end{minipage} +\hfill +\begin{minipage}[b]{\pwlayi} +\drawaspread{\pwlayii}{1.538}{2.647}{.1}{1}{3.833}{0} % Thames & Hudson +\end{minipage} +\caption[Two spreads: USA, 1994 and England, 1988]% + {Two spreads: (Left) USA, 1994. + (Right) England 1988.} \label{fb:7} +\end{figure} + + A modern technical book layout is given in \fref{fb:7}. The book +is \textit{Information Modeling the EXPRESS Way} by Douglas Schenck and Peter +Wilson, published by Oxford University Press (New York) in 1994. This is +set in Computer Modern Roman at $10/12 \times 27$ on a page +$233 \times 150$mm. Ruari McLean's \textit{The Thames and Hudson Manual of +Typography} (1988) is at the right in \fref{fb:7}. This is typeset in +$10/11 \times 20$ Monophoto Garamond on a $240 \times 156$mm page. The wide +\foredge{} is used for small illustrations\index{illustration}. Notes are also set in this +margin\index{margin} rather than at the foot of the page. + + + +\begin{figure} +\centering +\begin{minipage}[b]{\pwlayi} +\drawaspread{\pwlayii}{1.5}{2}{.2}{.5}{1}{0} % Rome +\end{minipage} +\hfill +\begin{minipage}[b]{\pwlayi} +\drawaspread{\pwlayii}{1.5}{1.7}{.111}{1}{2}{0} % Venice +\end{minipage} +\caption[Two spreads: Italy, 1523 and 1499]% + {Two spreads: (Left) Italy, 1523. + (Right) Italy 1499.} \label{fb:8} +\end{figure} + + Many page layouts in earlier days were constructed by +drawing with compass and ruler, usually based on regular geometric figures; +the use of squares, pentagons and hexagons being particularly +prevelant. + Unusually, the typeblock\index{typeblock} in \fref{fb:8} (left) is centered on the page. +The typeblock\index{typeblock} is based on a square, the depth being twice the measure. +The book, \textit{Canzone} by Giangiorgio Trissino, is a volume of poems +and was published in Rome about 1523 by Ludovico degli Arrighi. Prose works +from the same typographer followed the normal style of having the fore-edge +wider than the spine margin\index{margin}. + The page proportion\index{proportion} in \fref{fb:8} (right) is also a simple $3 : 2$ +ratio. The proportions\index{proportion} of the typeblock\index{typeblock}, being $1.7$, are based upon +a pentagon. +The book is \textit{Hypnerotomachia Poliphili} by Francesco Colonna and was +published by Aldus Manutius in Venice in 1499. The story of this, +including some reproductions from the original, is told by Helen +Barolini~\cite{BAROLINI92}. + + +\begin{figure} +\centering +\begin{minipage}[b]{\pwlayi} +\drawaspread{\pwlayii}{1.5}{1.571}{.0769}{2}{3.333}{0} % Magellan +\end{minipage} +\hfill +\begin{minipage}[b]{\pwlayi} +\drawaspread{\pwlayii}{1.5}{1.5}{.111}{1.5}{2}{0} % Gutenberg +\end{minipage} +\caption[Two spreads: France/Portugal, 1530 and Gutenberg, C15th]% + {Two spreads: (Left) France/Portugal, 1530. + (Right) Gutenberg, C15th.} \label{fb:9} +\end{figure} + + In 1519 the Portugese explorer Ferdinand Magellan set sail from +Sanl\'{u}car de Barramada, near C\'{a}diz in Spain, +with five ships and about 270 men. +Three years later one ship and 18 men returned, having made the first +circumnavigation. Among the few survivors was Antonio Pigafetta who recorded +the adventure. +A very few manuscripts of his report are in existence. +The layout of one of these manuscripts which is in the Beinecke Rare +Book and Manuscript Library at Yale is shown at the left of \fref{fb:9}. +The manuscript, which is written in French, is called +\textit{Navigation et descouurement de la Inde superieure et isles +de Malueque ou naissent les cloux de Girosle} (Navigation and discovery +of Upper India and the Isles of Molucca where the cloves grow) is written +in a beautiful humanistic miniscule. There are 27 lines to a page, which +is $286 \times 190$mm and made of vellum. The text measure is $29.5$ +and the `leading' is $21$pt. The wide fore margin\index{margin} is used for sidenotes +indicating highlights of the story. The manuscript was probably prepared +soon before 1530; the scribe and where he worked is unknown. + + Many of the books produced by Johannes Gutenberg (1398--1468) +and his early successors +followed the form shown in +\fref{fb:9} (right). This set of proportions\index{proportion} was also often used in +medieval incunabula\footnote{Early books, especially those printed before +1500.} and manuscripts. The page and typeblock\index{typeblock} proportions\index{proportion} +are the same ($3 : 2$). The margins\index{margin} are in the proportions\index{proportion} +$2 : 3 : 4 : 6$. +A graphical method for constructing this, and similar designs, is +shown later in \fref{flpage:lgut}. + +\begin{figure} +\centering +\begin{minipage}[b]{\pwlayi} +\drawaspread{\pwlayii}{1.5}{1.68}{.043}{2}{5}{0} % Persian Mss +\end{minipage} +\hfill +\begin{minipage}[b]{\pwlayi} +\drawaspread{\pwlayii}{1.5}{1.5}{.1}{2}{2.5}{0} % Persian book +\end{minipage} +\caption[Two spreads: Persia, 1525 and USA, 1975]% + {Two spreads: (Left) Persia, 1525. + (Right) USA, 1975.} \label{fb:10} +\end{figure} + + Two versions of the same publication are shown in \fref{fb:10}. +On the left is a Persian manuscript \textit{Khamsch of Nizami} written +about 1525. The page size is about $324 \times 216$mm. The +illustrations\index{illustration} and +the typeblock\index{typeblock} are inextricably mixed. On the right is a translation of +some of the manuscript published as \textit{Tales from the Khamsch of Nizami} +by the Metropolitan Museum of Art, New York, in 1975. The modern version +has a page size of $300 \times 200$mm, slightly smaller than the original +but in the same proportions\index{proportion}. The typeblock\index{typeblock} is $32$pc wide and the type is +set with a $15$pt leading. + +\begin{figure} +\centering +\begin{minipage}[b]{\pwlayi} +\drawaspread{\pwlayii}{1.48}{1.375}{.0833}{1.75}{2}{0} % Goudy +\end{minipage} +\hfill +\begin{minipage}[b]{\pwlayi} +\drawaspread{\pwlayii}{1.45}{1.414}{.0333}{2}{4.5}{2.175} % Doomsday +\end{minipage} +\caption[Two spreads: USA, 1952 and England, 1087]% + {Two spreads: (Left) USA, 1952. + (Right) England, 1087.} \label{fb:11} +\end{figure} + + Frederic Goudy was a prolific American type designer. Shown at the left of +\fref{fb:11} is the layout of his book \textit{The Alphabet and Elements +of Lettering} published by the University of California Press in 1952. +This is typeset in his University of California Old Style, which has +interesting ct and st ligatures. The measure is $36$pc and the leading +is $18$pt. The first half of the book gives a short history of the development +of writing and fonts. The second half consists of 27 plates, one for each +letter of the alphabet, and the last one for the ampersand character. These +show the evolution of each letter from Roman times to the mid-twentieth +century. + + + Figure~\ref{fb:11} (right) shows the layout of the English +\textit{Domesday Book} which is a manuscript book written in 1087. +It records all the +domains won by William the Conqueror in 1066. The book is written +in a Caroline miniscule +in two columns\index{column!double}, with 44 lines per column ragged right. The two columns +have slightly different widths. The first part of the book is more meticulously +written than the later parts, where the scribe appears to be in haste to +finish. + + +\begin{figure} +\centering +\begin{minipage}[b]{\pwlayi} +\drawaspread{\pwlayii}{1.414}{1.618}{.111}{1}{2}{0} % A4 orig +\end{minipage} +\hfill +\begin{minipage}[b]{\pwlayi} +\drawaspread{\pwlayii}{1.414}{1.618}{.125}{1}{1.667}{0} % A4 mod +\end{minipage} +\caption[Two spreads for ISO page sizes]% + {Two spreads: (Left) ISO (1). + (Right) ISO (2).} \label{fb:12} +\end{figure} + + Figure~\ref{fb:12} shows two different layouts for a page corresponding +to the ISO international standard proportion\index{proportion} of $\sqrt{2}$. In each case +the typeblock\index{typeblock} is the same and proportioned in the +golden section\index{golden section}, +but the margins\index{margin} are different. The layout on the left provides adequate +room for marginal\index{marginalia} notes in the fore-edge. + + +\begin{figure} +\centering +\begin{minipage}[b]{\pwlayi} +\drawaspread{\pwlayii}{1.404}{1.641}{.143}{1}{1.6}{0} % Emery Walker +\end{minipage} +\hfill +\begin{minipage}[b]{\pwlayi} +\drawaspread{\pwlayii}{1.294}{1.618}{.176}{1.037}{1.685}{0} % Latex +\end{minipage} +\caption[Two spreads: England, 1973 and LaTeX $10pt$ book style]% + {Two spreads: (Left) England, 1973. + (Right) LaTeX $10$pt book style.} \label{fb:13} +\end{figure} + + Another of the Cambridge Printer's Christmas books is at the left +of \fref{fb:13}. In this case it is \textit{Emery Walker --- Some Light +on his Theories of Printing and on his Relations with William Morris +and Cobden-Sanderson} by Colin Franklin and published in 1973. The +page size is $295 \times 210$mm with a measure of $31$pc set with +$15$pt leading. On the right is the default layout provided by the +LaTeX $10$pt book class on US letterpaper\index{paper!size!letterpaper}. + +\begin{figure} +\centering +\begin{minipage}[b]{\pwlayi} +\drawaspread{\pwlayii}{1.294}{1.444}{.0833}{1}{2}{0.5} % Adrian Wilson +\end{minipage} +\hfill +\begin{minipage}[b]{\pwlayi} +\drawaspread{\pwlayii}{1.286}{2.11}{.4}{.625}{.625}{0} % Kuniyoshi +\end{minipage} +\caption[Two spreads: USA, 1967 and England, 1982]% + {Two spreads: (Left) USA, 1967. + (Right) England, 1982.} \label{fb:14} +\end{figure} + + Adrian Wilson, who died in 1988, was an acclaimed American book designer. +His work on book design, \textit{The Design of Books}, out of print since +1988 but reissued in 1993 by +Chronicle Books, is outlined +at the left of \fref{fb:14}. This is in two columns\index{column!double}, with many illustrations\index{illustration}, +on letterpaper\index{paper!size!letterpaper} size pages. It is typeset in Palatino and Linotype Aldus +with $12$pt leading. Each column is $18$pc wide. The other layout in this +figure is B.~W.~Robinson's \textit{Kuniyoshi: The Warrior Prints} published +by Phaidon, Oxford in 1982. The page size is $310 \times 242$mm with a +measure of $28.5$pc. The type is set with $13$pt leading. The wide spine +margin\index{margin} is used for some small reproductions of Japanese woodblock prints, +some of which extend across the binding itself. The majority of the book +has no text apart from captioning the many reproduced prints which take +up full pages. + +\begin{figure} +\centering +\begin{minipage}[b]{\pwlayi} +\drawaspread{\pwlayii}{1.25}{1.182}{.1}{1.5}{2}{0} % Fens +\end{minipage} +\hfill +\begin{minipage}[b]{\pwlayi} +\drawaspread{\pwlayii}{1.167}{1.133}{.077}{1}{1}{0.382} % Durer +\end{minipage} +\caption[Two spreads: England, 1972 and Switzerland, 1980]% + {Two spreads: (Left) England, 1972. + (Right) Switzerland, 1980.} \label{fb:15} +\end{figure} + + \textit{The Waterways of the Fens} by Peter Eden with drawings by +Warwick Hutton is another of the Cambridge Printer's Christmas books. +This is set with $17$pt leading on a measure of $27$pc. The original +page size is $195 \times 150$mm and is illustrated on the left +of \fref{fb:15}. +The amount of text on a page varies +and there are many line drawings, some of which take a double spread. +On the right of this figure is another art book, namely \textit{D\"{u}rer} +by Fedja Anzelewsky published by Chartwell Books in 1980. This is set in +two columns\index{column!double} with $14$pt leading on a $23.5$pc measure, +although there are more illustrations\index{illustration} than text. The page +size is $280 \times 240$mm, considerably larger than its companion in +the figure, yet with much smaller margins\index{margin}. + +\begin{figure} +\centering +\begin{minipage}[b]{\pwlayi} +%\drawaspread{\pwlayii}{1.176}{1.46}{.107}{.833}{2.41}{0.25} % Art +\drawaspread{\pwlayii}{.865}{.951}{.111}{1}{2}{0} % Hammer & Hand +\end{minipage} +\hfill +\begin{minipage}[b]{\pwlayi} +\drawaspread{\pwlayii}{.714}{.667}{.111}{0.5}{0.667}{0.333} % Hokusai +\end{minipage} +\caption[Two spreads: England, 1969 and USA 1989]% + {Two spreads: (Left) England, 1969. + (Right) USA, 1989.} \label{fb:16} +\end{figure} + + + Two more layouts for illustrated books are given in \fref{fb:16}. +In this case the illustrations\index{illustration} are drawings in landscape mode (i.e., they +are wider than they are high); the shape of the drawings has had a major +effect on the page proportions\index{proportion}. In the case on the left the page +proportion\index{proportion} is in the ratio $\pi : e$. The measure is longer than usual +at $37$pc and to compensate for this the leading of $17$pt +is also larger than customary. It is typeset in Centaur. +The book is +\textit{Hammer and Hand} by Raymond Lister with drawings by Richard Bawden. +It was published in 1969 by Cambridge University Press and is another of +the University Printer's Christmas books. +Shown on the right of \fref{fb:16} is \textit{Hokusai --- One Hundred Poets} +by Peter Morse and published by George Braziller in 1989. The introductory +text is set in two columns\index{column!double} as shown. The body consists of illustrations\index{illustration} of +Japanese wood block prints, originally in the large \textit{oban} size +of about $250 \times 380$ mm. + +\subsection{A geometric construction} + + Nowadays it is easy to pick and calculate any kind of page proportion\index{proportion} +that takes your fancy, but how did the early printers do it? They certainly +did not have the use of calculators and I suspect that they had only enough +arithmetic to keep their accounts. Printing was a craft and craftsmen did +not release their trade secrets lightly. I believe that most of the designs +were based on simple geometric figures, which required nothing more than +a ruler and a pair of compasses. + + + Jan Tschichold gives a simple construction for the layout of many of Gutenberg's +books~\cite[pages 44--57]{TSCHICHOLD91}, which is shown in \fref{flpage:lgut}. +The construction actually divides the page up into ninths (the point +\textsc{p} in the diagram, which is at the intersection of the main and half +diagonal construction lines, is one third of the way down and across both the +page and the typeblock\index{typeblock}). This construction can be used no matter what the +page proportions\index{proportion} and will give the same relative result. + + +\begin{figure} +\centering +\setlength{\unitlength}{1pc} +\begin{picture}(20,15) +\put(0,0){\framebox(20,15){}} +\thicklines + \put(10,0){\line(0,1){15}} % spine +\put(0,0){\line(4,3){20}} % ll to tr diag +\put(20,0){\line(-4,3){20}} % lr to tl diagonal +\put(0,0){\line(2,3){10}} % ll to tm line +\put(20,0){\line(-2,3){10}} % lr to tm line +\put(13.333,0){\line(0,1){15}} % vertical line thro' half & full diags +\put(14,10){\makebox(0,0)[tl]{\textsc{p}}} +\put(13.333,15){\line(-4,-3){6.667}} % last line +\thinlines +\put(11.111,3.333){\framebox(6.667,10){}} +\put(2.222,3.333){\framebox(6.667,10){}} +\end{picture} +\setlength{\unitlength}{1pt} +\caption{The construction of the Gutenberg page design} +\label{flpage:lgut} +\end{figure} + +\index{spread|)} + +\section{The typeblock} \label{sec:tblock} + + + The typeblock\index{typeblock} is not just a rectangular block of text. If the typeblock\index{typeblock} +does consist of text, then this will normally be broken up into paragraphs\index{paragraph}; +it is not good style to have paragraphs that are longer than a page. Also, +the typeblock\index{typeblock} may include tables\index{table} and illustrations\index{illustration} which provide relief from +straight text. Some pages may have chapter or section headings\index{heading} + on them which +will also break the run of the text. In general the typeblock\index{typeblock} will +be a mixture of text, white space, and possibly non-text items. + + Consider a typeblock\index{typeblock} that includes no illustrations\index{illustration} or tables\index{table}. +The lines of text must be laid out so that they are easy to read. +Common practice, and more recently psychological testing, has shown that +long lines of text are difficult to read. Thus, there is a physiological +upper limit to the width of the typeblock\index{typeblock}. From a practical viewpoint, +a line should not be too short because then there is difficulty in justifying +the text. + + Experiments have shown that the number of characters in a line of +single column\index{column} text on a page should be +in the range 60 to 70 for ease of reading. The range may be as much +as 45 to 75 characters but 66 characters is often +considered to be the ideal number. Much shorter and the eye is dashing +back and forth between each line. Much longer it is hard to pick up the +start of the next line if the eye has to jump back too far --- the same line +may be read twice or the following line may be inadvertently jumped over. +For double column\index{column!double} text the ideal number of characters is around 45, +give or take 5 or so. + + Bringhurst~\cite{BRINGHURST92} gives a method for determining the number +of characters in a line for any font\index{font!measuring}: +measure the length of the lowercase +alphabet and use a copyfitting\index{copyfitting} +table that shows for a given alphabet +length and line length, the average number of characters in that line. + Table~\ref{tab:copyfitting} is an +abridged version of Bringhurt's copyfitting table. +For example, it suggests that a font with a length of 130pt should be +set on a measure of about 26pc for a single column\index{column!double} or in an 18pc wide +column if there are multiple\index{column!multiple} columns. + + +\begin{table} +\DeleteShortVerb{\|} +\centering +\caption{Average characters per line} \label{tab:copyfitting} +\begin{tabular}{r|rrrrrrrr} \hline +Pts. & \multicolumn{8}{c}{Line length in picas} \\ + & 10 & 14 & 18 & 22 & 26 & 30 & 35 & 40 \\ \hline +80 & \textit{40} & \textbf{56} & \textbf{72} & 88 & 104 & & & \\ +85 & \textit{38} & \textit{53} & \textbf{68} & 83 & 98 & 113 & & \\ +90 & \textit{36} & \textit{50} & \textbf{64} & 79 & 86 & 107 & & \\ +95 & 34 & \textit{48} & \textbf{62} & 75 & 89 & 103 & & \\ +100 & 33 & \textit{46} & \textbf{59} & \textbf{73} & 86 & 99 & 116 & \\ +105 & 32 & \textit{44} & 57 & \textbf{70} & 82 & 95 & 111 & \\ +110 & 30 & \textit{43} & 55 & \textbf{67} & 79 & 92 & 107 & \\ +115 & 29 & \textit{41} & 53 & \textbf{64} & 76 & 88 & 103 & \\ +120 & 28 & \textit{39} & \textit{50} & \textbf{62} & 73 & 84 & 98 & 112 \\ +125 & 27 & 38 & \textit{48} & \textbf{59} & \textbf{70} & 81 & 94 & 108 \\ +130 & 26 & 36 & \textit{47} & 57 & \textbf{67} & 78 & 91 & 104 \\ +135 & 25 & 35 & \textit{45} & 55 & \textbf{65} & 75 & 88 & 100 \\ +140 & 24 & 34 & \textit{44} & 53 & \textbf{63} & 73 & 85 & 97 \\ +145 & 23 & 33 & \textit{42} & 51 & \textbf{61} & \textbf{70} & 82 & 94 \\ +150 & 23 & 32 & \textit{41} & \textit{51} & \textbf{60} & \textbf{69} & 81 & 92 \\ +155 & 22 & 31 & \textit{39} & \textit{49} & 58 & \textbf{67} & 79 & 90 \\ +160 & 22 & 30 & 39 & \textit{48} & 56 & \textbf{65} & 76 & 87 \\ +165 & 21 & 30 & 38 & \textit{46} & 55 & \textbf{63} & 74 & 84 \\ +170 & 21 & 29 & 37 & \textit{45} & 53 & \textbf{62} & 72 & 82 \\ +175 & 20 & 28 & 36 & \textit{44} & 52 & \textbf{60} & \textbf{70} & 80 \\ +180 & 20 & 27 & 35 & \textit{43} & 51 & 59 & \textbf{68} & 78 \\ +185 & 19 & 27 & 34 & \textit{42} & \textit{49} & 57 & \textbf{67} & 76 \\ +190 & 19 & 26 & 33 & 41 & \textit{48} & 56 & \textbf{65} & 74 \\ +195 & 18 & 25 & 32 & 40 & \textit{47} & 54 & \textbf{63} & 72 \\ +200 & 18 & 25 & 32 & 39 & \textit{46} & 53 & \textbf{62} & \textbf{70} \\ +220 & 16 & 22 & 29 & 35 & \textit{41} & \textit{48} & 56 & \textbf{64} \\ +240 & 15 & 20 & 26 & 32 & 38 & \textit{44} & 51 & 58 \\ +260 & 14 & 19 & 24 & 30 & 35 & 41 & \textit{48} & 54 \\ +280 & 13 & 18 & 23 & 28 & 33 & 38 & \textit{44} & 50 \\ +300 & 12 & 17 & 21 & 26 & 31 & 35 & 41 & \textit{47} \\ +320 & 11 & 16 & 20 & 25 & 29 & 34 & 39 & \textit{45} \\ +340 & 10 & 15 & 19 & 23 & 27 & 32 & 37 & 42 \\ +\hline +\end{tabular} +\MakeShortVerb{\|} +\end{table} + + + + The vertical height of the typeblock\index{typeblock} should be constant from page to +page. The lines of text on facing pages should be aligned +horizontally across the spine, which also means that they will be at +the same place on both sides of a leaf. Alignment across the spine +means that the eye is not distracted by an irregularity at the centre +of a spread, and leaf alignment stops ghosting of text through a thin page, +giving a crisper look to the work. +So, the spacing between lines should +be constant. This implies that the depth of the typeblock\index{typeblock} should be an +integral multiple of the space required for each line; that is, be specified +as a multiple of the leading. A ten point type, for example, will normally +have two points between lines, to give a leading of 12 points. This can be +written as 10/12. Usefully, one pica is 12 points so with a 12pt leading +vertical distances can be conveniently expressed in picas +(one pica per line). Another +implication of this is that any space left for illustrations\index{illustration} or tables\index{table}, or +the amount of space taken by chapter and section headings\index{heading} +should also be +an integer multiple of the leading\index{leading}. + + A ten point type set solid is described as 10/10. The theoretical +face of the type is ten points high, from the top of a \emph{d} to the bottom +of a \emph{p}, and the distance of the baseline of one row of text to the +next row of text is also ten points. Note that if a \emph{p} is vertically +above a \emph{b} then the ascender of the \emph{b} will meet the descender +of the \emph{p}. To avoid this, the vertical separation between baselines +is increased above the type size. Adding two extra points of vertical space +allows the text to breathe, and gives a leading of 12 points. Few fonts +read well when set solid. Typical settings are 9/11, 10/12, 11/13 and 12/15. +Longer measures require more leading than shorter ones, as do darker and larger +fonts compared with lighter and smaller fonts. More leading is also +useful if the text contains many super-\index{superscript} or sub-scripts, +or many uppercase +letters. + + + +\subsection{Page color} + + One of the aims of the typographer is to produce pages that are uniform +in `color'\index{page color}. +By this they mean that the typeblock\index{typeblock} has a reasonably constant +grayness, not being broken up by too much white space which is a distraction +to the reader. There will be white space around headings\index{heading}, +which is acceptable +as a heading is meant to attract attention. There may be white space between +paragraphs\index{paragraph}, but this is usually under the control of the designer. There +may be vertical rivulets of white space when the interword spaces on +adjacent lines coincide; fixing this usually requires some handwork, either +by the author changing his wording so as to alter the location of +the spaces, or by the typesetter tweaking a little bit. + + Another form of distraction is if too many lines end with hyphens, or +several adjacent lines start or end with the same text; this not only +will cause a rivulet but will make it harder for the reader to reliably +jump to the next line. + + The main font used controls the depth of the color of a page. To +see what color is produced by a particular font it is necessary to look +at a fairly long, preferably a page, piece of normal text. Fonts from +different families produce different colors, and so may mixed fonts from +the same family. You can try this yourself by typesetting the same page +in, say, Computer Modern Roman, Italic, and Sans fonts. +The books by Rogers~\cite{ROGERS43}, Lawson~\cite{LAWSON90}, +Dowding~\cite{DOWDING98}, and +Morison~\cite{MORISON99} all show pages set in many different fonts. + + + +\subsection{Legibility} + + One of the principle requirements on the typography of a document is that +the document is \emph{legible}. Legibility means that the document is designed +to be easily read under a certain set of circumstances. The criteria for +legibility on a poster that is placed on the side of a bus, for example, are +different from those that apply to a book to be read while sitting in an +easy chair. Essentially, the viewer should be able to read the document +with no physical strain caused by the appearance, but the contents, of course, +may lead to anything ranging from acute mental strain to extreme boredom. + + Type faces and the layout of the typeblock\index{typeblock} must be chosen to optimise +between legibility and `artistic' presentation. The design of the document +should be almost invisible, giving full compliments to the author's +communication. However, if you are a master, like +Hermann Zapf~\cite{ZAPF00}, you can break the rules. + + + +\subsubsection{Type faces} + + The first European letter forms that have survived are Greek inscriptions +carved into stone. These were freehand carvings with thin strokes. In time, +the lettering became thicker and serifs started to appear. The Romans +picked up on this later style of letter form. In carving inscriptions, they +first wrote the inscription on the stone using a broad, flat brush. This +naturally led to serifs and differing thicknesses of the letter strokes, +depending on the angle of the stroke with respect to the movement and +orientation of the brush. + + Between the Roman times and Gutenberg there were many changes and +experiments in European letterforms. The scribes used different scripts +for titles, subheads, continuous text, illuminated initial letters, and so +on. In time, two families of letterforms evolved, called \emph{majuscules} +and \emph{miniscules}. The former were larger and more formal, while the latter +were smaller and less formal. We now call these two divisions upper case and +lower case. The upper case derives from Roman times, while the lower case +acquired its fundamental form during the reign of the Holy Roman Emperor +Charlemagne a thousand years later. +A further division also appeared, between black letter (what is +commonly referred to as Gothic or Old English) type and the roman type. + + These types were all upright. Italic letterforms were cut in Italy +in the early sixteenth century, as a more cursive style. Initially these were +lower case only, used in conjunction with upper case roman. By the end of +the century, sloped roman capitals were also in use with italic. + +\index{font!seriffed|(} +\index{font!sans|(} + The late nineteenth century saw the appearance again of sans-serif +typefaces. + + Looking carefully at seriffed and sans-serif fonts it is apparent that +the serifs have three main functions: +\begin{enumerate} +\item They help to keep letters apart. +\item At the same time, they help to keep letters in a word together. This + helps with legibility as research has shown that we tend to recognize + words by the shape of the word rather than by individual characters. +\item They help to differentiate between individual but similar letters. +\end{enumerate} + +Long experience has shown that a seriffed font is easier to +read\footnote{This is actually somewhat contentious as some take the view +that with enough practice, sans-serif is just as easy to read.} +than a +sans-serif font, particularly if part of the text is obscured. You can +try an experiment yourself to verify this. Try writing a phrase, once +using a sans-serif font and then with a serifed font. Cover up +the top halves of the two phrases and try to make out what they say. Then +repeat this, except this time cover up the bottom halves of the phrase. +Which is easier to read? Here are some example characters, firstly in san-serif: +\begin{center} +{\Huge\sffamily a c l m n p q o} +\end{center} +and then in roman: +\begin{center} +{\Huge a c l m n p q o} +\end{center} + + Sans-serif fonts often require context to decipher the word. +For example~\cite{MCLEAN80}, +seeing this in isolation +\begin{center} +{\Huge\sffamily lll} +\end{center} +does it stand for `Ill', `one hundred and eleven', `three', or something +completely different like a dingbat or a set of cricket stumps? + + + There are three generally agreed legibility principles for setting text for +continuous reading. + +\begin{enumerate} +\item \emph{Sans-serif type is intrinsically less legible than seriffed type}~\cite{WHEILDON95}. + + We have already seen that this is the case --- there is more variety +among seriffed letters than among sans-serif letters. Further, serifs +perform other functions as well, such as binding letters together within +a word. + + This is not to say that a sans-serif letterform is always more illegible +than a roman one. A poor seriffed form can be much more illegible than +a well used good sans-serif. In general, there is an illegibility factor +associated with sans-serif that must be borne in mind; for general +\emph{continuous} reading, a good seriffed form is more likely to be +easy on the eye than a good sans form. + +\item \emph{Well designed upper and lower case roman type is easier to read than +any of its variants.} + + This is a guiding principle with many exceptions. Among the variants +can be considered to be italic and bold types. These have usually been +designed for a special purpose, like emphasing\index{emphasis} +certain pieces of text, rather +than for general legibility. Some italic types, though, are as legible as their +roman counterparts. In the seventeenth century many books were set entirely +in italic, but we have become accustomed to the roman type. + +\item \emph{Words should be set closer together than the space between lines.} + + All text is a mixture of ink and white space. The eye, when reading, +tends to jump over the white spaces. Given a choice between two spaces, it +will tend to jump over the smaller of the two. If the word spacing is greater +than the line spacing, then you can find yourself skipping from one line +to the next before finishing the first one. + + Further, if the lines are too long, then when the eye jumps back from +the end of one line to the start of the next, it may have difficulty in +picking up the correct one. + + Text lines are justified by altering the inter-word spacing, and possibly +by hyphenating the last word on the line if the spacing would be too bad +otherwise. Sans-serif fonts often look best if set ragged right, as this will +keep the inter-word spacing constant. Text set in narrow columns\index{column} also often +looks best when set ragged right. + + +\end{enumerate} + +\subsubsection{Seriffed versus sans-seriffed fonts} + + As noted earlier there seems to be a permanent debate over the use +of seriffed and sans fonts. You will have to make up your own mind as +to what is best for any particular work, but here are some general +comments from some of the literature on the subject. + +\begin{itemize} +\def\makelabel#1{\noindent #1} +\item[Bohle~\cite{BOHLE90}] notes: Readers prefer a roman typeface for body + type because they are most used to seeing that face~\cite{REHE72}. + Roman type may well also be more readable than sans serif faces because + the serifs help connect the letters to form the word shape when + we read~\cite{REHE72}. + +\item[Craig~\cite{CRAIG92}] says: You will find that the serifs on a typeface + facilitate the horizontal flow necessary to comfortable reading. + +\item[Degani~\cite{DEGANI92}] in a study of pilots reading checklists + in emergency cockpit situations decided that sans serif faces were + better than serif faces. + +\item[Schriver~\cite{SCHRIVER97}] notes: Serif and sans serif typefaces + are likely to be equally preferred by + readers~\cite{HARTLEY83,TINKER63} + and read equally quickly~\cite{GOULD87,HARTLEY83,ZACHRISSOM69}. + Serif faces may be easier to read in continuous text than sans + serif faces~\cite{BURT59,HVISTENDAHL75,ROBINSON71,WHEILDON95}. + +\item[Wheildon~\cite{WHEILDON95}] did a series of studies with around +250 readers in Sydney, Australia, asking them to rate serif and sans fonts +in a variety of uses. Among the many results he reported: +\begin{itemize} + \item More than five times as many readers are likely to show good + comprehension when a serif body type is used instead of a sans serif + body type. + \item The top half of [upper case] letters is more recognizable than + the bottom half. + \item There is little difference in legibility between headlines + [section titles] set in serif and sans serif typefaces, or between + roman and italic. + \item Headlines set in capital letters are significantly less legible + than those set in lower case. +\end{itemize} + +\end{itemize} + + The consensus, such as it is, seems to lean towards serifed +typefaces for continuous reading, but for titling the choice is +wide open. + +\index{font!sans|)} +\index{font!seriffed|)} + +\subsection{Widows and orphans} + + Inconvenient page breaks can also cause a hiatus in the reader's perusal +of a work. These happen when a page break occurs near the start or end of +a paragraph\index{paragraph}. + + A \emph{widow}\index{widow} is where the last line of a paragraph\index{paragraph} is the first +line on the page. The term is sometimes also used to refer to when the +last word in a paragraph\index{paragraph} is on a line by itself. A widow looks forlorn. +As Robert Bringhurst said, `A widow has a past but no future'. +Typographically, widows should be avoided. Especially to be avoided +are widows that are +the only line on a page, for example at the end of a chapter\index{chapter}. Five lines +on the last page of a chapter\index{chapter} is a reasonable minimum. + + An orphan\index{orphan} is not nearly so troubling to typographers as a widow. An +\emph{orphan} is where the first one or two lines of a paragraph\index{paragraph} are at the +bottom of a page. Bringhurt's memory trick for orphans is, `An orphan has +a future but no past'. + +\subsection{Paragraphs and versals} \label{sec:versal} + +\index{paragraph|(} + + Early books did not have paragraphs as we know them nowadays; the text +was written continuously, except for a break at a major division like the +start of a new book in a bible. Instead +the scribes used a symbol like \P\ (the pilcrow) to mark the beginning of +paragraphs. This symbol is derived from the Greek $\Pi$, for +\textit{par\'{a}graphos}. Mind you, they often did not use any punctuation +at all and were sparing in their use of uppercase letters, +so you might have seen something like this\footnote{But probably not. +The two `paragraphs' are Latin abecedarian sentences.} + +\begin{quote} +usque \P\ te canit adcelebratque polus rex gazifier hymnis + \P\ transzephyrique globum scandunt tua facta per axem +\end{quote} + + Nowadays paragraphs are ended by stopping the line of text at +the end of the +paragraph, and then starting the next paragraph on a new line. The question +then becomes: how do you indicate a new paragraph when the last line of the +previous paragraph fills up the measure? There are two solutions, which +unfortunately you +sometimes see combined. Either indent the beginning of the first line of +each paragraph, or put additional vertical space between the last and +first lines of paragraphs. + + The traditional technique, which has served well for centuries, is to +indent the first line of a paragraph\index{paragraph!indentation}. The indentation need not be large, +about an em will be enough, but more will be required if the typeblock\index{typeblock} +is wide. + + The other method is used mainly in business letters and is a recent +invention. The first lines of paragraphs\index{paragraph!indentation} are not indented and typically + one blank line is left between paragraphs. This may +perhaps be acceptable when using a typewriter, but seems to have no real +justification aesthetically. There is also the problem when a paragraph +both ends with a full line and ends a page. As the next paragraph then starts +at the top of the next page, the blank line separating the two paragraphs +has effectively dissappeared, thus leaving the reader in a possible state +of uncertainty as to whether the paragraph continues across the page break +or not. + + If the paragraph is the first one after a heading\index{heading}, +then there +is no need to indicate that it is a new paragraph --- it is obvious from its +position. So, the first paragraph after a heading\index{heading} +should not be indented\index{paragraph!indentation}. +In some novels only chapters are headed yet each chapter is broken into +sections by putting additional vertical blank space between the sections. +Like nonindented paragraphs\index{paragraph!indentation}, this can cause problems where a section division +coincides with a page break. In this case, typographers sometimes use a +decoration to separate sections (for example, a short centered row of a few +asterisks). + + +%%%%%%%%\clearpage +%\subsection{Versals} + +\drop{S}{}\textsc{ome typographers}\index{versal|(} +like to start the first paragraph in a chapter +with a versal. A \emph{versal} is a large initial letter, either raised or +dropped. This comes from the scribal tradition of illuminating the first +letter of a manuscript. The versal may be raised or dropped, as already noted, +or it may be placed in the margin\index{margin}, or otherwise treated in a special manner. + +\versal{S}\textsc{ome versals,} especially dropped versals, are very difficult +to typeset correctly. Many attempts of this kind are abject failures, so +be warned. For example, compare the dropped versals at the start of these +first two paragraphs. They are both of the same letter and font, yet the first +one is horrible compared to the one starting this paragraph. + + +\noindent {\huge I}\textsc{t is easier} to start a paragraph with +a raised +capital than one that is dropped. A raised versal should only be used +where there is naturally some vertical space above it. As you can see, extra +spacing has had to be inserted before this paragraph to accomodate the versal. +There are still problems with typesetting a raised versal but as these tend +to be subtler than with a dropped versal, readers are less likely +to notice problems. + +Typically, small caps are used for a little while following a versal to +provide a transition between the large versal font and the normal body font. +These should not continue throughout the first line as this tends to divorce +it from the remainder of the paragraph. \index{versal|)} + +\noindent \textsc{Another way of starting} a paragraph is to use small +caps for the first few words. The font difference highlights the start +of the paragraph but in a much quieter manner than a versal does. Using +normal sized upper-case instead of the small caps is too much of a +contrast with the lower-case. + +\index{paragraph|)} + +\subsection{Footnotes} + +\index{footnote|(} + Footnotes are considered to be part of the typeblock\index{typeblock}. They are +typeset in the space allocated for the typeblock\index{typeblock}, in contrast to +footers\index{footer} +which are typeset below the typeblock\index{typeblock}. + + Footnotes are normally set in the same type style as the typeblock\index{typeblock}. +That is, if an upright seriffed font is used for the typeblock\index{typeblock}, it is +also used for the footnote. The +type size is smaller to distinguish the note from the body text and often +the leading in the footnote is also reduced from that in the main text body. +The bottom footnote line should be at the same height as the bottom line +of the typeblock\index{typeblock}. This usually requires some adjustment of the vertical +space before the footnotes. + + A vertical blank space is often used to set off the footnotes from the +main text, and sometimes a short horizontal line is also used as demarcation. + +\index{footnote|)} + +\section{Folios} + +\index{folio|(} + + The word \emph{folio} is a homonym. It can mean a leaf +(two back-to-back pages) in a book, the size of a book or a book of +folded sheets (as in Shakespeare's first folio), or the printed page number +in a book. Here I use folio in this last sense. + + Documents should have folios, at a minimum to help the reader know where +he is. Occasionally books have their folios placed near the spine but this +positioning is unhelpful for navigation. The more usual positions are +either centered with respect to the typeblock\index{typeblock} or aligned with the outside +of the typeblock\index{typeblock}, and sometimes even in the outside margin\index{margin}. The folios +can be either at the top or bottom of the page but at least on pages +with chapter\index{chapter} openings are normally placed at the bottom of the page so that +they do not distract from the title text. + + Every page in a document, except perhaps the title and half title pages +in a book, should be numbered, even if the page does not have a folio. +In books, the folios for the front material are often in roman numerals. +The main and rear matter folios are arabic numerals, with the sequence +starting from 1 after the front matter. In certain technical documents, +folios may be in the form of chapter number\index{chapter!number} and page number, with the page +number starting from 1 in each new chapter. Other folio schemes are possible +but unusual. + + Folios should be placed harmoniously with respect to the typeblock\index{typeblock} and +page margins\index{margin}. The font used for the folios need not be the same as that +for the typeblock\index{typeblock} but must at least be complementary and non-intrusive. + +\index{folio|)} + +\section{Headers and footers} + +\index{header|(}\index{footer|(} + Headers and footers are repetitive material that is placed at either +the head or the foot of the page. Typically, folios\index{folio} are headers or footers, +but not always as sometimes they are placed in the margin\index{margin} at or below the +first line in the typeblock.\index{typeblock} + + From now on I will not distinguish between headers and footers and +just use the word header. Sometimes the header is purely decorative (apart +from a folio\index{folio}) like a horizontal line or some other non-textual marking. +Normally they have a functional use in helping the reader locate himself +in the document. + + The most ubiquitous header is one which gives the title of the document. +If this is the only header, then I consider this to be decorative rather +than functional. As a reader I know what document I am reading and do not +need to be reminded every time I turn a page. More useful are headers that +identify the current part of the document, like a chapter\index{chapter} title or number. +When you put the document down and pick it up later to continue reading, these +help you find your place, or if you need to refer back to a previous chapter +for some reason, then it is a boon to have a chapter heading\index{heading} +on each +spread. The minimally functional headers are where the document title +is on one page and the chapter heading is on the facing page. In more technical +documents it may be more useful to have headers of chapter and section titles +on alternate pages. + + Occasionally both headers and footers are used, in which case one normally +has constant text, like a copyright\index{copyright} notice. +I have the feeling that using +the latter is only functional for the publishers of the document +when they fear photocopying or some such. + + The header text is usually aligned with the spine side +of the typeblock\index{typeblock}, but may be centered on top of the typeblock\index{typeblock}. In any event, +it should not interfere with the folio\index{folio}. The type style need not be the same +as the style for the typeblock\index{typeblock}. For example, headers could be set in italic +or small caps, which must blend with the style used for the +typeblock.\index{typeblock} + +\index{footer|)}\index{header|)} + +\chapter{Picky points} + +\section{Introduction} + + The main elements of good typography are legibility and page color. +This chapter discusses some of the smaller points related to these topics. + +\section{Word and line spacing} + + Research has shown that the competent reader recognises words by +their overall shape rather than by stringing together the individual letters +forming the words. A surprisingly narrow gap between words +is sufficient for most to distinguish the word boundaries. + + Most typographers state that the space between words in continuous +text should be about the width of the letter `i'. Any closer and the +words run together and too far apart the page looks speckled with white +spots and the eye finds it difficult to move along the line rather than +jumping to the next word in the next line. + Figure~\ref{fig:interword} illustrates different values of interword +spacing. + +\setlength{\unitlength}{\fontdimen2\font} +\begin{figure} +\centering +%\fbox{% +\begin{minipage}{\textwidth} +\mbox{}\hrulefill\mbox{} +\begin{quotation} +\fontdimen2\font=2\fontdimen2\font + The following paragraph is typeset with double the normal interword +spacing for this font. + + Most typographers state that the space between words in continuous +text should be about the width of the letter `i'. Any closer and the +words run together and too far apart the page looks speckled with white +spots and the eye finds it difficult to move along the line rather than +jumping to the next word in the next line. +Extra spacing after punctuation is not necessary. +\end{quotation} +\begin{quotation} +\fontdimen2\font=\unitlength + The following paragraph is typeset with the normal interword spacing +for this font. + + Most typographers state that the space between words in continuous +text should be about the width of the letter `i'. Any closer and the +words run together and too far apart the page looks speckled with white +spots and the eye finds it difficult to move along the line rather than +jumping to the next word in the next line. +Extra spacing after punctuation is not necessary. +\end{quotation} +\begin{quotation} +%\settowidth{\unitlength}{i} +\settowidth{\fontdimen2\font}{i} + The interword spacing in the following paragraph is the width +of the letter `i'. + + Most typographers state that the space between words in continuous +text should be about the width of the letter `i'. Any closer and the +words run together and too far apart the page looks speckled with white +spots and the eye finds it difficult to move along the line rather than +jumping to the next word in the next line. +Extra spacing after punctuation is not necessary. +\end{quotation} +\mbox{}\hrulefill\mbox{} +\end{minipage} +%} % end fbox +\fontdimen2\font=\unitlength \setlength{\unitlength}{1pt} +\caption{Interword spacings}\label{fig:interword} +\end{figure} + + In keeping with avoiding white spots, many typographers do not +recommend extra spacing after punctuation, although this does depend +partly on a country's typographic history and partly on the individual. +I always found typewritten texts with double spaces after the end +of sentences a particular eyesore. However, with typeset texts any +extra spacing is usually not as large as that. + + The spacing between lines of text should be greater than the interword +spacing, otherwise there is a tendency for the eye to skip to the +next line instead of the next word. Figure~\ref{fig:interline} illustrates +some text typeset with different line spacings. The normal interword +spacing is used in the samples. + +\begin{figure} +\centering +%\fbox{% +\begin{minipage}{\textwidth} +\mbox{}\hrulefill\mbox{} +\normalfont\setlength{\unitlength}{\baselineskip} +\begin{quotation} +\normalfont\setlength{\baselineskip}{1em} + This paragraph is set solid --- the interline spacing is the same +as the font size. The normal interword spacing is used. + The spacing between lines of text should be greater than the interword +spacing, otherwise there is a tendency for the eye to skip to the +next line instead of the next word. \par +\end{quotation} +\begin{quotation} +\normalfont\setlength{\baselineskip}{\unitlength} + This paragraph is set with the normal interline spacing for the font. +The normal interword spacing is used. + The spacing between lines of text should be greater than the interword +spacing, otherwise there is a tendency for the eye to skip to the +next line instead of the next word. \par +\end{quotation} +\begin{quotation} +\normalfont\setlength{\baselineskip}{1.2\unitlength} + This paragraph is set with the interline spacing 20\% greater than +is normal for the font. +The normal interword spacing is used. + The spacing between lines of text should be greater than the interword +spacing, otherwise there is a tendency for the eye to skip to the +next line instead of the next word. \par +\end{quotation} +\mbox{}\hrulefill\mbox{} +\end{minipage} +%} % end fbox +\normalfont\setlength{\baselineskip}{\unitlength} +\setlength{\unitlength}{1pt} +\caption{Interline spacings}\label{fig:interline} +\end{figure} + +\section{Abbreviations and acronyms} + +\index{abbreviation} + The English style with abbreviations is to put a full stop (period) after +the abbreviation, unless the abbreviation ends with the same letter as the +full word. Thus, it is Mr for Mister, Dr for Doctor, but Prof.~for Professor. +No extra spacing should be used after the full stop, even if extra +spacing is normally used after punctuation. + + Acroynms\index{acronym} are typeset in uppercase but the +question is, which uppercase? +The simple way is to use the uppercase of the normal font, like UNICEF, but +if there are too many acronyms scattered around the speckled effect starts +to intrude. If the font family has one, then small caps can be used, +giving \textsc{unicef}. If small caps are not available, or appear +undesireable, then a smaller size of the normal uppercase can be used, +such as {\small UNICEF} or {\footnotesize UNICEF}; some experimentation +may be required to select the appropriate size. + +\section{Dashes and ellipses} + +\index{dash|(} + Most fonts provide at least three lengths of dashes. The shortest is +the hyphen (-), then there is the en-dash (--) which is approximately the +width of the letter `n', and the largest is the em-dash (---) which is +approximately twice the length of an en-dash. An expert font may provide +more. + + Unsurprisingly, the hyphen is used for hyphenation, such as in em-dash, or +at the end of a line where a word had to be broken. + + The en-dash is normally used between numerals to indicate a range. For +example a reference may refer to pages 21--27 in some journal or book. There +is no space surrounding the en-dash when used in this manner. + + The em-dash, or the en-dash, is used as +punctuation --- often when making a side +remark --- as a phrase separator. + When en-dashes are used as punctuation it is normal to put spaces around them +but the question of spaces around an em-dash appears to be the subject of +some contention. Roughly half the participants in any discussion advocate +spaces while the other half view them as anathema. If you do use em-dashes +be sure to be consistent in your use, or otherwise, of spaces. + + Ellipses\index{ellipses} are those three, or is it four, +dots indicating something is +missing or continues somewhat indefinitely. In the middle of a sentence, +or clause or \ldots\ they have a space on either side. At the end of +a sentence the English style is to have no spaces and include the full +stop, making four dots in all, like so\ldots. + + Dashes are also used to indicate missing characters or a word. Missing +characters in the middle of a word are indicated by a 2em-dash (a dash that +is twice as long as an em-dash), as in: +\begin{quote} +\textbf{snafu,} \textit{(U.S. slang)} \textit{n.} chaos. --- \textit{adj.} + chaotic. [\textit{s}ituation \textit{n}ormal --- \textit{a}ll + \textit{f}------d \textit{u}p.] +\end{quote} +A 3em-dash is used to indicate a missing word. When I lived in Maryland my +local small town newspaper was the \textit{Frederick Post.} +The following is from an +obituary I happened to read; I have hidden the name to protect the +innocent. +\begin{quote} + Although he had spent the last 92 years of his life here, +Mr. --------- was not a Fredericktonian. +\end{quote} + +\index{dash|)} + +\section{Punctuation} + +\subsection{Quotation marks} + +\index{quotation marks|(} + Quotation marks surrounding speech and associated punctuation +are a fruitful source of confusion. + + The American style is to use double quotes at the start(``) and +end ('') of spoken words. If the speaker quotes in the speech then single +quote marks (` and ') are used to delineate the internal quotation\index{quotation}. + + The English practice is exactly the opposite. Main speech is delineated +by single quotes and internal quotations\index{quotation} by double quotes. In any event, +if single and double quotes are adjacent they should be separated by a thin +space in order to distinguish one from the other --- a full interword space +is too wide. + + As there are likely to be few internal quotations\index{quotation} it seems to me that +the English practice produces a less spotty appearance than the American. +Figure~\ref{fig:qmarks} shows the same text typeset in both the English +and American styles. The example is from Lewis Carroll's +\emph{Through the Looking Glass and what Alice Found There} +and has an unusually large number of internal quotations\index{quotation}. + +\begin{figure} +\centering +\begin{minipage}{\textwidth} +\mbox{}\hrulefill\mbox{} +\begin{quotation} + `There's glory for you!' + + `I don't know what you mean by ``glory''\,', Alice said. + + Humpty Dumpty smiled contemptuously. `Of course you don't --- till I tell +you. I meant ``there's a nice knock-down argument for you''!' + + `But ``glory'' doesn't mean ``a nice knock-down argument''\,', Alice +objected. + + `When \emph{I} use a word', Humpty Dumpty said, in a rather scornful +tone, `it means just what I choose it to mean --- neither more nor less'. +\end{quotation} +\mbox{}\hrulefill\mbox{} +\begin{quotation} + ``There's glory for you!'' + + ``I don't know what you mean by `glory,'\,'' Alice said. + + Humpty Dumpty smiled contemptuously. ``Of course you don't --- till I tell +you. I meant `there's a nice knock-down argument for you!'\,'' + + ``But `glory' doesn't mean `a nice knock-down argument,'\,'' Alice +objected. + + ``When \emph{I} use a word,'' Humpty Dumpty said, in a rather scornful +tone, ``it means just what I choose it to mean --- neither more nor less.'' +\end{quotation} +\mbox{}\hrulefill\mbox{} +\end{minipage} +\caption{Quotation marks: top English, bottom American}\label{fig:qmarks} +\end{figure} + + Where to put punctuation marks with quotes is vexatious. Again the +English and American practice tends to differ. The American tendency is +to put commas and periods inside the closing quote mark and colons and +semicolons after the mark. English editors prefer to put punctuation +after the mark. +In either case, it is difficult +to know exactly what to do. I get the impression that for every example +of the `correct' form there is a counter-example. +Some try and avoid the problem altogether by putting the lower marks, +like commas or periods, +directly below the quotation mark but that may cause problems if the +resulting constructs look like question or exclamation marks. +In \fref{fig:qmarks} I have tried to use the English and American +punctuation styles in the respective examples but it is likely that there +are misplacements in both. I think it's basically a question of doing what +you think best conveys the sense, provided there is consistency. +\index{quotation marks|)} + +\subsection{Footnote marks} + +\index{footnote!mark|(} + Where to put a footnote marker may be another vexed question in spite +of the general principal being easy to state: The mark goes immediately +after the text element that the note refers to. + + There is no doubt what this means\footnote{Except to some I know.} when +the text element is a word in the middle of other words. Doubt raises +its head when the reference is to a phrase, like this one\footnote{I hope +that this is a phrase.\label{fn:phrase}}, +which is set off within commas, or when the note refers to a complete +sentence.\footnote{Is this mark in the correct place?\label{fn:sentence}} + + Like punctuation and quotation marks\index{quotation marks}, +should a footnote mark come before +or after the punctuation mark at the end of a phrase or a sentence? I have +shown both positions\footnote{Marks \ref{fn:phrase} and \ref{fn:sentence}.} + in the previous paragraph. The +general rule that I have deduced is that the mark comes after the +punctuation, but there are always those who like to prove a rule. + +\index{footnote!mark|)} + +\index{symbol|(} + There are other marks that may be associated with a word, like +(registered) trademarks. These may produce ugly gaps. Sometimes these +cannot be avoided but it may be possible to change the text to minimise +the hiccup. There is an example of this on \pref{fn:ps}. I tried various +schemes in identifying `PostScript' as being a registered trademark of +Adobe Systems Incorporated. Among the discarded trials were: +\begin{quote} +\ldots languages like PostScript\texttrademark, presumably \ldots + +\ldots languages like PostScript\textsuperscript{\textregistered}, presumably \ldots + +\ldots like the PostScript\textsuperscript{\textregistered}{} language, presumably \ldots + +\end{quote} +My final solution was to note the registered trademark information in +a footnote: +\begin{quote} +\ldots languages, like PostScript\footnote{PostScript is a registered +trademark of Adobe Systems Incorporated.}, presumably \ldots +\end{quote} +In this case I decided that the footnote\index{footnote} was really tied to the word +`PostScript', taking the place of the registered symbol, so I put the +footnote mark\index{footnote!mark} before the comma rather than after it. +\index{symbol|)} + +\subsection{Font changes} + +\index{font!change|(} + + Sometimes a word or two may be set in a different font from the +surrounding text, such as when emphasizing\index{emphasis} +a word by setting it in an +italic font. If the word is followed by a punctuation mark the normal +practice is to set the mark using the new font instead of the normal +font. In some cases the font used for the punctuation may not be +particularly noticeable but sometimes it may be. + + The frontmatter contains two definitions of the word \textit{memoir,} +which is typeset using a bold font. The definitions thus commence like \\ +\hspace*{2em} \textbf{memoir,} \textit{n.} \ldots \\ +instead of \\ +\hspace*{2em} \textbf{memoir}, \textit{n}. \ldots + +\index{font!change|)} + +\section{Narrow measures} + +\index{measure!narrow|(} + + Typesetting in a narrow column\index{column} is difficult, especially if you are +trying to make the text flush left and right. As the lines get shorter +it becomes more and more difficult to fit the words in without an excessive +amount of interword spacing or word breaking at the ends of lines. +In the limit, of course, there +will not be even enough room to put a syllable on a line. + + The best recourse in situations like this is to forget justification +and typeset ragged right. Ragged right looks far better than justified +text with lots of holes in it. +The question then is, to hyphenate or not to hyphenate?\index{hyphenation} + + With no hyphenation there is likely to be increased raggedness at +the line ends when compared with permitting some hyphenation. Hyphenation +can be used to reduce the raggedness but somehow short lines ending with +a hyphen may look a bit odd. This is where you have to exercise your +judgement and design skills. + + Indexes\index{index} are often typeset in double, or even triple or quadruple columns\index{column!multiple}, +as each entry is typically short. Also, indexes\index{index} are typically consulted +for a particular entry rather than being read as continuous text. To help +the eye, page numbers are normally typeset immediately after the +the name of the indexed topic, so indexes\index{index} tend to be naturally ragged right +as a matter of reader convenience. + +\index{measure!narrow|)} + + Talking of hyphenation\index{hyphenation}, + each language has its own rules for allowable +hyphenation points. As you might now have come to suspect, English and +American rules are different even though the language is nominally the same. +Broadly speaking, American English hyphenation points are typically based on +the sound of the word, so the acceptable locations are between syllables. +In British English the hyphenation points tend to be related to the +etymology of the word, so there may be different locations depending on +whether the word came from the Greek or the Latin. If you are not sure +how a particular word should be hyphenated, look it up in a dictionary +that indicates the potential break points. + +\section{Emphasis} + +\index{emphasis|(} + Underlining\index{underline} should \underline{emphatically} \underline{not} be +used to emphasise something in a typeset document. This is a hangover +from the days when manuscripts were typewritten and there was little +that could be done. The other way of emphasising something was to +put extra space between the characters of the w\,o\,r\,d being +e\,m\,p\,h\,a\,s\,i\,s\,e\,d, as has been done twice in this sentence. +As an aside, for me at least, that extra spacing produces the +illusion that the +characters are slightly larger than normal, which is not the case. + + With the range of fonts and sizes available when typesetting there +are other methods for emphasis, although German typographers have used +letterspacing for emphasis with the fraktur and other similar font types. + + There are basically three aproaches: +change the {\large size} of the font; +change the \textbf{weight} of the font; or most usually, change the +\emph{shape} of the font. There is a creative tension when trying +to emphasise something --- there is the need to show the reader the +emphasised +element, but there is also the desire not to interrupt the general flow +of the text. Out of the three basic options, changing the shape seems +to be a reasonable compromise between the need and the desire. +\index{emphasis|)} + +\section{Captions and legends} + +\index{caption|(} +\index{legend|(} + + I am not entirely sure what is the difference between a +caption and a legend as both terms refer to the title of an illustration\index{illustration} +or table\index{table}. However, legend may also be used to refer to some explanatory +material within an illustration\index{illustration}, such as the explanation of the symbols +used on a map. + + In any event, captions and legends are usually typeset in a font that +is smaller than the main text font, and which may also be different from the +main font. For example, if the main font is roman and a sans font is used +for chapter titles, then it could be appropriate to use a small size +of the sans font for captions as well. + + The caption for a table\index{table} is normally placed above the table while +captions for illustrations\index{illustration} are placed below. + +\index{legend|)} +\index{caption|)} + +\section{Tables} + +\index{table|(} + + A table is text or numbers arranged in columns\index{column!multiple}, and nearly always +with a `legend'\index{legend} above each column describing the meaning of +the entries in the column. The legends and the column entries are +separated from each other, perhaps by some vertical space but more often +by a horizontal line. + + In general typographers dislike vertical lines in a table, which may +be likely to be used to separate the columns. I'm not sure why this is. +There is an obvious explanation when hand setting the individual characters +as although it would be easy to set horizontal rules it would be very +difficult to get all the pieces of type with the bits of the vertical rules +aligned properly --- the eye is very sensitive to jags in what is meant to +be a straight line. In the days of digital typography the alignment problem +has gone away, so perhaps the antipathy to vertical lines is a tradition +from earlier days. + + If you want to use vertical lines, just be aware that not everybody +may appreciate your effort. + + +\index{table|)} + + + +\chapter{Electronic books} +\index{electronic books|(}\index{Ebook|see{electronic books}} +\section{Introduction} + + For want of a better term I am calling electronic books, or Ebooks, +those documents intended to be read on a computer screen. The vast bulk +of Ebooks are in the form of email but I'm more interested here in +publications that are akin to hardcopy reports and books that require +more time than a few minutes to read. + + This brief chapter includes some suggestions for the +layout of Ebooks, based on my experience with such works. +Not considered are internal navigation aids +(e.g., hyperlinks) within and between Ebooks, nor HTML documents where +the visual appearance is meant to set by the viewing software and not +by the publisher. + +\section{Observations} + + Unlike real books which have been available for hundreds of years there +is virtually no experience to act as a guide in suggesting how Ebooks should +appear. + + The publication medium is obviously very different --- a TV-style +screen with limited resolution and pretty much fixed in position versus +foldable and markable paper\index{paper} held where the reader finds it best. +These differences lead to the following suggestions. + + A book can be held at whatever distance is comfortable for reading, even +when standing up. +The computer user is normally either sitting in a chair with the monitor +on a desk or table, or is trying to read from a laptop, which may be +lighter but nobody would want to hold one for any length of time. To try +and alleviate the physical constraints on the Ebook reader the font size +should be larger than normal for a similar printed book. This will provide +a wider viewing range. A larger font will also tend to +increase the sharpness of the print as more pixels will be available for +displaying each character. + + I find it extremely annoying if I have to keep scrolling up and down +to read a page. Each page should fit within the screen, which means that +Ebook pages will be shorter than traditional pages. + A suggested size for an Ebook page, in round numbers, is +about 9 by 6 inches~\cite{ADOBEBOOK} or 23 by 15 centimetres overall. + + The font size should not be less than 12pt. The font may have to be +more robust than you would normally use for printing, as fine hairlines +or small serifs will not display well unless on a high resolution screen. + + The page design for printed books is based on a double spread. For +Ebooks the design should be based on a single page. The typeblock\index{typeblock} must +be centered on the page otherwise it gets tiring, not to mention +aggravating, if your eyes have to +flip from side to side when moving from one page to the next. Likewise +any header\index{header} and the top of the typeblock\index{typeblock} must be at a constant height +on the screen. A constant position for the bottom of the text is not +nearly so critical. + + It is more difficult with an Ebook than with a paper\index{paper} book to flip through +it to find a particular place. Navigation aids --- headers\index{header} and footers\index{footer} --- +are therefor more critical. Each page should have both a chapter +(perhaps also a section) header\index{header} title and a page number. Note that I'm not +considering HTML publications. + + Many viewers for Ebooks let you jump to a particular page. The page +numbers that they use, though, are often based on the sequence number from +the first page, not the displayed folio\index{folio}. In such cases it can be helpful +to arrange for a continuous sequence of page numbers, even if the folios\index{folio} +are printed using different styles. For example, if the front matter uses +roman numerals and the main matter arabic numerals and the last page of the +frontmatter is page xi, then make the first page of the main matter page 12. + + I see no point in Ebooks having any blank pages --- effectively the +concept of recto and verso pages is irrelevant. + + Some printed books have illustrations\index{illustration} that are tipped in, and the tipped +in pages are sometimes excluded from the pagination. In an Ebook the +illustrations\index{illustration} have to be `electronically tipped in' in some fashion, either +by including the electronic source of the illustrations\index{illustration} or by providing +some navigation link to them. Especially in the former case, the +tipped in elements should be included in the pagination. + + Don't forget that a significant percentage of the population is +color-blind.\index{color|(}\index{color!blind} +The most common form is a reduced ability to distinguish +between red and green; for example some shades of pink may be perceived +as being a shade of blue, or lemons, oranges and limes may all appear to +be the same color. Along with color-blindness there may be a reduced +capacity to remember colors. + + I have seen Ebooks where color has been liberally used to indicate, say, +different revisions of the text or different sources for the data in a graph. +Unless the colors used are really +distinctive 10\% or more of the potential readership will be lost +or confused. Further, +Ebooks may be printed for reading off-line and if a non-color printer is +used then any colors will appear as shades of grey; these must be such that +they are both readily distinguishable and legible. Yellow on white is almost +as difficult to read as off-white on white or navy blue on black, all of +which I have seen on web sites but rarely after I have tried to print +the page. + +\index{color|)} +\index{electronic books|)} + + + + + + + + + + + + +%%%%%%%%%%%%%%%%%%%%%% +%\endinput +%%%%%%%%%%%%%%%%%%%%%%% + + + + + + + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\part{Practice} \label{part:practice} +%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + + +\chapter{Starting off} \label{chap:starting} + +\pagestyle{headings} +This chapter uses the \pstyle{headings} pagestyle\index{pagestyle}; +pagestyles are described in \S\ref{chap:signposts}. + + As usual, the \Lclass{memoir} class is called by +\cmd{\documentclass}\oarg{options}\texttt{\{memoir\}}. The \meta{options} +include being able to select a paper\index{paper!size} size from among a range of sizes, +selecting a type size, selecting the kind of manuscript, and some related +specifically to the typesetting of mathematics. + +\section{Stock paper size options} + + The stock\index{stock} size is the size of a single sheet of the paper\index{paper} you expect to +put through the printer. + There are a range of stock\index{stock} paper\index{paper!size} sizes from which to make a selection. +These include: +\begin{itemize} + +\item[\Lopt{a3paper}]\index{paper!size!A3} for a stock size of $420 \times 297$ millimeters +\item[\Lopt{a4paper}]\index{paper!size!A4} for a stock size of $297 \times 210$ millimeters +\item[\Lopt{a5paper}]\index{paper!size!A5} for a stock size of $210 \times 148$ millimeters +\item[\Lopt{a6paper}]\index{paper!size!A6} for a stock size of $148 \times 105$ millimeters +\item[\Lopt{b3paper}]\index{paper!size!B3} for a stock size of $500 \times 353$ millimeters +\item[\Lopt{b4paper}]\index{paper!size!B4} for a stock size of $353 \times 250$ millimeters +\item[\Lopt{b5paper}]\index{paper!size!B5} for a stock size of $250 \times 176$ millimeters +\item[\Lopt{b6paper}]\index{paper!size!B6} for a stock size of $176 \times 125$ millimeters +\item[\Lopt{letterpaper}]\index{paper!size!letterpaper} for a stock size of $11 \times 8.5$ inches +\item[\Lopt{legalpaper}]\index{paper!size!legal} for a stock size of $14 \times 8.5$ inches +\item[\Lopt{executivepaper}]\index{paper!size!executive} for a stock size of $10.5 \times 7.25$ inches +\item[\Lopt{ebook}] for a stock size of $6 \times 9$ inches, principally + for `electronic books' intended to be displayed + on a computer monitor +\item[\Lopt{landscape}] to interchange the height and width of the stock. + +\end{itemize} + + These options, except for \Lopt{landscape}, are mutually exclusive. +The default stock\index{stock} paper\index{paper!size} size is \Lopt{letterpaper}\index{paper!size!letterpaper}. + +\section{Type size options} + + The class offers a wider range of type sizes than usual. These are: +\begin{itemize} + +\item[\Lopt{9pt}] for 9pt type +\item[\Lopt{10pt}] for 10pt type +\item[\Lopt{11pt}] for 11pt type +\item[\Lopt{12pt}] for 12t type +\item[\Lopt{14pt}] for 14pt type +\item[\Lopt{17pt}] for 17pt type + +\end{itemize} + + These options are mutually exclusive. +The default type size is \Lopt{10pt}. + +\section{Printing options} + + This group of options includes: + +\begin{itemize} + +\item[\Lopt{twoside}] for when the document will be published with printing + on both sides of the paper\index{paper}. +\item[\Lopt{oneside}] for when the document will be published with only + one side of each sheet being printed on. + + The \Lopt{twoside} and \Lopt{oneside} options + are mutually exclusive. + +\item[\Lopt{onecolumn}] only one column\index{column!single} of text on a page. +\item[\Lopt{twocolumn}] two equal width columns\index{column!double} of text on a page. + + The \Lopt{onecolumn} and \Lopt{twocolumn} options + are mutually exclusive. + +\item[\Lopt{openright}] each chapter\index{chapter} will start on a recto page. +\item[\Lopt{openleft}] each chapter\index{chapter} will start on a verso page. +\item[\Lopt{openany}] a chapter\index{chapter} may start on either a recto or verso page. + + The \Lopt{openright}, \Lopt{openleft} and + \Lopt{openany} options + are mutually exclusive. + +\item[\Lopt{final}] for camera-ready copy of your labours. +\item[\Lopt{draft}] this marks overfull lines with black bars and enables + some change marking to be shown. There may be other + effects as well, particularly if some packages are used. +\item[\Lopt{ms}] this tries to make the document look as though it was + prepared on a typewriter. Some publishers prefer to receive + poor looking submissions. + + The \Lopt{final}, \Lopt{draft} and \Lopt{ms} options + are mutually exclusive. + +\item[\Lopt{showtrims}] this option prints marks at the corners of the + the sheet so that you can see where the stock\index{stock} must be + trimmed to produce the final page size. + +\end{itemize} + + The defaults among the printing options are \Lopt{twoside}, +\Lopt{onecolumn}, +\Lopt{openright}, and \Lopt{final}. + +\section{Other options} + + The remaining options are: +\begin{itemize} + +\item[\Lopt{leqno}] equations will be numbered at the left (the default is + to number them at the right). + +\item[\Lopt{fleqn}] displayed math environments will be indented an amount + \cmd{\mathindent} from the left margin\index{margin} (the default is to + center the environments). + +\item[\Lopt{openbib}] each part of a bibliography\index{bibliography} entry will start on a + new line, with second and succeding lines indented + by \cmd{\bibindent} (the default is for an entry + to run continuously with no indentations). + +\item[\Lopt{article}] typesetting simulates the \Lclass{article} class, + but the \cmd{\chapter} command is not disabled. + Chapters\index{chapter} do not start a new page and chapter headings\index{heading!chapter} are typeset + like a section heading\index{heading!sections}. The numbering of + figures\index{figure}, etc., is continuous + and not per chapter. However, a \cmd{\part} command still puts + its heading\index{heading!part} on a page by itself. + +\item[\Lopt{oldfontcommands}] makes the old, deprecated LaTeX version~2.09 + font commands available. Warning messages will be produced whenever + an old font command is encountered. + +\end{itemize} + + None of these options are defaulted. + +\section{Remarks} + + Calling the class with no options is equivalent to: +\begin{lcode} +\documentclass[letterpaper,10pt,twoside,onecolumn,openright,final]{memoir} +\end{lcode} + The source file for this manual starts +\begin{lcode} +\documentclass[letterpaper,10pt]{memoir} +\end{lcode} +which is overkill as both \Lopt{letterpaper} and \Lopt{10pt} are among +the default options. + + Actual typesetting only occurs within the \Ie{document} environment. The +region of the file between the \cmd{\documentclass} command and the start +of the \Ie{document} environment is called the +\emph{preamble}\index{preamble}. This is where you ask for external packages +and define you own macros if you feel so inclined. + +\begin{syntax} +\cmd{\flushbottom} \cmd{\raggedbottom} \\ +\end{syntax} +When the \Lopt{twoside} or \Lopt{twocolumn} option is selected then +typesetting is done with \cmd{\flushbottom}, otherwise it is done +with \cmd{\raggedbottom}. + + When \cmd{\raggedbottom} is in effect LaTeX makes little attempt to +keep a constant height for the typeblock\index{typeblock}; pages may run short. + + When \cmd{\flushbottom} is in effect LaTeX ensures that the typeblock\index{typeblock} +on each page is a constant height, except when a page break is deliberately +introduced when the page might run short. In order to maintain a constant +height it may stretch or shrink some vertical spaces +(e.g., between paragraphs\index{paragraph}, around headings\index{heading} or around floats\index{float} or other inserts). +This may have a deleterious affect on the color\index{page color} +of some pages. Serendipitously this has happened on \pref{chap:lpage} where +there is additional space between the paragraphs\index{paragraph} (caused by the next sectional +division having to be put at the top of the next page). You may wish to +compare that page with the following one to see the difference in the +colors. + + I could have made the page run short by inserting \cmd{\raggedbottom} +at an appropriate place, followed later by a \cmd{\flushbottom}. + + If you get too many strung out pages with \cmd{\flushbottom} you may +want to put \cmd{\raggedbottom} in the preamble\index{preamble}. + + If you use the \Lopt{ebook} option you may well also want to use the +\Lopt{12pt} and \Lopt{oneside} options. + + + +\chapter{Laying out the page} \label{chap:layingpage} + +\pagestyle{ruled} + + This chapter is typeset with the \pstyle{ruled} pagestyle. + + +\section{Introduction} + + The class provides a default page layout, in which the page size is the +same as the stock\index{stock} size and the typeblock\index{typeblock} is roughly in the middle of +the page. + This chapter describes the commands provided by the class to help you +produce your own page layout if the default is inappropriate. + + The pages of a book carry the text which is intended to educate, entertain +and/or amuse the reader. The page must be designed to serve the purposes of +the author and to ease the reader's task in assimilating the author's ideas. +A good page design is one which the general reader does not notice. If the +reader is constantly noticing the page layout, even unconsciously, it distracts +from the purpose of the book. It is not the job of the designer to +shout, or even to murmur, `look at my work'. + + There are three main parts to a page: the page itself, the typeblock\index{typeblock}, and +the margins\index{margin} separating the typeblock\index{typeblock} from the edges of the page. Of slightly +lesser importance are the headers\index{header} and footers\index{footer}, and possibly marginal\index{marginalia} notes. +The art of page design is obtaining a harmonious balance or rhythm between +all these. + + Although the form is different, the facilities described in this chapter +are similar to those provided by the \Lpack{geometry} +package~\cite{GEOMETRY}. + +\section{Stock material} + + Printing is the act of laying symbols onto a piece of stock\index{stock} material. +Some print on T shirts by a process called silk screening, where the shapes of +the symbols are made in a screen and then fluid is squeezed through the screen +onto the stock material --- in this case the fabric of the T shirt. Whether or +not this is of general interest it is not the sort of printing or stock +material that is usually used in book production. Books, except for the very +particular, are printed on paper\index{paper}. + + In the desktop publishing world the stock\index{stock} +paper\index{paper!size} is usually one from a range of standard sizes. In the USA it is typically +letterpaper\index{paper!size!letterpaper} (11 by 8.5 inches) and in the rest of the world A4\index{paper!size!A4} paper +(297 by 210 mm), with one page per piece of stock\index{stock}. In commercial +printing the stock\index{stock} material is much larger with several pages being +printed on each stock\index{stock} piece; the stock\index{stock} is then folded, cut and trimmed to form +the final pages for binding. For our purposes we only consider desktop +publishing. + + +\section{The page} + + We only consider one page per piece of stock\index{stock}. + + +\begin{figure} +\centering +\drawpage +\caption{LaTeX page layout parameters for a recto page} \label{fig:anoddpage} +\end{figure} + + + The parameters used by LaTeX itself to define the page layout are +illustrated in \fref{fig:anoddpage}. LaTeX does not actually care about the +physical size of a page --- it assumes that, with respect to the top lefthand +corner, the sheet of paper\index{paper} to be printed is infinitely wide and infinitely +long. If you happen to have a typeblock\index{typeblock} that is too wide or too long for +the sheet, LaTeX will merrily position text outside the physical boundaries. + + The LaTeX parameters are often not particularly convenient if, say, the top +of the text must be a certain distance below the top of the page and the +\foredge{} margin\index{margin} must be twice the spine margin\index{margin}. It is obviously possible +to calculate the necessary values for the parameters, but it is +not a pleasurable task. + + The class provides various means of specifying the page layout, which are +hopefully more convenient to use than the standard ones. Various +adjustable parameters are used that define the stock\index{stock} size, page size, and so +on. These differ in some respects from the parameters in the standard classes. +Figure~\ref{fig:oddstock} shows the stock\index{stock} for a recto page, with a page layout, +illustrating the main layout parameters. These may be changed individually +by \cmd{\setlength} or by using the commands described below. + +\begin{figure} +\centering +\drawmarginparsfalse +\drawstock +\caption{The main \textsf{memoir} class page layout parameters for a recto page} \label{fig:oddstock} +\end{figure} + + + In the code for the standard classes it says: +\begin{quotation} +`The variables \cmd{\paperwidth} and \cmd{\paperheight} should reflect +the physical paper\index{paper!size} size after trimming. For desk printer output this is +usually the real paper\index{paper!size} size since there is no post-processing. Classes for +real book production will probably add other paper\index{paper!size} sizes and additionally +the production of crop marks for trimming.' +\end{quotation} + + This class has introduced the additional lengths \cmd{\stockwidth} +and \cmd{\stockheight} to denote the physical paper\index{paper!size} size \emph{before} +trimming. + + + The first step in designing the page layout is to decide on the page size +and then pick an appropriate stock\index{stock} size. Selecting a standard stock\index{stock} size will +be cheaper than having to order specially sized stock\index{stock} material. + +\begin{syntax} +\cmd{\setstocksize}\marg{height}\marg{width} \\ +\lnc{\stockheight} \lnc{\stockwidth} \\ +\end{syntax} + The class options provide for some common stock\index{stock} sizes. If you have some +other size that you want to use the +command \cmd{\setstocksize} can be used to +specify that the stock\index{stock} size is \meta{height} by \meta{width}. For example +the following specifies a stock\index{stock} of 9 by 4 inches: +\begin{lcode} +\setstocksize{9in}{4in} +\end{lcode} + +The size of the page must be +no larger than the stock\index{stock} but may be smaller which means that after printing +the stock\index{stock} must be trimmed down to the size of the page. +The page may +be positioned anywhere within the bounds of the stock\index{stock}. + + Page layout should be conceived in terms of a spread\index{spread}; when +you open a book in the middle what you see is a spread --- a verso page on the +left and a recto page on the right with the spine between them. Most books when +closed are taller than they are wide; this makes them easier to hold when open +for reading. A squarish page when opened out into a wide spread +makes for discomfort unless the book is supported on a table. + +\begin{syntax} +\cmd{\settrimmedsize}\marg{height}\marg{width}\marg{ratio} \\ +\lnc{\paperheight} \lnc{\paperwidth} \\ +\end{syntax} +The command \cmd{\settrimmedsize} +can be used to specify +the height and width of the page (after any trimming). Initially the page +size is made the same as the stock\index{stock} size, as set by the paper\index{paper!size} size option. +The \meta{ratio} argument is +the amount by which the \meta{height} or the \meta{width} must be multiplied +by to give the +width or the height. Only two out of the three possible arguments must be +given values with the other (unvalued) argument given as |*| +(an asterisk). The lengths \lnc{\paperheight} and \lnc{\paperwidth} are +calculated according to the given arguments. That is, the command enables +the \lnc{\paperheight} +and \lnc{\paperwidth} to be specified directly or as one being in a given +ratio to the other. + + If you have used \cmd{\setstocksize} to redefine the stock\index{stock}, then to get +the same page size, do: +\begin{lcode} +\settrimmedsize{\stockheight}{\stockwidth}{*} +\end{lcode} +or for the page to be 90\% of the size of the stock\index{stock}: +\begin{lcode} +\settrimmedsize{0.9\stockheight}{0.9\stockwidth}{*} +\end{lcode} + + The following are three different ways of defining an 8 by 5 inch page. +\begin{lcode} +\settrimmedsize{8in}{5in}{*} +\settrimmedsize{8in}{*}{0.625} % 5 = 0.625 times 8 +\settrimmedsize{*}{5in}{1.6} % 8 = 1.6 times 5 +\end{lcode} + +If you look at a well bound hardback book you +can see that the sheets are folded so that they are continuous at the spine, +where they are sewn together into the binding. The top of the pages should be +smooth so that when the book is upright on a bookshelf dust has a harder +job seeping between the pages than if the top was all raggedy. Thus, if +the stock\index{stock} is trimmed it will be trimmed at the top. It will also have been +cut at the \foredge s of the pages and at the bottom, otherwise the book +would be unopenable and unreadable. + +\begin{syntax} +\cmd{\settrims}\marg{top}\marg{edge} \\ +\lnc{\trimtop} \lnc{\trimedge} \\ +\end{syntax} +The command \cmd{\settrims} can be used to specify +the amount intended to +be trimmed from the top (\meta{top}) and \foredge{} (\meta{edge}) of the stock\index{stock} +material to produce the top and fore edge of a recto page. +Note that the combination of \cmd{\settrims} and \cmd{\settrimmedsize} +locate the page with respect to the stock\index{stock}. +By default the top and edge trims are zero, which means that if any trimming +is required it will be at the spine and bottom edges of the stock\index{stock}. + + You can either do any trim calculation for youself or let LaTeX do it for +you. For example, with an 8in by 5in page on 10in by 7in stock\index{stock} +\begin{lcode} +\settrims{2in}{2in} +\end{lcode} +specifies trimming 2in from the top and \foredge{} of the stock\index{stock}, +giving the desired page size. Taking a design where, say, the page is 90\% of the +stock\index{stock} size it's easy to get LaTeX to do the calculation: +\begin{lcode} +\setlength{\trimtop}{\stockheight} % \trimtop = \stockheight +\addtolengh{\trimtop}{-\paperheight} % \trimtop = \stockheight - \paperheight +\setlength{\trimedge}{\stockwidth} +\addtolength{\trimedge}{-\paperwidth} +\end{lcode} +which will set all the trimming to be at the top and \foredge. If you wanted, say, +equal trims at the top and bottom you could go on as +\begin{lcode} +\settrims{0.5\trimtop}{\trimedge} +\end{lcode} + + +\section{The typeblock} \label{sec:typeblock2} + + Like the page, the typeblock\index{typeblock} is normally rectangular with the height +greater than the width. + + +Table~\ref{tab:cmrlengths} gives the lowercase alphabet lengths for a range +of Computer Modern Roman font sizes; this may be used in conjunction +with \tref{tab:copyfitting} on \pref{tab:copyfitting} when deciding +on an appropriate textwidth. +\begin{syntax} +\lnc{\xlvchars} \lnc{\lxvchars} \\ +\end{syntax} +Based on this table, the two lengths +\lnc{\xlvchars} and +\lnc{\lxvchars} are approximately the lengths of a line of text with +45 or 65 characters, respectively, for the type size selected for the document. + + If you are using a different font you can use something like the +following to calculate and print out the length for you. +\begin{lcode} +\newlength{\mylen} % a length +\newcommand{\alphabet}{abc...xyz} % the lowercase alphabet +\begingroup % keep font change local +% font specification e.g., \Large\sffamily +\settowidth{\mylen}{\alphabet} +The length of this alphabet is \the\mylen. % print in document +\typeout{The length of the Large sans alphabet is \the\mylen} % in log file +\endgroup % end the grouping +\end{lcode} +The \cmd{\typeout} macro will print the result to the terminal and the +log file. + +\begin{table} +\centering +\caption{Length of CMR lowercase alphabets}\label{tab:cmrlengths} +\begin{tabular}{rr}\hline +\multicolumn{1}{c}{Font} & \multicolumn{1}{c}{Length} \\ +\multicolumn{1}{c}{size} & \multicolumn{1}{c}{(points)} \\ \hline +5 pt & 87 \\ +6 pt & 94 \\ +7 pt & 102 \\ +8 pt & 108 \\ +9 pt & 118 \\ +10 pt & 128 \\ +11 pt & 139 \\ +12 pt & 150 \\ +14 pt & 175 \\ +17 pt & 207 \\ +20 pt & 245 \\ +25 pt & 290 \\ +\hline +\end{tabular} +\end{table} + + + Morten H{\o}gholm has done some curve fitting to the data in + \tref{tab:copyfitting}. +He found that the expressions +\begin{displaymath} +L_{65} = 2.042\alpha + 33.41 \mbox{pt} +\end{displaymath} +and +\begin{displaymath} +L_{45} = 1.415\alpha + 23.03 \mbox{pt} +\end{displaymath} +fitted aspects of the data, where $\alpha$ is the length of the +alphabet and $L_{i}$ is the desired linewidth when the line should +contain $i$ characters. He suggested the following macros. +\begin{syntax} +\cmd{\setlxvchars}\oarg{fontspec} \\ +\cmd{\setxlvchars}\oarg{fontspec} \\ +\end{syntax} +The macros \cmd{\setlxvchars} and \cmd{\setxlvchars} set the lengths +\lnc{\lxvchars} and \lnc{\xlvchars} respectively for the font \meta{fontspec}. +The default for \meta{fontspec} is \cmd{\normalfont}. + + For example, the values of \lnc{\lxvchars} and \lnc{\xlvchars} after +calling \setlxvchars \setxlvchars[\small\sffamily] +\begin{lcode} +\setlxvchars \setxlvchars[\small\sffamily] +\end{lcode} +are: \verb?\lxvchars? = \the\lxvchars, and \verb?\xlvchars? = \the\xlvchars. + + Continuing on this theme, Morten also wrote: +\begin{quotation} +\ldots I was defining some environments that had to have \lnc{\parindent} +as their indentation. For some reason I just wrote \texttt{1.5em} instead +of \lnc{\parindent} because I knew that was the value. What I had +overlooked was that I had loaded the \Lpack{mathpazo} +package~\cite{MATHPAZO}, thus +altering various \cmd{\fontdimen}s. Conclusion: the environment would +insert \mbox{1.5 em = 18.0 pt}, whereas the \lnc{\parindent} was only +\mbox{17.6207 pt}. + + This, and other related situations can be avoided if one places +\begin{center} +\cmd{\RequirePackage}\marg{font-package}\cmd{\normalfont} +\end{center} +before \cmd{\documentclass}, but I have to this day never seen this suggested. +I would believe that most document classes have settings that depend on +\emph{current} font settings, which they should do for such things as +\lnc{\parindent}. However the decision to let Computer Modern be the +default font in LaTeX causes these dimensions to be set to erroneous +values\ldots +\end{quotation} + + + + + + The height of the typeblock\index{typeblock} should be equivalent to an integral number +of lines. + +\begin{syntax} +\cmd{\settypeblocksize}\marg{height}\marg{width}\marg{ratio} \\ +\lnc{\textheight} \lnc{\textwidth} \\ +\end{syntax} +The command +\cmd{\settypeblocksize} is the same as +\cmd{\settrimmedsize} except that it sets the \lnc{\textheight} and +\lnc{\textwidth} for the typeblock\index{typeblock}. For instance, here are three ways of specifying +a 6in by 3in typeblock\index{typeblock}: +\begin{lcode} +\settypeblocksize{6in}{3in}{*} +\settypeblocksize{6in}{*}{0.5} +\settypeblocksize{*}{3in}{2} +\end{lcode} + + The typeblock\index{typeblock} has to be located on the page. There is a relationship +between the page, typeblock\index{typeblock} and margins\index{margin}. The sum of the spine margin\index{margin}, +the \foredge{} margin\index{margin} +and the width of the typeblock\index{typeblock} must equal the width +of the page. Similarly the sum of the upper margin\index{margin}, the lower margin\index{margin} and the +height of the typeblock\index{typeblock} must equal the height of the page. The process +of locating the typeblock\index{typeblock} with respect to the page can be viewed +either as positioning the typeblock\index{typeblock} with respect to the edges of the page +or as setting the margins\index{margin} between the page and the typeblock\index{typeblock}. + + Remembering that the page layout should be defined in terms of the +appearance as a spread, the spine margin\index{margin} is normally half the \foredge{} +margin\index{margin}, so that the white space is equally distributed around the +sides of the text. + + There is usually more latitude in choosing the proportions\index{proportion} of the upper and +lower margins\index{margin}, though usually the upper margin\index{margin} is less than the lower margin\index{margin} +so the typeblock\index{typeblock} is not vertically centered. + + Two methods are provided for setting the horizontal dimensions on a page. +One where the width of the typeblock\index{typeblock} is fixed and the margins\index{margin} +are adjustable, and the other where the size of the margins\index{margin} determines the +width of the typeblock\index{typeblock}. + +\begin{syntax} +\cmd{\setlrmargins}\marg{spine}\marg{edge}\marg{ratio} \\ +\lnc{\spinemargin} \lnc{\foremargin} \\ +\end{syntax} +The command \cmd{\setlrmargins} +can be used to specify +the side margins\footnote{Only the spine margin is noted in +\fref{fig:oddstock}; the \foredge{} margin\index{margin} is at the opposite side of the +typeblock.} with the width of the page and the typeblock being fixed. + +Either zero or one argument values are required, with any +unvalued argument being denoted by an asterisk. There are several cases to +consider and these are tabulated in \tref{tab:lrmargins}. + + In the Table, $S$ is the calculated spine margin\index{margin}, $E$ is the calculated +\foredge{} margin\index{margin}, and $P_{w}$ and $B_{w}$ are respectively the page and typeblock\index{typeblock} +widths. +The \cmd{\setlrmargins} command maintains the relationship +\begin{displaymath} +S + E = K_{w} = \textrm{constant} \mbox{\space} (= P_{w} - B_{w}). +\end{displaymath} + + +\begin{table} +\DeleteShortVerb{\|} +\centering +\caption{Arguments and results for \cs{setlrmargins} } \label{tab:lrmargins} +\begin{tabular}{ccc|l} \hline +\meta{spine} & \meta{edge} & \meta{ratio} & Result \\ \hline + S & E & r & ambiguous \\ + S & E & * & ambiguous \\ + S & * & r & ambiguous \\ + S & * & * & $E = K_{w} - S$ \\ +{*} & E & r & ambiguous \\ +{*} & E & * & $S = K_{w} - E$ \\ +{*} & * & r & $E + S = K_{w}$, $E = rS$ \\ +{*} & * & * & $E + S = K_{w}$, $E = S$ \\ +\hline +\end{tabular} +\MakeShortVerb{\|} +\end{table} + +The cases marked ambiguous in the Table are where the particular combination +of argument values may make it impossible to guarantee the relationship. + + Assuming that we have a 3in wide typeblock\index{typeblock} on a 5in wide page and we want +the spine margin\index{margin} to be 0.8in and the \foredge{} margin\index{margin} to be 1.2in (i.e., the +\foredge{} margin\index{margin} is half as big again as the spine margin\index{margin}) this can be +accomplished in three ways (with the \cmd{\pagewidth} and \lnc{\textwidth} being +previously specified and fixed): +\begin{lcode} +\setlrmargins{0.8in}{*}{*} % specify spine margin +\setlrmargins{*}{1.2in}{*} % specify foredge margin +\setlrmargins{*}{*}{1.5} % specify foredge/spine ratio +\end{lcode} + +\begin{syntax} +\cmd{\setlrmarginsandblock}\marg{spine}\marg{edge}\marg{ratio}\\ +\end{syntax} +The command \cmd{\setlrmarginsandblock} +can be used to specify the spine and \foredge{} margins\index{margin}, where the page width +is fixed and the width of the typeblock\index{typeblock} depends on the margins\index{margin}. Results +for this command are given in \tref{tab:lrblock}. The same notation is used, +but in this case \cmd{\setlrmarginsandblock} maintains the +relationship +\begin{displaymath} +S + B_{w} + E = \textrm{constant} \mbox{\space} (= P_{w}). +\end{displaymath} +The width of the typeblock\index{typeblock} is calculated from $B_{w} = P_{w} - S - E$. + +\begin{table} +\DeleteShortVerb{\|} +\centering +\caption{Arguments and results for \cs{setlrmarginsandblock} } \label{tab:lrblock} +\begin{tabular}{ccc|l} \hline +\meta{spine} & \meta{edge} & \meta{ratio} & Result \\ \hline + S & E & r & $S$, $E$ \\ + S & E & * & $S$, $E$ \\ + S & * & r & $E = rS$ \\ + S & * & * & $E = S$ \\ +{*} & E & r & $S = rE$ \\ +{*} & E & * & $S = E$ \\ +{*} & * & r & ambiguous \\ +{*} & * & * & ambiguous \\ +\hline +\end{tabular} +\MakeShortVerb{\|} +\end{table} + + Assuming that we want a 3in wide typeblock\index{typeblock} on a 5in wide page and we want +the spine margin\index{margin} to be 0.8in and the \foredge{} margin\index{margin} to be 1.2in (i.e., the +\foredge{} margin\index{margin} is half as big again as the spine margin\index{margin}) this can be +accomplished in the following ways (with the \lnc{\textwidth} being calculated +from the previously specified \cmd{\pagewidth} and the specified margins\index{margin}): +\begin{lcode} +\setlrmarginsandblock{0.8in}{1.2in}{*} % specify both margins +\setlrmarginsandblock{0.8in}{*}{1.5} % specify spine & foredge/spine ratio +\setlrmarginsandblock{*}{1.2in}{0.667} % specify foredge & spine/foredge ratio +\end{lcode} +If we wanted the margins to be both 1in instead then any of the following +will do it: +\begin{lcode} +\setlrmarginsandblock{1in}{1in}{*} % specify both margins +\setlrmarginsandblock{1in}{*}{1} % specify spine & foredge/spine ratio +\setlrmarginsandblock{1in}{*}{*} % specify spine (foredge = spine) +\setlrmarginsandblock{*}{1in}{1} % specify foredge & spine/foredge ratio +\setlrmarginsandblock{*}{1in}{*} % specify foredge (spine = foredge) +\end{lcode} + + That completes the methods for specifying the horizontal spacings. There +are similar commmands for setting the vertical spacings which are +described below. + +\begin{syntax} +\cmd{\setulmargins}\marg{upper}\marg{lower}\marg{ratio} \\ +\lnc{\uppermargin} \lnc{\lowermargin} \\ +\end{syntax} +The command \cmd{\setulmargins} can be used to specify +the upper and lower margins\footnote{Only the upper margin is noted in +\fref{fig:oddstock}; the lower margin\index{margin} is the distance between the bottom +of the typeblock\index{typeblock} and the bottom of the page.} where the heights of the page +and the typeblock\index{typeblock} are fixed. This is similar to \cmd{\setlrmargins}. Using +a slightly different notation this time, with $U$ being the upper margin\index{margin}, +$L$ being the lower margin\index{margin}, and $P_{h}$ and $B_{h}$ being the +\emph{height} of the page +and typeblock\index{typeblock}, respectively, the results are shown in \tref{tab:ulmargins}. +The \cmd{\setlrmargins} command maintains the relationship +\begin{displaymath} +U + L = K_{h} = \textrm{constant} \mbox{\space} (= P_{h} - B_{h}). +\end{displaymath} + + +\begin{table} +\DeleteShortVerb{\|} +\centering +\caption{Arguments and results for \cs{setulmargins} } \label{tab:ulmargins} +\begin{tabular}{ccc|l} \hline +\meta{upper} & \meta{lower} & \meta{ratio} & Result \\ \hline + U & L & r & ambiguous \\ + U & L & * & ambiguous \\ + U & * & r & ambiguous \\ + U & * & * & $L = K_{h} - U$ \\ +{*} & L & r & ambiguous \\ +{*} & L & * & $U = K_{h} - L$ \\ +{*} & * & r & $L + U = K_{h}$, $L = rU$ \\ +{*} & * & * & $L + U = K_{h}$, $L = U$ \\ +\hline +\end{tabular} +\MakeShortVerb{\|} +\end{table} + +\begin{syntax} +\cmd{\setulmarginsandblock}\marg{upper}\marg{lower}\marg{ratio} \\ +\end{syntax} +The command \cmd{\setulmarginsandblock} +can be used to specify the upper and lower margins\index{margin}, where the page height +is fixed and the height of the typeblock\index{typeblock} depends on the margins\index{margin}. Results +for this command are given in \tref{tab:ulblock}. The same notation is used, +but in this case \cmd{\setulmarginsandblock} maintains the +relationship +\begin{displaymath} +U + B_{h} + L = \textrm{constant} \mbox{\space} (P_{h}). +\end{displaymath} +The height of the typeblock\index{typeblock} is calculated from $B_{h} = P_{h} - U - L$. + +\begin{table} +\DeleteShortVerb{\|} +\centering +\caption{Arguments and results for \cs{setulmarginsandblock} } \label{tab:ulblock} +\begin{tabular}{ccc|l} \hline +\meta{upper} & \meta{lower} & \meta{ratio} & Result \\ \hline + U & L & r & $U$, $L$ \\ + U & L & * & $U$, $L$ \\ + U & * & r & $L = rU$ \\ + U & * & * & $L = U$ \\ +{*} & L & r & $U = rL$ \\ +{*} & L & * & $U = L$ \\ +{*} & * & r & ambiguous \\ +{*} & * & * & ambiguous \\ +\hline +\end{tabular} +\MakeShortVerb{\|} +\end{table} + +\begin{syntax} +\cmd{\setcolsepandrule}\marg{colsep}\marg{thickness} \\ +\lnc{\columnsep} \lnc{\columseprule} \\ +\end{syntax} + For twocolumn\index{column!double} text the width of the gutter between the columns must be +specified. LaTeX also lets you draw a vertical rule in the middle of the +gutter. The macro \cmd{\setcolsepandrule} +sets the gutter width, \lnc{\columnsep}, to \meta{colsep} +and \lnc{\columnseprule}, the thickness of the rule, +to \meta{thickness}. A \meta{thickness} of 0pt means that the rule will be +invisible. Visible rules usually have a thickness of about 0.4pt. +The total width of the twocolumns\index{column!double} of text and the gutter equals the width of +the typeblock\index{typeblock}. + + This completes the main elements of the page --- the page size, the size +of the typeblock\index{typeblock} and the margins\index{margin} surrounding the typeblock\index{typeblock}. + +\section{Headers, footers and marginal notes} +\index{header|(}\index{footer|(} + + A page may have two additional items, and usually has at least one of +these. They are the running header and running footer. If the page has a folio\index{folio} then it is located either in the +header or in the footer. The word `in' is used rather lightly here as the folio\index{folio} +may not be actually \emph{in} the header or footer but is always located +at some constant relative position. A common position for the folio\index{folio} is towards +the \foredge{} of the page, either in the header of the footer. This makes it +easy to spot when thumbing through the book. It may be placed at the center of +the footer, but unless you want to really annoy the reader do not place it near +the spine. + + Often a page header contains the current chapter title, with perhaps a +section title on the opposite header, as aids to the reader in navigating +around the book. Some books +put the book title into one of the headers, usually the verso one, but I see +little point in that as presumably the reader knows which particular book he +is reading, and the space would be better used providing more useful signposts. + +\begin{syntax} +\cmd{\setheadfoot}\marg{headheight}\marg{footskip} \\ +\lnc{\headheight} \lnc{\footskip} \\ +\end{syntax} +The command \cmd{\setheadfoot} sets the +\lnc{\headheight} parameter to the value \meta{headheight} and the +\lnc{\footskip} parameter to \meta{footskip}. + +\begin{syntax} +\cmd{\setheaderspaces}\marg{headdrop}\marg{headsep}\marg{ratio} \\ +\lnc{\headdrop} \lnc{\headsep} \\ +\end{syntax} +The command \cmd{\setheaderspaces} is similar to \cmd{\setulmargins}. +Using the notation $U$ for the upper margin\index{margin} (as before), $H_{h}$ for the +\lnc{\headheight}, $H_{s}$ for the \lnc{\headsep} and $D$ for the +\lnc{\headdrop}, where the \lnc{\headdrop} is the distance between the top +of the trimmed page and the top of the header\footnote{The head drop is not +shown in \fref{fig:oddstock}.}, then the macro \cmd{\setheaderspaces} +maintains the relationship +\begin{displaymath} +D + H_{s} = C_{h} = \textrm{constant} \mbox{\space} (= U - H_{h}). +\end{displaymath} + +\begin{table} +\DeleteShortVerb{\|} +\centering +\caption{Arguments and results for \cs{setheaderspaces} } \label{tab:headspaces} +\begin{tabular}{ccc|l} \hline +\meta{headdrop} & \meta{headsep} & \meta{ratio} & Result \\ \hline + D & $H_{s}$ & r & ambiguous \\ + D & $H_{s}$ & * & ambiguous \\ + D & * & r & ambiguous \\ + D & * & * & $H_{s} = C_{h} - D$ \\ +{*} & $H_{s}$ & r & ambiguous \\ +{*} & $H_{s}$ & * & $D = C_{h} - H_{s}$ \\ +{*} & * & r & $H_{s} + D = C_{h}$, $H_{s} = rD$ \\ +{*} & * & * & $H_{s} + D = C_{h}$, $H_{s} = D$ \\ +\hline +\end{tabular} +\MakeShortVerb{\|} +\end{table} + +The macro \cmd{\setheaderspaces} is for specifying the spacing above and below +the page header. +The possible arguments and results are shown in \tref{tab:headspaces}. Typically, +the \lnc{\headsep} is of more interest than the \lnc{\headdrop}. + +\index{footer|)}\index{header|)} + +\index{marginalia|(} + Finally, some works have marginal notes. These really come last in the +design scheme, providing the margins have been made big enough to accomodate +them. Figure~\ref{fig:evenstock} shows the marginal note parameters on a verso +page, and also illustrates that some parameters control different +positions on the stock\index{stock}. + + +\begin{figure} +\centering +\oddpagelayoutfalse +\drawstock +\caption{The \textsf{memoir} class page layout parameters for a verso page} \label{fig:evenstock} +\end{figure} + + + +\begin{syntax} +\cmd{\setmarginnotes}\marg{separation}\marg{width}\marg{push} \\ +\lnc{\marginparsep} \lnc{\marginparwidth} \lnc{\marginparpush} \\ +\end{syntax} +The command \cmd{\setmarginnotes} +sets the parameters for marginal notes. The distance \lnc{\marginparsep} +between the typeblock\index{typeblock} and any note is set to \meta{separation}, the +maximum width for a note, \lnc{\marginparwidth}, is set to \meta{width} +and the minimum vertical distance between notes, \lnc{\marginparpush}, +is set to \meta{push}. + +\index{marginalia|)} + +\section{Putting it together} + + The page layout parameters just discussed are not always the same +as those that are expected by LaTeX, or by LaTeX packages. The parameters +that LaTeX expects are shown in \fref{fig:anoddpage}. You can either use +the class commands for changing the page layout or change the LaTeX parameters +directly using either \cmd{\setlength} or \cmd{\addtolength} applied to the +parameter(s) to be modified. If you choose the latter route, those class +parameters which differ from the standard LaTeX parameters will \emph{not} be +modified. + + The general process of setting up your own page layout is along these +lines: +\begin{itemize} +\item Decide on the required finished page size, and pick a stock\index{stock} size that + is at least as large as the page. +\item Use \cmd{\setstocksize} to set the values of \lnc{\stockheight} + and \lnc{\stockwidth}, followed by \cmd{\settrimmedsize} to specify + the values of \lnc{\paperheight} and \lnc{\paperwidth}. +\item Decide on the location of the page with respect to the stock\index{stock}. If the + page and stock\index{stock} sizes are the same, then call |\settrims{0pt}{0pt}|. + If they are not the same size then decide on the appropriate + values for \lnc{\trimtop} and \lnc{\trimedge} to position the page on + the stock\index{stock}, and then set these through \cmd{\settrims}. +\item Decide on the size of the typeblock\index{typeblock} and use \cmd{\settypeblocksize} + to specify the values of \lnc{\textheight} and \lnc{\textwidth}. +\item Pick the value for the spine margin\index{margin}, and use \cmd{\setlrmargins} + to set the values for the \lnc{\spinemargin} and \lnc{\foremargin}. + + An alternative sequence is to use \cmd{\setlrmarginsandblock} to + set the \lnc{\textwidth} for a particular choice of side margins\index{margin}. + +\item Pick the value for the upper margin\index{margin} and use \cmd{\setulmargins} + to set the values for the \lnc{\uppermargin} and \cmd{\lowermargin}. + + An alternative sequence is to use \cmd{\setulmarginsandblock} to + set the \lnc{\textheight} for a particular choice of upper and + lower margins\index{margin}. + +\item Pick the values for the \lnc{\headheight} and \lnc{\footskip} + and use \cmd{\setheadfoot} to specify these. + +\item Pick your value for \cmd{\headskip} and use \cmd{\setheaderspaces} + to set this and \lnc{\headdrop}. + +\item If you are going to have any marginal\index{marginalia} notes, use \cmd{\setmarginnotes} + to specify the values for \lnc{\marginparsep}, \lnc{\marginparwidth} + and \lnc{\marginparpush}. + +\end{itemize} + + You can plan and specify your layout in any order that is +convenient to you. Each of the page layout commands are independent; also if +a value is set at one point, say the \lnc{\textwidth}, and is then +later changed in some way, only the last of the settings is used as the actual +value. + + + Comparing \figurerefname s~\ref{fig:oddstock} and~\ref{fig:anoddpage} you can see +the different layout parameters provided by the class and used by standard +LaTeX. For convenience, and because the figures do not show all +the parameters, the two sets of parameters are listed in \tref{tab:stockpage}. + +\begin{table} +\centering +\caption{The class and LaTeX page layout parameters}\label{tab:stockpage} +\begin{tabular}{ll} \hline +Class & LaTeX \\ \hline +\lnc{\stockheight} & \\ +\lnc{\trimtop} & \\ +\lnc{\trimedge} & \\ +\lnc{\stockwidth} & \\ +\lnc{\paperheight} & \lnc{\paperheight} \\ +\lnc{\paperwidth} & \lnc{\paperwidth} \\ +\lnc{\textheight} & \lnc{\textheight} \\ +\lnc{\textwidth} & \lnc{\textwidth} \\ +\lnc{\columnsep} & \lnc{\columnsep} \\ +\lnc{\columnseprule} & \lnc{\columnseprule} \\ +\lnc{\spinemargin} & \\ +\lnc{\foremargin} & \\ + & \lnc{\oddsidemargin} \\ + & \lnc{\evensidemargin} \\ +\lnc{\uppermargin} & \\ +\lnc{\headdrop} & \\ + & \lnc{\topmargin} \\ +\lnc{\headheight} & \lnc{\headheight} \\ +\lnc{\headsep} & \lnc{\headsep} \\ +\lnc{\footskip} & \lnc{\footskip} \\ +\lnc{\lowermargin} & \\ +\lnc{\marginparsep} & \lnc{\marginparsep} \\ +\lnc{\marginparwidth} & \lnc{\marginparwidth} \\ +\lnc{\marginparpush} & \lnc{\marginparpush} \\ +\hline +\end{tabular} +\end{table} + +\begin{syntax} +\cmd{\checkandfixthelayout} \\ +\end{syntax} + The macro \cmd{\checkandfixthelayout} takes all the class layout parameters, +checks +that they have `sensible' values (e.g., the \lnc{\textwidth} is not negative), +and then calculates the values for all those LaTeX layout parameters that +differ from the class parameters. If you have used the class macros to change +the layout in any way, you must call \cmd{\checkandfixthelayout} after you have +made all the necessary changes. As an aid, the final layout parameter values +are displayed on the terminal and written out to the log file. + +\begin{syntax} +\cmd{\typeoutlayout} \\ +\cmd{\typeoutstandardlayout} \\ +\end{syntax} +The command \cmd{\typeoutlayout} may be used at any point in the document +to display the current class layout parameter values on the terminal and +to write +them to the log file. The \cmd{\typeoutstandardlayout} does the same thing, +except that it outputs the values of the standard parameters. + + When pdfLaTeX is used to generate a PDF version of a \Lclass{memoir} +document some special setup must be done. + +\begin{syntax} +\cmd{\fixpdflayout} \\ +\end{syntax} +The macro \cmd{\fixpdflayout} is automatically called after +the preamble when pdfLaTeX is used to generate PDF. +The default definition is effectively: +\begin{lcode} +\newcommand{\fixpdflayout}{\ifpdf\ifnum\pdfoutput>0\relax + \pdfpageheight=\the\stockheight + \pdfpagewidth=\the\stockwidth + \ifdim\pdfvorigin=0pt\pdfvorigin=1in\fi + \ifdim\pdfhorigin=0pt\pdfhorigin=1in\fi + \fi\fi} +\end{lcode} +The first settings (\verb?\pdfpage...?) ensure that pdfLaTeX knows the +size of the physical sheet for printing. The \verb?\...origin? settings +set the pdf origin per the TeX origin, provided that their values are 0pt. +If you have set the origin values yourself, either in a pdfLaTeX +configuration file or earlier in the preamble, the \cmd{\fixpdflayout} macro +will not alter them (if you need an origin value to be 0, then set it to +0sp, which is visually indistinguishable from 0pt). + +\begin{syntax} +\cmd{\fixdvipslayout} \\ +\end{syntax} +The macro \cmd{\fixdvipslayout} is automatically called after the preamble +when PDF output is not being produced. It provides the dvips processor +with information about the stock size which a viewer or printer may use. + + With a landscape document and using the processing route +\texttt{latex -> dvips} the resulting \file{.ps} PostScript file may appear +upside-down when viewed with, say, \texttt{ghostview}. If this happens +try putting the following in your preamble: +\begin{lcode} +\addtodef{\fixdvipslayout}{}{% + \special{!TeXDict begin /landplus90{true}store end }} +\end{lcode} +If required, additional code can be added to \cmd{\fixdvipslayout} +by repeated applications of \cmd{\addtodef}. +Some other potential specials for PostScript printing may be (at least +for an HP 5SiMx LaserJet duplex printer): +\begin{lcode} +\special{!TeXDict begin <</Duplex true>> setpagedevice end} % duplex +\special{!TeXDict begin <</Tumble true>> setpagedevice end} % short side binding\end{lcode} + +\subsection{Example} \label{sec:pexamp} + + Suppose you want a page that will fit on both A4\index{paper!size!A4} and US letterpaper\index{paper!size!letterpaper} stock\index{stock}, +wanting to do the least amount of trimming. The width of the typeblock\index{typeblock} should +be such that there are the optimum number of characters per line, and the +ratio of the height to the width of the typeblock\index{typeblock} should equal the golden +section. The text has to start 50pt below the top of the page. +We will use the default \lnc{\headheight} and \lnc{\footskip}. +The ratio of the \foredge{} margin\index{margin} to the spine margin\index{margin} should equal the +golden section\index{golden section}, +as should the space above and below the header\index{header}. There is +no interest at all in marginal\index{marginalia} notes, so we can ignore any settings for these. + + We can either do the maths ourselves or get LaTeX to do it for us. Let's +use LaTeX. First we will work out the size of the largest sheet that can be +cut from A4\index{paper!size!A4} and letterpaper\index{paper!size!letterpaper}, whose sizes are $297 \times 210$mm and +$11 \times 8.5$in; A4 is taller and narrower than letterpaper. +\begin{lcode} +\settrimmedsize{11in}{210mm}{*} +\end{lcode} +The stocksize is defined by the class option, but we have to work out the +trims to reduce the stock\index{stock} to the page. To make life easier, we will only trim +the \foredge{} and the bottom of the stock\index{stock}, so the \lnc{\trimtop} is zero. +The \lnc{\trimtop} and \lnc{\trimedge} are easily specified by +\begin{lcode} +\setlength{\trimtop}{0pt} +\setlength{\trimedge}{\stockwidth} +\addtolength{\trimedge}{-\paperwidth} +\end{lcode} +Specification of the size of the typeblock\index{typeblock} is also easy +\begin{lcode} +\settypeblocksize{*}{\lxvchars}{1.618} +\end{lcode} +and now the upper and lower margins\index{margin} are specified by +\begin{lcode} +\setulmargins{50pt}{*}{*} +\end{lcode} +The spine and \foredge{} margins\index{margin} are specified just by the value of the golden section\index{golden section}, via +\begin{lcode} +\setlrmargins{*}{*}{1.618} +\end{lcode} +The only remaining calculation to be done is the \lnc{\headdrop} and +\lnc{\headsep}. Again this just involves using a ratio +\begin{lcode} +\setheaderspaces{*}{*}{1.618} +\end{lcode} +To finish off we have to make sure that the layout is changed +\begin{lcode} +\checkandfixthelayout +\end{lcode} + +\subsection{The page layout of this manual} + +\begin{figure} +\currentstock +\oddpagelayouttrue +\twocolumnlayoutfalse +\drawmarginparstrue +\drawparametersfalse +\drawstock +\caption{The recto page layout for this manual}\label{fig:thispagelay} +\end{figure} + + + + The page layout for this manual is defined in the preamble\index{preamble} as: +\begin{lcode} +\settrimmedsize{11in}{210mm}{*} +\setlength{\trimtop}{0pt} +\setlength{\trimedge}{\stockwidth} +\addtolength{\trimedge}{-\paperwidth} +\settypeblocksize{7.75in}{33pc}{*} +\setulmargins{4cm}{*}{*} +\setlrmargins{1.25in}{*}{*} +\setmarginnotes{17pt}{51pt}{\onelineskip} +\setheadfoot{\onelineskip}{2\onelineskip} +\setheaderspaces{*}{2\onelineskip}{*} +\checkandfixthelayout +\end{lcode} + +An illustration of the layout is shown in \fref{fig:thispagelay} which also +lists the parameter values resulting from the code above, to the nearest point. + +I initially used the layout defined in \S\ref{sec:pexamp}, which I thought +looked reasonable, but then I decided to use the one above in order +to save paper\index{paper} when anyone printed out the manual. The wider +typeblock\index{typeblock} also makes it easier for TeX when dealing with lines that include +unhyphenatable text, like the LaTeX code. + + + Andreas Mathias, via Rolf Niepraschk,\footnote{Email +from \url{niepraschk@ptb.de} on 2002/02/05.} +has suggested that the following might be better for typesetting the manual +on A4 paper. +\begin{lcode} +\documentclass[a4paper]{memoir} +... +\settrimmedsize{297mm}{210mm}{*} +\setlength{\trimtop}{0pt} +\setlength{\trimedge}{\stockwidth} +\addtolength{\trimedge}{-\paperwidth} +\settypeblocksize{634pt}{448.13pt}{*} +\setulmargins{4cm}{*}{*} +\setlrmargins{*}{*}{1.5} +\setmarginnotes{17pt}{51pt}{\onelineskip} +\setheadfoot{\onelineskip}{2\onelineskip} +\setheaderspaces{*}{2\onelineskip}{*} +\checkandfixthelayout +\end{lcode} + +\chapter{Titles and abstracts} + +\section{Introduction} + + The typeset format of the \cmd{\maketitle} command is virtually fixed +within the LaTeX standard classes. This class +provides a set of formatting commands that can be used to modify +the appearance of the title\index{title} information; that is, the contents of +the \cmd{\title}, \cmd{\author} and \cmd{\date} commands. +It also keeps the values +of these commands so that they may be printed again later in the +document. + The class also inhibits the normal automatic cancellation of titling +commands after \cmd{\maketitle}. This means that you can have multiple +instances of the same, or perhaps different, titles in one document; +for example on a half title page\index{half title page} and the +full title page\index{title page}. +Hooks are provided so that additional titling elements can be defined +and printed by \cmd{\maketitle}. + The \cmd{\thanks} command is enhanced to provide various configurations +for both the marker symbol and the layout of the thanks\index{thanks} notes. + +Questions about how to have a one-column\index{column!single} abstract\index{abstract} in a +two-column\index{column!double} paper +seem to pop up fairly regularly on the +\texttt{comp.text.tex} newsgroup. While an answer based on responses +on \texttt{ctt} is provided in the FAQ, +the class provides a more author-friendly means +of accomplishing this. Further, additional controls are provided +for the typesetting of the \Ie{abstract} environment in general. + +\section{Titles} + +\subsection{Styling the titling} + + +\index{title!styling|(} + + This part of the class is a reimplementation of the \Lpack{titling} +package~\cite{TITLING}. + +The class provides a configurable \cmd{\maketitle} command. +The \cmd{\maketitle} command as defined by the class +is essentially +\begin{lcode} +\newcommand{\maketitle}{% + \vspace*{\droptitle} + \maketitlehooka + {\pretitle \title \posttitle} + \maketitlehookb + {\preauthor \author \postauthor} + \maketitlehookc + {\predate \date \postdate} + \maketitlehookd + \thispagestyle{title} +} +\end{lcode} +where the \pstyle{title} pagestyle is initially the same as the +\pstyle{plain} pagestyle. +The various macros used within \cmd{\maketitle} are described below. + + +\begin{syntax} +\cmd{\pretitle}\marg{text} \cmd{\posttitle}\marg{text} \\ +\cmd{\preauthor}\marg{text} \cmd{\postauthor}\marg{text} \\ +\cmd{\predate}\marg{text} \cmd{\postdate}\marg{text} \\ +\end{syntax} +These six commands each have a single argument, \meta{text}, +which controls the typesetting of the +standard elements of the document's \cmd{\maketitle} +command. The \cmd{\title} is effectively processed between the +\cmd{\pretitle} and \cmd{\posttitle} commands; that is, like: +\begin{lcode} +{\pretitle \title \posttitle} +\end{lcode} +and similarly for the \cmd{\author} and \cmd{\date} commands. The +commands are initialised to mimic the normal result of \cmd{\maketitle} +typesetting in the \Lclass{report} class. +That is, the default definitions of the commands are: +\begin{lcode} +\pretitle{\begin{center}\LARGE} +\posttitle{\par\end{center}\vskip 0.5em} +\preauthor{\begin{center} + \large \lineskip 0.5em% + \begin{tabular}[t]{c}} +\postauthor{\end{tabular}\par\end{center}} +\predate{\begin{center}\large} +\postdate{\par\end{center}} +\end{lcode} + +They can be changed to obtain different effects. For example to get +a right justified sans-serif title and a left justifed small caps +date: +\begin{lcode} +\pretitle{\begin{flushright}\LARGE\sffamily} +\posttitle{\par\end{flushright}\vskip 0.5em} +\predate{\begin{flushleft}\large\scshape} +\postdate{\par\end{flushleft}} +\end{lcode} + +\begin{syntax} +\lnc{\droptitle} \\ +\end{syntax} + The \cmd{\maketitle} command puts the title at a particular height on the +page. + You can change the vertical position of the title via the length +\lnc{\droptitle}. Giving this a positive value will lower the title and a +negative value will raise it. The default definition is: +\begin{lcode} +\setlength{\droptitle}{0pt} +\end{lcode} + +\begin{syntax} +\cmd{\maketitlehooka} \cmd{\maketitlehookb} \\ +\cmd{\maketitlehookc} \cmd{\maketitlehookd} \\ +\end{syntax} + These four hook commands are provided so that additional elements may +be added to \cmd{\maketitle}. These are initially defined to do nothing +but can be renewed. For example, some publications +want a statement about where an article is published immediately +before the actual titling text. The following defines a command +\cmd{\published} that can be used to hold the publishing information +which will then be automatically printed by \cmd{\maketitle}. +\begin{lcode} +\newcommand{\published}[1]{% + \gdef\puB{#1}} +\newcommand{\puB}{} +\renewcommand{\maketitlehooka}{% + \par\noindent \puB} +\end{lcode} +You can then say: +\begin{lcode} +\published{Originally published in + \textit{The Journal of ...}\thanks{Reprinted with permission}} +... +\maketitle +\end{lcode} +to print both the published and the normal titling information. Note +that nothing extra had to be done in order to use the \cmd{\thanks} command +in the argument to the new \cmd{\published} command. + +\index{title page|(} + +\begin{syntax} +\senv{titlingpage} text \eenv{titlingpage} \\ +\end{syntax} + When one of the standard classes is used with the \Lopt{titlepage} +option, \cmd{\maketitle} puts the title elements on an unnumbered page +and then starts a new page numbered page 1. +The standard classes also provide +a \Ie{titlepage} environment which starts a new unnumbered page and at the +end starts a new page numbered 1. You are entirely responsible +for specifying exactly what and where is to go on this title page. +If \cmd{\maketitle} is used within the \Ie{titlepage} environment it +will start yet another page. + + This class provides neither a \Lopt{titlepage} option nor +a \Ie{titlepage} environment; instead it provides the \Ie{titlingpage} +environment which falls between the \Lopt{titlepage} +option and the \Ie{titlepage} environment. Within the \Ie{titlingpage} +environment you can use the \cmd{\maketitle} command, and any others +you wish. The \pstyle{titlingpage} pagestyle is used, and +at the end it starts another ordinary page numbered one. +The \pstyle{titlingpage} pagestyle is initially defined to be the same +as the \pstyle{empty} pagestyle. + + For example, to put both the title and an abstract\index{abstract} +on a title page, +with a \pstyle{plain} pagestyle: +\begin{lcode} +\begin{document} +\begin{titlingpage} +\aliaspagestyle{titlingpage}{plain} +\setlength{\droptitle}{30pt} lower the title +\maketitle +\begin{abstract}...\end{abstract} +\end{titlingpage} +\end{lcode} + + By default, titling information is centered with respect to the +width of the typeblock\index{typeblock}. + Occasionally someone asks on the \texttt{comp.text.tex} newsgroup how +to center the titling information on a title page +with respect to the width of the physical +page. If the typeblock\index{typeblock} is centered with respect to the physical page, +then the default centering suffices. If the typeblock\index{typeblock} is not physically +centered, then the titling information either has to be shifted +horizontally or \cmd{\maketitle} has to be made to think that the typeblock\index{typeblock} +has been shifted horizontally. The simplest solution is to use the +\cmd{\calccentering} and \Ie{adjustwidth*} command and environment. For +example: +\begin{lcode} +\begin{titlingpage} + \calccentering{\unitlength} + \begin{adjustwidth*}{\unitlength}{-\unitlength} + \maketitle + \end{adjustwidth*} +\end{titlingpage} +\end{lcode} + +\index{title page|)} + +\begin{syntax} +\cmd{\title}\marg{text} \cmd{\thetitle} \\ +\cmd{\author}\marg{text} \cmd{\theauthor} \\ +\cmd{\date}\marg{text} \cmd{\thedate} \\ +\end{syntax} + In the usual document classes, the contents (\meta{text}) of +the \cmd{\title}, \cmd{\author} and \cmd{\date} +macros used for \cmd{\maketitle} are unavailable once \cmd{\maketitle} +has been +issued. The class provides the \cmd{\thetitle}, +\cmd{\theauthor} and \cmd{\thedate} commands that can be used for printing +these elements of the title later in the document, +if desired. + +\begin{syntax} +\cmd{\and} \cmd{\andnext} \\ +\end{syntax} + The macro \cmd{\and} is used within the argument to the +\cmd{\author} command to add some extra space between the author's names. +The class \cmd{\andnext} macro inserts a newline instead of a space. +Within the \cmd{\theauthor} macro both \cmd{\and} and \cmd{\andnext} +are replaced by a comma. + + The class does not follow the the standard classes' habit +of automatically killing the titling +commands after \cmd{\maketitle} has been issued. You can have multiple +\cmd{\title}, \cmd{\author}, \cmd{\date} and \cmd{\maketitle} +commands in your +document if you wish. For example, some reports are issued with +a title page, followed by an executive summary, and then they +have another, possibly modified, title at the start of +the main body of the report. This can be accomplished like this: +\begin{lcode} +\title{Cover title} +... +\begin{titlingpage} +\maketitle +\end{titlingpage} +... +\title{Body title} +\maketitle +... +\end{lcode} + +\begin{syntax} +\cmd{\killtitle} \cmd{\keepthetitle} \\ +\cmd{\emptythanks} \\ +\end{syntax} + The \cmd{\killtitle} macro makes all aspects of titling, including +\cmd{\thetitle} etc., +unavailable from the point that it is issued (using this command will save +some macro space if the \cmd{\thetitle}, etc., commands are not required). +Using this command is the class's manual version +of the automatic killing performed by the standard classes. +The \cmd{\keepthetitle} command performs a similar function, except that +it keeps the \cmd{\thetitle}, \cmd{\theauthor} and \cmd{\thedate} commands, + while killing everything else. + +The \cmd{\emptythanks} command discards any text from prior use of +\cmd{\thanks}. +This command is useful when \cmd{\maketitle} is used multiple times --- +the \cmd{\thanks} commands in each use just stack up the texts for output +at each use, so each subsequent use of \cmd{\maketitle} will output all +previous \cmd{\thanks} texts together with any new ones. To avoid this, +put \cmd{\emptythanks} before each \cmd{\maketitle} after the first. + +\index{title!styling|)} + + +\subsection{Styling the thanks} \label{sec:thanks} + +\index{thanks} +\index{thanks!styling|(} + + The class provides a configurable \cmd{\thanks} command. + +\begin{syntax} +\cmd{\thanksmarkseries}\marg{format} \\ +\cmd{\symbolthanksmark} \\ +\end{syntax} + Any |\thanks{}| are marked with symbols in the +titling and footnotes\index{footnote}. +The command \cmd{\thanksmarkseries} +can be used to change the marking style. The \meta{format} argument +is the name of one of the formats for printing a counter. The name +is the same as that of a counter format but without the backslash. +To have the \cmd{\thanks} marks as lowercase letters instead of symbols +do: +\begin{lcode} +\thanksmarkseries{alph} +\end{lcode} +Just for convenience the \cmd{\symbolthanksmark} command sets the series +to be footnote\index{footnote} symbols. +Using this class the potential names for \meta{format} are: +|arabic|, |roman|, |Roman|, |alph|, |Alph|, and |fnsymbol|. + +\begin{syntax} +\cmd{\continuousmarks} \\ +\end{syntax} +The \cmd{\thanks} command uses the \Icn{footnote} counter, +and normally the counter +is zeroed after the titling so that the footnote marks\index{footnote!mark} start from 1. +If the counter should not be zeroed, then just specify +\cmd{\continuousmarks}. +This might be required if numerals are used as the thanks markers. + +\begin{syntax} +\cmd{\thanksheadextra}\marg{pre}\marg{post} \\ +\end{syntax} +The \cmd{\thanksheadextra} command will insert +\meta{pre} and \meta{post} before and after the thanks markers in the +titling block. By default \meta{pre} and \meta{post} are empty. +For example, to put parentheses round the titling markers do: +\begin{lcode} +\thanksheadextra{(}{)} +\end{lcode} + + +\begin{syntax} +\cmd{\thanksmark}\marg{n} \\ +\end{syntax} +It is sometimes desireable to have the same thanks text be applied to, +say, four out of six authors, these being the first 3 and the last one. +The command \cmd{\thanksmark}\marg{n} is similar to +\cmd{\footnotemark}\oarg{n} in that it prints a thanks mark identical +to that of the \meta{n}'th \cmd{\thanks} command. No changes are made +to any thanks in the footnotes\index{footnote}. For instance, in the following +the authors Alpha and Omega will have the same mark: +\begin{lcode} +\title{The work\thanks{Draft}} +\author{Alpha\thanks{ABC}, + Beta\thanks{XYZ} and + Omega\thanksmark{2}} +\maketitle +\end{lcode} + +%\begin{syntax} +%\cmd{\thanksgap}\marg{length} \\ +%\end{syntax} +%The marks in the titling block printed by the +%\cmd{\thanks} and \cmd{\thanksmark} +%commands take zero space. This is acceptable if they come at the end of +%a line, but not in the middle of a line. Use the +%\cmd{\thanksgap} command immediately after a mid-line +%\cmd{\thanks} or \cmd{\thanksmark} command to add \meta{length} amount of +%space before the next word. For example, if there are three authors +%from two different institutions: +%\begin{lcode} +%\author{Alpha\thanks{ABC}, +% Omega\thanks{XYZ}\thanksgap{1ex} and +% Beta\thanksmark{1}} +%\end{lcode} + +\begin{syntax} +\cmd{\thanksmarkstyle}\marg{defn} \\ +\end{syntax} +By default the thanks mark at the foot is typeset as a superscript. In +the class this is specifed via +\begin{lcode} +\thanksmarkstyle{\textsuperscript{#1}} +\end{lcode} +where |#1| will be replaced by the thanks mark symbol. You can change +the mark styling +if you wish. For example, to put parentheses round the +mark and typeset it at normal size on the baseline: +\begin{lcode} +\thanksmarkstyle{(#1)} +\end{lcode} + + +\begin{syntax} +\lnc{\thanksmarkwidth} \\ +\end{syntax} + The thanks mark in the footnote\index{footnote} is typeset right justified in a box +of width \lnc{\thanksmarkwidth}. The first line of the thanks text starts +after this box. The initialisation is +\begin{lcode} +\setlength{\thanksmarkwidth}{1.8em} +\end{lcode} +giving the default position. + +\begin{syntax} +\lnc{\thanksmarksep} \\ +\end{syntax} +The value of the length + \lnc{\thanksmarksep} controls the indentation the +second and subsequent lines of the thanks text, with respect to +the end of the mark box. As examples: +\begin{lcode} +\setlength{\thanksmarksep}{0em} +\end{lcode} + will align the left hand ends of of a multiline thanks text, while: +\begin{lcode} +\setlength{\thanksmarksep}{-\thanksmarkwidth} +\end{lcode} +will left justify any second and subsequent lines of the thanks text. +This last +setting is the initialised value, giving the default appearance. + +\begin{syntax} +\cmd{\thanksfootmark} \\ +\end{syntax} + A thanks mark in the footnote\index{footnote} region is typeset by \cmd{\thanksfootmark}. +The code for this is roughly: +\begin{lcode} +\newcommand{\thanksfootmark}{% + \hbox to\thanksmarkwidth{\hfil\normalfont% + \thanksscript{\thanksfootpre \thefootnote \thanksfootpost}}} +\end{lcode} +where \cmd{\thanksfootpre} and \cmd{\thanksfootpost} are specified via the +\cmd{\thanksfootextra} macro. You should not need to change the definition +of \cmd{\thanksfootmark} +but you may want to change the default definitions of one or more +of the macros it uses. + +\begin{comment} + +\begin{syntax} +\cmd{\thanksscript}\marg{text} \\ +\end{syntax} +Note that the thanks mark, together with the |\...pre| and |\...post| +commands form the \meta{text} argument to the \cmd{\thanksscript} command. +This is initially defined as: +\begin{lcode} +\newcommand{\thanksscript}[1]{\textsuperscript{#1}} +\end{lcode} +so that \cmd{\thanksscript} typesets its argument as a superscript, which +is the default for thanks notes. If you would prefer the mark to be +set at the baseline instead, for example, just do: +\begin{lcode} +\renewcommand{\thanksscript}[1]{#1} +\end{lcode} + and if you also wanted very small symbols on the baseline you could do: +\begin{lcode} +\renewcommand{\thanksscript}[1]{\tiny #1} +\end{lcode} + +Alternatively +\begin{lcode} +\renewcommand{\thanksscript}[1]{#1} +\thanksfootextra{\bfseries}{.} +\end{lcode} +will give a bold baseline mark followed by a dot. + + Using combinations of these macros you can easily define +different layouts for the thanks footnotes\index{footnote}. Here are some +sample, but to shorten them I have ignored any +|\renewcommand|s and |\setlength|s, leaving these to be implied +as necessary. +\begin{itemize} +\item Setting |\thanksfootextra{}{\hfill}| left justifies the mark + in its box: + \begin{itemize} + \item |\thanksscript{\llap{#1\space}}|, |\thanksmarkwidth{0em}| and \\ + |\thanksmargin{0em}| puts the baseline mark in the margin\index{margin} + and the text left justified. + \item Using |\thanksscript{#1}|, |\thanksmarkwidth{1em}| and \\ + |\thanksmargin{-\thanksmarkwidth}| makes the baseline mark + and text left adjusted. + \item |\thanksscript{#1}|, |\thanksmarkwidth{1em}| and + |\thanksmargin{0em}| puts the baseline mark left adjusted + and the text indented and aligned, like this marked + sentence is typeset. + \end{itemize} + +\item Setting |\thanksfootextra{ }| and |\thanksscript{#1}| + right justifies the baseline mark and a space in the mark box: + \begin{itemize} + \item The normal style is + defined by |\thanksmarkwidth{1.8em}| and \\ + |\thanksmargin{-\thanksmarkwidth}| which put the mark + indented and the text left adjusted, like a normal indented + paragraph\index{paragraph!indentation}. + \item |\thanksmarkwidth{1.8em}| and + |\thanksmargin{0em}| put the mark indented + and the text indented and aligned. + \end{itemize} + +\end{itemize} + +%%%%%%%%%%%%%%%%%%%%% +\end{comment} +%%%%%%%%%%%%%%%%%%%% + +\begin{syntax} +\cmd{\makethanksmark} \\ +\cmd{\makethanksmarkhook} \\ +\end{syntax} +The macro \cmd{\makethanksmark} typesets both the thanks marker (via +\cmd{\thanksfootmark}) and the thanks text. You probably will not need +to change its default definition. Just in case, though, +\cmd{\makethanksmark} +calls the macro \cmd{\makethanksmarkhook} before it does any typesetting. +The default definition of this is: +\begin{lcode} +\newcommand{\makethanksmarkhook}{} +\end{lcode} +which does nothing. + + You can redefine \cmd{\makethanksmarkhook} to do something useful. For +example, if you wanted a slightly bigger baseline skip you could do: +\begin{lcode} +\renewcommand{\makethanksmarkhook}{\fontsize{8}{11}\selectfont} +\end{lcode} +where the numbers |8| and |11| specify the point size of the font +and the baseline skip +respectively. In this example 8pt is the normal \cmd{\footnotesize} in +a 10pt document, and 11pt is the baselineskip for \cmd{\footnotesize} +text in an 11pt document (the baseline skip is 9.5pt in a 10pt document); +adjust these numbers to suit. + +\begin{syntax} +\cmd{\thanksrule} \\ +\cmd{\usethanksrule} \\ +\cmd{\cancelthanksrule} \\ +\end{syntax} +By default, there is no rule above \cmd{\thanks} +text that appears in a \Ie{titlingpage} environment. +If you want a rule in that environment, put \cmd{\usethanksrule} +before the \cmd{\maketitle} command, which will then print a rule according +to the current definition of \cmd{\thanksrule}. +\cmd{\thanksrule} is initialised to be a copy of \cmd{\footnoterule} as it +is defined at the +end of the preamble\index{preamble}. The definition of \cmd{\thanksrule} can be changed +after |\begin{document}|. If the definition of \cmd{\thanksrule} is modified +and a \cmd{\usethanksrule} command has been issued, then the redefined +rule may also be used for footnotes\index{footnote}. Issuing the command +\cmd{\cancelthanksrule} will cause the normal \cmd{\footnoterule} definition +to be used from thereon; another \cmd{\usethanksrule} +command can be issued later +if you want to swap back again. + +The parameters for the vertical positioning of footnotes\index{footnote} +and thanks notes, and the default \cmd{\footnoterule} are the same +(see \fref{fig:fn} on \pref{fig:fn}). +You will have to change one or more of these if the vertical spacings of +footnotes\index{footnote} +and thanks notes are meant to be different. + + +\index{thanks!styling|)} + +\section{Abstracts} + +\index{abstract|(} + + Much of this part of the class is a reimplementation of the +\Lpack{abstract} package~\cite{ABSTRACT}. + + The typeset format of an \Ie{abstract} in a \Lclass{report} or +\Lclass{article} class\footnote{The \texttt{abstract} environment is not +available for the \Lclass{book} class.} document depends on the class +options. The formats are: +\begin{itemize} +\item \Lopt{titlepage} class option: The abstract heading\index{heading!abstract} (i.e., value of + \cmd{\abstractname}) is typeset centered in a bold font; the text is set in + the normal font and to the normal width. +\item \Lopt{twocolumn} class option: The abstract heading\index{heading!abstract} is typeset like + an unnumbered section; the text is set in the normal font and to the + normal width (of a single column\index{column!single}). +\item Default (neither of the above class options): The abstract heading\index{heading!abstract} + is typeset centered in a small bold font; the text is set in a small + font and indented like the |quotation| environment. +\end{itemize} + + This class provides an \Ie{abstract} environment and +handles to modify the typesetting of an \Ie{abstract}. + +\begin{syntax} +\senv{abstract} text \eenv{abstract} \\ +\end{syntax} +There is nothing special about using the \Ie{abstract} environment. +Formatting is controlled by the macros described below. + + The usual advice~\cite{FAQ} about creating a one-column\index{column!double} +\Ie{abstract} in a +\Lopt{twocolumn} document is to write code like this: +\begin{lcode} +\documentclass[twocolumn...]{...} +... +\twocolumn[ + \begin{@twocolumnfalse} + \maketitle need full-width title + \begin{abstract} + abstract text... + \end{abstract} + \end{@twocolumnfalse} +] +... hand make footnotes for any \thanks commands +... +\end{lcode} + +\begin{syntax} +\senv{onecolabstract} text \eenv{onecolabstract} \\ +\cmd{\saythanks} \\ +\end{syntax} +The class provides a \Ie{onecolabstract} environment that you can use +for a one column\index{column!single} abstract in a \Lopt{twocolumn} document, and it is used +like this: +\begin{lcode} +\documentclass[twocolumn...]{memoir} +... +\twocolumn[ + \maketitle need full-width title + \begin{onecolabstract} + abstract text... + \end{onecolabstract} +] +\saythanks typesets any \thanks commands +... +\end{lcode} +The command \cmd{\saythanks} ensures that any \cmd{\thanks} texts are +printed out as normal. + + If you want, you can use the \Ie{onecolabstract} environment in place +of the \Ie{abstract} environment --- it doesn't have to be within the +optional argument of the \cmd{\twocolumn} command. In fact, +\Ie{onecolabstract} internally uses \Ie{abstract} for the typesetting. + +\begin{syntax} +\cmd{\abstractcol} \\ +\cmd{\abstractintoc} \\ +\cmd{\abstractnum} \\ +\cmd{\abstractrunin} \\ +\end{syntax} + The normal format for an abstract is with a centered, bold title +and the text in a small font, inset from the margins\index{margin}. + +The \cmd{\abstractcol} declaration specifies that an abstract in a +\Lopt{twocolumn} class option document should be typeset like a +normal, unnumbered chapter. +The \cmd{\abstractintoc} specifies that the abstract title should +be added to the \toc. The declaration \cmd{\abstractnum} specifies that the +abstract should be typeset like a numbered chapter and +\cmd{\abstractrunin} specifies that +the title of the abstract should look like a runin heading; these two +declarations are mutually exclusive. Note that the \cmd{\abstractnum} +declaration has no effect if the abstract is in the \cmd{\frontmatter}. + +\begin{syntax} +\cmd{\abstractnamefont} \\ +\cmd{\abstracttextfont} \\ +\end{syntax} + These two commands can be redefined to change the fonts used for +typesetting the heading (defined via \cmd{\abstractname}) of the +\Ie{abstract} +environment and the font for typesetting the text of the abstract, +respectively. The default definitions are +\begin{lcode} +\newcommand{\abstractnamefont}{\normalfont\small\bfseries} +\newcommand{\abstracttextfont}{\normalfont\small} +\end{lcode} + +\begin{syntax} +\lnc{\absleftindent} \lnc{\absrightindent} \\ +\lnc{\absparindent} \lnc{\absparsep} \\ +\end{syntax} + This version of \Ie{abstract} uses a list environment for typesetting +the text. These four lengths can be changed (via \cmd{\setlength} + or \cmd{\addtolength}) to adjust +the left and right margins\index{margin}, the paragraph indentation\index{paragraph!indentation}, and the vertical skip +between paragraphs in this environment. +The default values depend on whether or not the \Lopt{twocolumn} +class option is used. + +\begin{syntax} +\cmd{\abslabeldelim}\marg{text} \\ +\end{syntax} +If the \cmd{\abstractrunin} declaration has been given, +the heading is typeset as a run-in heading. That is, it is the +first piece of text on the first line of the abstract text. +The \meta{text} argument of \cmd{\abslabeldelim} is typeset +immediately after the heading. By default it is defined to do nothing, but +if you wanted, for example, the \cmd{\abstractname} to be followed by +a colon and some extra space you could specify +\begin{lcode} +\abslabeldelim{:\quad} +\end{lcode} + +\begin{syntax} +\cmd{\absnamepos} \\ +\end{syntax} + If the \cmd{\abstractrunin} declaration is not used then the heading +is typeset in its own environment, specified by +\cmd{\absnamepos}. The default definition is +\begin{lcode} +\newcommand{\absnamepos}{center} +\end{lcode} +It can be defined to be one of \Ie{flushleft}, \Ie{center}, +or \Ie{flushright} to give a left, centered or right aligned heading; +or to any +other appropriate environment which is supported by a used package\index{package}. + +\begin{syntax} +\lnc{\abstitleskip} \\ +\end{syntax} + With the \cmd{\abstractrunin} declaration a horizontal space of length +\lnc{\abstitleskip} is typeset +before the heading. For example, if \lnc{\absparindent} is non-zero, then: +\begin{lcode} +\setlength{\abstitleskip}{-\absparindent} +\end{lcode} + will typeset the heading flush left. + +Without the \cmd{\abstractrunin} declaration, \lnc{\abstitleskip} is +aditional vertical +space (either positive +or negative) that is inserted between the abstract name and the text of +the abstract. + +\index{abstract|)} + + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\renewcommand{\printchaptername}{} +\renewcommand{\chapternamenum}{} +\renewcommand{\chapnumfont}{\normalfont\huge\sffamily} +\renewcommand{\chaptitlefont}{\chapnumfont} +\renewcommand{\afterchapternum}{\space} +\setsecheadstyle{\Large\sffamily\raggedright} +\setsubsecheadstyle{\large\sffamily\raggedright} +\setsubsubsecheadstyle{\normalsize\sffamily\raggedright} +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + + +\chapter{Document divisions} + + The chapter is typeset using the sectional headings\index{heading} styles specified +at the end of the chapter. + + +\section{Introduction} + + In this chapter I first discuss the various kinds of divisions +within a book and the commands for typesetting these. + +After that I describe the class methods for modifying the appearance +of the chapter and other sectional headings\index{heading}. + The facilities described here provide roughly the same as you would +get if you used the \Lpack{titlesec}~\cite{TITLESEC} and +\Lpack{sectsty}~\cite{SECTSTY} packages together; the commands are different, +though. + +\section{Book divisions} + + As described earlier there are three main logical divisions to a book; +the front, main and back matter. There are three LaTeX +commands that correspond to these, namely \cmd{\frontmatter}, +\cmd{\mainmatter} and \cmd{\backmatter}. + +\begin{syntax} +\cmd{\frontmatter} \cmd{\frontmatter*} \\ +\end{syntax} +The \cmd{\frontmatter} declaration sets the folios\index{folio} to be printed in lowercase +roman numerals, starts the page numbering from~i, and prohibits any numbering +of sectional divisions. Caption\index{caption}, equations, etc., will be numbered +continuously. The starred version of the command, +\cmd{\frontmatter*}, is similar to the unstarred version except that it +makes no changes to the page numbering or the print style for the folios\index{folio}. + +\begin{syntax} +\cmd{\mainmatter} \cmd{\mainmatter*} \\ +\end{syntax} +The \cmd{\mainmatter} declaration, which is the default at the start of a document, +sets the folios\index{folio} to be printed in arabic numerals, starts the page numbering +from~1, and sections and above will be numbered. Float\index{float} captions\index{caption}, equations, +etc., will be numbered per chapter\index{chapter}. The starred version of the command, +\cmd{\mainmatter*}, is similar to the unstarred version except that it +makes no changes to the page numbering or the print style for the folios\index{folio}. + + +\begin{syntax} +\cmd{\backmatter} \\ +\end{syntax} +The \cmd{\backmatter} declaration makes no change to the pagination or folios\index{folio} +but does prohibit sectional division numbering, and captions\index{caption}, etc., will +be numbered continuously. + + +\section{Sectional divisions} + + The \theclass{} class lets you divide a document up into seven levels +of named divisions. They range from part\index{part} through chapter\index{chapter} and down to +sub-paragraph. A particular sectional division is specified by one of +the commands \cmd{\part}, \cmd{\chapter}, \cmd{\section}, \cmd{\subsection}, +which is probably as deep as you want to go. If you really need finer +divisions, they are + \cmd{\subsubsection}, \cmd{\paragraph} and lastly \cmd{\subparagraph}. +All the sectional commands, except for chapters, + have the same form, so rather than describing +each one in turn I will use \cmd{\section} to stand for any one of them. + +\begin{syntax} +\cmd{\section}\oarg{toc-title}\oarg{head-title}\marg{title}\\ +\cmd{\section*}\marg{title}\\ +\end{syntax} +There are two forms of the command; +the starred version is simpler, so I'll describe its +effects first --- it just typesets \meta{title} in the document in the format +for that particular sectional division. Like the starred version, the plain +version also typesets \meta{title} in the document, but it may be numbered. +Diferent forms of the division title are available for the +Table of Contents (\toc) and a running header\index{header}, as follows: +\begin{itemize} +\item No optional argument: \meta{title} is used for the division title, + the ToC title and a page header title. +\item One optional argument: \meta{title} is used for the division title; + \meta{toc-title} is used for the ToC title and a page header\index{header} title. +\item Two optional arguments: \meta{title} is used for the division title; + \meta{toc-title} is used for the ToC title; \meta{head-title} + is used for a page header\index{header} title. +\end{itemize} + +A \cmd{\section} command restarts the numbering of any \cmd{\subsection}s +from one. +For most of the divisions the \meta{title} is put on the page where the command +was issued. The \cmd{\part} and \cmd{\chapter} commands behave a little +differently. + +The \cmd{\part}\meta{title} command puts the part name (default |Part|), + number and +\meta{title} on a page by itself. The +numbering of parts\index{part!number} has no effect on the numbering of chapters\index{chapter!number}. + + Later I'll give a list of LaTeX's default names, like |Part|. + +\begin{syntax} +\cmd{\chapter}\oarg{toc-title}\oarg{head-title}\marg{title} \\ +\cmd{\chapter*}\oarg{head-title}\marg{title} \\ +\end{syntax} + +The \cmd{\chapter} command starts a new page and puts +the chapter name (default |Chapter|), number and \meta{title} +at the top of the page. It restarts the numbering of any \cmd{\section}s +from one. If no optional arguments are specified, \meta{title} +is used as the \toc{} entry and for any page headings. If one optional +argument is specified this is \meta{toc-title} and is used for the +\toc{} entry and for page headings. If both optional arguments +are specified the \meta{head-title} is used for page headings. + +The \cmd{\chapter*} command starts a new page and puts +\meta{title} at the top of the page. It makes no \toc{} entry, +changes no numbers and by default changes no page headings. +If the optional \meta{head-title} argument is given, this is used +for page headings. Use of the optional argument has the side-effect +that the \Icn{secnumdepth} counter is set to |maxsecnumdepth| (see below +for an explanation of these). + + When the \Lopt{article} option is in effect, however, things are slightly +different. New chapters do not necessarily start on a new page. +The \cmd{\mainmatter} command +just turns on sectional numbering and starts arabic page numbering; the +\cmd{\backmatter} command just turns off sectional numbering. + The \cmd{\tableofcontents} command and friends, as well as any +other commands created via \cmd{\newlistof}, +\emph{always}\footnote{This is a consequence of the internal +timing of macro calls.} +call |\thispagestyle{chapter}|. If you are using the \Lopt{article} option you +will probably want to ensure that the \pstyle{chapter} pagestyle is the +same as you normally use for the document. + + Unlike the standard classes the \meta{title} is typeset ragged right. +This means that if you need to force a linebreak in the \meta{title} you +have to use \cmd{\newline} instead of the more usual \cmd{\\}. For instance +\begin{lcode} +\section{A broken\newline title} +\end{lcode} + + In the standard classes a \cmd{\section} or other divisional heading +that is too close to the bottom of a page is moved to the top of the +following page. If this happens and \cmd{\flushbottom} is in effect, the +contents of the short page are stretched to make the last line flush with +the bottom of the typeblock. +\begin{syntax} +\cmd{\raggedbottomsectiontrue} \\ +\cmd{\raggedbottomsectionfalse} \\ +\lnc{\bottomsectionskip} \\ +\end{syntax} +The \cmd{\raggedbottomsectiontrue} declaration will typeset any pages that +are short because of a moved divisional header as though \cmd{\raggedbottom} +was in effect for the short page; other pages are not affected. The +length \lnc{\bottomsectionskip} controls the amount of stretch on the short +page. Setting it to zero allows the last line to be flush with the bottom +of the typeblock. The default setting of 10mm appears to remove any stretch. + +The declaration \cmd{\raggedbottomsectionfalse}, which is the default, +cancels any previous \cmd{\raggedbottomsectiontrue} declaration. + + + +\begin{syntax} +\cmd{\plainbreak}\marg{num} \cmd{\plainbreak*}\marg{num} \\ +\cmd{\fancybreak}\marg{text} \cmd{\fancybreak*}\marg{text} \\ +\end{syntax} + The \cmd{\plainbreak} is an anonymous division. It puts \meta{num} +blank lines into the typescript and the first line of the following +paragraph is not indented\index{paragraph!indentation}. Another anonymous division is +\cmd{\fancybreak} which puts \meta{text} centered into the typescript and the +initial line of the following paragraph is not indented\index{paragraph!indentation}. For +example: +\begin{lcode} +\fancybreak{{*}\\{* * *}\\{*}} +\end{lcode} +typesets a little diamond made of asterisks. + + The starred versions of the commands indent the first line of the +following paragraph\index{paragraph!indentation}. + +\begin{syntax} +\cmd{\plainfancybreak}\marg{space}\marg{num}\marg{text} \\ +\cmd{\plainfancybreak*}\marg{space}\marg{num}\marg{text} \\ +\end{syntax} +If a plain break comes at the top or bottom of a page then it is very +difficult for a reader to discern that there is a break at all. +If there is text on the page and enough space left to put some text +after a break the \cmd{\plainfancybreak} command will use a \cmd{\plainbreak} +with \meta{num} lines, +otherwise (the break would come at the top or bottom of the page) it +will use a \cmd{\fancybreak} with \meta{text}. The \meta{space} argument is a +length specifying the space needed for the \meta{num} blank lines and some +number of text lines for after the plain break. The starred version of +the command uses the starred versions of the \cmd{\plainbreak} and +\cmd{\fancybreak} commands. + + Unfortunately there is an interaction between the requested, plain, +and fancy break spaces. + Let $P$ be the space (in lines) required for the plain break, +$F$ the space (in lines) +required for the fancy break, and $S$ the \meta{space} space (in lines). +From some experiments it appears that the condition for the plain break +to avoid the top and bottom of the page is that $S - P > 1$. +Also, the condition for the fancy break to avoid being put in the middle +of a page (i.e., not at the top or bottom) is that $S - F < 3$. +For example, if the plain and fancy breaks take the same vertical space +then $S = P +2$ is the only value that matches the conditions. In general, +if $F = P + n$ then the condition is $1 < S-P < 3+n$, which means that +for the \cmd{\plainfancybreak} command the +fancy break must always take at least as much space as the plain break. + + +\fancybreak{\pfbreakdisplay} + + The \cmd{\plainfancybreak} macro inserts a plain break in the middle of +a page or if the break would come at the bottom or top of a page it +inserts a fancy break instead. + +\begin{syntax} +\cmd{\pfbreak} \cmd{\pfbreak*} \\ +\lnc{\pfbreakskip} \\ +\cmd{\pfbreakdisplay}\marg{text} \\ +\end{syntax} +The \cmd{\pfbreak} macro is an alternate for \cmd{\plainfancybreak} that may +be more convenient to use. The gap for the plain break is given by the +length \lnc{\pfbreakskip} which is initialised to produce two blank lines. +The fancy break, which takes the same vertical space, is given by the +\meta{text} argument of \cmd{\pfbreakdisplay}. The default definition +typesets three asterisks, as shown a few lines before this. + +%%\renewcommand{\pfbreakdisplay}{\huge \ding{167}\quad\ding{167}\quad\ding{167}} +\renewcommand{\pfbreakdisplay}{% + $\clubsuit$\quad$\diamondsuit$\quad$\clubsuit$} +\fancybreak{\pfbreakdisplay} + + You can change the definition of \cmd{\pfbreakdisplay} for a different +style if you wish. The +fancy break just before this was produced via: +\begin{lcode} +\renewcommand{\pfbreakdisplay}{% + $\clubsuit$\quad\$\diamondsuit$\quad$\clubsuit$} +\fancybreak{\pfbreakdisplay} +\end{lcode} +I used \cmd{\fancybreak} as I'm not sure where the break will come on the +page and the simple \cmd{\pfbreak} macro might just have produced a couple +of blank lines instead of the fancy display. + + The paragraph following \cmd{\pfbreak} is not indented. If you want +it indented use the \cmd{\pfbreak*} starred version. + + +\begin{syntax} +\cmd{\tableofcontents} \cmd{\tableofcontents*} \\ +\cmd{\listoffigures} \cmd{\listoffigures*} \\ +\cmd{\listoftables} \cmd{\listoftables*} \\ +\end{syntax} +In the standard classes the command \cmd{\tableofcontents} typesets a +Table of Contents (\toc) at the point in the document where it is issued. +In the \theclass{} class it also adds \emph{its} +title to the \toc. There is a starred version, \cmd{\tableofcontents*}, +which does not enter itself into the \toc. So, in this class +\cmd{\tableofcontents*} is equivalent to the standard classes' +\cmd{\tableofcontents}. The class also provides the \cmd{\listoffigures} +and \cmd{\listoftables} commands which typeset a List of +Figures (\lof) and +a List of Tables (\lot), also entering their titles into the \toc. The +starred versions of these make no \toc{} entry. + + You can use \cmd{\tableofcontents}, \cmd{\listoffigures}, etc., more +than once in a \Lclass{memoir} class document. + +\begin{syntax} +\cmd{\appendix} \\ +\cmd{\appendixname} \\ +\end{syntax} +In the standard classes the \cmd{\appendix} command changes the numbering of +chapters\index{chapter!number} to an alphabetic form and changes the names of chapters from +\cmd{\chaptername} (default |Chapter|) +to the value of \cmd{\appendixname} (default |Appendix|)\index{appendix}. +Thus, the first and any subsequent \cmd{\chapter}s after +the \cmd{\appendix} command +will be `Appendix A \ldots', `Appendix B \ldots', and so on. +This class provides the same command plus some other ways of dealing with +appendices\index{appendix}. + +\begin{syntax} +\cmd{\appendixpage}\\ +\cmd{\appendixpage*}\\ +\cmd{\appendixpagename}\\ +\end{syntax} +The \cmd{\appendixpage} command generates a part-like page (but no |Part| +or number) with the title given by the value of \cmd{\appendixpagename} +(default |Appendices|)\index{appendix}. It also makes an entry in the \toc{} using +\cmd{\addappheadtotoc} (see below). The starred version generates the +appendix\index{appendix} page but makes no \toc{} entry. + +\begin{syntax} +\cmd{\addappheadtotoc}\\ +\cmd{\appendixtocname}\\ +\end{syntax} +The command \cmd{\addappheadtotoc} adds an entry to the \toc. The title is +given by the value of \cmd{\appendixtocname} (default |Appendices|)\index{appendix}. + +\begin{syntax} +\senv{appendices} text \eenv{appendices}\\ +\end{syntax} +The \Ie{appendices} environment acts like the \cmd{\appendix}\index{appendix} command in that it +resets the numbering and naming of chapters\index{chapter}. However, at the end of the +environment, chapters are restored to their original condition and any +chapter numbers continue in sequence as though the \Ie{appendices} environment +had never been there. + +\begin{syntax} +\senv{subappendices} text \eenv{subappendices} \\ +\cmd{\namesubappendixtrue} \cmd{\namesubappendixfalse} \\ +\end{syntax} +The \Ie{subappendices} environment can be used to put appendices\index{appendix} at the end +of a chapter\index{chapter}. Within the environment \cmd{\section} starts a +new sub-appendix\index{appendix}. You may put \cmd{\addappheadtotoc} at the start +of the environment if you want a heading entry in the \toc. +If you put the declaration \cmd{\namesubappendixtrue} +\emph{before} the \Ie{subappendices} environment, the sub-appendix number +in the body of the document will be preceded by the value of +\cmd{\appendixname}. The \cmd{\namesubappendixfalse} declaration may be +used to switch off this behaviour. + + + + +\section{Numbering} \label{sec:secnumbers} + + Each type of sectional division has an associated \emph{level} as +shown in \tref{tab:seclevels}. +Divisions are numbered if the value of the \Icn{secnumdepth} counter +is equal to or greater than their level. For example, with +\begin{lcode} +\setcounter{secnumdepth}{2} +\end{lcode} +then subsections up to parts\index{part!number} will be numbered. + +\begin{table} +\centering +\caption{Division levels} \label{tab:seclevels} +\begin{tabular}{lr} \hline +Division & Level \\ \hline +\cmd{\part} & -1 \\ +\cmd{\chapter} & 0 \\ +\cmd{\section} & 1 \\ +\cmd{\subsection} & 2 \\ +\cmd{\subsubsection} & 3 \\ +\cmd{\paragraph} & 4 \\ +\cmd{\subparagraph} & 5 \\ \hline +\end{tabular} +\end{table} + +\begin{syntax} +\cmd{\setsecnumdepth}\marg{secname} \\ +\cmd{\maxsecnumdepth}\marg{secname} \\ +\end{syntax} +Instead of having to remember the levels if you want to change what +gets numbered you can use the \cmd{\setsecnumdepth} command. It +sets \Icn{secnumdepth} so that divisions \meta{secname} and above +will be numbered. The argument \meta{secname} is the name of a sectional +division without the backslash. For example, to have subsections +and above numbered: +\begin{lcode} +\setsecnumdepth{subsection} +\end{lcode} + + The command \cmd{\maxsecnumdepth} sets the maximum value for +\Icn{secnumdepth} that can be used in the document. You can use +\cmd{\setsecnumdepth} anywhere you want in the document to (temporarily) +change the numbering level. + + By default, the class sets: +\begin{lcode} +\maxsecnumdepth{section} +\setsecnumdepth{section} +\end{lcode} +The commands \cmd{\mainmatter} and \cmd{\mainmatter*} set the +\Icn{secnumdepth} to the value specified by \cmd{\maxsecnumdepth}. + + The number setting commands come from the \Lpack{tocvsec2} +package~\cite{TOCVSEC2}. + + + + + +\section{Part headings} + +\index{heading!part|(} + + Part titles \emph{always} start on a new page with the \pstyle{part} +pagestyle. + + + Several aspects of the typesetting of the \cmd{\part} title are +configurable. + +\begin{syntax} +\cmd{\beforepartskip} \cmd{\afterpartskip} \\ +\end{syntax} +These two commands effectively control the spacing before and after the part +title. Their default definitions are: +\begin{lcode} +\newcommand{\beforepartskip}{\null\vfil} +\newcommand{\afterpartskip}{\vfil\newpage} +\end{lcode} +Together, these vertically center any typesetting on the page, and then start +a new page. To move the title upwards on the page, for example, you could do: +\begin{lcode} +\renewcommand{\beforepartskip}{\null\vskip 0pt plus 0.3fil} +\renewcommand{\afterpartskip}{\vskip 0pt plus 0.7fil \newpage} +\end{lcode} + +\begin{syntax} +\lnc{\midpartskip} \\ +\end{syntax} +The length \lnc{\midpartskip} is the vertical distance between the part +number line and the part title. Its default value is 20pt and can be changed +by \cmd{\setlength} or \cmd{\addtolength}. It is probably better to have +the spacing in terms of the \lnc{\baselineskip}, which will change depending +on the font size, instead of a fixed amount. + +\begin{syntax} +\cmd{\printpartname} \cmd{\partnamefont} \\ +\cmd{\partnamenum} \\ +\cmd{\printpartnum} \cmd{\partnumfont} \\ +\end{syntax} +The macro \cmd{\printpartname} typesets the part name +(the value of \cmd{\partname}) using the font +specified by \cmd{\partnamefont}. The default is the \cmd{\bfseries} font in +the \cmd{\huge} size. Likewise the part number is typeset by \cmd{\printpartnum} +using the font specified by \cmd{\partnumfont}, which has the same default as +\cmd{\partnamefont}. The macro +\cmd{\partnamenum}, which is defined to be a space, is called between printing +the part name and the number. All these can be changed to obtain different +effects. For example, to have a large sans font with the part name flush left: +\begin{lcode} +\renewcommand{\partnamefont}{\normalfont\huge\sffamily\raggedright} +\renewcommand{\partnumfont}{\normalfont\huge\sffamily} +\end{lcode} +or to only print the part number in the default font: +\begin{lcode} +\renewcommand{\printpartname}{} +\renewcommand{\partnamenum}{} +\end{lcode} + + +\begin{syntax} +\cmd{\printparttitle}\marg{title} \cmd{\parttitlefont} \\ +\end{syntax} +The title is typeset by \cmd{\printparttitle} using the font specified +by \cmd{\parttitlefont}. +By default this is a \cmd{\bfseries} font in the \cmd{\Huge} size. This can +be changed to have, say, the title set raggedleft in a small caps font by +\begin{lcode} +\renewcommmand{\parttitlefont}{\normalfont\Huge\scshape\raggedleft} +\end{lcode} + + The \cmd{\parttitlefont} font is also used by +\cmd{\appendixpage}, or its starred version, when +typesetting an appendix\index{appendix} page. + +\index{heading!part|)} + +\section{Chapter headings} + +\index{heading!chapter|(} + + The chapter headings are configurable in much the same way as part +headings, but in addition there are some built in chapter styles that you may +wish to try, or define your own. + + Chapters \emph{always} start on a new page with the \pstyle{chapter} +pagestyle. The particular page, recto or verso, that they start on is +mainly controlled by the class options. If the \Lopt{oneside} option is used +they start on the next new page, but if the \Lopt{twoside} option is +used the starting page may differ, as follows. +\begin{itemize} +\item[\Lopt{openright}] The chapter heading is typeset on the next recto page, + which may leave a blank verso leaf. +\item[\Lopt{openleft}] The chapter heading is typeset on the next verso page, + which may leave a blank recto leaf. +\item[\Lopt{openany}] The chapter heading is typeset on the next page and there + will be no blank leaf. +\end{itemize} + +\begin{syntax} +\cmd{\openright} \cmd{\openleft} \cmd{\openany} \\ +\end{syntax} +These three declarations have the same effect as the options of the same name. +They can be used anywhere in the document to change the chapter opening page. + +\begin{syntax} +\cmd{\clearforchapter} \\ +\end{syntax} +The actual macro that sets the opening page for a chapter is +\cmd{\clearforchapter}. The \cmd{\openright}, \cmd{\openleft} and +\cmd{\openany} define \cmd{\clearforchapter} to be respectively +(see \S\ref{sec:moving}) +\cmd{\cleartorecto}, \cmd{\cleartoverso} and \cmd{\clearpage}. You can +obviously change \cmd{\clearforchapter} to do more than just start a +new page. + + Some books have the chapter headings on a verso page, with perhaps +an illustration\index{illustration} or epigraph\index{epigraph}, and then the text starts on the opposite +recto page. The effect can be achieved like: +\begin{lcode} +\openleft % chapter title on verso page +\chapter{The title} % chapter title +\begin{centering} % include a centered illustration +\includegraphics{...} +\end{centering} +\clearpage % go to recto page +Start of the text % chapter body +\end{lcode} + +\begin{syntax} +\cmd{\chapterstyle}\marg{style} \\ +\end{syntax} +The macro \cmd{\chapterstyle} is rather like the \cmd{\pagestyle} command in +that it sets the style of any subsequent chapter headings to be \meta{style}. + + The class provides some predefined chapter styles, including the +\cstyle{default} style which is the familiar LaTeX \Lclass{book} class chapter +headings style. To use the chapterstyle \cstyle{fred} just issue the commmand +|\chapterstyle{fred}|. Different styles can be used in the same document. +The predefined styles include: +\begin{itemize} +\item[\cstyle{default}] The normal LaTeX style. +\item[\cstyle{section}] The heading is typeset like a section; that is, +there is just the number and the title on one line. + See \Cref{chap:topsandtails} on \pref{chap:topsandtails} for an example. +\item[\cstyle{hangnum}] Like the \pstyle{section} style except that the chapter +number is put in the margin\index{margin}. + See \Cref{chap:captions} on \pref{chap:captions} for an example. +\item[\cstyle{companion}] This produces chapter headings like those the the +\textit{LaTeX Companion} series of books. + See \Cref{chap:signposts} on \pref{chap:signposts} for an example. +\item[\cstyle{article}] The heading is typeset like a \cmd{\section} +heading in the \Lclass{article} class. This is similar to the +\cstyle{section} style but different fonts and spacings are used. +\item[\cstyle{demo}] Try this one to see what it does. On the other + hand you can look at \Cref{chap:verse} on \pref{chap:verse} to see + what it looks like. +\end{itemize} + + +\begin{syntax} +\lnc{\beforechapskip} \lnc{\afterchapskip} \\ +\end{syntax} +These two lengths define the spacing before and after the chapter heading. +Their default values are 50pt and 40pt, respectively. + + + +\begin{syntax} +\lnc{\midchapskip} \\ +\end{syntax} +The length \lnc{\midchapskip} is the vertical distance between the chapter +number line and the chapter title. Its default value is 20pt and can be changed +by \cmd{\setlength} or \cmd{\addtolength}. It is probably better to have +the spacing in terms of the \lnc{\baselineskip}, which will change depending +on the font size, instead of a fixed amount. + +\begin{syntax} +\cmd{\printchaptername} \cmd{\chapnamefont} \\ +\cmd{\chapternamenum} \\ +\cmd{\printchapternum} \cmd{\chapnumfont} \\ +\end{syntax} +The macro \cmd{\printchaptername} typesets the chapter name +(the value of \cmd{\chaptername}, default |Chapter|) using the font +specified by \cmd{\chapnamefont}. The default is the \cmd{\bfseries} font in +the \cmd{\huge} size. Likewise the chapter number is typeset by +\cmd{\printchapternum} +using the font specified by \cmd{\chapnumfont}, which has the same default as +\cmd{\chapnamefont}. The macro +\cmd{\chapternamenum}, which is defined to be a space, is called between printing +the chapter name and the number. + +\begin{syntax} +\cmd{\printchaptertitle}\marg{title} \cmd{\chaptitlefont} \\ +\end{syntax} +The title is typeset by \cmd{\printchaptertitle} using the font specified +by \cmd{\chaptitlefont}. +By default this is a \cmd{\bfseries} font in the \cmd{\Huge} size. + + +\begin{syntax} +\cmd{\insertchapterspace} \\ +\end{syntax} +By default a \cmd{\chapter} inserts a small amount of vertical space +into the List of Figures and List of Tables. It calls \cmd{\insertchapterspace} +to do this. The default definition is: +\begin{lcode} +\newcommand{\insertchapterspace}{% + \addtocontents{lof}{\protect\addvspace{10pt}}% + \addtocontents{lot}{\protect\addvspace{10pt}}% +} +\end{lcode} +If you would prefer no inserted spaces then +|\renewcommand{\insertchapterspace}{}| will do the job. +Different spacing can be inserted by +changing the value of the length arguments to \cmd{\addvspace}. + +\index{heading!chapter|)} + +\subsection{Defining a chapter style} \label{sec:chapterstyle} + +\index{chapterstyle|(} + + The following illustrates the essential parts of the code for typesetting +a numbered chapter heading. +\begin{lcode} +\chapterheadstart +\printchaptername \chapternamenum \printchapternum +\afterchapternum +\printchaptertitle{The chapter title} +\afterchaptertitle +\end{lcode} + +\begin{syntax} +\cmd{\printchapternonum} \\ +\end{syntax} + + The essential code for an unnumbered chapter is simpler than +when there is a number to be typeset. +\begin{lcode} +\chapterheadstart +\pintchapternonum +\printchaptertitle{The chapter title} +\afterchaptertitle +\end{lcode} + +The various macros in the above are initially defined as: +\begin{lcode} +\newcommmand{\chapterheadstart}{\vspace*{\beforechapskip}} +\newcommand{\printchaptername}{\chapnamefont \@chapapp} +\newcommand{\chapternamenum}{\space} +\newcommand{\printchapternum}{\chapnumfont \thechapter} +\newcommand{\afterchapternum}{\par\nobreak\vskip \midchapskip} +\newcommand{\printchapternonum}{} +\newcommand{\printchaptertitle}[1]{\chaptitlefont #1} +\newcommand{\afterchaptertitle}{\par\nobreak\vskip \afterchapskip} +\end{lcode} + + A new style is specified by changing the definitions of this last set of +macros and/or the various font and skip specifications. + +\begin{syntax} +\cmd{\makechapterstyle}\marg{style}\marg{text} \\ +\end{syntax} +Chapter styles are defined via the \cmd{\makechapterstyle} command, where +\meta{style} is the style being defined and \meta{text} is the LaTeX code +defining the style. + + As an example, here is the code for defining the \cstyle{section} chapter +style. +\begin{lcode} +\makechapterstyle{section}{% + \renewcommand{\printchaptername}{} + \renewcommand{\chapternamenum}{} + \renewcommand{\chapnumfont}{\chaptitlefont} + \renewcommand{\printchapternum}{\chapnumfont \thechapter\space} + \renewcommand{\afterchapternum}{} +} +\end{lcode} +In this style, \cmd{\printchaptername} is vacuous, so the normal `Chapter' +is never typeset. The same font is used for the number and the title, and +the number is typeset with a space after it. The macro \cmd{\afterchapternum} +is vacuous, so the chapter title will be typeset immediately after the number. + + In the standard classes the title of an unnumbered chapter is typeset +at the same position on the page as the word `Chapter' for numbered chapters. +The macro \cmd{\printchapternonum} is called just before an unnumbered +chapter title text is typeset. By default this does nothing but you can use +\cmd{\renewcommand} to change this. For example, if you wished the title +text for both numbered and unnumbered chapters to be at the same height on +the page then you could redefine \cmd{\printchapternonum} to insert +the amount of vertical space taken by any `Chapter N' line. + + Bastiaan Veelo +posted the code for a new chapter style to \pictt{} on 2003/07/22 under the +title \textit{[memoir] [contrib] New chapter style}. His code, which +I have slightly modified and changed the name to \cstyle{veelo}, +is below. I have also exercised editorial privilege on his comments. + +\begin{quote} + I thought I'd share a new chapter style to be used with the memoir class + The style is tailored for documents that are to be trimmed to a smaller + width. When the bound document is bent, black tabs will appear on the + fore side at the places where new chapters start as a navigational aid. + We are scaling the chapter number, which most DVI viewers + will not display accurately. \\[0.5\onelineskip] +Bastiaan. +\end{quote} + +\begin{lcode} +\makeatletter +\newlength{\numberheight} +\newlength{\barlength} +\makechapterstyle{veelo}{% + \setlength{\beforechapskip}{40pt} + \setlength{\midchapskip}{25pt} + \setlength{\afterchapskip}{40pt} + \renewcommand{\chapnamefont}{\normalfont\LARGE\flushright} + \renewcommand{\chapnumfont}{\normalfont\HUGE} + \renewcommand{\chaptitlefont}{\normalfont\HUGE\bfseries\flushright} + \renewcommand{\printchaptername}{% + \chapnamefont\MakeUppercase{\@chapapp}} + \renewcommand{\chapternamenum}{} + \setlength{\numberheight}{18mm} + \setlength{\barlength}{\paperwidth} + \addtolength{\barlength}{-\textwidth} + \addtolength{\barlength}{-\spinemargin} + \renewcommand{\printchapternum}{% + \makebox[0pt][l]{% + \hspace{.8em}% + \resizebox{!}{\numberheight}{\chapnumfont \thechapter}% + \hspace{.8em}% + \rule{\barlength}{\numberheight} + } + } + \makeoddfoot{plain}{}{}{\thepage} +} +\makeatother +\end{lcode} + +\makeatletter +\newlength{\numberheight} +\newlength{\barlength} +\makechapterstyle{veelo}{% + \setlength{\beforechapskip}{40pt} + \setlength{\midchapskip}{25pt} + \setlength{\afterchapskip}{40pt} + \renewcommand{\chapnamefont}{\normalfont\LARGE\flushright} + \renewcommand{\chapnumfont}{\normalfont\HUGE} + \renewcommand{\chaptitlefont}{\normalfont\HUGE\bfseries\flushright} + \renewcommand{\printchaptername}{% + \chapnamefont\MakeUppercase{\@chapapp}} + \renewcommand{\chapternamenum}{} + \setlength{\numberheight}{18mm} + \setlength{\barlength}{\paperwidth} + \addtolength{\barlength}{-\textwidth} + \addtolength{\barlength}{-\spinemargin} + \renewcommand{\printchapternum}{% + \makebox[0pt][l]{% + \hspace{.8em}% + \resizebox{!}{\numberheight}{\chapnumfont \thechapter}% + \hspace{.8em}% + \rule{\barlength}{\numberheight} + } + } + \makeoddfoot{plain}{}{}{\thepage} +} +\makeatother + + If you implement this you will also need to use the \Lpack{graphicx} +package~\cite{GRAPHICX} because of the \cmd{\resizebox} macro. +The \cstyle{veelo} style works best for chapters that start +on recto pages. + + For details of how the other chapter styles are defined, +look at the +documented class code. This should give you ideas if you want to define +your own style. + + Note that it is not necessary to define a new chapterstyle if you want +to change the chapter headings --- you can just change the individual macros +without putting them into a style. + +\index{chapterstyle|)} + +\section{Lower level headings} + +\index{heading!sections|(} + + The lower level headings --- sections down to subparagraphs --- are also +configurable, but there is nothing corresponding to chapter styles. + + There are essentially three things that may be adjusted for a heading: +(a) the vertical distance between the baseline of the text above the heading to +the baseline of the heading title, (b) the indentation of the heading from the +left hand margin\index{margin}, and (c) the style (font) used for the heading title. +Additionally, a heading may be runin to the text or as a display before +the following text; +in the latter case the vertical distance between the heading and the +following text may also be adjusted. Figure~\ref{fig:displaysechead} shows the +parameters controlling a displayed sectional heading and \fref{fig:runsechead} +shows the parameters for a runin heading. + + In the following I will use |S| to stand for one of |sec|, |subsec|, +|subsubsec|, |para| or |subpara|, which are in turn shorthand for |section| +through to |subparagraph|. + +\begin{figure} +\centering +\setlayoutscale{1} +\drawparameterstrue +\drawheading{} +\caption{Displayed sectional headings} \label{fig:displaysechead} +\end{figure} + +\begin{figure} +\centering +\setlayoutscale{1} +\drawparameterstrue +\runinheadtrue +\drawheading{} +\caption{Runin sectional headings} \label{fig:runsechead} +\end{figure} + +\begin{syntax} +\cmd{\setbeforeSskip}\marg{skip} \\ +\end{syntax} +The absolute value of the \meta{skip} length argument is the space to leave +above the heading. If the actual value is negative then the first line +after the heading will not be indented. The default \meta{skip} depends on the +particular level of heading, but for a \cmd{\section} (i.e., when |S = sec|) +it is +\begin{lcode} +-3.5ex plus -1ex minus -.2ex +\end{lcode} +where the plus and minus values are the +allowable stretch and shrink; note that all the values are negative so that +there is no indentation of the following text. If you wanted indentation then +you could do +\begin{lcode} +\setbeforesecskip{3.5ex plus 1ex minus .2ex} +\end{lcode} + + +\begin{syntax} +\cmd{\setSindent}\marg{length} \\ +\end{syntax} +The value of the \meta{length} length argument is the indentation of +the heading (number and title) from the lefthand margin\index{margin}. This is normally +0pt. + +\begin{syntax} +\cmd{\setSheadstyle}\marg{text} \\ +\end{syntax} +This macro specifies the style (font) for the sectional number and title. +As before, the default value of the \meta{text} argument depends on the +level of the heading. For a \cmd{\subsection} (i.e., |S=subsec|) it is +|\large\bfseries\raggedright|, to typeset in the \cmd{\bfseries} font +in the \cmd{\large} size; the title will also be set ragged right (i.e., +there will be no hyphenation in a multiline title). + + Note that the very last element in the \meta{text} argument may be a +macro that takes one argument (the number and title of the heading). So, +if for some reason you wanted \cmd{\subsubsection} titles to be all uppercase, +centered, and in the normal font, you can do +\begin{lcode} +\setsubsubsecheadtstyle{\normalfont\centering\MakeUppercase} +\end{lcode} + + As another example, although I don't recommend this, you can draw a +horizontal line under section titles via: +\begin{lcode} +\newcommand{\ruledsec}[1]{% + \Large\bfseries\raggedright #1 \rule{\textwidth}{0.4pt}} +\setsecheadstyle{\ruledsec} +\end{lcode} + + +\begin{syntax} +\cmd{\setafterSskip}\marg{skip} \\ +\end{syntax} +If the value of the \meta{skip} length argument is positive it is the space +to leave between the display heading and the following text. If it is negative, +then the heading will be runin and the value is the horizontal space +between the end of the heading and the following text. +The default \meta{skip} depends on the +particular level of heading, but for a \cmd{\section} (i.e., when |S = sec|) +it is |2.3ex plus .2ex|, +and for a \cmd{\subparagraph} (i.e., |S = subpara|), which is a runin heading, it is +|-1em|. + +\begin{syntax} +\cmd{\@hangfrom}\marg{stuff} \\ +\cmd{\sethangfrom}\marg{code} \\ +\end{syntax} +Internally all the titling macros use a macro called \cmd{\@hangfrom} which +by default makes multiline titles look like a hanging paragraph\index{paragraph!hanging}. The +default definition of \cmd{\@hangfrom} (in file \file{ltsect.dtx}) is +effectively: +\begin{lcode} +\newcommand{\@hangfrom}[1]{\setbox\@tempboxa\hbox{{#1}}% + \hangindent \wd\@tempboxa\noindent\box\@tempboxa} +\end{lcode} +The argument is put into a box and its width is measured, then a hanging +paragraph\index{paragraph!hanging} is started with the argument as the first thing and second and +later lines indented by the argument's width. + +The \cmd{\sethangfrom} macro redefines \cmd{\@hangfrom} to be \meta{code}. +For example, to have the titles set as block paragraphs\index{paragraph!block} instead of hanging +paragraphs\index{paragraph!hanging}, simply do: +\begin{lcode} +\sethangfrom{\noindent #1} +\end{lcode} +Note that you have to use |#1| at the position in the replacement +code for \cmd{\@hangfrom} where the argument to \cmd{\@hangfrom} +is to be located. + +\begin{syntax} +\cmd{\@seccntformat}\marg{stuff} \\ +\cmd{\setsecnumformat}\marg{code} \\ +\end{syntax} +Internally all the titling macros use a macro called \cmd{\@seccntformat} +which defines the formatting of sectional numbers in a title. Its +default definition (in file \file{ltsect.dtx}) is effectively: +\begin{lcode} +\newcommand{\@seccntformat}[1]{\csname the#1\endcsname\quad} +\end{lcode} +which formats the sectional numbers as |\thesec...| with a space afterwards. +The command \cmd{\setsecnumformat} redefines \cmd{\@seccntformat} +to be \meta{code}. +For example, to put a colon and space after the number +\begin{lcode} +\setsecnumformat{\csname the#1\endcsname:\quad} +\end{lcode} +Note that you have to use |#1| where you want the argument +(sectional number) of \cmd{\@seccntformat} to go. + +\begin{syntax} +\cmd{\hangsecnum} \\ +\cmd{\defaultsecnum} \\ +\end{syntax} +The macro \cmd{\hangsecnum} is a declaration that makes sectional numbers hang +in the margin\index{margin}. The macro \cmd{\defaultsecnum} is a declaration that reverses the +effect of \cmd{\hangsecnum}, that is, sectional numbers will be typeset in +their familiar places. + + +\begin{syntax} +\cmd{\Shook} \\ +\cmd{\setShook}\marg{text} \\ +\end{syntax} +The macro \cmd{\Shook} is called immediately before the typesetting of the +title; its default definition does nothing. The macro \cmd{\setShook} +redefines \cmd{\Shook} to be \meta{text}. You can use this hook, for example, +to insert a \cmd{\sethangfrom} or \cmd{\setsecnumformat} command into the +definition of a particular section division command. + +\index{heading!sections|)} + +\section{Heading styles for this chapter} + + As a reference, \tref{tab:secfonts} lists the default fonts used +for the sectional headings. These fonts are all bold but in different +sizes depending on the division level. + +\begin{table} +\centering +\caption{Default fonts for sectional headings}\label{tab:secfonts} +\begin{tabular}{ll} \hline +\cmd{\partnamefont} & |\huge\bfseries| \\ +\cmd{\partnumfont} & |\huge\bfseries| \\ +\cmd{\parttitlefont} & |\Huge\bfseries| \\ +\cmd{\chapnamefont} & |\normalfont\huge\bfseries| \\ +\cmd{\chapnumfont} & |\normalfont\huge\bfseries| \\ +\cmd{\chaptitlefont} & |\normalfont\Huge\bfseries| \\ +\cmd{\secheadstyle} & |\Large\bfseries\raggedright| \\ +\cmd{\subsecheadstyle} & |\large\bfseries\raggedright| \\ +\cmd{\subsubsecheadstyle} & |\normalsize\bfseries\raggedright| \\ +\cmd{\paraheadstyle} & |\normalsize\bfseries| \\ +\cmd{\subparaheadstyle} & |\normalsize\bfseries| \\ +\hline +\end{tabular} +\end{table} + +\index{heading!chapter|(} +\index{chapterstyle|(} + + The commands described below have been put just before the start +of this chapter. + + For this chapter I have used sans fonts instead of bold fonts. The +commands to do this are shown below for chapters down to subsubsections. +\begin{lcode} +\renewcommand{\chapnumfont}{\normalfont\huge\sffamily} +\renewcommand{\chaptitlefont}{\chapnumfont} +\setsecheadstyle{\Large\sffamily\raggedright} +\setsubsecheadstyle{\large\sffamily\raggedright} +\setsubsubsecheadstyle{\normalsize\sffamily\raggedright} +\end{lcode} + + The chapter heading is typeset like a section heading. I redefine +\cmd{\printchaptername} and \cmd{\chapternamenum} to do nothing, which +eliminates the printing of the chapter name and also anything +that may be between the name and the number. Changing \cmd{\afterchapternum} +to be just \cmd{\space} eliminates the vertical space that is normally +between the number and the title, and instead puts a normal word space +between the number and the title. +\begin{lcode} +\renewcommand{\printchaptername}{} +\renewcommand{\chapternamenum}{} +\renewcommand{\afterchapternum}{\space} +\end{lcode} + + Before the next chapter starts, I want to revert back to the default +divisional styles, so the following code is used at the end of +this chapter. +\begin{lcode} +\chapterstyle{default} +\setsecheadstyle{\Large\bfseries\raggedright} +\setsubsecheadstyle{\large\bfseries\raggedright} +\setsubsubsecheadstyle{\normalsize\bfseries\raggedright} +\end{lcode} +Calling |\chapterstyle{default}| deals with the chapter heading. The other +commands change the lower level fonts back to their default values. + + +\index{chapterstyle|)} +\index{heading!chapter|)} + +\section{Footnotes and headers} + +\index{footnote!in heading|(} + + With the sectioning commands the text of the required argument +\meta{title} is used as the text for the section title in the body +of the document. + + When the optional argument \meta{toc-title} is used in a sectioning +command it is moving and any fragile commands must be \cmd{\protect}ed, +while the \meta{title} argument is fixed. The \meta{toc-title} also +serves double duty: +\begin{enumerate} +\item It is used as the text of the title in the \toc; +\item It is used as the text in page headers\index{header}. +\end{enumerate} + + If the optional argument is not present, then the \meta{title} is +moving and serves the triple duty of providing the text for the body and \toc{} +titles and for page headers\index{header}. + + Some folk feel an urge to add a footnote\index{footnote} to a sectional title, which +should be resisted. If their flesh is weak, then the optional argument must +be used and the \cmd{\footnote} attached to the required argument only. +If the optional argument is not used then the footnote mark\index{footnote!mark} and text is +likely to be scattered all over the place, on the section page, in the \toc, +on any page that includes \meta{title} in its header\index{header}. This is +unacceptable to any reader. So, a footnoted\index{footnote} title should look like +this: +\begin{lcode} +\chapter[Title text]{Title text\footnote{Do you really have to do this?}} +\end{lcode} + +\index{footnote!in heading|)} + + +\section{Pagination and folios} + + Every page in a LaTeX document is included in the +pagination\index{pagination}. That is, +there is a number associated with every page and this is the value of +the \Icn{page} counter. This value can be changed at any time via either +\cmd{\setcounter} or \cmd{\addtocounter}. + +\begin{syntax} +\cmd{\pagenumbering}\marg{num-style} \\ +\cmd{\pagenumbering*}\marg{num-style} \\ +\end{syntax} +The macros \cmd{\pagenumbering} and \cmd{\pagenumbering*} cause +the folios\index{folio} to be printed using +\meta{num-style} for the page number, where \meta{num-style} can be one of: +\Itt{Alph}, \Itt{alph}, \Itt{arabic}, \Itt{Roman} or +\Itt{roman} for uppercase and lowercase letters, arabic numerals, and +uppercase and lowercase Roman numerals, respectively. As there +are only 26~letters, \Itt{Alph} or \Itt{alph} can only be +used for a limited number of pages. Effectively, the macros redefine +\cmd{\thepage} to be |\num-style{page}|. +Additionally, the \cmd{\pagenumbering} +command resets the \Icn{page} counter to one; the starred version does not +change the counter. + + It is usual to reset the page number back to one each time the style +is changed, but sometimes it may be desireable to have a continuous sequence +of numbers irrespective of their displayed form, which is where +\cmd{\pagenumbering*} comes in handy. + +\begin{syntax} +\cmd{\savepagenumber} \\ +\cmd{\restorepagenumber} \\ +\end{syntax} +The macro \cmd{\savepagenumber} saves the current page number, and the +macro \cmd{\restorepagenumber} sets the page number to the saved value. +This pair of commands may be used to apparently interrupt the pagination. +For example, perhaps some full page illustrations\index{illustration} will be electronically, +as opposed to physically, +tipped in\index{tip in} to the document and pagination is not required for these. +This could be done along the lines of: +\begin{lcode} +\clearpage % get onto next page +\savepagenumber % save the page number +\pagestyle{empty} % no headers or footers +%% insert the illustrations +\clearpage +\pagestyle{...} +\restorepagenumber +... +\end{lcode} +If you try this sort of thing, you may have to adjust the restored page +number by one. +\begin{lcode} +\restorepagenumber +% perhaps \addtocounter{page}{1} or \addtocounter{page}{-1} +\end{lcode} +Whether or not this will be necessary depends on the timing of the +|\...pagenumber| commands and TeX's decisions on page breaking. + + + + + + + + + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\chapterstyle{default} +\setsecheadstyle{\Large\bfseries\raggedright} +\setsubsecheadstyle{\large\bfseries\raggedright} +\setsubsubsecheadstyle{\normalsize\bfseries\raggedright} +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + + + +\chapter{Paragraphs and lists} + +%%%%%%%%%%%%%%%%%%%%% +\tightlists +%%%%%%%%%%%%%%%%%%%%% + + This chapter is typeset with the default sectional +headings\index{heading!default}. + +\section{Introduction} + + Within a sectional division the text is typically broken up into +paragraphs. Sometimes there may be text that is set off from the normal +paragraphing, like quotations\index{quotation} or lists. + +\section{Paragraphs} + +\index{paragraph|(} + + There are basically two parameters that control the appearance of normal +paragraphs. + +\begin{syntax} +\lnc{\parindent} \lnc{\parskip} \\ +\end{syntax} + + The length \lnc{\parindent} is the indentation of the first line of a +paragraph\index{paragraph!indentation} and the length \lnc{\parskip} is the vertical spacing between +paragraphs, as illustrated in \fref{fig:para}. The value of \lnc{\parskip} +is usually 0pt, and \lnc{\parindent} is usually defined in terms of ems so +that the actual indentation depends on the font being used. If \lnc{\parindent} +is set to a negative length, then the first line of the paragraphs will be +`outdented' into the lefthand margin\index{margin}. + +\begin{figure} +\centering +\drawparameterstrue +\drawparagraph +\caption{Paragraphing parameters}\label{fig:para} +\end{figure} + + A block paragraph\index{paragraph!block} is obtained by setting \lnc{\parindent} to 0em; +\lnc{\parskip} should be set to some positive value so that there is some +space between paragraphs to enable them to be identified. Most typographers +heartily dislike block paragraphs, not only on aesthetical grounds but also +on practical grounds. Consider what happens if the last line of a block +paragraph is full and also is the last line on the page. The following +block paragraph will start at the top of the next page but there will be +no identifiable space to indicate an inter-paragraph break. + + It is important to know that LaTeX typesets paragraph by paragraph. +For example, the \lnc{\baselineskip} that is used for a paragraph is the value +that is in effect at the end of the paragraph, and the font size used for a +paragraph is according to the size declaration (e.g., \cmd{\large} or +\cmd{\normalsize} or \cmd{\small}) in effect at the end of the paragraph. + +\subsection{Hanging paragraphs} + +\index{paragraph!hanging|(} + + A hanging paragraph is one where the length of the first few lines differs +from the length of the remaining lines. (A normal indented paragraph +may be considered +to be a special case of a hanging paragraph where `few = one'). + +\begin{syntax} +\cmd{\hangpara}\marg{indent}\marg{num} \\ +\end{syntax} + +\hangpara{3em}{-3}% + Using \cmd{\hangpara} at the start of a paragraph will cause the paragraph +to be hung. If the length \meta{indent} is positive the lefthand end of the +lines will be indented but if it is negative the righthand ends will be +indented by the specified amount. + If the number \meta{num}, say N, is is negative the first N lines of +the paragraph will be indented while if N is positive the N+1 th lines onwards +will be indented. This paragraph was set with |\hangpara{3em}{-3}|. There +should be no space between the \cmd{\hangpara} command and the start of the +paragraph. + +\begin{syntax} +\senv{hangparas}\marg{indent}\marg{num} text \eenv{hangparas} \\ +\end{syntax} + The \Ie{hangparas} environment is like the \cmd{\hangpara} command except +that every paragraph in the environment will be hung. + + The code implementing the hanging paragraphs is the same as for +the \Lpack{hanging} package~\cite{HANGING}. Examples of some uses +can be found in~\cite{TTC199}. + + + As noted eleswhere the sectioning commands use the internal +macro \cmd{\@hangfrom} as part of the formatting of the titles. + +\begin{syntax} +\cmd{\hangfrom}\marg{text} \\ +\end{syntax} + +\hangfrom{Simple hung paragraphs }(like this one) can be specified +using the \cmd{\hangfrom} macro. The macro puts \meta{text} in a box +and then makes a hanging paragraph of the following material. This +paragraph commenced with \\ +\verb?\hangfrom{Simple hung paragraphs }(like ...? \\ +and you are now reading the result. + + +\index{paragraph!hanging|)} + +\index{paragraph|)} + +\section{Flush and ragged} + + Flushleft\index{flushleft} text has the lefthand end of the lines +aligned vertically at the lefthand margin\index{margin} and +flushright\index{flushright} text has the righthand end of the lines +aligned vertically at the righthand margin\index{margin}. The +opposites of these are raggedleft\index{raggedleft} text where the +lefthand ends are not aligned +and raggedright\index{raggedright} where the righthand end of lines are +not aligned. LaTeX normally typesets flushleft and flushright. + +\begin{syntax} +\senv{flushleft} text \eenv{flushleft} \\ +\senv{flushright} text \eenv{flushright} \\ +\senv{center} text \eenv{center} \\ +\end{syntax} + Text in a \Ie{flushleft} environment is typeset flushleft and raggedright, +while in a \Ie{flushright} environment is typeset raggedleft and flushright. +In a \Ie{center} environment the text is set raggedleft and raggedright, and each +line is centered. A small vertical space is put before and after each of these +environments. + +\begin{syntax} +\cmd{\raggedleft} \cmd{\raggedright} \cmd{\centering} \\ +\end{syntax} + The \cmd{\raggedleft} declaration can be used to have text typeset +raggedleft and flushright, and similary the declaration \cmd{\raggedright} +causes typesetting to be flushleft and raggedright. The declaration +\cmd{\centering} typesets raggedleft and raggedright with each line centered. +Unlike the environments, no additional space is added. + +\begin{syntax} +\cmd{\raggedyright}\oarg{space} \\ +\lnc{\ragrparindent} \\ +\end{syntax} +When using \cmd{\raggedright} in narrow columns the right hand edge tends to +be too ragged, and paragraphs are not indented. +Text set \cmd{\raggedyright} usually fills more of the available +width and paragraphs are indented by \lnc{\ragrparindent}, which is initially +set to \lnc{\parindent}. The optional \meta{space} argument, whose default +is 2em, can be used to adjust the amount of raggedness. As examples: +\begin{lcode} +\raggedyright[0pt] % typeset flushright +\raggedyright[1fil] % same as \raggedright +\raggedyright[0.5em] % less ragged than \raggedright +\end{lcode} + + Remember that LaTeX typesets on a per-paragraph basis, so that putting +the sequence of \cmd{\centering}, \cmd{\raggedleft} declarations in the same +paragraph\index{paragraph} will cause the entire paragraph to be typeset raggedleft and +flushright --- the \cmd{\centering} declaration is not the one in effect +at the end of the paragraph. + +\section{Quotations} + + LaTeX provides two environments that are typically used for typesetting +quotations\index{quotation}. + +\begin{syntax} +\senv{quote} text \eenv{quote} \\ +\senv{quotation} text \eenv{quotation} \\ +\end{syntax} + In both of these environments the text is set flushleft and flushright +in a measure that is smaller than the normal textwidth. The only difference +between the two environments is that paragraphs\index{paragraph!indentation} are not indented in the \Ie{quote} +environment but normal paragraphing is used in the \Ie{quotation} environment. + +\section{Changing the textwidth} + + The \Ie{quote} and \Ie{quotation} environments both locally change the textwidth, +or more precisely, they temporarily increase the left and right margins\index{margin} by +equal amounts. +Generally speaking it is not a good idea to change the textwidth but sometimes +it may be called for. + + The commands and environment described below are similar to those +in the \Lpack{chngpage} package~\cite{CHNGPAGE}, but do differ in some +respects. + +\begin{syntax} +\senv{adjustwith}\marg{left}\marg{right} text \eenv{adjustwith} \\ +\senv{adjustwith*}\marg{left}\marg{right} text \eenv{adjustwith*} \\ +\end{syntax} +The \Ie{adjustwidth} environment temporarily adds the length \meta{left} +to the lefthand margin\index{margin} and \meta{right} to the righthand margin\index{margin}. That is, +a positive length value increases the margin\index{margin} and hence reduces the textwidth, +and a negative value reduces the margin\index{margin} and increases the textwidth. The +\Ie{quotation} environment is roughly equivalent to +\begin{lcode} +\begin{adjustwidth}{2.5em}{2.5em} +\end{lcode} + + The starred version of the environment, \Ie{adjustwidth*}, + is only useful if the left and right +margin\index{margin} adjustments are different. The starred version checks the page number +and if it is odd then adjusts the left (spine) and right (outer) margins\index{margin} +by \meta{left} and \meta{right} respectively; if the page number is even +(a verso page) it adjusts the left (outer) and right (spine) margins\index{margin} by +\meta{right} and \meta{left} respectively. + +\begin{syntax} +\cmd{\strictpagechecktrue} \cmd{\strictpagecheckfalse} \\ +\end{syntax} +Odd/even page checking may be either strict (\cmd{\strictpagechecktrue}) +or lazy (\cmd{\strictpagecheckfalse}). Lazy checking works most of the time +but if it fails at any point then the strict checking should be used. + + As an example, if a figure\index{figure} is wider than the textwidth it will stick out +into the righthand margin\index{margin}. It may be desireable to have any wide figure\index{figure} +stick out into the \foredge{} margin\index{margin} where there is usually more room than at +the spine margin\index{margin}. This can be accomplished by +\begin{lcode} +\begin{figure} +\centering +\strictpagechecktrue +\begin{adjustwidth*}{0em}{-3em} +% the illustration +\caption{...} +\end{adjustwidth*} +\end{figure} +\end{lcode} + + A real example in this manual is \tref{tab:fpp} on \pref{tab:fpp}, +which is wider than the typeblock\index{typeblock}. In that case I just centered it by +using \Ie{adjustwidth} to decrease each margin\index{margin} equally. In brief, like +\begin{lcode} +\begin{table} +\begin{adjustwidth}{-1cm}{-1cm} +\centering +... +\end{adjustwidth} +\end{table} +\end{lcode} + + Note that the \Ie{adjustwidth} environment applies to complete paragraphs; +you can't change the width of part of a paragraph\index{paragraph} +except for hanging paragraphs\index{paragraph!hanging} or more esoterically via \cmd{\parshape}. +Further, if the adjusted paragraph crosses a +page boundary the margin\index{margin} changes are constant; a paragraph that is, say, +wider at the right on the first page will also be wider at the right as it +continues onto the following page. + + The \Ie{center} environment horizontally centers its contents +with respect to the typeblock\index{typeblock}. +Sometimes you may wish to horizontally center some text with respect +to the physical page, for example when typesetting a +colophon\index{colophon} which may look odd centered with respect +to the (unseen) typeblock\index{typeblock}. + + The calculation of the necessary changes to the spine and \foredge{} +margins\index{margin} are simple. Using the same symbols as earlier in +\S\ref{sec:typeblock2} ($P_{w}$ and +$B_{w}$ are the width of the trimmed page and the typeblock\index{typeblock}, respectively; +$S$ and $E$ are the spine and \foredge{} margins\index{margin}, respectively) then +the amount $M$ to be added to the spine margin\index{margin} and subtracted from the +\foredge{} margin\index{margin} is calculated as: +\begin{displaymath} + M = 1/2(P_{w} - B_{w}) - S +\end{displaymath} + +For example, +assume that the \lnc{\textwidth} is 5 inches and the \lnc{\spinemargin} +is 1 inch. On US letterpaper\index{paper!size!letterpaper} (\lnc{\paperwidth} is 8.5 inches) the +\foredge{} margin\index{margin} is then 2.5 inches, and 0.75 inches\footnote{On A4\index{paper!size!A4} +paper the result would be different.} must +be added to the spine margin\index{margin} and subtracted from the \foredge{} to +center the typeblock\index{typeblock}. +The \Ie{adjustwidth} environment can be used to make the (temporary) change. +\begin{lcode} +\begin{adjustwidth*}{0.75in}{-0.75in} ... +\end{lcode} + +\begin{syntax} +\cmd{\calccentering}\marg{length} \\ +\end{syntax} + If you don't want to do the above calculations by hand, +\cmd{\calccentering} will do it for you. +The \meta{length} +argument must be the name of a pre-existing length command, +including the backslash. After calling +|\calccentering|, \meta{length} is the amount to be added to the +spine margin\index{margin} and subtracted from the foredge margin\index{margin} to center the typeblock\index{typeblock}. +An example usage is +\begin{lcode} +\calccentering{\mylength} +\begin{adjustwidth*}{\mylength}{-\mylength} +text horizontally centered on the physical page +\end{adjustwidth*} +\end{lcode} + + You do not necessarily have to define a new length for the purposes +of \cmd{\calccentering}. Any existing length will do, such as +\lnc{\unitlength}, provided it will be otherwise unused between performing +the calculation and changing the margins\index{margin} (and that you can, if necessary +reset it to its original value --- the default value for \lnc{\unitlength} +is 1pt). + +\section{Lists} + +\index{list|(} + + Standard LaTeX provides 4 kinds of lists. There is a general \Ie{list} +environment which you can use to define your own particular kind of list, +and the \Ie{description}, \Ie{itemize} and \Ie{enumerate} lists (which are internally +defined in terms of the general \Ie{list} environment). + + This class provides the normal \Ie{description} list but the \Ie{itemize} and +\Ie{enumerate} lists are extended versions of the normal ones. + +\begin{syntax} +\senv{description} \cmd{\item}\oarg{label} ... \eenv{description} \\ +\cmd{\descriptionlabel}\meta{style} \\ +\end{syntax} +In a \Ie{description} list the style of the \meta{label} is given by the +\meta{style} argument of the \cmd{\descriptionlabel} command. The default +definition is +\begin{lcode} +\newcommand*{\descriptionlabel}[1]{\hspace\labelsep + \normalfont\bfseries #1} +\end{lcode} +which gives a bold label. To have, for example, a sans label instead, do +\begin{lcode} +\renewcommand*{\descriptionlabel}[1]{\hspace\labelsep + \normalfont\sffamily #1} +\end{lcode} + + The \Ie{itemize} and \Ie{enumerate} environments below are based on +the \Lpack{enumerate} package~\cite{ENUMERATE}. + +\begin{syntax} +\senv{itemize}\oarg{mark} \cmd{\item} ... \eenv{itemize} \\ +\end{syntax} +The normal markers for \cmd{\item}s in an \Ie{itemize} list are: +\begin{enumerate} +\item bullet (\textbullet |\textbullet|), +\item bold en-dash ({\normalfont\bfseries \textendash} |\bfseries\textendash|), +\item centered asterisk (\textasteriskcentered |\textasteriskcentered|), and +\item centered dot (\textperiodcentered |\textperiodcentered|). +\end{enumerate} +The optional \meta{mark} argument can be used to specify the marker for the +list items in a particular list. If for some reason you wanted to use a +pilcrow symbol as the item marker for a particular list you could do +\begin{lcode} +\begin{itemize}[\P] +\item ... +... +\end{lcode} + + + +\begin{syntax} +\senv{enumerate}\oarg{style} \cmd{\item} ... \eenv{enumerate} \\ +\end{syntax} +The normal markers for, say, the third item in an \Ie{enumerate} list are: +3., c., iii., and C. The optional \meta{style} argument can be used to +specify the style used to typeset the item counter. An occurrence of +one of the special characters |A|, |a|, |I|, |i| +or |1| in \meta{style} specifies that the counter will be typeset using +uppercase letters (|A|), lowercase letters (|a|), +uppercase Roman numerals (|I|), +lowercase Roman numerals (|i|), or arabic numerals (|1|). These characters +may be surrounded by any LaTeX commands or characters, but if so the special +characters must be put inside braces (e.g., |{a}|) if they are to be +considered as ordinary characters instead of as special styling characters. + For example, to have the +counter typeset as a lowercase Roman numeral followed by a single parenthesis +\begin{lcode} +\begin{enumerate}[i)] +... +\end{lcode} + +\index{list!tight|(} + +\begin{syntax} +\cmd{\tightlists} \cmd{\defaultlists} \\ +\end{syntax} +The normal LaTeX \Ie{description}, \Ie{itemize} and \Ie{enumerate} lists have an open +look about them when they are typeset as there is significant vertical space +between the items in the lists. After the declaration \cmd{\tightlists} is +issued, the extra vertical spacing between the list items is deleted. The open +list appearance is used after the \cmd{\defaultlists} declaration is issued. +These declarations, if used, must come \emph{before} the relevant list +environment(s). + + The class initially sets \cmd{\defaultlists}. If you had noticed that +the lists in this chapter have a different appearance than those in earlier +chapters (or even if you hadn't noticed) then that is because +the declaration \cmd{\tightlists} was put at the start of this chapter. + +\begin{syntax} +\cmd{\firmlist} \cmd{\tightlist} \\ +\end{syntax} +The command \cmd{\firmlist} or \cmd{\tightlist} can be used immediately +after the start of a list environment to reduce the vertical space within +that list. The \cmd{\tightlist} removes all the spaces while the +\cmd{\firmlist} produces a list that still has some space but not as much +as in an ordinary list. + +\index{list!tight|)} + + +\begin{figure} +\centering +\drawparameterstrue +\drawlist +\caption{The layout parameters for general lists}\label{fig:listlay} +\end{figure} + +\index{list!new|(} + +\begin{syntax} +\senv{list}\marg{default-label}\marg{code} items \eenv{list} \\ +\end{syntax} +LaTeX's list environments are defined in terms of a general \Ie{list} +environment; some other environments, such as the \Ie{quote}, \Ie{quotation} +and \Ie{adjustwidth} are also defined in terms of a \Ie{list}. +Figure~\ref{fig:listlay} shows the parameters controlling the layout +of the \Ie{list} environment. + + The \Ie{list} environment takes two arguments. The \meta{default-label} +argument is the code that should be used when the \cmd{\item} macro is +used without its optional \meta{label} argument. For lists like \Ie{enumerate} +this is specified but often it is left empty, such as for the \Ie{adjustwidth} +environment. + + The \meta{code} argument is typically used for setting the particular +values of the list layout parameters. When defining your own types of lists +it is advisable to set each of the parameters unless you know that the default +values are suitable for your purposes. These parameters can all be modified +with either the \cmd{\setlength} or \cmd{\addtolength} commands. + + As an example, here is the specification for a description-like list +that uses an italic rather than bold font for the items, and is somewhat +tighter than the normal \Ie{description} list. + +\begin{lcode} +%%%%% An italic and tighter description environment +\newcommand{\itlabel}[1]{\hspace\labelsep\normalfont\itshape #1} +\newenvironment{itdesc}{% + \list{}{% + \setlength{\labelsep}{0.5em} + \setlength{\itemindent}{0pt} + \setlength{\leftmargin}{\parindent} + \setlength{\labelwidth}{\leftmargin} + \addtolength{\labelwidth}{-\labelsep} + \setlength{\listparindent}{\parindent} + \setlength{\parsep}{\parskip} + \setlength{\itemsep}{0.5\onelineskip} + \let\makelabel\itlabel}}{\endlist} +\end{lcode} + + This gets used like any other list: +\begin{lcode} +\begin{itdesc} +\item[label] .... +\end{itdesc} +\end{lcode} + +Here is another kind of list called \Ie{aglossary} that could be used for +a glossary or other similar kind of listing. +\begin{lcode} +% Glossary list +\newenvironment{aglossary}% + {\begin{list}{}% empty label + {\setlength{\topsep}{\baselineskip} + \setlength{\partopsep}{0pt} + \setlength{\itemsep}{0.5\baselineskip} + \setlength{\parsep}{0pt} + \setlength{\leftmargin}{2em} + \setlength{\rightmargin}{0em} + \setlength{\listparindent}{1em} + \setlength{\itemindent}{0em} + \setlength{\labelwidth}{0em} + \setlength{\labelsep}{2em}}}% + {\end{list}} +\newcommand{\gloss}[1]{\item[#1]\mbox{}\\\nopagebreak} +\end{lcode} +In this case it gets used like this +\begin{lcode} +\begin{aglossary} +\gloss{TERM 1} definition +\gloss{TERM 2} ... +\end{aglossary} +\end{lcode} + +\index{list!new|)} + +\begin{syntax} +\cmd{\zerotrivseps} \cmd{\restoretrivseps} \cmd{\savetrivseps} \\ +\end{syntax} +Several environments, such as \Ie{center}, are defined in terms of a +\Ie{trivlist} (a very simple list form). There is vertical space +before and after such an environment. If you don't want this, then +the declaration \cmd{\zerotrivseps} eliminates such spaces. You can think +of it being defined like: +\begin{lcode} +\newcommand*{\zerotrivseps}{% + \setlength{\topsep}{0pt}% + \setlength{\partopsep}{0pt}} +\end{lcode} +To restore the spacing call the \cmd{\restoretrivseps} declaration. +The command \cmd{\savetrivseps} stores the \lnc{\topsep} and +\lnc{\partopsep} values, and \cmd{\restoretrivseps} sets them to +whatever values were stored. The class itself calls \cmd{\savetrivseps} +to keep the default values. + + + +\index{list|)} + + + +%%%%%%%%%%%%%%%%%%%%%%%%%% +\chapterstyle{section} +%%%%%%%%%%%%%%%%%%%%%%%%%% +\chapter{Tops and tails} \label{chap:topsandtails} + +This chapter uses the \cstyle{section} chapterstyle. + + \section{Introduction} + + The following discussions are focussed on the elements at the start +and end of a document; the Table of Contents at the start and the Index\index{index} +at the end. + The functionality described is equivalent to the combination +of the \Lpack{tocloft} and \Lpack{tocbibind} +packages~\cite{TOCLOFT,TOCBIBIND} + + In the standard classes the typographic design of the Table of Contents + (\toc), the List of Figures (\lof) and List of Tables (\lot) is fixed or, + more precisely, it is buried within the class definitions. + + \section{LaTeX's \prtoc{} methods} + + This is a general description of how LaTeX does the processing + for a Table of Contents (\toc). As the processing for List of Figures +(\lof) and + List of Tables (\lot) is similar I will just + discuss the \toc. + + First of all, remember that each sectional division has an +associated level as listed in \tref{tab:seclevels} on +\pref{tab:seclevels}. LaTeX will not typeset an entry in the \toc{} +unless the value of the \Icn{tocdepth} counter is equal to or greater +than the level of the entry. + +\begin{syntax} +\cmd{\maxtocdepth}\marg{secname} \\ +\cmd{\settocdepth}\marg{secname} \\ +\end{syntax} +The \Lclass{memoir} class \cmd{\maxtocdepth} command sets the maximum +allowable value +for the \Icn{tocdepth} counter. If used, the command must appear +before the \cmd{\tableofcontents} command. By default, the class +sets |\maxtocdepth{section}|. + + The \Lclass{memoir} class command \cmd{\settocdepth} is somewhat +analagous to the \cmd{\setsecnumdepth} command +described in \S\ref{sec:secnumbers}. +It sets the value of the \Icn{tocdepth} counter and puts it into +the \toc{} to (temporarily) modify what will appear. +The command can only be used after the preamble\index{preamble} +but may be used before calling the \cmd{\tableofcontents}. +The \cmd{\settocdepth} and \cmd{\maxtocdepth} macros are from the +\Lpack{tocvsec2} package~\cite{TOCVSEC2}. + +\begin{syntax} +\cmd{\addcontentsline}\marg{file}\marg{kind}\marg{text} \\ +\end{syntax} + LaTeX generates a \file{.toc} file if the document contains a + \cmd{\tableofcontents} command. The sectioning + commands\footnote{For figures and tables it is the +%% \texttt{\bs caption} command + \cmd{\caption} command + that populates the \file{.lof} and \file{.lot} files.} + put entries into the \file{.toc} file by calling the LaTeX + \cmd{\addcontentsline} + command, where \meta{file} is the file extension (e.g., |toc|), + \meta{kind} is the kind of entry (e.g., |section| or |subsection|), + and \meta{text} is the (numbered) title text. In the cases where + there is a number, the \meta{title} argument is given in the + form |{\numberline{number} title-text}|. + +\begin{syntax} +\cmd{\phantomsection} \\ +\end{syntax} +\Note{} The \Lpack{hyperref} package~\cite{HYPERREF} appears to dislike +authors using + \cmd{\addcontentsline}. To get it to work properly with \Lpack{hyperref} + you normally have to put \cmd{\phantomsection} (a macro defined within +this class and the \Lpack{hyperref} package) immediately + before \cmd{\addcontentsline}. + +\begin{syntax} +\cmd{\contentsline}\marg{kind}\marg{text}\marg{page} \\ +\end{syntax} + The \cmd{\addcontentsline} command writes an entry to the given file + in the form: \\ + \cmd{\contentsline}\marg{kind}\marg{text}\marg{page} \\ + where \meta{page} is the page number. + For each \meta{kind}, LaTeX provides a command: \\ + \cmd{\l@kind}\marg{title}\marg{page} \\ +which performs the actual + typesetting of the \cmd{\contentsline} entry. + + +\begin{figure} +\setlayoutscale{0.8} +\drawtoc +\caption{Layout of a \prtoc{} (\prlof, \prlot) entry} \label{fig:ltoc} +\end{figure} + + +\begin{syntax} +\cmd{\@pnumwidth}\marg{length} \\ +\cmd{\@tocrmarg}\marg{length} \\ +\cmd{\@dotsep}\marg{number} \\ +\end{syntax} + The general layout of a + typeset entry is illustrated in \fref{fig:ltoc}. There are three + internal LaTeX commands that are used in the typesetting. The page + number is typeset flushright in a box of width \cmd{\@pnumwidth}, and the box + is at the righthand margin\index{margin}. If the page number is too long to fit into + the box it will stick out into the righthand margin\index{margin}. The title text + is indented from the righthand margin\index{margin} by an amount given by \cmd{\@tocrmarg}. + Note that \cmd{\@tocrmarg} should be greater than \cmd{\@pnumwidth}. Some + entries are typeset with a dotted leader between the end of the title + title text and the righthand margin\index{margin} indentation. The distance, in + \emph{math units}\footnote{There are 18mu to 1em.} between the dots + in the leader is given by the value of \cmd{\@dotsep}. In the standard + classes the same values are used for the \toc, \lof{} and the \lot. + + The standard values for these internal commands are: + \begin{itemize} + \item |\@pnumwidth| = 1.55em + \item |\@tocrmarg| = 2.55em + \item |\@dotsep| = 4.5 + \end{itemize} + The values can be changed by using \cmd{\renewcommand}, in spite of the + fact that the first two appear to be lengths. + + Dotted leaders are not available for Part\index{part} and Chapter\index{chapter} \toc{} entries + +\begin{syntax} +\cmd{\numberline}\marg{number} \\ +\end{syntax} + Each \cmd{\l@kind} macro is responsible for setting the general + \textit{indent} from the lefthand margin\index{margin}, and the \textit{numwidth}. + The \cmd{\numberline} macro is responsible for typesetting + the number flushleft in a box of width + \textit{numwidth}. If the number is too long for the box then it will + protrude into the title text. The title text is indented by + (\textit{indent + numwidth}) from the lefthand margin\index{margin}. That is, the title + text is typeset in a block of width \\ + (|\linewidth| - \textit{indent} - \textit{numwidth} - |\@tocrmarg|). + + \begin{table} + \centering + \caption[Indents and Numwidths]{Indents and Numwidths (in ems)} \label{tab:indents} + \begin{tabular}{lcrrrr} \hline + Entry & Level & \multicolumn{2}{c}{Standard} & \multicolumn{2}{c}{\Lclass{memoir} class} \\ + & & indent & numwidth & indent & numwidth \\ \hline + part & -1 & 0 & --- & 0 & --- \\ + chapter & 0 & 0 & 1.5 & 0 & 1.5 \\ + section & 1 & 1.5 & 2.3 & 1.5 & 2.3 \\ + subsection & 2 & 3.8 & 3.2 & 3.8 & 3.2 \\ + subsubsection & 3 & 7.0 & 4.1 & 7.0 & 4.1 \\ + paragraph & 4 & 10.0 & 5.0 & 10.0 & 5.0 \\ + subparagraph & 5 & 12.0 & 6.0 & 12.0 & 6.0 \\ + figure/table & (1) & 1.5 & 2.3 & 0 & 1.5 \\ + subfigure/table & (2) & ---& ---& 1.5 & 2.3 \\ +\hline + \end{tabular} + \end{table} + + Table~\ref{tab:indents} lists the standard values for the \textit{indent} + and \textit{numwidth}. There is no explicit \textit{numwidth} for a + part\index{part}; instead a gap of 1em is put between the number and the title text. + Note that for a sectioning command the values + depend on whether or not the document class provides the \cmd{\chapter} + command. Also, which somewhat surprises me, the table\index{table} and figure\index{figure} entries + are all indented. + +\begin{syntax} +\cmd{\@dottedtocline}\marg{level}\marg{indent}\marg{numwidth} \\ +\end{syntax} + Most of the |\l@kind| commands are defined in terms of the + \cmd{\@dottedtocline} command. This command takes three arguments: +the \meta{level} argument is the level as shown in \tref{tab:indents}, +and \meta{indent} and \meta{numwidth} are the \textit{indent} and +\textit{numwidth} as illustrated in \fref{fig:ltoc}. + For example, one definition of the |\l@section| command is: \\ + |\newcommand*{\l@section}{\@dottedtocline{1}{1.5em}{2.3em}}| \\ + If it is necessary to change the default typesetting of the entries, + then it is usually necessary to change these definitions, but this +class gives you handles to easily alter things without + having to know the LaTeX internals. + + You can use the \cmd{\addcontentsline} command to add +\cmd{\contentsline} commands to a file. + +\begin{syntax} +\cmd{\addtocontents}\marg{file}\marg{text} \\ +\end{syntax} + LaTeX also provides the \cmd{\addtocontents} + command that will insert \meta{text} into \meta{file}. You can use + this for adding extra text and/or macros into the file, for processing + when the file is typeset by \cmd{\tableofcontents} (or whatever other + command is used for \meta{file} processing, such as \cmd{\listoftables} + for a \file{.lot} file). + + As \cmd{\addcontentsline} and \cmd{\addtocontents} write their arguments to a + file, any fragile commands used in their arguments must be \cmd{\protect}ed. + + You can make certain adjustments to the \toc{} etc., layout by modifying +some of the above macros. Some examples are: + \begin{itemize} + \item If your page numbers stick out into the righthand margin\index{margin} + \begin{lcode} + \renewcommand{\@pnumwidth}{3em} + \renewcommand{\@tocrmarg}{4em} + \end{lcode} + but using lengths appropriate to your document. + + \item To have the (sectional) titles in the \toc, etc., typeset ragged +right with no hyphenation + \begin{lcode} + \renewcommand{\@tocrmarg}{2.55em plus1fil} + \end{lcode} + where the value |2.55em| can be changed for whatever margin\index{margin} space you want. + + \item The dots in the leaders can be eliminated by increasing |\@dotsep| + to a large value: + \begin{lcode} + \renewcommand{\@dotsep}{10000} + \end{lcode} + + \item To have dotted leaders in your \toc{} and \lof{} but not in your \lot: + \begin{lcode} + ... + \tableofcontents + \makeatletter \renewcommand{\@dotsep}{10000} \makeatother + \listoftables + \makeatletter \renewcommand{\@dotsep}{4.5} \makeatother + \listoffigures + ... + \end{lcode} + + \item To add a horizontal line across the whole width of the \toc{} below + an entry for a Part\index{part}: + \begin{lcode} + \part{Part title} + \addtocontents{toc}{\protect\mbox{}\protect\hrulefill\par} + \end{lcode} + As said earlier any fragile commands in \cmd{\addtocontents} and +\cmd{\addcontentsline} + their arguments must be protected + by preceding each fragile command with \cmd{\protect}. + The result of the example above + would be the following two lines in the \file{.toc} file (assuming that it + is the second Part and is on page 34): + \begin{lcode} + \contentsline {part}{II\hspace {1em}Part title}{34} + \mbox {}\hrulefill \par + \end{lcode} + If the \cmd{\protect}s were not used, then the second line would +instead be: + \begin{lcode} + \unhbox \voidb@x \hbox {}\unhbox \voidb@x \leaders \hrule \hfill \kern \z@ \par + \end{lcode} + +\item To change the level of entries printed in the \toc{} (for example + when normally subsections are listed in the \toc{} but for + appendices\index{appendix} only the main title is required) + \begin{lcode} + \appendix + \settocdepth{chapter} + \chapter{First appendix} + ... + \end{lcode} + + \end{itemize} + Remember, if you are modifying any command that includes an |@| sign then this + must be done in either a \file{.sty} file or if in the document itself + it must be + surrounded by \cmd{\makeatletter} and \cmd{\makeatother}. For example, if you + want to modify \cmd{\@dotsep} in the preamble\index{preamble} to your document you have + to do it like this: + \begin{lcode} + \makeatletter + \renewcommand{\@dotsep}{9.0} + \makeatother + \end{lcode} + + + \section{The class \prtoc{} methods} + + The class provides various means of changing the look of the \toc, etc., +without having to go through some of the above. + +\begin{syntax} +\cmd{\tableofcontents} \cmd{\tableofcontents*} \\ +\cmd{\listoffigures} \cmd{\listoffigures*} \\ +\cmd{\listoftables} \cmd{\listoftables*} \\ +\end{syntax} + The \toc, \lof, and \lot{} are printed at the point in the document where + these commands are called, as per normal LaTeX. However, there are + two differences between the standard LaTeX behaviour and the behaviour + with this class. In the standard LaTeX classes + that have \cmd{\chapter} headings\index{heading}, the \toc, \lof{} and \lot{} each appear on + a new page. With this class they do not necessarily + start new pages; if you want them to be on new pages you may have to + specifically issue an appropriate command beforehand. For example: + \begin{lcode} + ... + \clearpage + \tableofcontents + \clearpage + \listoftables + ... + \end{lcode} +Also, the unstarred versions of the commands put their headings\index{heading} into the +\toc, while the starred versions do not. + + \subsection{Changing the titles} \label{sec:titles} + + Commands are provided for controlling the appearance of the +\toc, \lof{} and \lot{} titles. + +\begin{syntax} +\cmd{\contentsname} \cmd{\listfigurename} \cmd{\listtablename} \\ +\end{syntax} +Following LaTeX custom, the title texts are the values + of the \cmd{\contentsname}, \cmd{\listfigurename} and \cmd{\listtablename} + commands. + + The commands for controlling the typesetting of the \toc, \lof{} and \lot{} titles +all follow a similar pattern So for convenience (certainly mine, +and hopefully yours) + in the following + descriptions I will use |Z| to stand for `toc' or `lof' or `lot'. For + example, |\Zmark| stands for |\tocmark| or |\lofmark| or |\lotmark|. + + The code for typesetting the \toc{} title looks like: +\begin{lcode} +\tocheadstart +\printtoctitle{\contentsname} +\tocmark +\thispagestyle{chapter} +\aftertoctitle +\end{lcode} +where the macros are described below. + +\begin{syntax} +\cmd{\Zheadstart} \\ +\end{syntax} +This macro is called before the title is actually printed. +Its default definition is +\begin{lcode} +\newcommand{\Zheadstart}{\chapterheadstart} +\end{lcode} + +\begin{syntax} +\cmd{\printZtitle}\marg{title} \\ +\end{syntax} +The title is typeset via \cmd{\printZtitle}, which defaults to +using \cmd{\printchaptertitle} for the actual typesetting. + +\begin{syntax} +\cmd{\Zmark} \\ +\end{syntax} + These macros sets the appearance of the running heads on the \toc, \lof, and + \lot{} pages. The default definition is equivalent to: +\begin{lcode} +\newcommmand{\Zmark}{\@mkboth{\...name}{\...name}} +\end{lcode} +where |\...name| is \cmd{\contentsname} or \cmd{\listfigurename} or +\cmd{\listtablename} as appropriate. You probably don't need to change these, and +in any case they may well be changed by the particular \cmd{\pagestyle} in +use. + +\begin{syntax} +\cmd{\afterZtitle} \\ +\end{syntax} + This macro is called after the title is typeset and by +default it is defined to be \cmd{\afterchaptertitle}. + + Essentially, the \toc, \lof{} and \lot{} titles use the same format +as the chapter titles, and will be typeset according to the current +chapterstyle. You can modify their appearance by either using a +different chapterstyle for them than for the actual chapters, or +by changing some of the macros. As examples: +\begin{itemize} +\item Doing + \begin{lcode} + \renewcommand{\printZtitle}[1]{\hfill\Large\itshape #1} + \end{lcode} + will print the title right justified in a Large italic font. +\item For a Large bold centered title you can do + \begin{lcode} + \renewcommand{\printZtitle}[1]{\centering\Large\bfseries #1} + \end{lcode} +\item Writing + \begin{lcode} + \renewcommand{\afterZtitle}{\thispagestyle{empty}\afterchaptertitle} + \end{lcode} + will result in the first page of the listing using the \pstyle{empty} + pagestyle instead of the default \pstyle{chapter} pagestyle. +\item Doing + \begin{lcode} + \renewcommand{\afterZtitle}{% + \par\nobreak \mbox{}\hfill{\normalfont Page}\par\nobreak} + \end{lcode} + will put the word `Page' flushright on the line following + the title. +\end{itemize} + + + + + \subsection{Typesetting the entries} \label{sec:entries} + + Commands are also provided to enable finer control over the typesetting + of the different kinds of entries. The parameters defining the default + layout of the entries are illustrated as part of the \Lpack{layouts} + package~\cite{LAYOUTS} or in~\cite[page 34]{GOOSSENS94}, and are repeated in + \fref{fig:ltoc}. + +\begin{syntax} + \cmd{\cftdot}\marg{text} \\ +\end{syntax} + In the default \toc{} typsetting only the more minor entries have dotted + leader lines between the sectioning title and the page number. The + class provides for general leaders for all entries. + The `dot' in a leader is given by the value of \cmd{\cftdot}. Its default + definition is |\newcommand{\cftdot}{.}| which gives the default + dotted leader. By changing \cmd{\cftdot} you can use symbols other than + a period in the leader. For example + \begin{lcode} + \renewcommand{\cftdot}{\ensuremath{\ast}} + \end{lcode} + will result in a dotted leader using asterisks as the symbol. + +\begin{syntax} + \cmd{\cftdotsep} \\ + \cmd{\cftnodots} \\ +\end{syntax} + Each kind of entry can control the separation between the dots + in its leader (see below). For consistency though, all dotted leaders + should use the same spacing. The macro \cmd{\cftdotsep} specifies the + default spacing. + However, if the separation is too large + then no dots will be actually typeset. The macro \cmd{\cftnodots} is + a separation value that is `too large'. + +\begin{syntax} + \cmd{\setpnumwidth}\marg{length} \\ + \cmd{\setrmarg}\marg{length} \\ +\end{syntax} + The page numbers are typeset in a fixed width box. The command + \cmd{\setpnumwidth} can be used to change the width + of the box (LaTeX 's internal \cmd{\@pnumwidth}). + The title texts will end before reaching the righthand margin\index{margin}. + \cmd{\setrmarg} can be used to set this distance + (LaTeX 's internal \cmd{\@tocrmarg}). + Note that the length used in \cmd{\setrmarg} should be greater + than the length set in \cmd{\setpnumwidth}. These values should remain + constant in any given document. + + This manual requires more space for the page numbers than the default, +so the following was set in the preamble\index{preamble}: +\begin{lcode} +\setpnumwidth{2.55em} +\setrmarg{3.55em} +\end{lcode} + + +\begin{syntax} +\lnc{\cftparskip} \\ +\end{syntax} + Normally the \lnc{\parskip} in the \toc, etc., is zero. This may be changed + by changing the length \lnc{\cftparskip}. Note that the current value + of \lnc{\cftparskip} is used for the \toc, \lof{} and \lot, but you can change + the value before calling \cmd{\tableofcontents} or \cmd{\listoffigures} or + \cmd{\listoftables} if one or other of these should have different values + (which is not a good idea). + + + Again for convenience, in the following I will use |X| to stand for any +of the following: + \begin{itemize} + \item |part| for |\part| titles + \item |chapter| for |\chapter| titles + \item |section| for |\section| titles + \item |subsection| for |\subsection| titles + \item |subsubsection| for |\subsubsection| titles + \item |paragraph| for |\paragraph| titles + \item |subparagraph| for |\subparagraph| titles + \item |figure| for figure |\caption| titles + \item |subfigure| for subfigure |\caption| titles + \item |table| for table |\caption| titles + \item |subtable| for subtable |\caption| titles + \end{itemize} + + +\begin{syntax} +\cmd{\cftchapterbreak} \\ +\end{syntax} +When \cmd{\l@chapter} starts to typeset a \cmd{\chapter} entry in the +\toc{} the first thing it does is to call the macro \cmd{\cftchapterbreak}. +This is defined as: +\begin{lcode} +\newcommand{\cftchapterbreak}{\addpenalty{-\@highpenalty}} +\end{lcode} +which encourages a page break before rather than after the entry. As usual, +you can change \cmd{\cftchapterbreak} to do other things that you feel might +be useful. + +\begin{syntax} +\lnc{\cftbeforeXskip} \\ +\end{syntax} + This length controls the vertical space before an entry. It can be changed + by using \cmd{\setlength}. + +\begin{syntax} +\lnc{\cftXindent} \\ +\end{syntax} + This length controls the indentation of an entry from the left margin\index{margin} + (\textit{indent} in \fref{fig:ltoc}). It + can be changed using \cmd{\setlength}. + +\begin{syntax} +\lnc{\cftXnumwidth} \\ +\end{syntax} + This length controls the space allowed for typesetting title numbers + (\textit{numwidth} in \fref{fig:ltoc}). It can + be changed using \cmd{\setlength}. Second and subsequent lines of a multiline + title will be indented by this amount. + + The remaining commands are related to the specifics of typesetting + an entry. + This is a simplified pseudo-code version for the typesetting of numbered + and unnumbered entries. + \begin{lcode} + {\cftXfont {\cftXpresnum SNUM\cftXaftersnum\hfil} \cftXaftersnumb TITLE} + {\cftXleader}{\cftXpagefont PAGE}\cftXafterpnum\par + + {\cftXfont TITLE}{\cftXleader}{\cftXpagefont PAGE}\cftXafterpnum\par + \end{lcode} + where |SNUM| is the section number, |TITLE| is the title text and |PAGE| + is the page number. In the numbered entry the pseudo-code \\ + |{\cftXpresnum SNUM\cftaftersnum\hfil}| \\ + is typeset within a box of width \lnc{\cftXnumwidth}. + +\begin{syntax} +\cmd{\cftXfont} \\ +\end{syntax} + This controls the appearance of the title (and its preceding number, + if any). It may be changed using \cmd{\renewcommand}. + +\begin{syntax} +\cmd{\cftXpresnum} \cmd{\cftXaftersnum} \cmd{\cftXaftersnumb} \\ +\end{syntax} + The section number is typeset within a box of width \lnc{\cftXnumwidth}. + Within the box the macro \cmd{\cftXpresnum} is first called, then the + number is typeset, and the \cmd{\cftXaftersnum} + macro is called after the number is typeset. The last command + within the box is \cmd{\hfil} to make the box contents flushleft. + After the box is + typeset the \cmd{\cftXaftersnumb} macro is called before typesetting + the title text. All three of these can be changed by \cmd{\renewcommand}. + By default they are defined to do nothing. + + +\begin{syntax} +\cmd{\partnumberline}\marg{num} \\ +\cmd{\chapternumberline}\marg{num} \\ +\end{syntax} +In the \toc, the macros \cmd{\partnumberline} and \cmd{\chapternumberline} +are responsible respectively for typesetting the \cmd{\part} and \cmd{\chapter} +numbers. Internally they use \cmd{\cftXpresnum}, \cmd{\cftXaftersnum} +and \cmd{\cftaftersnumb} as above. If you do not want, say, +the \cmd{\chapter} number to appear you +can do: +\begin{lcode} +\renewcommand{\chapternumberline}[1]{} +\end{lcode} + +\Note{} Because the \Lpack{hyperref} package~\cite{HYPERREF} +does not understand +the \cmd{\partnumberline} and \cmd{\chapternumberline} commands, +if you use the \Lpack{hyperref} package you will also have to use +the \Lpack{memhfixc} package, which comes with memoir. + + + +\begin{syntax} +\cmd{\cftXleader} \\ +\cmd{\cftXdotsep} \\ +\end{syntax} + \cmd{\cftXleader} defines the leader between the title and the page number; + it can be changed by \cmd{\renewcommand}. + The spacing between any dots in the leader is controlled by \cmd{\cftXdotsep} + (\cmd{\@dotsep} in \fref{fig:ltoc}). + It can be changed by \cmd{\renewcommand} and its value must be either a + number (e.g., 6.6 or \cmd{\cftdotsep}) or \cmd{\cftnodots} (to disable the dots). + The spacing + is in terms of \emph{math units} where there are 18mu to 1em. + +\begin{syntax} +\cmd{\cftXpagefont} \\ +\end{syntax} + This defines the font to be used for typesetting the page number. It + can be changed by \cmd{\renewcommand}. + +\begin{syntax} +\cmd{\cftXafterpnum} \\ +\end{syntax} + This macro is called after the page number has been typeset. Its default + is to do nothing. It can be changed by \cmd{\renewcommand}. + +\begin{syntax} +\cmd{\cftsetindents}\marg{entry}\marg{indent}\marg{numwidth} \\ +\end{syntax} + The command + \cmd{\cftsetindents} sets the \meta{entry}'s \textit{indent} to the +length \meta{indent} and its + \textit{numwidth} to the length \meta{numwidth}. The \meta{entry} argument + is the name of one of the standard entries (e.g., |subsection|) or the +name of entry that has been defined within the document. + For example +\begin{lcode} + \cftsetindents{figure}{0em}{1.5em} +\end{lcode} + will make figure\index{figure} entries left justified. + + This manual requires more space for section numbers in the \toc{} than +the default (which allows for three digits). Consequently the preamble\index{preamble} +contains the following: +\begin{lcode} +\cftsetindents{section}{1.5em}{3.0em} +\cftsetindents{subsection}{4.5em}{3.9em} +\cftsetindents{subsubsection}{8.4em}{4.8em} +\cftsetindents{paragraph}{10.7em}{5.7em} +\cftsetindents{subparagraph}{12.7em}{6.7em} +\end{lcode} +Note that changing the indents at one level implies that any lower level +indents should be changed as well. + + + Various effects can be achieved by changing the definitions of \cmd{\cftXfont}, + \cmd{\cftXaftersnum}, \cmd{\cftXaftersnumb}, \cmd{\cftXleader} and +\cmd{\cftXafterpnum}, + either singly or in combination. + For the sake of some examples, assume that we have the following initial + definitions + \begin{lcode} + \newcommand{\cftXfont}{} + \newcommand{\cftXaftersnum}{} + \newcommand{\cftXaftersnumb}{} + \newcommand{\cftXleader}{\cftdotfill{\cftXdotsep}} + \newcommand{\cftXdotsep}{\cftdotsep} + \newcommand{\cftXpagefont}{} + \newcommand{\cftXafterpnum}{} + \end{lcode} + (Note that the same font should be used for the title, leader and page + number to provide a coherent appearance). + + \begin{itemize} + \item To eliminate the dots in the leader: + \begin{lcode} + \renewcommand{\cftXdotsep}{\cftnodots} + \end{lcode} + + \item To put something (e.g., a name) before the title (number): + \begin{lcode} + \renewcommand{\cftXpresnum}{SOMETHING } + \end{lcode} + + \item To add a colon after the section number: + \begin{lcode} + \renewcommand{\cftXaftersnum}{:} + \end{lcode} + + \item To put something before the title number, add a colon after the + the title number, set everything in bold font, + and start the title text on the following line: + \begin{lcode} + \renewcommand{\cftXfont}{\bfseries} + \renewcommand{\cftXleader}{\bfseries\cftdotfill{\cftXdotsep}} + \renewcommand{\cftXpagefont}{\bfseries} + \renewcommand{\cftXpresnum}{SOMETHING } + \renewcommand{\cftXaftersnum}{:} + \renewcommand{\cftXaftersnumb}{\\} + \end{lcode} + + If you are adding text in the number box in addition to the number, + then you will probably have to increase the width of the box so that + multiline titles have a neat vertical alignment; changing box widths + usually implies that the indents will require modification as + well. One possible method of adjusting the box width for the above example + is: + \begin{lcode} + \newlength{\mylen} % a "scratch" length + \settowidth{\mylen}{\bfseries\cftXpresnum\cftXaftersnum} + \addtolength{\cftXnumwidth}{\mylen} % add the extra space + \end{lcode} + + \item To set the section numbers flushright: + \begin{lcode} + \setlength{\mylen}{0.5em} % extra space at end of number + \renewcommand{\cftXpresnum}{\hfill} % note the double `l' + \renewcommand{\cftXaftersnum}{\hspace*{\mylen}} + \addtolength{\cftXnumwidth}{\mylen} + \end{lcode} + In the above, the added initial \cmd{\hfill} in the box overrides the + final \cmd{\hfil} in the box, thus shifting everything to the right hand + end of the box. The extra space is so that the number is not typeset + immediately at the left of the title text. + + \item To set the entry ragged left (but this only looks good for single + line titles): + \begin{lcode} + \renewcommand{\cftXfont}{\hfill\bfseries} + \renewcommand{\cftXleader}{} + \end{lcode} + + \item To set the page number immediately after the entry text instead of at + the righthand margin\index{margin}: + \begin{lcode} + \renewcommand{\cftXleader}{} + \renewcommand{\cftXafterpnum}{\cftparfillskip} + \end{lcode} + \end{itemize} + +\begin{syntax} +\cmd{\cftparfillskip} \\ +\end{syntax} + By default the \cmd{\parfillskip} value is locally set to fill up the last + line of a paragraph\index{paragraph}. Just changing \cmd{\cftXleader} puts horrible interword + spaces into the last line of the title. The \cmd{\cftparfillskip} + command is provided just so that the above effect can be achieved. + +\begin{syntax} +\cmd{\cftpagenumbersoff}\marg{entry} \\ +\cmd{\cftpagenumberson}\marg{entry} \\ +\end{syntax} + The command \cmd{\cftpagenumbersoff} will + eliminate the page numbers for \meta{entry} in the listing, where + \meta{entry} is the name of one of the standard + kinds of entries (e.g., |subsection|, or |figure|) or the name of a + new entry defined in the document. + + The command \cmd{\cftpagenumberson} reverses + the effect of a corresponding \cmd{\cftpagenumbersoff} for \meta{entry}. + + One question that appeared on the \file{comp.text.tex} newsgroup asked + how to get the titles of Appendices\index{appendix} list in the \toc{} \emph{without} + page numbers. Here is a simple way of doing it. + \begin{lcode} + ... + \appendix + \addtocontents{toc}{\cftpagenumbersoff{chapter}} + \chapter{First appendix} + \end{lcode} + If there are other chapter type headings\index{heading!chapter} to go into the \toc{} after the + appendices\index{appendix} (perhaps a bibliography\index{bibliography} or an index\index{index}), + then it will be necessary to do a similar + \begin{lcode} + \addtocontents{toc}{\cftpagenumberson{chapter}} + \end{lcode} + after the appendices\index{appendix} to restore the page numbering in the \toc. + + At this point, I leave it up to your ingenuity as to other effects that + you can achieve. However, if you come up with further examples, let me + know for possible inclusion in a later version of this document. + + \section{New list of\ldots{} and entries} + +\index{list!new list of|(} + + \begin{syntax} +\cmd{\newlistof}\marg{listofcom}\marg{ext}\marg{listofname} \\ +\end{syntax} + The command \cmd{\newlistof} + creates a new \listofx, and assorted commands to go along with it. + The first argument, \meta{listofcom} is used to define a new + command called |\listofcom| which can then be used like |\listoffigures| +to typeset the \listofx. The \meta{ext} argument is the file extension to +be used for the new listing. The last argument, \meta{listofname} is +the title for the \listofx. Unstarred and starred versions of +|\listofcom| are created. The unstarred version, |\listofcom|, will add +\meta{listofname} to the \toc, while the starred version, |\listofcom*|, +makes no entry in the \toc. + + As an example: + \begin{lcode} + \newcommand{\listanswername}{List of Answers} + \newlistof{listofanswers}{ans}{\listanswername} + \end{lcode} + will create a new \cmd{\listofanswers} commmand that can be used +to typeset a listing of answers under the +title \cmd{\listanswername}, where the answer titles are in a \file{.ans} +file. + It is up to the author of the document to specify the `answer' code +for the answers in the document. For example: + \begin{lcode} + \newcounter{answer}[chapter] + \renewcommand{\theanswer}{\thechapter.\arabic{answer}} + \newcommand{\answer}[1]{ + \refstepcounter{answer} + \par\noindent\textbf{Answer \theanswer. #1} + \addcontentsline{ans}{answer}{\protect\numberline{\theanswer}#1}\par} + \end{lcode} + which, when used like: \\ + |\answer{Hard} The \ldots| \\ + will print as: +\begin{syntax} + \textbf{Answer 1. Hard} \\ + \hspace*{2em} The \ldots \\ +\end{syntax} + + As mentioned above, the \cmd{\newlistof} command creates several +new commands in addition to |\listofcom|, most of which you should now be +familiar with. For convenience, + assume that |\newlistof{...}{Z}{...}| has been issued so that + |Z| is the new file extension and corresponds to the |Z| in + \S\ref{sec:titles}. Then in addition to |\listofcom| the following +new commands will be made available. + + The four commands, |\Zmark|, + |\Zheadstart|, + |\printZtitle|, and + |\afterZtitle|, +are analagous to the commands of the same names +described in \S\ref{sec:titles} (internally the class uses +the \cmd{\newlistof} macro to define the \toc, \lof{} and \lot). +In particular the default definition of |\Zmark| is equivalent to: +\begin{lcode} +\newcommand{\Zmark}{\@mkboth{listofname}{listofname}} +\end{lcode} +However, this may well be altered by the particular \cmd{\pagestyle} in +use. + +\begin{syntax} +|Zdepth| \\ +\end{syntax} + The counter |Zdepth| is analagous to the standard + \Icn{tocdepth} counter, in that it specifies that entries + in the new listing should not be typeset if their numbering level + is greater + than |Zdepth|. The default definition is equivalent to +\begin{lcode} +\setcounter{Zdepth}{1} +\end{lcode} + +\begin{syntax} +\cmd{\insertchapterspace} \\ +\cmd{\addtodef}\marg{macro}\marg{prepend}\marg{append} \\ +\end{syntax} +Remember that the \cmd{\chapter} command uses \cmd{\insertchapterspace} +to insert vertical spaces into the \lof{} and \lot. If you want similar +spaces added to your new listing then you have to modify +\cmd{\insertchapterspace}. The easiest way to do this is via +the \cmd{\addtodef} macro, like: +\begin{lcode} +\addtodef{\insertchapterspaces}{}% + {\addtocontents{ans}{\protect\addvspace{10pt}}} +\end{lcode} +The \cmd{\addtodef} macro is described later in \S\ref{sec:addtodef}. + + The other part of creating a new \listofx, is to specify the +formatting of the entries, i.e., define an appropriate |\l@kind| macro. + +\begin{syntax} +\cmd{\newlistentry}\oarg{within}\marg{cntr}\marg{ext}\marg{level-1} \\ +\end{syntax} + The command \cmd{\newlistentry} creates the commands necessary for +typesetting an entry in a \listofx. + The first required argument, \meta{cntr} is used to define a new + counter called |cntr|, unless |cntr| is already defined. +The optional \meta{within} argument can + be used so that |cntr| gets reset to one every time the counter called + |within| is changed. That is, the first two arguments when |cntr| is not +already defined, are equivalent to + calling \cmd{\newcounter}\marg{cntr}\oarg{within}. If |cntr| is already +defined, \cmd{\newcounter} is not called. |cntr| is used for the number that +goes along with the title of the entry. + + The second required argument, \meta{ext}, is the file extension for the + entry listing. + The last argument, \meta{level-1}, is a number specifying the numbering + level minus one, + of the entry in a listing. + + + Calling \cmd{\newlistentry} creates several new commands. Assuming that + it is called as |\newlistentry[within]{X}{Z}{N}|, where |X| and |Z| are + similar to the + previous uses of them (e.g., |Z| is the file extension), +and |N| is an integer number, then the following + commands are made available. + + + The set of commands |\cftbeforeXskip|, + |\cftXfont|, + |\cftXpresnum|, + |\cftXaftersnum|, + |\cftXaftersnumb|, + |\cftXleader|, + |\cftXdotsep|, + |\cftXpagefont|, and + |\cftXafterpnum|, + are analagous to the commands of the same names + described in \S\ref{sec:entries}. Their default values are also + as described earlier. + + The default values of |\cftXindent| and |\cftXnumwidth| are set according + to the value of the \meta{level-1} argument (i.e., |N| in this example). + For |N=0| the settings correspond to those for + figures\index{figure} and tables\index{table}, as listed in \tref{tab:indents} for the +\Lclass{memoir} class. + For |N=1| the settings correspond + to subfigures\index{figure!sub-}, and so on. + For values of |N| less than zero or greater than four, + or for non-default values, use the + \cmd{\cftsetindents} command to set the values. + + + |\l@X| is an internal command that typesets an entry in the list, and + is defined in terms of the above |\cft*X*| commands. It will not typeset + an entry if |\Zdepth| is |N| or less, where |Z| is the listing's file + extension. + + The command |\theX| prints the value of the |X| counter. It is initially + defined so that it prints arabic numerals. If the optional \meta{within} + argument is used, |\theX| is defined as +\begin{lcode} + \renewcommand{\theX}{\thewithin.\arabic{X}} +\end{lcode} + otherwise as +\begin{lcode} +\renewcommand{\theX}{\arabic{X}} +\end{lcode} + + + As an example of the independent use of \cmd{\newlistentry}, the following + will set up for sub-answers. + \begin{lcode} + \newlistentry[answer]{subanswer}{1} + \renewcommand{\thesubanswer}{\theanswer.\alph{subanswer}} + \newcommand{\subanswer}[1]{ + \refstepcounter{subanswer} + \par\textbf{\thesubanswer) #1} + \addcontentsline{ans}{subanswer{\protect\numberline{\thesubanswer}#1}} + \setcounter{ansdepth}{2} + \end{lcode} + And then: + \begin{lcode} + \answer{Harder} The \ldots + \subanswer{Reformulate the problem} It assists \ldots + \end{lcode} + will be typeset as: +\begin{syntax} +\textbf{Answer 2. Harder} \\ +\hspace*{2em} The \ldots \\ +\hspace*{2em} \textbf{2.a) Reformulate the problem} It assists \ldots \\ +\end{syntax} + + By default the answer entries will appear in the List of Answers listing + (typeset by the |\listofanswers| command). + In order to get the subanswers to appear, + the |\setcounter{ansdepth}{2}| command was used above. + + To turn off page numbering for the subanswers, do \\ + |\cftpagenumbersoff{subanswer}| + + As another example of \cmd{\newlistentry}, suppose that an extra sectioning + division below |subparagraph| is required, called |subsubpara|. + The |\subsubpara| command itself can be defined via the LaTeX kernel + \cmd{\@startsection} command. + Also it is necessary to define a |\subsubparamark| macro, + a new |subsubpara| counter, a |\thesubsubpara| macro and a |\l@subsubpara| + macro. Using \cmd{\newlistentry} + takes care of most of these as shown below (remember + the caveats about commands with |@| signs in them). + \begin{lcode} + \newcommand{\subsubpara}{\@startsection{subpara} + {6} % level + {\parindent} % indent from left margin + {3.25ex \@plus1ex \@minus .2ex} % skip above heading + {-1em} runin heading with % 1em between title & text + {\normalfont\normalsize\itshape} % italic number and title + } + \newlistentry[subparagraph]{subsubpara}{toc}{5} + \cftsetindents{subsubpara}{14.0em}{7.0em} + \newcommand*{\subsubparamark}[1]{} % gobble heading mark + \end{lcode} + + + Each \listofx{} uses a file to store the list entries, and these + files must remain open for writing throughout the document processing. + TeX has only a limited number of files that it can keep open, and this + puts a limit on the number of listings that can be used. For a document + that includes a \toc{} but no other extra ancilliary files (e.g., no + index\index{index} or bibliography\index{bibliography} output files) the maximum number of LoX's, including + a \lof{} and \lot, is no more than about eleven. If you try and create too many + new listings LaTeX will respond with the error message: + \begin{center} + |No room for a new write| + \end{center} + If you get such a message the only recourse is to redesign your document. + +\subsection{Example --- plates} + + As has been mentioned earlier, some illustrations\index{illustration} may be +tipped in\index{tip in} to a book. Often, these are called `plates' if +they are on glossy paper\index{paper} and the rest of the book is on ordinary paper\index{paper}. +We can define a new kind of Listing for these. + +\begin{lcode} +\newcommand{\listplatename}{Plates} +\newlistof{listofplates}{lop}{\listplatename} +\newlistentry{plate}{lop}{0} +\cftpagenumbersoff{plate} +\end{lcode} +This code defines the \cmd{\listofplates} command to start the listing which +will be titled `Plates' from the \cmd{\listplatename} macro. The entry name +is |plate| and the file extension is |lop|. As plate pages typically do +not have printed folios\index{folio}, the \cmd{\cftpagenumbersoff} command has been +used to prohibit page number printing in the listing. + + If pages are tipped in, then they are put between a verso and a recto +page. The \Lpack{afterpage} package~\cite{AFTERPAGE} lets you specify +something that should happen after the current page is finished. The next +piece of code uses the package and its \cmd{\afterpage} macro to +define two macros which let you specify something that is to be +done after the next verso or recto page has been completed. +\begin{lcode} +\newcommand{\afternextverso}[1]{% + \afterpage{\ifodd\c@page #1\else\afterpage{#1}\fi}} +\newcommand{\afternextrecto}[1]{% + \afterpage{\ifodd\c@page\afterpage{#1}\else #1\fi}} +\end{lcode} + + + The \cmd{\pageref}\marg{labelid} command typesets the page number +corresponding to the location in the document where +\cmd{\label}\marg{labelid} is specified. The following code defines +two macros\footnote{These only work for arabic page numbers.} +that print the page number before or after that given by +\cmd{\pageref}. +\begin{lcode} +\newcounter{mempref} +\newcommand{\priorpageref}[1]{% + \setcounter{mempref}{\pageref{#1}}\addtocounter{mempref}{-1}\themempref} +\newcommand{\nextpageref}[1]{% + \setcounter{mempref}{\pageref{#1}}\addtocounter{mempref}{1}\themempref} +\end{lcode} + + With these preliminaries out of the way, we can use code like the +following for handling a set of physically tipped in plates. +\begin{lcode} +\afternextverso{\label{tip} + \addtocontents{lop}{% + Between pages \priorpageref{tip} and \pageref{tip} + \par\vspace*{\baselineskip}} + \addcontentsline{lop}{plate}{First plate} + \addcontentsline{lop}{plate}{Second plate} + ... + \addcontentsline{lop}{plate}{Nth plate} +} +\end{lcode} +This starts off by waiting until the next recto page is started, which +will be the page immediately after the plates, and then +inserts the label |tip|. The \cmd{\addtocontents} macro puts its argument +into the plate list |lop| file, indicating the page numbers before and after +the set of plates. With the plates being physically added to the document +it is not possible to use \cmd{\caption}, instead the \cmd{\addcontentsline} +macros are used to add the plate titles to the |lop| file. + + With a few modifications the code above can also form the basis +for listing plates that are +electronically tipped in but do not have printed folios\index{folio} or \cmd{\caption}s. + +\index{list!new list of|)} + + + + \section{Extras} + +\index{chapter!precis|(} + + Some old style novels, and even some modern text + books,\footnote{For example, Robert Sedgewick, \textit{Algorithms}, + Addison-Wesley, 1983.} include a short synopsis of the contents of + the chapter either immediately + after the chapter heading\index{heading!chapter} or in the \toc, or in both places. + +\begin{syntax} +\cmd{\chapterprecis}\marg{text} \\ +\end{syntax} + The command \cmd{\chapterprecis} prints its argument + both at the + point in the document where it is called, and also adds it to the \file{.toc} + file. For example: + \begin{lcode} + ... + \chapter{} first chapter + \chapterprecis{Our hero is introduced; family tree; early days.} + ... + \end{lcode} + +\begin{syntax} +\cmd{\chapterprecishere}\marg{text} \\ +\cmd{\chapterprecistoc}\marg{text} \\ +\end{syntax} + The \cmd{\chapterprecis} command calls these two commands to print the + \meta{text} in the document (the \cmd{\chapterprecishere} command) + and to put it into the \toc{} (the \cmd{\chapterprecistoc} command). + These can be used individually if required. + +\begin{syntax} +\cmd{\prechapterprecis} \cmd{\postchapterprecis} \\ +\end{syntax} +The \cmd{\chapterprecishere} macro is intended for use immediately after +a \cmd{\chapter}. The \meta{text} argument is typeset in +italics in a \Ie{quote} environment. The macro's definition is: +\begin{lcode} +\newcommand{\chapterprecishere}[1]{% + \prechapterprecis #1\postchapterprecis} +\end{lcode} +where \cmd{\prechapterprecis} and \cmd{\postchapterprecis} are defined +as: +\begin{lcode} +\newcommand{\prechapterprecis}{% + \vspace*{-2\baselineskip}% + \begin{quote}\normalfont\itshape} +\newcommand{\postchapterprecis}{\end{quote}} +\end{lcode} +The \cmd{\prechapterprecis} and \cmd{\postchapterprecis} macros can be +changed if another style of typesetting is required. + +\begin{syntax} +\cmd{\precistoctext}\marg{text} \cmd{\precistocfont} \\ +\end{syntax} +The \cmd{\chapterprecistoc} macro puts the macro \cmd{\precistoctext} into +the \ixfile{toc} file. The default definition is +\begin{lcode} +\DeclareRobustCommand{\precistoctext}[1]{% + {\leftskip \cftchapterindent\relax + \advance\leftskip \cftchapternumwidth\relax + \rightskip \@tocrmarg\relax + \precistocfont #1\par}} +\end{lcode} +Effectively, in the \toc{} \cmd{\precistoctext} typesets its argument like +a chapter title using the \cmd{\precistocfont} (default \cmd{\itshape}). + +\index{chapter!precis|)} + + Sometimes it may be desirable to make a change to the global parameters + for an individual entry. For example, a figure\index{figure} might be placed on + the end paper\index{paper!end} of a book (the inside of the front or back cover), and + this needs to be placed in a \lof{} with the page number set as, say + `inside front cover'. If `inside front cover' is typeset as an ordinary + page number it will stick out into the margin\index{margin}. Therefore, the parameters + for this particular entry need to be changed. + +\begin{syntax} +\cmd{\cftlocalchange}\marg{ext}\marg{pnumwidth}\marg{tocrmarg} \\ +\end{syntax} + The command \cmd{\cftlocalchange} + will write an entry into the file with extension \meta{ext} to reset +the global \cmd{\@pnumwidth} and \cmd{\@tocrmarg} parameter lengths. + The command should be called again after any special entry to reset + the parameters back to their usual values. Any fragile commands used + in the arguments must be protected. + +\begin{syntax} +\cmd{\cftaddtitleline}\marg{ext}\marg{kind}\marg{text}\marg{page} \\ +\cmd{\cftaddnumtitleline}\marg{ext}\marg{kind}\marg{num}\marg{title}\marg{page} \\ +\end{syntax} + The command \cmd{\cftaddtitleline} + will write a \cmd{\contentsline} entry into \meta{ext} for a \meta{kind} + entry with title \meta{title} and page number \meta{page}. + Any fragile commands used in the arguments must be protected. +That is, + an entry is made of the form: +\begin{lcode} +\contentsline{kind}{title}{page} +\end{lcode} + The command \cmd{\cftaddnumtitleline} + is similar to \cmd{\cftaddtitleline} except that it also includes +\meta{num} as the argument to + \cmd{\numberline}. That is, an entry is made of the form +\begin{lcode} +\contentsline{kind}{\numberline{num} title}{page} +\end{lcode} + + As an example of the use of these commands, + noting that the default LaTeX values for + \cmd{\@pnumwidth} and \cmd{\@tocrmarg} are 1.55em and 2.55em respectively, + one might do the + following for a figure\index{figure} on the frontispiece\index{frontispiece} page. + \begin{lcode} + ... + this is the frontispiece page with no number + draw or import the picture (with no \caption) + \cftlocalchange{lof}{4em}{5em} % make pnumwidth big enough for + % frontispiece and change margin + \cftaddtitleline{lof}{figure}{The title}{frontispiece} + \cftlocalchange{lof}{1.55em}{2.55em} % return to normal settings + \clearpage + ... + \end{lcode} + Recall that a \cmd{\caption} command will put an entry in the \file{.lof} + file, which is not wanted here. If a caption\index{caption} is required, then you can + either craft one youself or, assuming that your general captions\index{caption} are not + too exotic, use the \cmd{\legend} command (see later). + If the illustration\index{illustration} is numbered, use + \cmd{\cftaddnumtitleline} instead of \cmd{\cftaddtitleline}. + + +\section{Tails} + + The commands for producing a bibliography\index{bibliography} and an index\index{index} are +the same as for the standard classes, but there are two differences. + +\subsection{Bibliography} + +\index{bibliography|(} + +\begin{syntax} +\senv{thebibliography}\marg{exlabel} \\ +\cmd{\bibitem} ... \\ +\eenv{thebibliography} \\ +\cmd{\bibname} \\ +\end{syntax} +The bibliography is typeset within the \Ie{thebibliography} environment. +This takes one required argument, \meta{exlabel}, which is a piece of text +as wide as the widest label in the bibliography. The value of +\cmd{\bibname} (default `Bibliography') is used +as the title. + +\begin{syntax} +\cmd{\bibintoc} \cmd{\nobibintoc} \\ +\end{syntax} +The declaration \cmd{\bibintoc} will cause the |thebibliography| +environment to add the title to the \toc, while the declaration +\cmd{\nobibintoc} ensures that the title is not added to the \toc. +The default is \cmd{\bibintoc}. + + +\begin{syntax} +\cmd{\prebibhook} \cmd{\postbibhook} \\ +\end{syntax} +The commands \cmd{\prebibhook} and \cmd{postbibhook} are called after +typesetting the title of the bibliography and after typesetting the list of +entries, respectively. By default, they are defined to do nothing. You may +wish to use one or other of these to provide some general information about +the bibliography. For example: +\begin{lcode} +\renewcommand{\postbibhook}{% +CTAN is the Comprehensive TeX Archive Network and URLS for the +several CTAN mirrors can be found at \url{http://www.tug.org}.} +\end{lcode} + +\begin{syntax} +\cmd{\setbiblabel}\marg{style} \\ +\end{syntax} +The style of the labels marking the bibliographic entries can be set +via \cmd{\setbiblabel}. The default definition is +\begin{lcode} +\setbiblabel{[#1]\hfill} +\end{lcode} +where |#1| is the citation mark position, which generates flushleft +marks enclosed in square brackets. To have marks just +followed by a dot +\begin{lcode} +\setbiblabel{#1.\hfill} +\end{lcode} + + + + The definition of the \Ie{thebibliography} environment is: +\begin{lcode} +\newenvironment{thebibliography}[1]{% + \bibsection + \begin{bibitemlist}{#1}}{\end{bibitemlist}\postbibhook} +\end{lcode} + +\begin{syntax} +\cmd{\bibsection} \\ +\end{syntax} +The macro \cmd{\bibsection} defines the heading for the \Ie{thebibliography} +environment; that is, everything before the actual list of bibliographic +items starts. Its default definition is: +\begin{lcode} +\newcommand{\bibsection}{% + \chapter*{\bibname} + \bibmark + \ifnobibintoc\else + \phantomsection + \addcontentsline{toc}{chapter}{\bibname} + \fi + \prebibhook} +\end{lcode} +To change the style of the heading for the bibliography, redefine +\cmd{\bibsection}. For example, to have the bibliography typeset as a +numbered section instead of a chapter, redefine \cmd{\bibsection} as: +\begin{lcode} +\renewcommand{\bibsection}{% + \section{\bibname} + \prebibhook} +\end{lcode} + + If you use the \Lpack{natbib} and/or the \Lpack{chapterbib} +packages~\cite{NATBIB,CHAPTERBIB} with the \Lopt{sectionbib} option, +then \cmd{\bibsection} is +changed appropriately to typeset as a numbered section. + + The \Lpack{jurabib} package~\cite{JURABIB} redefines +the \Ie{thebibliography} +environment, +providing its own methods for listing the items. However, +the redefinition also eliminates the opportunity to add the +Bibliography to the Table of Contents and to have some introductory text. +To restore these to the class specification, put the following in your +preamble after loading \Lpack{jurabib}: +\begin{lcode} +\usepackage{jurabib} +\makeatletter +\renewcommand{\bib@heading}{\bibsection} +\makeatother +\end{lcode} +However, thanks to the kindness of Jens Berger, if your version of +\Lpack{jurabib} is 0.6 or later then +the fix is not required. + + +\begin{syntax} +\lnc{\bibitemsep} \\ +\end{syntax} + The \Lpack{natbib} package provides a length, \lnc{\bibsep} which can +be used to alter the vertical spacing between the entries in the bibliography. +Setting \lnc{\bibsep} to 0pt removes any extra space between the entries. + The equivalent length provided by the class for changing the space between +bibliography entries is \lnc{\bibitemsep}, which by default is set to +the default value of \lnc{\itemsep}. + + The bibliography is set as a list, and the spacing between the items is +(\lnc{\bibitemsep} + \lnc{\parsep}). To eliminate any extra vertical space do +\begin{lcode} +\setlength{\bibitemsep}{-\parsep} +\end{lcode} + +\begin{syntax} +\cmd{\biblistextra} \\ +\end{syntax} + A hook, called \cmd{\biblistextra}, is provided that is called at the +end of the bibliography list setup. By default it does nothing but +it can be used, for example, to set all bibliography entries flushleft by +modify the list parameters as shown below. +\begin{lcode} +\renewcommand{\biblistextra}{% + \setlength{\leftmargin}{0pt}% + \setlength{\itemindent}{\labelwidth}% + \setlength{\itemindent}{\labelsep}% +} +\end{lcode} + + + +\index{bibliography|)} + +\subsection{Index} + +\index{index|(} + + The indexing commands have been significantly enhanced with respect +to the standard classes and include the +functionality provided by the \Lpack{makeidx}, \Lpack{showidx} and +\Lpack{index} packages~\cite{MAKEIDX,INDEX}; these packages should not be used. + + In the standard classes the index is set in two columns. +\begin{syntax} +\cmd{\onecolindextrue} \\ +\cmd{\onecolindexfalse} \\ +\end{syntax} +The declaration \cmd{\onecolindexfalse}, which is the default, causes +any indexes to be set in two columns. The declaration \cmd{\onecolindextrue} +causes any following indexes to be set in one column. This can be useful +if, for example, you need an index of the first lines of poems. + +\begin{syntax} +\cmd{\makeindex}\oarg{file} \\ +\cmd{\printindex}\oarg{file} \\ +\end{syntax} +The macro \cmd{\makeindex}, which must be put in the preamble if it is used, +opens an \ixfile{idx} file, which by default is called \file{jobname.idx}, +where \file{jobname} is the name of the main LaTeX source file. +If the optional \meta{file} argument is given then a file called +\file{file.idx} will be opened instead. +The macro \cmd{\printindex} reads an \ixfile{ind} +file called \file{jobname.ind}, which should contain an +\Ie{theindex} environment +and the indexed items. If the optional \meta{file} argument is given then +the \file{file.ind} file will be read. The \textsc{makeindex} program is often +used to convert an \ixfile{idx} file to an \ixfile{ind} file. + + + +\begin{syntax} +\senv{theindex} entries \eenv{theindex} \\ +\cmd{\indexname} \\ +\end{syntax} +The index\index{index} is typeset in two columns\index{column!double} within the \Ie{theindex} environment. +The index\index{index} title is given by the current value of \cmd{\indexname} (default +`Index'). + +\begin{syntax} +\cmd{\indexintoc} \cmd{\noindexintoc} \\ +\end{syntax} +The declaration \cmd{\indexintoc} will cause the |theindex| +environment to add the title to the \toc, while the declaration +\cmd{\noindexintoc} ensures that the title is not added to the \toc. +The default is \cmd{\indexintoc}. + +\begin{syntax} +\lnc{\indexcolsep} \\ +\lnc{\indexrule} \\ +\end{syntax} +The length \lnc{\indexcolsep} is the width of the gutter between the two +index columns\index{column!double}. Its default value is 35pt. The length \lnc{\indexrule}, default +value 0pt, is the thickness of a vertical rule separating the two columns. + + +\begin{syntax} +\cmd{\preindexhook} \\ +\end{syntax} + The macro \cmd{\preindexhook} is called after the title is typeset and +before the twocolumn index\index{index} listing starts. By default it does nothing but +can be changed. For example +\begin{lcode} +\renewcommand{\preindexhook}{Bold page numbers are used to indicate +the main reference for an entry.} +\end{lcode} + + +\begin{syntax} +\cmd{\index}\oarg{file}\marg{item} \\ +\cmd{\specialindex}\marg{file}\marg{counter}\marg{item} \\ +\end{syntax} +The macro \cmd{\index} writes its \meta{item} argument to an \ixfile{idx} +file. If the optional \meta{file} argument is given then it will write +to \file{file.idx} otherwise it writes to \file{jobname.idx}. The page for +the \meta{item} is also written to the \file{idx} file. +The \cmd{\specialindex} macro writes its \meta{item} argument to the +\file{file.idx} and also writes the page number (in parentheses) and +the value of the \meta{counter}. This means that indexing can be with +respect to something other than page numbers. However, if the \Lpack{hyperref} +package is used the special index links will be to pages even though they +appear to be with respect to the \meta{counter}; for example, +if figure numbers are used as the index reference the hyperref link will be +to the page where the figure appears and not the figure itself. + +\begin{syntax} +\cmd{\see}\marg{item} \cmd{\seename} \\ +\cmd{\seealso}\marg{items} \cmd{\alsoname} \\ +\end{syntax} +The macro \cmd{\see} can be used in an \cmd{\index} command to tell the +reader to `see \meta{item}' instead of printing a page number. Likewise +the \cmd{\seealso} macro directs the reader to `see also \meta{items}'. +For example: +\begin{lcode} +\index{Alf|see{Alfred}} +\index{Frederick|seealso{Fred, Rick}} +\end{lcode} +The actual values for `see' and `see also' are given by the +\cmd{\seename} and \cmd{\alsoname} macros whose default +definitions are: +\begin{lcode} +\newcommand{\seename}{see} +\newcommand{\alsoname}{see also} +\end{lcode} + +\begin{syntax} +\cmd{\reportnoidxfilefalse} \\ +\cmd{\reportnoidxfiletrue} \\ +\end{syntax} +Following the declaration \cmd{\reportnoidxfilefalse}, which is the default, +LaTeX will silently pass over attempts to use an \ixfile{idx} file which has +not been declared via \cmd{\makeindex}. After the declaration +\cmd{\reportnoidxfiletrue} LaTeX will whinge about any attempts to +write to an unopened file. + +\begin{syntax} +\cmd{\showindexmarktrue} \\ +\cmd{\showindexmarkfalse} \\ +\end{syntax} +After the declaration \cmd{\showindexmarktrue} (practically) +all \cmd{\index} and +\cmd{\specialindex} \meta{item} arguments are listed in the margin of +the page on which the index command is issued. The default is +\cmd{\showindexmarkfalse}. + +\subsubsection{Indexing and the \Lpack{natbib} package} + + The \Lpack{natbib} package~\cite{NATBIB} will make an index +of citations if +\cmd{\citeindextrue} is put in the preamble after the \Lpack{natbib} +package is called for. + +\begin{syntax} +\cmd{\citeindexfile} \\ +\end{syntax} +The name of the file for the citation index is stored in the +macro \cmd{\citeindexfile}. This is initially defined as: +\begin{lcode} +\newcommand{\citeindexfile}{\jobname} +\end{lcode} +That is, the citation entries will be written to the default +\ixfile{idx} file. +This may be not what you want so you can change this, for example to: +\begin{lcode} +\renewcommand{\citeindexfile}{names} +\end{lcode} +If you do change \cmd{\citeindexfile} then you have to put +\begin{lcode} +\makeindex[\citeindex] +\end{lcode} +\emph{before} +\begin{lcode} +\usepackage[...]{natbib} +\end{lcode} + + So, there are effectively two choices, either along the lines of +\begin{lcode} +\renewcommand{\citeindexfile}{authors} % write to authors.idx +\makeindex[\citeindexfile] +\usepackage{natbib} +\citeindextrue +... +\renewcommand{\indexname}{Index of citations} +\printindex[\citeindexfile] +\end{lcode} +or along the lines of +\begin{lcode} +\usepackage{natbib} +\citeindextrue +\makeindex +... +\printindex +\end{lcode} + +\subsubsection{Populating the \file{idx} file} + + In the standard classes, indexed items are written directly to an +\ixfile{idx} file. With the class, however, the indexed items are +written to the \ixfile{aux} file and then on the next LaTeX run the +indexed items in the \ixfile{aux} file are written to the designated +\ixfile{idx} file. + + The disadvantage of this two stage process is that after any change to +the indexed items LaTeX has to be run twice to ensure that the change +is propagated to the \ixfile{idx} file. Then, of course, a new \ixfile{ind} +will have to be created and LaTeX run one more time. However, this process +is very similar to what you have to do if you are using BibTeX to create +a bibliography. + + The advantage of the approach is that indexed items from \cmd{\include} +files that are not processed on a particular run are not lost. The +standard direct write to an \ixfile{idx} file loses any `non-inluded' +indexed items. + +\index{index|)} + + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\chapterstyle{hangnum} +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + \chapter{Captions and floats} \label{chap:captions} + +This chapter uses the \cstyle{hangnum} chapterstyle. Section numbers +are also hung into the margin\index{margin} to match via the declaration \cmd{\hangsecnum}. +\hangsecnum + +\newcommand{\pname}{ccaption} + + \section{Introduction} + +\index{caption|(} + + Some publishers require, and some authors prefer, captioning styles + other than the one style provided by standard LaTeX. This chapter +describes how you can implement your own captioning style. + + Some publishers require that documents that include multi-part + tables\index{table} use a \textit{continuation caption} on all but the first + part of the multi-part table\index{table}. For the times where such a table\index{table} + is specified by the author as a set of tables\index{table}, the + class + provides a simple `continuation' caption command to meet this + requirement. It also provides + a facility for an `anonymous' caption which can be used in any + float\index{float} environment. + Captions can be defined that are suitable for use in non-float + environments, such as placing a picture in a minipage and captioning + it just as though it had been put into a normal figure\index{figure} environment. + Further, a mechanism is provided for defining new float\index{float} environments. + + The commands and environments described below are very similar to +those supplied by the \Lpack{ccaption} package~\cite{CCAPTION}. + + \section{Captions} + + + \subsection{Changing the caption style} + +\index{caption!style|(} + +\begin{syntax} +\cmd{\captiondelim}\marg{delim} \\ +\end{syntax} + The default captioning style is to put a delimeter in the form + of a colon between the caption + number and the caption title. The command \cmd{\captiondelim} + can be used to change the delimeter. For example, to have an en-dash instead + of the colon, |\captiondelim{-- }| will do the trick. Notice that no space is + put between the delimeter and the title unless it is specified in the + \meta{delim} parameter. + The class initially specifies |\captiondelim{: }| + to give the normal delimeter. + +\begin{syntax} +\cmd{\captionnamefont}\marg{fontspec} \\ +\end{syntax} + The \meta{fontspec} specified by \cmd{\captionnamefont} is used + for typesetting the caption name; that is, the first part of the caption + up to and including the delimeter (e.g., the portion `Table 3:'). + \meta{fontspec} can be any kind of font specification and/or command and/or + text. This first part of the caption is treated like: +|{\captionnamefont Table 3: }|, + so font declarations, not font text-style commands, are needed for \meta{fontspec} + For instance, |\captionnamefont{\Large\sffamily}| to specify a large +sans-serif font. + The class initially specifies |\captionnamefont{}| + to give the normal font. + + +\begin{syntax} +\cmd{\captiontitlefont}\marg{fontspec} \\ +\end{syntax} + Similarly, the \meta{fontspec} specified by \cmd{\captiontitlefont} + is used for typesetting the title text of a caption. For example, + |\captiontitlefont{\itshape}| for an italic title text. + The class initially specifies |\captiontitlefont{}| + to give the normal font. + +\begin{syntax} +\cmd{\captionstyle}\oarg{short}\marg{normal} \\ +\cmd{\raggedleft} \cmd{\centering} \cmd{\raggedright} \cmd{centerlastline} \\ +\end{syntax} +Caption styles are set according to the \cmd{\captionstyle} declaration. +Unless the optional \meta{short} argument is given all captions are typeset +according to \meta{normal}. If the optional \meta{short} argument +is specififed, captions that are less than one line in length are typeset +according to \meta{short}. + By default the name and title of a caption are typeset as a block + (non-indented) + paragraph\index{paragraph!block}. + + Sensible values for the arguments include: +\cmd{\raggedleft}, \cmd{\centering}, \cmd{\raggedright}, and + \cmd{centerlastline}. The class initially specifies +\begin{lcode} +\captionstyle{} +\end{lcode} +which gives the block paragraph style. The \cmd{\centerlastline} style +gives a block paragraph\index{paragraph!block} but with the last +line centered. + + +\begin{syntax} +\cmd{\hangcaption} \\ +\cmd{\indentcaption}\marg{length} \\ +\cmd{\normalcaption} \\ +\end{syntax} + The command \cmd{\hangcaption} will cause captions to be typeset +with the second + and later lines of a multiline caption title indented by the width + of the caption name. The command \cmd{\indentcaption} + will indent title lines after the first by \meta{length}. These + commands are independent of the |\captionstyle{...}|. Note that a + caption will not be simultaneously hung and indented. The \cmd{\normalcaption} + command undoes any previous \cmd{\hangcaption} or \cmd{\indentcaption} command. + The class initially specifies \cmd{\normalcaption} + to give the normal non-indented paragraph\index{paragraph!indentation} style. + +\begin{syntax} +\cmd{\changecaptionwidth} \\ +\cmd{\captionwidth}\marg{length} \\ +\cmd{\normalcaptionwidth} \\ +\end{syntax} + Issuing the command \cmd{\changecaptionwidth} will cause the captions to + be typeset within a total width \meta{length} as specified by + \cmd{\captionwidth}. Issuing the command \cmd{\normalcaptionwidth} + will cause captions to be typeset as normal full width captions. + The class initially specifies \cmd{\normalcaptionwidth} and + |\captionwidth{\linewidth}| + to give the normal width. If a caption is being set within the + side captioned environments from the \Lpack{sidecap} package~\cite{SIDECAP} + then it must be a \cmd{\normalcaptionwidth} caption. + +\begin{syntax} +\cmd{\precaption}\marg{pretext} \\ +\cmd{\postcaption}\marg{posttext} \\ +\end{syntax} + The commands \cmd{\precaption} and + \cmd{\postcaption} + specify \meta{pretext} and \meta{posttext} that will be processed at the + start and end of a caption. For example +\begin{lcode} +\precaption{\rule{\linewidth}{0.4pt}\par} +\postcaption{\rule{\linewidth}{0.4pt}} +\end{lcode} + will draw a horizontal line above and below the captions. + The class initially specifies |\precaption{}| and |\postcaption{}| + to give the normal appearance. + + + If any of the above commands are used in a float\index{float}, or other, environment + their effect is limited to the environment. If they are used in the preamble\index{preamble} + or the main text, their effect persists until replaced by a similar + command with a different parameter value. The commands do not affect the + apperance of the title in any \listofx. + +\begin{syntax} +\cmd{\\}\oarg{length} \\ +\cmd{\\*}\oarg{length} \\ +\end{syntax} + The normal LaTeX command \cmd{\\} can be used within the + caption text to start a new line. Remember that \cmd{\\} is a fragile + command, so if it is + used within text that will be added to a \listofx{} + it must be protected. + As examples: +\begin{lcode} +\caption{Title with a \protect\\ new line in both the body and List of} +\caption[List of entry with no new line]{Title with a \\ new line} +\caption[List of entry with a \protect\\ new line]{Title text} +\end{lcode} + + Effectively, a caption is typeset as though it were: + \begin{lcode} + \precaption + {\captionnamefont NAME NUMBER \captiondelim} + {\captionstyle\captiontitlefont THE TITLE} + \postcaption + \end{lcode} + Replacing the above commands by their defaults leads to the simple + format: \\ + |{NAME NUMBER: }{THE TITLE}| + + As well as using the styling commands to make simple changes to the + captioning style more noticeable modifications can also be made. + To change the captioning style so that the name and title are typeset in + a sans font it is sufficient to do: + \begin{lcode} + \captionnamefont{\sffamily} + \captiontitlefont{\sffamily} + \end{lcode} + + \begin{table} + \centering + \captionnamefont{\sffamily} + \captiondelim{} + \captionstyle{\\} + \captiontitlefont{\scshape} + \setlength{\belowcaptionskip}{10pt} + \caption{Redesigned table caption style} \label{tab:style} + \begin{tabular}{lr} \hline + three & III \\ + five & V \\ + eight & VIII \\ \hline + \end{tabular} + \end{table} + + A more obvious change in styling is shown in \tref{tab:style}, + which was coded as: + \begin{lcode} + \begin{table} + \centering + \captionnamefont{\sffamily} + \captiondelim{} + \captionstyle{\\} + \captiontitlefont{\scshape} + \setlength{\belowcaptionskip}{10pt} + \caption{Redesigned table caption style} \label{tab:style} + \begin{tabular}{lr} \hline + ... + \end{table} + \end{lcode} + This leads to the approximate caption format (processed within |\centering|): \\ + |{\sffamily NAME NUMBER}{\\ \scshape THE TITLE}| \\ + Note that the newline command (\cmd{\\}) cannot be put in the first part + of the format (i.e., the |{\sffamily NAME NUMBER}|); it has to go into + the second part, which is why it is specified via |\captionstyle{\\}| + and not |\captiondelim{\\}|. + + If a mixture of captioning styles will be used you may want to + define a special caption command for each non-standard style. For + example for the style of the caption in \tref{tab:style}: + \begin{lcode} + \newcommand{\mycaption}[2][\@empty]{ + \captionnamefont{\sffamily\hfill} + \captiondelim{\hfill} + \captionstyle{\centerlastline\\} + \captiontitlefont{\scshape} + \setlength{\belowcaptionskip}{10pt} + \ifx #1\@empty \caption{#2}\else \caption[#1]{#2}} + \end{lcode} + \textbf{NOTE:} Any code that involves the |@| sign must be either in + a package (\file{.sty}) file or enclosed between a \cmd{\makeatletter} \ldots + \cmd{\makeatother} pairing. + + The code for the \tref{tab:style} example can now be written as: + \begin{lcode} + \begin{table} + \centering + \mycaption{Redesigned table caption style} \label{tab:style} + \begin{tabular}{lr} \hline + ... + \end{table} + \end{lcode} + Note that in the code for |\mycaption| I have added two + \cmd{\hfill} commands and \cmd{\centerlastline} compared with the original + specification. + It turned out that the original definitions + worked for a single line caption but not for a multiline caption. + The additional commands makes it work in both cases, forcing the + name to be centered as well as the last line of a multiline title, + thus giving a balanced appearence. + + \index{caption!style|)} + + + \subsection{Continuation captions and legends} + +\index{caption!continuation|(} + +\begin{syntax} +\cmd{\contcaption}\marg{text} \\ +\end{syntax} + The \cmd{\contcaption} command can be used to put + a `continuation' or `concluded' + caption into a float\index{float} environment. It neither increments the + float number nor makes any entry into a float listing, but it + does repeat the numbering of the previous \cmd{\caption} command. + + + Table~\ref{tab:m} illustrates the use of the \cmd{\contcaption} + command. The table\index{table} was produced from the following code. + \begin{lcode} + \begin{table} + \centering + \caption{A multi-part table} \label{tab:m} + \begin{tabular}{lc} \hline + just a single line & 1 \\ \hline + \end{tabular} + \end{table} + + \begin{table} + \centering + \contcaption{Continued} + \begin{tabular}{lc} \hline + just a single line & 2 \\ \hline + \end{tabular} + \end{table} + + \begin{table} + \centering + \contcaption{Concluded} + \begin{tabular}{lc} \hline + just a single line & 3 \\ \hline + \end{tabular} + \end{table} + \end{lcode} + + \begin{table} + \centering + \caption{A multi-part table} \label{tab:m} + \begin{tabular}{lc} \hline + just a single line & 1 \\ \hline + \end{tabular} + \end{table} + + \begin{table} + \centering + \contcaption{Continued} + \begin{tabular}{lc} \hline + just a single line & 2 \\ \hline + \end{tabular} + \end{table} + + \begin{table} + \centering + \contcaption{Concluded} + \begin{tabular}{lc} \hline + just a single line & 3 \\ \hline + \end{tabular} + \end{table} + +\index{caption!continuation|)} + +\index{legend} +\index{caption!anonymous|(} + +\begin{syntax} +\cmd{\legend}\marg{text} \\ +\end{syntax} + The \cmd{\legend} command is intended to be used to put an + anonymous + caption into a float\index{float} environment, but may be used anywhere. + + \begin{table} + \centering + \caption{Another table} \label{tab:legend} + \begin{tabular}{lc} \hline + A legendary table & 5 \\ + with two lines & 6 \\ \hline + \end{tabular} + \legend{The legend} + \end{table} + + For example, the following code was used to produce the two-line + \tref{tab:legend}. The \cmd{\legend} command can be used within a + float\index{float} + independently of any \cmd{\caption} command. + \begin{lcode} + \begin{table} + \centering + \caption{Another table} \label{tab:legend} + \begin{tabular}{lc} \hline + A legendary table & 5 \\ + with two lines & 6 \\ \hline + \end{tabular} + \legend{The legend} + \end{table} + \end{lcode} + + \marginpar{\legend{Title legend} + This is a marginal note with a legend.} + + Captioned floats\index{float} are usually thought of in terms of the |table| + and |figure|\index{figure} environments. There can be other kinds of +float\index{float}. + As perhaps a more interesting example, the following code produces + the titled marginal\index{marginalia} note which should be displayed near here. + \begin{lcode} + \marginpar{\legend{Title legend} + This is a marginal note with a legend.} + \end{lcode} + + If you want the legend text to be included in the \listofx{} + use the \cmd{\addcontentsline} command in conjunction with the + \cmd{\legend}. For example: + \begin{lcode} + \addcontentsline{lot}{table}{Titling text} % left justifified + \addcontentsline{lot}{table}{\protect\numberline{}Titling text} % indented + \end{lcode} + The first of these forms will align the first line of the legend text + under the normal table\index{table} numbers. The second form will align the first + line of the legend text under the normal table\index{table} titles. In either case, + second and later lines of a multi-line text will be aligned under + the normal title lines. + + \begin{table} + \centering + \captiontitlefont{\sffamily} + \legend{Legendary table} + \addcontentsline{lot}{table}{Legendary table (toc 1)} + \addcontentsline{lot}{table}{\protect\numberline{} + Legendary table (toc 2)} + \begin{tabular}{lc} \hline + An anonymous table & 5 \\ + with two lines & 6 \\ \hline + \end{tabular} + \end{table} + + As an example, the \textsf{Legendary table} is produced by the following code: + \begin{lcode} + \begin{table} + \centering + \captiontitlefont{\sffamily} + \legend{Legendary table} + \addcontentsline{lot}{table}{Legendary table (toc 1)} + \addcontentsline{lot}{table}{\protect\numberline{}Legendary table (toc 2)} + \begin{tabular}{lc} \hline + An anonymous table & 5 \\ + with two lines & 6 \\ \hline + \end{tabular} + \end{table} + \end{lcode} + Look at the List of Tables to see how the two forms of \cmd{\addcontentsline} + are typeset. + + As with the \cmd{\caption} command, the spacing before and after + a legend is controlled by the \lnc{\abovecaptionskip} and +\lnc{\belowcaptionskip} lengths. + +\begin{syntax} +\cmd{\namedlegend}\oarg{short-title}\marg{long-title} \\ +\end{syntax} + As a convenience, the \cmd{\namedlegend} + command is like the \cmd{\caption} command except that it does not number + the caption and, by default, puts no entry into a \listofx{} file. Like + the \cmd{\caption} command, it picks up the name to be prepended to the + title text from the float\index{float} environment in which it is called (e.g., + it will use \cmd{\tablename} if called within a |table| environment). The + following code is the source of the \textit{Named legendary table}. + \begin{lcode} + \begin{table} + \centering + \captionnamefont{\sffamily} + \captiontitlefont{\itshape} + \namedlegend{Named legendary table} + \begin{tabular}{lr} \hline + seven & VII \\ + eight & VIII \\ \hline + \end{tabular} + \end{table} + \end{lcode} + + \begin{table} + \centering + \captionnamefont{\sffamily} + \captiontitlefont{\itshape} + \namedlegend{Named legendary table} + \begin{tabular}{lr} \hline + seven & VII \\ + eight & VIII \\ \hline + \end{tabular} + \end{table} + +\begin{syntax} +\cmd{\flegtype}\marg{name} \\ +\cmd{\flegtoctype}\marg{title} \\ +\end{syntax} + The macro \cmd{\flegtype}, where |type| is the name + of a float\index{float} environment + (e.g., |table|) is called by the \cmd{\namedlegend} macro. It is provided + as a hook that defines the \meta{name} to be used as the name in + \cmd{\namedlegend}. Two defaults are provided, namely: + \begin{lcode} + \newcommand{\flegtable}{\tablename} + \newcommand{\flegfigure}{\figurename} + \end{lcode} + which may be altered via \cmd{\renewcommand} if desired. + The macro \cmd{\flegtoctype}, where again |type| is the name + of a float\index{float} environment + (e.g., |table|) is also called by the \cmd{\namedlegend} macro. It is provided + as a hook that can be used to add \meta{title} to the \listofx. + By default it is defined to do nothing, and can be changed via +\cmd{\renewcommand}. For instance, it could be changed for tables\index{table} as: + \begin{lcode} + \renewcommand{\flegtoctable}[1]{ + \addcontentsline{lot}{table}{#1}} + \end{lcode} + + The \cmd{\legend} command produces a plain, unnumbered heading. It can also + be useful sometimes to have named and numbered captions outside + a floating\index{float} environment, perhaps in a |minipage| if you want the table\index{table} + or picture\index{illustration} to appear at a precise location in your document. + +\index{caption!anonymous|)} + +\index{caption!fixed|(} + +\begin{syntax} +\cmd{\newfixedcaption}\oarg{capcommand}\marg{command}\marg{float} \\ +\cmd{\renewfixedcaption}\oarg{capcommand}\marg{command}\marg{float} \\ +\cmd{\providefixedcaption}\oarg{capcommand}\marg{command}\marg{float} \\ +\end{syntax} + The \cmd{\newfixedcaption} + command, and its friends, can be used to create a new captioning + \meta{command} that may be used outside the float\index{float} environment \meta{float}. + Both the environment \meta{float} and a captioning command, + \meta{capcommand}, for that environment must have been defined before + calling \cmd{\newfixedcaption}. Note that \cmd{\namedlegend} can be used + as \meta{capcommand}. + The \cmd{\renewfixedcaption} and \cmd{\providefixedcaption} commands take the same + arguments as \cmd{\newfixedcaption}; the three commands are analagous + to those in the \cmd{\newcommand} family. + + For example, to define a new |\figcaption| command for captioning pictures + outside the |figure|\index{figure} environment, do\\ + |\newfixedcaption{\figcaption}{figure}| \\ + The optional \meta{capcommand} argument is the name of the float\index{float} + captioning command that is being aliased. It defaults to \cmd{\caption}. + As another example, where the optional argument is required, if you + want to create a new continuation caption command for non-floating + tables\index{table}, say |\ctabcaption|, then do \\ + |\newfixedcaption[\contcaption]{\ctabcaption}{table}| + + Captioning commands created by \cmd{\newfixedcaption} will be named and + numbered in the same style as the original \meta{capcommand}, can + be given a \cmd{\label}, and will appear in the appropriate + \listofx. They can also be used within floating\index{float} + environments, but will not use the environment name as a guide to + the caption name or entry into the \listofx. For + example, using |\ctabcaption| in a |figure|\index{figure} environment will still + produce a \textbf{Table\ldots} named caption. + + Sometimes captions are required on the opposite page to a figure\index{figure}, and + \cmd{\newfixedcaption} can be useful in this context. For example, if +figure\index{figure} + captions should be placed on an otherwise empty page immediately before + the actual figure\index{figure}, then this can be accomplished by the following hack: + \begin{lcode} + \newfixedcaption{\figcaption}{figure} + ... + \afterpage{ % fill current page then flush pending floats + \clearpage + \begin{midpage} % vertically center the caption + \figcaption{The caption} % the caption + \end{midpage} + \clearpage + \begin{figure}THE FIGURE, NO CAPTION HERE\end{figure} + \clearpage + } % end of \afterpage + \end{lcode} + Note that the \Lpack{afterpage} package~\cite{AFTERPAGE} is required, +which is part of the + required tools bundle. The \Lpack{midpage} package supplies the |midpage| + environment, which can be simply defined as: + \begin{lcode} + \newenvironment{midpage}{\vspace*{\fill}}{\vspace*{\fill}} + \end{lcode} + The code might need adjusting to meet your particular requirements. + The \cmd{\cleartoevenpage} command ensures that you get to the next + even-numbered page (the \cmd{\cleardoublepage} gets you to the next odd-numbered + page and \cmd{\clearpage} gets you to the next page which may be odd or even). + +\index{caption!fixed|)} + + \subsection{Bilingual captions} + +\index{caption!bilingual|(} + + Some documents require bilingual (or more) captions. The class + provides a set of commands for bilingual captions. Extensions to the + set, perhaps to support trilingual captioning, are left as an exercise + for the document author. + +\begin{syntax} +\cmd{\bitwonumcaption}\oarg{label}\marg{short1}\marg{long1}\marg{NAME}\marg{short2}\marg{long2} \\ +\cmd{\bionenumcaption}\oarg{label}\marg{short1}\marg{long1}\marg{NAME}\marg{short2}\marg{long2} \\ +\end{syntax} + Bilingual captions can be typeset by the \cmd{\bitwonumcaption} + command which has six arguments. + The first, optional argument \meta{label}, is the name of a label, if + required. + \meta{short1} and \meta{long1} are the short (i.e., equivalent + to the optional argument + to the \cmd{\caption} command) and long caption texts for + the main language of the document. The value of the \meta{NAME} argument + is used as the caption name for the second language caption, while + \meta{short2} and \meta{long2} are the short and long caption texts + for the second language. For example, if the main and secondary languages + are English and German and a figure\index{figure} is being captioned: \\ + |\bitwonumcaption{Short}{Long}{Bild}{Kurz}{Lang}| \\ + If the short title text(s) is not required, then leave the appropriate + argument(s) either empty or as one or more spaces, like: \\ + |\bitwonumcaption[fig:bi1]{}{Long}{Bild}{ }{Lang}| \\ + Both language texts are entered into the appropriate \listofx, + and both texts are numbered. + + Figure~\ref{fig:bi1} is an example of using the above code. + \begin{figure} + \centering + EXAMPLE FIGURE WITH BITWONUMCAPTION + \bitwonumcaption[fig:bi1]{}{Long \cs{bitwonumcaption}}{Bild}{ }{Lang \cs{bitwonumcaption}} + \end{figure} + + The \cmd{\bionenumcaption} command takes the same arguments as +\cmd{\bitwonumcaption}. + The difference between the two commands is that \cmd{\bionenumcaption} does + not number the second language text in the \listofx. + Figure~\ref{fig:bi3} is an example of using \cmd{\bionenumcaption}. + \begin{figure} + \centering + EXAMPLE FIGURE WITH BIONENUMCAPTION + \bionenumcaption[fig:bi3]{}{Long English \cs{bionenumcaption}}{Bild}{ }{Lang Deutsch \cs{bionenumcaption}} + \end{figure} + +\begin{syntax} +\cmd{\bicaption}\oarg{label}\marg{short1}\marg{long1}\marg{NAME}\marg{long2} \\ +\end{syntax} + When bilingual captions are typeset via the \cmd{\bicaption} + command the second language text is not put into + the \listofx. The command + takes 5 arguments. + The optional \meta{label} is for a label if required. + \meta{short1} and \meta{long1} are the short and long caption texts for + the main language of the document. The value of the \meta{NAME} argument + is used as the caption name for the second language caption. The last + argument, \meta{long2}, is the caption text + for the second language (which is not put into the \listofx). + For example, if the main and secondary languages + are English and German: \\ + |\bicaption{Short}{Long}{Bild}{Langlauf}| \\ + If the short title text is not required, then leave the appropriate + argument either empty or as one or more spaces. + + Figure~\ref{fig:bi2} is an example of using \cmd{\bicaption} and was + produced by the following code: + \begin{lcode} + \begin{figure} + \centering + EXAMPLE FIGURE WITH A RULED BICAPTION + \precaption{\rule{\linewidth}{0.4pt}\par} + \midbicaption{\precaption{}\postcaption{\rule{\linewidth}{0.4pt}}} + \bicaption[fig:bi2]{Short English \cs{bicaption}}{Longingly}{Bild}{Langlauf} + \end{figure} + \end{lcode} + + \begin{figure} + \centering + EXAMPLE FIGURE WITH A RULED BICAPTION + \precaption{\rule{\linewidth}{0.4pt}\par} + \midbicaption{\precaption{}\postcaption{\rule{\linewidth}{0.4pt}}} + \bicaption[fig:bi2]{Short English \cs{bicaption}}{Longingly}{Bild}{Langlauf} + \end{figure} + +\begin{syntax} +\cmd{\bicontcaption}\marg{long1}\marg{NAME}\marg{long2} \\ +\end{syntax} + Bilingual continuation captions can be typeset via the \cmd{\bicontcaption} + command. In this case, neither language text is put into + the \listofx. The command + takes 3 arguments. + \meta{long1} is the caption text for + the main language of the document. The value of the \meta{NAME} argument + is used as the caption name for the second language caption. The last + argument, \meta{long2}, is the caption text + for the second language. + For example, if the main and secondary languages + are again English and German: \\ + |\bicontcaption{Continued}{Bild}{Fortgefahren}| + +\begin{syntax} + \cmd{\midbicaption}\marg{text} \\ +\end{syntax} + The bilingual captions are implemented by calling \cmd{\caption} twice, + once for each language. The command \cmd{\midbicaption}, + which is similar to the \cmd{\precaption} and \cmd{\postcaption} commands, + is executed + just before calling the second \cmd{\caption}. Among other things, + this can be used to + modify the style of the second caption with respect to the first. + For example, if there is a line above and below normal + captions, it is probably undesirable to have a double line in the + middle of a bilingual caption. So, for bilingual captions the + following may be done within the float\index{float} before the caption: + \begin{lcode} + \precaption{\rule{\linewidth}{0.4pt}\par} + \postcaption{} + \midbicaption{\precaption{}\postcaption{\rule{\linewidth}{0.4pt}}} + \end{lcode} + This sets a line before the first of the two captions, then the + \cmd{\midbicaption}{...} nulls the pre-caption line and adds a post-caption + line for the second caption. The class initially specifies + |\midbicaption{}|. + +\index{caption!bilingual|)} + + \subsection{Subcaptions} + +\index{caption!subcaption|(} + + The \Lpack{subfigure} package~\cite{SUBFIGURE} enables the captioning of +sub-figures\index{figure!sub-} within a larger figure\index{figure}, +and similarly for tables\index{table}. The \Lpack{subfigure} package may +be used with the class, or you can use the class commands described below. +These commands can only be used inside a float environment for which a +subfloat\footnote{See \S\ref{sec:newsub} on \pref{sec:newsub}.} +has been specified. + +\begin{syntax} +\cmd{\subcaption}\oarg{list-entry}\marg{subcaption} \\ +\end{syntax} +The \cmd{\subcaption} command is similar to the \cmd{caption} command. It +typesets an identified \meta{subcaption}, where the identification is +an alphabetic character enclosed in parentheses. If the optional +\meta{list-entry} argument is present, \meta{list-entry} is added to +the caption listings for the float. If it is not present, then +\meta{subcaption} is added to the listing. The \cmd{\subcaption} macro +should only be used in a fixed width box of some sort, for example +a |minipage| environment, as the \meta{subcaption} will be typeset using +a box which is the width of the environment. + + For example: +\begin{lcode} +\begin{figure} + \centering + \begin{minipage}{0.3\textwidth} + \verb?Some verbatim text? + \subcaption{First text} + \end{minipage} + \hfill + \begin{minipage}{0.3\textwidth} + \verb?More verbatim text? + \subcaption{Second text} + \end{minipage} + \caption{Verbatim texts} +\end{figure} +\end{lcode} + + +If a +figure that\index{figure} + includes sub-figures\index{figure!sub-} is itself continued then it may be desireable to + continue the captioning of the sub-figures. For example, if Figure~3 + has three sub-figures, say A, B and C, and Figure~3 is continued then + the sub-figures\index{figure!sub-} in the continuation should be D, E, etc. +\begin{syntax} +\cmd{\contsubcaption}\oarg{list-entry}\marg{subcaption} \\ +\end{syntax} +The \cmd{\contsubcaption} command is the continued version of +\cmd{\subcaption}. + + +\begin{syntax} +\cmd{\label}|(|\meta{bookmark}|)|\marg{key} \\ +\cmd{\subcaptionref}\marg{key} \\ +\end{syntax} + A \cmd{\label} command may be included in the \meta{subcaption} argument +of \cmd{\subcaption} or \cmd{\contsubcaption}. +Using \cmd{\ref} to refer to the label will typeset the number of the float +(obtained from a labelled \cmd{\caption}) and the subcaption identifier. On +the other hand, using \cmd{\subcaptionref} will typeset just the subcaption +identifier. + + In case the \Lpack{hyperref} package is used, the \cmd{\label} +command when used inside a \meta{subcaption} argument can take an optional +argument, \emph{enclosed in parentheses \emph{not} square brackets}, +\meta{bookmark} which will create a bookmark field of the form +`Subfigure 3.2(c)'. + +\begin{syntax} +\cmd{\tightsubcaptions} \cmd{\loosesubcations} \\ +\end{syntax} +The \cmd{\tightsubcaptions} declaration will put little vertical space +around the subcaption, while \cmd{\loosesubcaptions} will add more +whitespace. The default is \cmd{\tightsubcaptions}. + +\begin{syntax} +\cmd{\subcaptionsize}\marg{font-size} \\ +\cmd{\subcaptionlabelfont}\marg{fontspec} \\ +\cmd{\subcaptionfont}\marg{fontspec} \\ +\end{syntax} +The size of the font used for subcaptions is set by \cmd{\subcaptionsize}. +The default is: +\begin{lcode} +\subcaptionsize{\footnotesize} +\end{lcode} +The fonts used for the identifier and the subcaption are set by +\cmd{\subcaptionlabelfont} and \cmd{\subcaptionfont}, respectively, +where \meta{fontspec} is one or more font style declarations (e.g., +|\bfseries\slshape| for a bold, slanted font). +The defaults are: +\begin{lcode} +\subcaptionlabelfont{\normalfont} +\subcaptionfont{\normalfont} +\end{lcode} + +\begin{syntax} +\cmd{\subcaptionstyle}\marg{style} \\ +\end{syntax} + By default the identifier and title of a subcaption are typeset as a block +(non-indented) paragraph\index{paragraph!block}. +\cmd{\subcaptionstyle} can be used to alter this. +Sensible values for \meta{style} are: \cmd{\centering}, \cmd{\raggedleft} or +\cmd{\raggedright} for styles corresponding to these declarations. +The \cmd{\centerlastline} style gives a block +paragraph\index{paragraph!block} but with the last line centered. +The class initially specifies |\subcaptionstyle{}| +to give the normal block paragraph style. + +\begin{syntax} +\cmd{\hangsubcaption} \\ +\cmd{\shortsubcaption} \\ +\cmd{\normalsubcaption} \\ +\end{syntax} + The \cmd{\hangsubcaption} declaration causes subcaptions to be typeset +with the identifier above the title. With the \cmd{\shortsubcaption} +declaration subcaptions that are less than one line in length are +typeset left justified instead of centered. +The \cmd{\normalsubcaption} command undoes any previous +\cmd{\hangsubcaption} or \cmd{\shortsubcaption} command. +The class initially specifies \cmd{\normalcaption}. + +\begin{syntax} + \cmd{\subtop}\oarg{list-entry}\oarg{subcaption}\marg{text} \\ + \cmd{\subbottom}\oarg{list-entry}\oarg{subcaption}\marg{text} \\ +\end{syntax} + The command \cmd{\subtop} puts a subcaption number on top of +the \meta{text}. If both optional arguments are present, \meta{list-entry} +will be added to the appropriate listing, and an alphabetic identifier +and \meta{subcaption} will be placed above \meta{text}. If only one +optional argument is present, this is treated as \meta{subcaption}; the +identifier and \meta{subcaption} are placed above \meta{text} and +\meta{subcaption} is added to the listing. In all cases, the identifier +is placed above \meta{text} and added to the listing. + + The \cmd{\subbottom} command is similar, except that the identifier +and any \meta{subcaption} is placed below the \meta{text}. + + The main caption can be at either the top or the bottom of the float. + + For example: +\begin{lcode} +\begin{figure} +\subbottom{...} % captioned as (a) below +\subtop{...} % captioned as (b) above +\caption{...} +\end{figure} +\end{lcode} + + As another example, \fref{subfig:sf} and the next paragraph +was produced by the code below. + +\begin{figure} +\centering +\subbottom[Subfigure 1]{\fbox{SUBFIGURE ONE}\label{sf:1}} +\hfill +\subbottom[Subfigure 2]{\fbox{SUBFIGURE TWO}\label{sf:2}} +\caption{Figure with two subfigures} \label{subfig:sf} +\end{figure} + + Figure \ref{subfig:sf} has two subfigures, namely \ref{sf:1} +and \subcaptionref{sf:2}. + +\begin{lcode} + Figure \ref{subfig:sf} has two subfigures, namely \ref{sf:1} +and \subcaptionref{sf:2}. +\begin{figure} +\centering +\subbottom[Subfigure 1]{\fbox{SUBFIGURE ONE}\label{sf:1}} +\hfill +\subbottom[Subfigure 2]{\fbox{SUBFIGURE TWO}\label{sf:2}} +\caption{Figure with two subfigures} \label{subfig:sf} +\end{figure} +\end{lcode} + + + The major difference between the \cmd{\subcaption} command and the +\cmd{\subtop} and \cmd{\subbottom} commands, apart from the \meta{text} +argument, is that \cmd{\subcaption} +must be used in a fixed width environment while \cmd{\subtop} uses +the width of \meta{text} for the box in which to typeset the +\meta{subcaption}. + +\begin{syntax} + \cmd{\contsubtop}\oarg{list-entry}\oarg{subcaption}\marg{text} \\ + \cmd{\contsubbottom}\oarg{list-entry}\oarg{subcaption}\marg{text} \\ +\end{syntax} + The command \cmd{\contsubtop} + will continue the sub-caption numbering scheme across (continued) floats\index{float}, + putting the \meta{subcaption} at the top of the \meta{text}. + The \cmd{\contsubbottom} command is similar but puts the \meta{subcaption} + at the bottom of the \meta{text}. In either case, the main caption can + be at the top or bottom of the float\index{float}. + + For example: +\begin{lcode} + \begin{table} + \caption{...} + \subtop{...} % captioned as (a) above + \subtop{...} % captioned as (b) above + \end{table} + ... + \begin{table} + \contcaption{Concluded} + \contsubtop{...} % captioned as (c) above + \contsubtop{...} % captioned as (d) above + \end{table} + \end{lcode} + + As with the \cmd{\subcaption} command, a \cmd{\label} command may be +used in either the \meta{subcaption} or the \meta{text} arguments to +\cmd{\subtop} and friends. + + +\index{caption!subcaption|)} + + \subsection{How LaTeX makes captions} \label{sec:ltx} + +\index{caption!LaTeX methods|(} + + This section provides an overview of how LaTeX creates captions and + gives some examples of how to change the captioning style without + having to use any package. + The section need not be looked at more than once unless you like + reading LaTeX code + or you want to make changes to LaTeX's style of captioning. + + The LaTeX kernel provides tools to help in the definition of captions, + but it is the particular class that decides on their format. + +\begin{syntax} + \cmd{\caption}\oarg{short}\marg{long} \\ +\end{syntax} + The kernel (in \file{ltfloat.dtx}) defines the caption command via +\begin{lcode} +\def\caption{\refstepcounter\@captype \@dblarg{\@caption\@captype}} +\end{lcode} + +\begin{syntax} + \cmd{\@captype} \\ +\end{syntax} + \cmd{\@captype} is defined by the code that creates a new float\index{float} environment + and is set to the environment's name (see the code for |\@xfloat| + in \file{ltfloat.dtx}). For a |figure| environment, + there is an equivalent to +\begin{lcode} +\def\@captype{figure} +\end{lcode} + +\begin{syntax} + \cmd{\@caption}\marg{type}\oarg{short}\marg{long} \\ +\end{syntax} + The kernel also provides the \cmd{\@caption} macro as: +\begin{lcode} + \long\def\@caption#1[#2]#3{ + \par + \addcontentsline{\csname ext@#1\endcsname}{#1} <-- + {\protect\numberline{\csname the#1\endcsname}{\ignorespaces #2}} + \begingroup + \@parboxrestore + \if@minipage + \@setminipage + \fi + \normalsize + \@makecaption{\csname fnum@#1\endcsname}{\ignorespaces #3}\par <-- + \endgroup} + \end{lcode} + where \meta{type} is the name of the environment in which the caption + will be used. + Putting these three commands together results in the user's view of the caption + command as |\caption[|\meta{short}|]{|\meta{long}|}|. + + It is the responsibilty of the class (or package) which defines floats\index{float} + to provide definitions for \cmd{\ext@type}, \cmd{\fnum@type} and +\cmd{\@makecaption} + which appear in the definition of \cmd{\@caption} (in the lines marked + |<--| above). + +\begin{syntax} + \cmd{\ext@type} \\ +\end{syntax} + This macro holds the name of the extension for a \listofx{} file. + For example for the |figure| float\index{float} environment there is the + definition equivalent to +\begin{lcode} + \newcommand{\ext@figure}{lof} +\end{lcode} + +\begin{syntax} + \cmd{\fnum@type} \\ +\end{syntax} + This macro is responsible for typesetting the caption number. For example, + for the |figure| environment there is the definition equivalent to +\begin{lcode} + \newcommand{\fnum@figure}{\figurename~\thefigure} +\end{lcode} + +\begin{syntax} + \cmd{\@makecaption}\marg{number}\marg{text} \\ +\end{syntax} + The \cmd{\@makecaption} macro, where \meta{number} + is a string such as `Table~5.3' and \meta{text} is the caption text, + performs the typesetting of the caption, and + is defined in the standard classes (in \file{classes.dtx}) as the + equivalent of: +\begin{lcode} + \newcommand{\@makecaption}[2]{ + \vskip\abovecaptionskip <- 1 + \sbox\@tempboxa{#1: #2} <- 2 + \ifdim \wd\@tempboxa >\hsize + #1: #2\par <- 3 + \else + \global \@minipagefalse + \hb@xt@\hsize{\hfil\box\@tempboxa\hfil} + \fi + \vskip\belowcaptionskip} <- 4 +\end{lcode} + +\begin{syntax} + \lnc{\abovecaptionskip} + \lnc{\belowcaptionskip} \\ +\end{syntax} + Vertical space is added before and after a caption (lines marked 1 and 4 + in the code for \cmd{\@makecaption} above) and the amount of space is given + by the lengths \lnc{\abovecaptionskip} and \lnc{\belowcaptionskip}. The + standard classes set these to 10pt and 0pt respectively. If you want + to change the space before or after a caption, use \cmd{\setlength} to change + the values. In figures\index{figure}, the caption is usually placed below the + illustration\index{illustration}. The actual space between the bottom of the illustration\index{illustration} + and the baseline of the first line of the caption + is the \lnc{\abovecaptionskip} plus the \lnc{\parskip} plus the \lnc{\baselineskip}. + If the illustration\index{illustration} is in a |center| environment then additional space + will be added by the |\end{center}|; it is usually better to use + the \cmd{\centering} command rather than the |center| environment. + + The actual typesetting of a caption is effectively performed by the code + in lines marked 2 and 3 in the code for \cmd{\@makecaption}; note that + these are where the colon that is typeset after the number is specified. + If you want to + make complex changes to the default captioning style you may have to + create your own version of \cmd{\@caption} using + \cmd{\renewcommand}. On the other hand, many such changes can be achieved + by changing the definition of the + the appropriate \cmd{\fnum@type} command(s). For example, to make the + figure\index{figure} name and number bold: +\begin{lcode} +\renewcommand{\fnum@figure}{\textbf{\figurename~\thefigure}} +\end{lcode} + + REMEMBER: If you are doing anything involving commands that include + the |@| character, and it's not in a class or package file, you have + to do it within a \cmd{\makeatletter} and \cmd{\makeatother} pairing. So, + if you modify the \cmd{\fnum@figure} command anywhere in your document + it has to be done as: +\begin{lcode} + \makeatletter + \renewcommand{\fnum@figure}{......} + \makeatother +\end{lcode} + + \makeatletter + \renewcommand{\fnum@figure}{\textsc{\figurename~\thefigure}} + \makeatother + \begin{figure} + \centering + A THOUSAND WORDS\ldots + \caption{A picture is worth a thousand words}\label{fig:sc} + \end{figure} + + As an example, \fref{fig:sc} was created by the following code: +\begin{lcode} + \makeatletter + \renewcommand{\fnum@figure}{\textsc{\figurename~\thefigure}} + \makeatother + \begin{figure} + \centering + A THOUSAND WORDS\ldots + \caption{A picture is worth a thousand words}\label{fig:sc} + \end{figure} +\end{lcode} + + As another example, suppose that you needed to typeset the \cmd{\figurename} + and its number in a bold font, replace the colon that normally appears + after the number by a long dash, and typeset the actual title text in + a sans-serif font, as is illustrated by the caption for + \fref{fig:sf}. The following code does this. + + \makeatletter + \renewcommand{\fnum@figure}[1]{\textbf{\figurename~\thefigure} --- \sffamily} + \makeatother + \begin{figure} + \centering + ANOTHER THOUSAND WORDS\ldots + \caption{A different kind of figure caption}\label{fig:sf} + \end{figure} + +\begin{lcode} + \makeatletter + \renewcommand{\fnum@figure}[1]{\textbf{\figurename~\thefigure} + --- \sffamily} + \makeatother + \begin{figure} + \centering + ANOTHER THOUSAND WORDS\ldots + \caption{A different kind of figure caption}\label{fig:sf} + \end{figure} +\end{lcode} + Perhaps a little description of how this works is in order. + Doing a little bit of TeX 's macro processing by hand, the typesetting + lines in \cmd{\@makecaption} (lines 2 and 3) get instantiated like: \\ + |\fnum@figure{\figurename~\thefigure}: text| \\ + Redefining \cmd{\fnum@figure} to take one argument and then not using the + value of the argument essentially gobbles up the colon. Using \\ + |\textbf{\figurename~\thefigure}| \\ + in the definition causes \cmd{\figurename} and the number to be typeset in + a bold font. After this comes the long dash. Finally, putting \cmd{\sffamily} + at the end of the redefinition causes any following text (i.e., the actual + title) to be typeset using the sans-serif font. + + If you do modify \cmd{\@makecaption}, then spaces in the definition may be + important; also you must use the comment (\%) character in the same + places as I have done above. Hopefully, though, the class provides the +tools that you need to make most, if not all, of any likely caption styles. + +\index{caption!LaTeX methods|)} + + + \subsection{Captions with footnotes} + +\index{caption!footnote|(} +\index{footnote!in caption|(} + + If you want to have a caption with a footnote, think long and hard + as to whether this is really essential. It is not normally considered + to be good typographic practice, and to rub the point in LaTeX does not + make it necessarily easy to do. However, if you (or your publisher) + insists, read on. + + If it is present, the optional argument to \cmd{\caption} is put into + the \lof/lot{} as appropriate. If the argument is not present, then the + text of the required argument is put into the \lof. In the first case, + the optional argument is moving, and in the second case the required + argument is moving. The \cmd{\footnote} command is fragile and must be + |\protect|ed (i.e., |\protect\footnote{}|) if it is used in a moving + argument. If you don't want the footnote to appear in +the \lof, use a + footnoteless optional argument and a footnoted required argument. + + You will probably be surprised if you just do, for example: + \begin{lcode} + \begin{figure} + ... + \caption[For LoF]{For figure\footnote{The footnote}} + \end{figure} + \end{lcode} + because (a) the footnote number may be greater than you thought, and (b) + the footnote text has vanished. This latter is because LaTeX won't typeset + footnotes from a float\index{float}. To get an actual footnote within the float you + have to use a minipage, like: + \begin{lcode} + \begin{figure} + \begin{minipage}{\linewidth} + ... + \caption[For LoF]{For figure\footnote{The footnote}} + \end{minipage} + \end{figure} + \end{lcode} + If you are using the standard classes you may now find that you get two +footnotes for the price of one. Fortunately this will not occur with this +class, nor will an unexpected increase of the footnote number. + + When using a minipage as above, the footnote text is typeset at the + bottom of the minipage (i.e., within the float\index{float}). If you want the footnote + text typeset at the bottom of the page, then you have to use the + \cmd{\footnotemark} and \cmd{\footnotetext} commands like: + \begin{lcode} + \begin{figure} + ... + \caption[For LoF]{For figure\footnotemark} + \end{figure} + \footnotetext{The footnote} + \end{lcode} + This will typeset the argument of the \cmd{\footnotetext} command at the + bottom of the page where you called the command. Of course, the figure\index{figure} + might have floated\index{float} to a later page, and then it's a matter of some + manual fiddling to get everything on the same page, and possibly + to get the footnote marks\index{footnote!mark} to match correctly with the footnote text. + + At this point, you are on your own. + +\index{footnote!in caption|)} +\index{caption!footnote|)} + + +\index{caption|)} + +\section{Floats} + + + \subsection{New float environments} + +\index{float!new|(} + +\begin{syntax} + \cmd{\newfloat}\oarg{within}\marg{fenv}\marg{ext}\marg{capname} \\ +\end{syntax} + The \cmd{\newfloat} command + creates two new floating environments called \meta{fenv} and \meta{fenv*}. +If there +is not already a counter defined for \meta{fenv} a new one will be created +to be restarted by \meta{within}, if that is specified. + A caption within + the environment will be written out to a file with extension \meta{ext}. + The caption, if present, will start with \meta{capname}. For example, +the |figure| float for the class is defined as: +\begin{lcode} +\newfloat[chapter]{figure}{lof}{\figurename} +\renewcommmand{\thefigure}{% + \ifnum\c@chapter>\z@ \thechapter.\fi \@arabic\c@figure} +\end{lcode} +The last bit of the definition is internal code to make sure that if a +figure\index{figure} is in the document before chapter numbering starts, then the figure\index{figure} +number will not be preceded by a non-existent chapter number. + + + The captioning style for floats defined with \cmd{\newfloat} is the same as + for the figures\index{figure} and tables\index{table}. + + The \cmd{\newfloat} command generates several new commands, some of +which are internal LaTeX commands. For convenience, assume that the command +was called as +\begin{lcode} +\newfloat{X}{Z}{capname} +\end{lcode} + so |X| is the name of the float +environment and also the name of the counter for the caption, and |Z| is +the file extension. +The following float environment and related commands are then created. + +\begin{syntax} +\senv{X} float material \eenv{X} \\ +\senv{X*} float material \eenv{X*} \\ +\end{syntax} + The new float environment is called |X|, and can be used as either + |\begin{X}| or |\begin{X*}|, with the matching |\end{X}| or |\end{X*}|. +It is given the standard default position specification of |tbp|. + +\begin{syntax} + \Icn{Zdepth} \\ +\end{syntax} + The \Icn{Zdepth} counter is analogous to the standard \Icn{tocdepth} counter + in that it specifies that entries in a listing should not be + typeset if their numbering level is greater than \Icn{Zdepth}. The + default definition is |\setcounter{Zdepth}{1}|. To have a subfloat + of |Z| appear in the listing do |\setcounter{Zdepth}{2}|. + + + As a fuller example, suppose you wanted both + figures\index{figure} (which come with the + class), and diagrams. You could then do something like the following. + \begin{lcode} + \newcommand{\diagramname}{Diagram} + \newcommand{\listdiagramname}{List of Diagrams} + \newlistof{listofdiagrams}{dgm}{\listdiagramname} + \newfloat{diagram}{dgm}{\diagramname} + \newfixedcaption{\fdiagcaption}{diagram} + \newlistentry{diagram}{dgm}{0} + \begin{document} + ... + \listoffigures + \listfofdiagrams + ... + \begin{diagram} + \caption{A diagram} \label{diag1} + ... + \end{diagram} + As diagram~\ref{diag1} shows ... + \begin{minipage}{.9\textwidth} + \fdiagcaption{Another diagram} \label{diag2} + ... + \end{minipage} + + In contrast to diagram~\ref{diag1}, diagram~\ref{diag2} provides ... + \end{lcode} + + As a word of warning, if you mix both floats and fixed environments with the + same kind of caption you have to ensure that they get printed in the correct + order in the final document. If you do not do this, then the \listofx{} + captions will come out in the wrong order (the lists are ordered according the + page number in the typeset document, \emph{not} your source input order). + +\index{float!new|)} + + +\subsection{New subfloats} \label{sec:newsub} + +\index{subfloat!new|(} + + The \Lpack{subfigure} package defines the |subfigure| and |subtable| +subfloats. The class does not define any subfloats, if you need them you have +to specify them yourself. + +\begin{syntax} + \cmd{\newsubfloat}\marg{fenv} \\ +\end{syntax} + The \cmd{\newsubfloat} command enables the subcaptioning commands +(\cmd{\subcaption}, \cmd{\subtop}, etc.) to be used within the float +environment \meta{fenv} previously defined via +|\newfloat|. + + Calling |\newsubfloat{fenv}| will, among other things, +create a new counter called |subfenv| and the command |\thesubfenv| +for typesetting the counter. The default definition of |\thesubfenv| +is equivalent to: +\begin{lcode} +\newcommand{\thesubfenv}{(\alph{subfenv})} +\end{lcode} +which typesets a lowercase letter enclosed in parentheses. This is +the identifier for subcaptions, and may be changed via \cmd{\renewcommand}. + + If you are not using the \Lpack{subfigure} package and want, say, +subfigures then in the preamble call: +\begin{lcode} +\newsubfloat{figure} +\end{lcode} +and if you want the subcaptions to appear in the List of Figures, put: +\begin{lcode} +\setcounter{lofdepth}{2} +\end{lcode} +between the |\begin{document}| and \cmd{\listoffigures} commands. + + Further, if you had some subfigures that were originally planned +for use with the \Lpack{subfigure} package and wanted to use these +but without the package, you could: +\begin{lcode} +\let\subfigure\subbottom +\end{lcode} +which will make |\subfigure| an alias for \cmd{\subbottom}. + +\index{subfloat!new|)} + + + \subsection{Multiple floats} + +\index{float!multiple|(} + + As far as LaTeX is concerned, a float is a box with certain + restrictions as to where it can be placed. You can effectively + put what you like inside a float box. Normally there is just a single + picture or tabular in a float but you can put as many of these as will + fit inside the box. + + \begin{figure} + \centering + \hspace*{\fill} + {ILLUSTRATION 1} \hfill {ILLUSTRATION 2} + \hspace*{\fill} + \caption{Float with two illustrations} \label{fig:mult1} + \end{figure} + + Three typical cases of multiple figures\index{figure}/tables\index{table} in a single + float come to mind: + \begin{itemize} + \item Multiple illustrations\index{illustration}/tabulars with a single caption. + \item Multiple illustrations\index{illustration}/tabulars each individually captioned. + \item Multiple illustrations\index{illustration}/tabulars with one main caption and + individual subcaptions. + \end{itemize} + + The \Lpack{subfigure} package is designed for the last of these cases; + the others do not require a package. + + Figure~\ref{fig:mult1} is an example of multiple illustrations\index{illustration} + in a single float with a single caption. + This figure was produced by the following code. + \begin{lcode} + \begin{figure} + \centering + \hspace*{\fill} + {ILLUSTRATION 1} \hfill {ILLUSTRATION 2} + \hspace*{\fill} + \caption{Float with two illustrations} \label{fig:mult1} + \end{figure} + \end{lcode} + The |\hspace*{\fill}| and |\hfill| commands were used to space the two + illustrations\index{illustration} equally. Of course |\includegraphics| or |tabular| + environments could just as well + be used instead of the |{ILLUSTRATION N}| text. + + The following code produces \figurerefname s~\ref{fig:mult2} and~\ref{fig:mult3} + which are examples of two separately captioned illustrations\index{illustration} in one + float. + \begin{lcode} + \begin{figure} + \centering + \begin{minipage}{0.4\textwidth} + \centering + ILLUSTRATION 3 + \caption{Illustration 3} \label{fig:mult2} + \end{minipage} + \hfill + \begin{minipage}{0.4\textwidth} + \centering + ILLUSTRATION 4 + \caption{Illustration 4} \label{fig:mult3} + \end{minipage} + \end{figure} + \end{lcode} + In this case the illustrations\index{illustration} (or graphics or tabulars) are put into + separate |minipage| environments within the float, and the captions + are also put within the |minipage|s. Note that any required |\label| + must also be inside the |minipage|. If you wished, you could add yet + another caption after the end of the two |minipage|s. + + \begin{figure} + \centering + \begin{minipage}{0.4\textwidth} + \centering + ILLUSTRATION 3 + \caption{Illustration 3} \label{fig:mult2} + \end{minipage} + \hfill + \begin{minipage}{0.4\textwidth} + \centering + ILLUSTRATION 4 + \caption{Illustration 4} \label{fig:mult3} + \end{minipage} + \end{figure} + + Keith Reckdahl~\cite{EPSLATEX} provides more examples of this + kind of thing. + +\index{float!multiple|)} + + + \subsection{Where LaTeX puts floats} + +\index{float!placement|(} + + The general format for a float environment is: \\ + |\begin{float}[|\meta{loc}|] ... \end{float}| or for double column\index{column!double} floats: \\ + |\begin{float*}[|\meta{loc}|] ... \end{float*}| \\ + where the optional argument \meta{loc}, consisting of one or more characters, + specifies a location where the float may be placed. Note that the + \Lpack{multicol}\index{column!multiple} package~\cite{MULTICOL} +only supports the starred floats and it will not + let you have a single column\index{column!single} float. The possible \meta{loc} values are one + or more of the following: + \begin{itemize} + \item[\texttt{b}] \textit{bottom}: at the bottom of a page. This does not apply + to double column\index{column!double} floats as they may only be placed at the top of a page. + \item[\texttt{h}] \textit{here}: if possible exactly where the float environment + is defined. It does not apply to double column\index{column!double} floats. + \item[\texttt{p}] \textit{page}: on a separate page containing only + floats (no text). + \item[\texttt{t}] \textit{top}: at the top of a page. + \item[\texttt{!}] make an extra effort to place the float at the earliest place + specified by the rest of the argument. + \end{itemize} + The default for \meta{loc} is |tbp|, so the float may be placed at the top, + or bottom, or on a float-only page; the default works well 95\% of the time. + Floats of the same kind are output in + definition order, except that a double column\index{column!double} float may be output before + a later single column\index{column!single} float of the same kind, or + \textit{vice-versa}\footnote{This little quirk + is fixed by the \Lpack{fixltx2e} package, at least for tables and figures. + The package is part of a normal LaTeX distribution.}. + A float is never put on + an earlier page than its definition but may be put on the same or later page + of its definition. If a float cannot be placed, all + suceeding floats will be held up, and LaTeX can store no more than 16 held + up floats. A float cannot + be placed if it would cause an overfull page, or it otherwise cannot be fitted + according the the float parameters. + A |\clearpage| or |\cleardoublepage| or |\end{document}| flushes + out all unprocessed floats, irrespective of the \meta{loc} and float + parameters, putting them on float-only pages. + +\begin{syntax} + \cmd{\suppressfloats}\oarg{pos} \\ +\end{syntax} + You can use the command \cmd{\suppressfloats} to suppress floats + at a given \meta{pos} on the current page. |\suppressfloats[t]| prevents + any floats at the top of the page and |\suppressfloats[b]| prevents any + floats at the bottom of the page. The simple |\suppressfloats| prevents + both top and bottom floats. + + The \Lpack{flafter} package, which should have come with your LaTeX + distribution, provides a means of preventing floats from moving + backwards from their definition position in the text. This can be useful to + ensure, for example, that a float early in a |\section{}| is not typeset before + the section heading\index{heading}. + +\begin{figure} +\centering +\drawparameterstrue +\drawfloatpage +\caption{Float and text page parameters}\label{fig:fpp} +\end{figure} + +\begin{figure} +\centering +\drawparameterstrue +\setlayoutscale{0.9} +\drawfloat +\caption{Float parameters}\label{fig:flp} +\end{figure} + + \begin{table} +\begin{adjustwidth}{-1cm}{-1cm} + \centering + \captionnamefont{\small\sffamily} + \captiontitlefont{\small\sffamily} + \setlength{\belowcaptionskip}{10pt} + \caption{Float placement parameters}\label{tab:fpp} + \begin{tabular}{lp{0.5\linewidth}r} \hline + Parameter & Controls & Default \\ \hline + \multicolumn{3}{c}{Counters --- change with \cs{setcounter} } \\ \hline + \Icn{topnumber} & max number of floats at top of a page & 2 \\ + \Icn{bottomnumber} & max number of floats at bottom of a page & 1 \\ + \Icn{totalnumber} & max number of floats on a text page & 3 \\ + \Icn{dbltopnumber} & like \Icn{topnumber} for double column\index{column!double} floats & 2 \\ \hline + \multicolumn{3}{c}{Commands --- change with \cs{renewcommand} } \\ \hline + \cmd{\topfraction} & max fraction of page reserved for top floats & 0.7 \\ + \cmd{\bottomfraction} & max fraction of page reserved for bottom floats & 0.3 \\ + \cmd{\textfraction} & min fraction of page that must have text & 0.2 \\ + \cmd{\dbltopfraction} & like \cmd{\topfraction} for double column\index{column!double} floats & 0.7 \\ + \cmd{\floatpagefraction} & min fraction of a float page that must have float(s) & 0.5 \\ + \cmd{\dblfloatpagefraction} & like \cmd{\floatpagefraction} for double column\index{column!double} floats & 0.5 \\ \hline + \multicolumn{3}{c}{Text page lengths --- change with \cs{setlength} } \\ \hline + \lnc{\floatsep} & vertical space between floats & 12pt \\ + \lnc{\textfloatsep} & vertical space between a top (bottom) float and suceeding (preceding) text & 20pt \\ + \lnc{\intextsep} & vertical space above and below an \texttt{h} float & 12pt \\ + \lnc{\dblfloatsep} & like \lnc{\floatsep} for double column\index{column!double} floats & 12pt \\ + \lnc{\dbltextfloatsep} & like \lnc{\textfloatsep} for double column\index{column!double} floats & 20pt \\ \hline + \multicolumn{3}{c}{Float page lengths --- change with \cs{setlength} } \\ \hline + \lnc{\@fptop} & space at the top of the page & |0pt plus 1fil| \\ + \lnc{\@fpsep} & space between floats & |8pt plus 2fil| \\ + \lnc{\@fpbot} & space at the bottom of the page & |0pt plus 1fil| \\ + \lnc{\@dblfptop} & like \lnc{\@fptop} for double column\index{column!double} floats & |0pt plus 1fil| \\ + \lnc{\@dblfpsep} & like \lnc{\@fpsep} for double column\index{column!double} floats & |8pt plus 2fil| \\ + \lnc{\@dblfpbot} & like \lnc{\@fpbot} for double column\index{column!double} floats & |0pt plus 1fil| \\ \hline + \end{tabular} +\end{adjustwidth} + \end{table} + + Figures~\ref{fig:fpp} and~\ref{fig:flp} illustrate the many float parameters +and \tref{tab:fpp} lists the float parameters and the typical + standard default values. All the lengths are rubber lengths, and the actual + defaults depend on both the class and its size option. + + Given the displayed defaults, the height of a top float must be + less than 70\% of the textheight and there can be no more than 2 top floats + on a text page. Similarly, the height of a bottom float must not + exceed 30\% of the textheight and there can be no more than 1 bottom + float on a text page. There can be no more than 3 floats (top, bottom and here) + on the page. At least 20\% of a text page with floats must be text. + On a float page (one that has no text, only floats) the sum of the heights + of the floats must be at least 50\% of the textheight. The floats on a float + page should be vertically centered. + + It can be seen that with the defaults LaTeX might have trouble finding + a place for a float. Consider what will happen if a float is a bottom float + whose height is 40\% of the textheight and this is followed by a float whose + height is 90\% of the textheight. The first is too large to actually go at the + bottom of a text page but too small to go on a float page by itself. The second + has to go on a float page but it is too large to share the float page with the + first float. LaTeX is stuck! + + At this point it is worthwhile to be precise about the effect of a + one character \meta{loc} argument: + \begin{itemize} + \item[\texttt{[b]}] means: `put the float at the bottom of a page with some + text above it, and nowhere else'. The float must fit into the + |\bottomfraction| space otherwise it and subsequent floats will be held up. + \item[\texttt{[h]}] means: `put the float at this point and nowhere else'. + The float must fit into the space left on the page otherwise it and + subsequent floats will be held up. + \item[\texttt{[p]}] means: `put the float on a page that has no text but may + have other floats on it'. There must be at least `|\floatpagefraction|' + worth of floats to go on a float only page before the float will be + be output. + \item[\texttt{[t]}] means: `put the float at the top of a page with some + text below it, and nowhere else'. The float must fit into the + |\topfraction| space otherwise it and subsequent floats will be held up. + \item[\texttt{[!...]}] means: `ignore the |\...fraction| values for this + float'. + \end{itemize} + + You must try and pick a combination from these that will let LaTeX find + a place to put your floats. However, you can + also can change the float parameters to make it easier to find places + to put floats. Some examples are: + \begin{itemize} + \item Decrease \cmd{\textfraction} to get more `float' on a text page, but + the sum of \cmd{\textfraction} and \cmd{\topfraction} and the sum of \cmd{\textfraction} + and \cmd{\bottomfraction} should not exceed 1.0, otherwise the placement algorithm + falls apart. A minimum value for \cmd{\textfraction} is about 0.10 --- a page + with less than 10\% text looks better with no text at all, just floats. + + \item Both \cmd{\topfraction} and \cmd{\bottomfraction} can be increased, and it does + not matter if their sum exceeds 1.0. A good typographic style is that floats + are encouraged to go at the top of a page, and a better balance is achieved + if the float space on a page is larger + at the top than the bottom. + + \item Making \cmd{\floatpagefraction} too small might have the effect of a + float page just having one small float. However, to make sure that a float + page never has more than one float on it, do: +\begin{lcode} +\renewcommand{\floatpagefraction}{0.01} +\setlength{\@fpsep}{\textheight} +\end{lcode} + + \item Setting \lnc{\@fptop} to |0pt|, \lnc{\@fpsep} to |8pt| and \lnc{\@fpbot} + to |0pt plus 1fil| will force floats on a float page to start at the top + of the page. + \end{itemize} + If you are experimenting, a reasonable starting position is: + \begin{lcode} + \setcounter{topnumber}{3} + \setcounter{bottomnumber}{2} + \setcounter{totalnumber}{4} + \renewcommand{\topfraction}{0.85} + \renewcommand{\bottomfraction}{0.5} + \renewcommand{\textfraction}{0.15} + \renewcommand{\floatpagefraction}{0.7} + \end{lcode} + and similarly for double column\index{column!double} floats if you will have any. Actually, don't +bother to try these settings as they are the default for this class. + + One of LaTeX's little quirks is that on a text page, the `height' of a float + is its actual height plus \lnc{\textfloatsep} or \lnc{\floatsep}, while on a float + page the `height' is the actual height. This means that when using the default + \meta{loc} of |[tbp]| at least one of the text page float fractions + (\cmd{\topfraction} and/or \cmd{\bottomfraction}) must be + larger than the \cmd{\floatpagefraction} by an amount sufficient to take account + of the maximum text page separation value. + +\index{float!placement|)} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\DeleteShortVerb{\|} +\MakeShortVerb{\=} +%%%%\input{tabmanbody} %% rows & columns +%%%% tabmanbody.tex + + \chapter{Rows and columns} + +\section{Introduction} + + The class provides extensions to the standard \Ie{array} and \Ie{tabular} +environments. These are based partly on a merging of the + \Lpack{array}~\cite{ARRAY}, + \Lpack{dcolumn}~\cite{DCOLUMN}, + \Lpack{delarray}~\cite{DELARRAY}, + \Lpack{tabularx}~\cite{TABULARX}, and + \Lpack{booktabs}~\cite{BOOKTABS} + packages. + Much of the material in this chapter strongly reflects the +documentation of these packages. + + However, new kinds of tabular environments are also provided. + + +\section{General} + +\begin{syntax} +\cmd{\[} \senv{array}\oarg{pos}\marg{preamble} rows \eenv{array} \cmd{\]} \\ +\senv{tabular}\oarg{pos}\marg{preamble} rows \eenv{tabular} \\ +\senv{tabular*}\marg{width}\oarg{pos}\marg{preamble} rows \eenv{tabular*} \\ +\senv{tabularx}\marg{width}\oarg{pos}\marg{preamble} rows \eenv{tabularx} \\ +\end{syntax} +The \Ie{array} and \Ie{tabular} environments are traditional and the others +are extensions. The \Ie{array} is for typesetting +math and has to be within a math environment of some kind. The \Ie{tabular} +series are for typesetting ordinary text. + + The optional \meta{pos} argument can be one of \texttt{t}, \texttt{c}, +or \texttt{b} (the default is \texttt{c}), and controls the vertical position +of the array or tabular; either the \texttt{t}op or the \texttt{c}enter, +or the \texttt{b}ottom is aligned with the baseline. +Each row consists of elements separated by +\&, and finished with \cmd{\\}. There may be as many rows as desired. +The number and style of the columns is specified by the \meta{preamble}. +The width of each column is wide enough to contain its longest entry and +the overall width of the \Ie{array} or \Ie{tabular} is sufficient to contain +all the columns. However, the \Ie{tabular*} and \Ie{tabularx} provide +more control over the width through their \meta{width} argument. + +\section{The preamble} + + You use the \meta{preamble} argument to the array and tabular +environments to specify the number of columns and how you want column +entries to appear. The preamble consists of a sequence of options, which +are listed in \tref{tab:tabpream}. + + \begin{table} + \begin{center} + \caption{The array and tabular preamble options.} \label{tab:tabpream} + \setlength{\extrarowheight}{1pt} + \begin{tabular}{cp{9cm}} \toprule + \texttt{l} & Left adjusted column. \\ + \texttt{c} & Centered adjusted column. \\ + \texttt{r} & Right adjusted column. \\ + \texttt{p}\marg{width} & Equivalent to =\parbox[t]=\marg{width}. \\ + \texttt{m}\marg{width} & Defines a column of width \meta{width}. + Every entry will be centered in proportion to + the rest of the line. It is somewhat like + =\parbox=\marg{width}. \\ + \texttt{b}\marg{width} & Coincides with =\parbox[b]=\marg{width}. \\ + \texttt{>}\marg{decl} & Can be used before an \texttt{l}, \texttt{r}, + \texttt{c}, \texttt{p}, \texttt{m} or a + \texttt{b} option. It inserts \meta{decl} + directly in front of the entry of the column. + \\ + \texttt{<}\marg{decl} & Can be used after an \texttt{l}, \texttt{r}, + \texttt{c}, =p{..}=, =m{..}= or a =b{..}= + option. It inserts \meta{decl} right + after the entry of the column. \\ + \texttt{|} & Inserts a vertical line. The distance between + two columns will be enlarged by the width of + the line. \\ + \texttt{@}\marg{decl} & Suppresses inter-column space and inserts + \meta{decl} instead. \\ + \texttt{!}\marg{decl} & Can be used anywhere and corresponds with the + \texttt{|} option. The difference is that + \meta{decl} is inserted instead of a + vertical line, so this option doesn't + suppress the normally inserted space between + columns in contrast to =@{...}=.\\ + \texttt{D}\marg{ssep}\marg{osep}\marg{places} & Column entries aligned + on a `decimal point' \\ + \bottomrule + \end{tabular} + \end{center} + \end{table} + + Examples of the options include: + \begin{itemize} + \item A flush left column with bold font can be specified + with =>{\bfseries}l=. +%% Companion, page 106. +\begin{lcode} +\begin{center} +\begin{tabular}{>{\large}c >{\large\bfseries}l >{\large\itshape}c} \toprule +A & B & C \\ +100 & 10 & 1 \\ \bottomrule +\end{tabular} +\end{center} +\end{lcode} + +\begin{center} +\begin{tabular}{>{\large}c >{\large\bfseries}l >{\large\itshape}c} \toprule +A & B & C \\ +100 & 10 & 1 \\ \bottomrule +\end{tabular} +\end{center} + + \item + In columns which have been generated with \texttt{p}, \texttt{m} + or \texttt{b}, the default value of =\parindent= is + \textsf{0pt}. + +%Companion, page 106. + +\begin{lcode} +\begin{center} +\begin{tabular}{m{1cm}m{1cm}m{1cm}} \toprule +1 1 1 1 1 1 1 1 1 1 1 1 & +2 2 2 2 2 2 2 2 & +3 3 3 3 \\ \bottomrule +\end{tabular} +\end{center} +\end{lcode} + +\begin{center} +\begin{tabular}{m{1cm}m{1cm}m{1cm}} \toprule +1 1 1 1 1 1 1 1 1 1 1 1 & +2 2 2 2 2 2 2 2 & +3 3 3 3 \\ \bottomrule +\end{tabular} +\end{center} + + The \lnc{\parindent} can be changed with, for example + =>{\setlength{\parindent}{1cm}}p=. + +%%Companion, page 107. + +\begin{lcode} +\begin{center} +\begin{tabular}{>{\setlength{\parindent}{5mm}}p{2cm} p{2cm}} \toprule +1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 & +1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 \\ \bottomrule +\end{tabular} +\end{center} +\end{lcode} + +\begin{center} +\begin{tabular}{>{\setlength{\parindent}{5mm}}p{2cm} p{2cm}} \toprule +1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 & +1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 \\ \bottomrule +\end{tabular} +\end{center} + + \item + The specification =>{$}c<{$}= generates a column in math + mode in a \Ie{tabular} environment. When used in an \Ie{array} + environment the column is in LR mode (because the additional + \$'s cancel the existing \$'s). + \item + Using =c!{\hspace{1cm}}c= you get space between two + columns which is enlarged by one centimeter, while + =c@{\hspace{1cm}}c= gives you exactly one centimeter + space between two columns. +\item Elsewhere reasons are given why you should not use vertical + lines (e.g., the \texttt{|} option) in tables. Any examples + that use vertical lines are for illustrative purposes only where + it is advantageous to denote column boundaries, for example + to show different spacing effects. + \end{itemize} + + \subsection{D column specifiers} \label{sec:dcolumns} + + In financial tables dealing with pounds +and pence or dollars and cents, column entries +should be aligned on the separator between the numbers. The \texttt{D} +column specifier is provided for columns which are to be aligned on +a `decimal point'. The specifier takes three arguments. +\begin{syntax} + \texttt{D}\marg{ssep}\marg{osep}\marg{places} \\ +\end{syntax} +\begin{itemize} +\item[\meta{ssep}] is the single character which is used as the + separator in the source \texttt{.tex} file. Thus it will usually +be `\texttt{.}' or `\texttt{,}'. + +\item[\meta{osep}] is the separator in the output, this may + be the same as the first argument, but may be any math-mode + expression, such as \cmd{\cdot}. A \texttt{D} column + always uses math mode for the digits as well as the separator. + +\item[\meta{places}] should be the maximum number of decimal places + in the column (but see below for more on this). +If this is negative, any number of decimal places can + be used in the column, and all entries will be centred on + (the leading edge of) the + separator. Note that this can cause a column to be too wide; for instance, +compare the first two columns in the example below. +\end{itemize} + + Here are some example specifications which, for convenience, employ +the \cmd{\newcolumntype} macro described later. + +\begin{lcode} +\newcolumntype{d}[1]{D{.}{\cdot}{#1}} +\end{lcode} + This defines \texttt{d} to be a column specifier taking a single argument +specifying the number of decimal places, +and the \file{.tex} file should use `\texttt{.}' as the separator, with +\cmd{\cdot} ($\cdot$) being used in the output. + +\begin{lcode} +\newcolumntype{.}{D{.}{.}{-1}} +\end{lcode} +The result of this is that `\texttt{.}' specifies a column of entries to +be centered on the~`$.$'. + +\begin{lcode} +\newcolumntype{,}{D{,}{,}{2}} +\end{lcode} +And the result of this is that `\texttt{,}' specifies a column of +entries with at most two decimal places after a~`$,$'. + + \newcolumntype{d}[1]{D{.}{\cdot}{#1}} + \newcolumntype{.}{D{.}{.}{-1}} + \newcolumntype{,}{D{,}{,}{2}} + + The following table is typeset from this code: +\begin{lcode} +\begin{center} + \begin{tabular}{|d{-1}|d{2}|.|,|} + 1.2 & 1.2 &1.2 &1,2 \\ + 1.23 & 1.23 &12.5 &300,2 \\ + 1121.2& 1121.2&861.20 &674,29 \\ + 184 & 184 &10 &69 \\ + .4 & .4 & &,4 \\ + & &.4 & + \end{tabular} + \end{center} +\end{lcode} + + \begin{center} + \begin{tabular}{|d{-1}|d{2}|.|,|} + 1.2 & 1.2 &1.2 &1,2 \\ + 1.23 & 1.23 &12.5 &300,2 \\ + 1121.2& 1121.2&861.20 &674,29 \\ + 184 & 184 &10 &69 \\ + .4 & .4 & &,4 \\ + & &.4 & + \end{tabular} + \end{center} + + Note that the first column, which had a negative \meta{places} + argument is wider than the second column, so that the decimal point + appears in the middle of the column. + + The third + \meta{places} argument may specify \emph{both} the number of + digits to the left and to the right of the decimal place. The third + column in the next table below is set with =D{.}{.}{5.1}= and in the + second table, =D{.}{.}{1.1}=, to specify + `five places to the left and one to the right' and `one place to the + left and one to the right' respectively. (You may use `,' or other + characters, not necessarily `.' in this argument.) The column of figures + is then positioned such that a number with the specified numbers of + digits is centred in the column. + + If you have table headings (inserted with \cmd{\multicolumn}={1}{c}{...}= + to over-ride the =D= column type) then it may be that neither of the + above `centred' or `right aligned' forms is quite what you want. +\begin{lcode} + \begin{center}\small + \begin{tabular}[t]{|D..{-1}|D..{1}|D..{5.1}|} +\multicolumn{1}{|c|}{head}& +\multicolumn{1}{c|}{head}& +\multicolumn{1}{c|}{head}\\[3pt] + 1.2 & 1.2 &1.2 \\ + 11212.2& 11212.2&11212.2 \\ + .4 & .4 &.4 + \end{tabular} + \hfill + \begin{tabular}[t]{|D..{-1}|D..{1}|D..{1.1}|} +\multicolumn{1}{|c|}{wide heading}& +\multicolumn{1}{c|}{wide heading}& +\multicolumn{1}{c|}{wide heading}\\[3pt] + 1.2 & 1.2 &1.2 \\ + .4 & .4 &.4 + \end{tabular} + \end{center} +\end{lcode} + + \begin{center}\small + \begin{tabular}[t]{|D..{-1}|D..{1}|D..{5.1}|} +\multicolumn{1}{|c|}{head}& +\multicolumn{1}{c|}{head}& +\multicolumn{1}{c|}{head}\\[3pt] + 1.2 & 1.2 &1.2 \\ + 11212.2& 11212.2&11212.2 \\ + .4 & .4 &.4 + \end{tabular} + \hfill + \begin{tabular}[t]{|D..{-1}|D..{1}|D..{1.1}|} +\multicolumn{1}{|c|}{wide heading}& +\multicolumn{1}{c|}{wide heading}& +\multicolumn{1}{c|}{wide heading}\\[3pt] + 1.2 & 1.2 &1.2 \\ + .4 & .4 &.4 + \end{tabular} + \end{center} + + In both of these tables the first column is set with =D{.}{.}{-1}= + to produce a column centered on the `\texttt{.}', and the second column is + set with =D{.}{.}{1}= to produce a right aligned column. + + The centered (first) column produces columns that are wider than necessary + to fit in the numbers under a heading as it has to ensure that the + decimal point is centered. The right aligned (second) column does not have + this drawback, but under a wide heading a column of small right + aligned figures is somewhat disconcerting. + + The notation for the \meta{places} argument also enables columns that +are centred on the mid-point + of the separator, rather than its leading edge; for example + =D{+}{\,\pm\,}{3,3}= will give a symmetric layout of up to three + digits on either side of a $\pm$ sign. + + \subsection{Defining new column specifiers} + + You can easily type + \begin{quote} + =>{=\meta{some declarations}=}{c}<{=\meta{some more + declarations}=}= + \end{quote} +when you have a one-off column in a table, but it gets tedious + if you often use columns of this form. +The \cmd{\newcolumntype} lets you define a new column option like, say + \begin{quote} + =\newcolumntype{x}{>{=\meta{some declarations}=}{c}<{=\meta{some + more declarations}=}}=\hspace*{-3cm} + \end{quote} +and you can then use the \texttt{x} column specifier in the preamble wherever +you want a column of this kind. + +\begin{syntax} +\cmd{\newcolumntype}\marg{char}\oarg{nargs}\marg{spec} \\ +\end{syntax} +The +\meta{char} argument is the character that identifies the option and \meta{spec} +is its specification in terms of the regular preamble options. +The \cmd{\newcolumntype} command is similar to \cmd{\newcommand} --- +\meta{spec} itself can take arguments with the optional \meta{nargs} +argument declaring their number. + + For example, it is commonly required to have both math-mode and text +columns in the same alignment. Defining: +\begin{lcode} +\newcolumntype{C}{>{$}c<{$}} +\newcolumntype{L}{>{$}l<{$}} +\newcolumntype{R}{>{$}r<{$}} +\end{lcode} + Then \texttt{C} can be used to get centred text in an +\Ie{array}, or centred math-mode in a \Ie{tabular}. Similarly +\texttt{L} and \texttt{R} are for left- and right-aligned columns. + + The \meta{spec} in a \cmd{\newcolumntype} command may refer to any of + the primitive column specifiers (see table \ref{tab:tabpream} on page + \pageref{tab:tabpream}), or to any new letters defined in other +\cmd{\newcolumntype} commands. + +\begin{syntax} +\cmd{\showcols} \\ +\end{syntax} + A list of all the currently active +\cmd{\newcolumntype} definitions is sent to the terminal and log file if + the \cmd{\showcols} command is given. + +\subsection{Notes} + + \begin{itemize} + \item A preamble of the form ={wx*{0}{abc}yz}= is treated as ={wxyz}= + + \item An incorrect positional argument, such as \texttt{[Q]}, + is treated as \texttt{[t]}. + + \item A preamble such as ={cc*{2}}= with an error in + a $*$-form will generate an error message + that is not particularly helpful. + + \item Error messages generated when parsing the column specification + refer to the preamble argument \emph{after} it has been re-written + by the \cmd{\newcolumntype} system, not to the preamble entered by the + user. + + \item Repeated \texttt{<} or \texttt{>} constructions + are allowed. \texttt{>}\marg{decs1}\texttt{>}\marg{decs2} + is treated the same as \texttt{>}\marg{decs2}\marg{decs1}. + + The treatment of multiple \texttt{<} or \texttt{>} +declarations may seem strange. Using the obvious ordering +of \texttt{>}\marg{decs1}\marg{decs2} has the disadvantage +of not allowing the settings of a \cmd{\newcolumntype} +defined using these declarations to be overriden. + + \item The \cmd{\extracolsep} command may be used in \texttt{@}-expressions + as in standard \ltx, and also in \texttt{!}-expressions. + + The use of \cmd{\extracolsep} is subject to the following + two restrictions. There must be at most one \cmd{\extracolsep} + command per \texttt{@}, or \texttt{!} expression and the command must be + directly entered into the \texttt{@} expression, not as part of a macro + definition. Thus +\begin{lcode} +\newcommand{\ef}{\extracolsep{\fill}} ... @{\ef} +\end{lcode} + does not work. However you can use + something like +\begin{lcode} +\newcolumntype{e}{@{\extracolsep{\fill}} +\end{lcode} +instead. + + \item As noted by the \ltx{} book, a + \cmd{\multicolumn}, with the exception of the first column, + consists of the entry and the \emph{following} inter-column + material. This means that in a tabular with the preamble + =|l|l|l|l|= input such as =\multicolumn{2}{|c|}= in + anything other than the first column is incorrect. + + In the standard array/tabular implementation this error is not + noticeable as a =|= takes no horizontal space. But in the class the + vertical lines take up their natural width and you will see two lines if + two are specified --- another reason to avoid using \verb?|?. + + \end{itemize} + +\section{The array environment} + + Mathematical arrays are usually produced using the \Ie{array} environment. + +\begin{syntax} +\cmd{\[} \senv{array}\oarg{pos}\marg{preamble} rows \eenv{array} \cmd{\]} \\ +\cmd{\[} \senv{array}\oarg{pos}\meta{left}\marg{preamble}\meta{right} rows \eenv{array} \cmd{\]} \\ +\end{syntax} + Math formula are usually centered in the columns, but a column of +numbers often looks best flush right, or aligned on some distinctive +feature. In the latter case the \texttt{D} column scheme is very handy. +\begin{lcode} +\[ \begin{array}{lcr} + a +b +c & d - e - f & 123 \\ + g-h & j k & 45 \\ + l & m & 6 + \end{array} \] +\end{lcode} + +\[ \begin{array}{lcr} + a +b +c & d - e - f & 123 \\ + g-h & j k & 45 \\ + l & m & 6 + \end{array} \] + + Arrays are often enclosed in brackets or vertical lines or brackets +or other symbols to +denote math constructs like matrices. The delimeters are often large and have +to be indicated using \cmd{\left} and \cmd{\right} commands. +\begin{lcode} +\[ \left[ \begin{array}{cc} + x_{1} & x_{2} \\ + x_{3} & x_{4} + \end{array} \right] \] +\end{lcode} + +\[ \left[ \begin{array}{cc} + x_{1} & x_{2} \\ + x_{3} & x_{4} + \end{array} \right] \] + + + The \Ie{array} environment is an extension of the standard environment +in that it provides a + a system of implicit \cmd{\left} \cmd{\right} pairs. If you want an array + surrounded by parentheses, you can enter: +\begin{lcode} + \[ \begin{array}({cc})a&b\\c&d\end{array} \] +\end{lcode} + + \[ \begin{array}({cc})a&b\\c&d\end{array} \] + +Or, a litle more complex +\begin{lcode} +\[ \begin{array}({c}) + \begin{array}|{cc}| + x_{1} & x_{2} \\ + x_{3} & x_{4} + \end{array} \\ + y \\ + z + \end{array} \] +\end{lcode} + +\[ \begin{array}({c}) + \begin{array}|{cc}| + x_{1} & x_{2} \\ + x_{3} & x_{4} + \end{array} \\ + y \\ + z + \end{array} \] + + Similarly an environment equivalent to plain TeX's \cmd{\cases} could + be defined by:\\ +\begin{lcode} + \[ f(x)=\begin{array}\{{lL}. + 0 &if $x=0$\\ + \sin(x)/x&otherwise + \end{array} \] +\end{lcode} + + \DeleteShortVerb{\=} + \newcolumntype{L}{>{$}l<{$}} + \[ f(x)=\begin{array}\{{lL}. + 0 &if $x=0$\\ + \sin(x)/x&otherwise + \end{array} \] + \MakeShortVerb{\=} + + Here \texttt{L} denotes a column of left aligned L-R text, as described +earlier. + Note that as the delimiters must always be used in pairs, the `=.=' + must be used to denote a `null delimiter'. + + This feature is especially useful if the =[t]= or =[b]= + arguments are also used. In these cases the result is not equivalent + to surrounding the environment by \cmd{\left}\ldots\cmd{\right}, as + can be seen from the following example: +\begin{lcode} + \begin{array}[t]({c}) 1\\2\\3 \end{array} + \begin{array}[c]({c}) 1\\2\\3 \end{array} + \begin{array}[b]({c}) 1\\2\\3 \end{array} + \quad\mbox{not}\quad + \left(\begin{array}[t]{c} 1\\2\\3 \end{array}\right) + \left(\begin{array}[c]{c} 1\\2\\3 \end{array}\right) + \left(\begin{array}[b]{c} 1\\2\\3 \end{array}\right) +\end{lcode} + + + \[ + \begin{array}[t]({c}) 1\\2\\3 \end{array} + \begin{array}[c]({c}) 1\\2\\3 \end{array} + \begin{array}[b]({c}) 1\\2\\3 \end{array} + \quad\mbox{not}\quad + \left(\begin{array}[t]{c} 1\\2\\3 \end{array}\right) + \left(\begin{array}[c]{c} 1\\2\\3 \end{array}\right) + \left(\begin{array}[b]{c} 1\\2\\3 \end{array}\right) + \] + +\section{Tables} + + A table is one way of presenting a large amount of information +in a limited space. Even a simple table can presents facts that could +require several wordy paragraphs --- it is not only a picture that is worth +a thousand words. + + A table should have at least two columns, otherwise it is really a list, +and often has more. The leftmost column is often called the \emph{stub} +and it typically contains a vertical listing of the information categories + in the other columns. The columns have \emph{heads} (or \emph{headings}) at +the top indicating the nature of the entries in the column, although +it is not always necessary to provide a head for the stub if the +heading is obvious from the table's caption. Column heads +may include subheadings, often to specify the unit of measurement for numeric +data. + + A less simple table may need two or more levels of headings, in which +case \emph{decked heads} are used. A decked head consists of a \emph{spanner +head} and the two or more column heads it applies to. A horizontal +\emph{spanner rule} is set between the the spanner and column heads to +show the columns belonging to the spanner. + + Double decking, and certainly triple decking or more, should be avoided +as it can make it difficult following them down the table. It may be possible +to use a \emph{cut-in head} instead of double decking. A cut-in head is +one that cuts across the columns of the table and applies to all the +matter below it. + + No mention has been made of any vertical rules in a table, and this is +deliberate. There should be no vertical rules in a table. Rules, +if used at all, should be horizontal only, and these should be single, +not double or triple. It's not that ink is expensive, or that practically +no typesetting is done by hand any more, it's that the visual clutter should +be eliminated. + + For example, in \tref{tab:2views}, \tref{tab:before} is from the \ltx{} book and +\tref{tab:after} is how Simon Fear~\cite{BOOKTABS} suggests it +should be cleaned up. +\begin{lcode} +\begin{table} +\centering +\caption{Two views of one table} \label{tab:2views} +\subtop[Before]{\label{tab:before}% + \begin{tabular}{||l|lr||} \hline + gnats & gram & \$13.65 \\ \cline{2-3} + & each & .01 \\ \hline + gnu & stuffed & 92.50 \\ \cline{1-1} \cline{3-3} + emu & & 33.33 \\ \hline + armadillo & frozen & 8.99 \\ \hline + \end{tabular}} +\hfill +\subtop[After]{\label{tab:after}% + \begin{tabular}{@{}llr@{}} \toprule + \multicolumn{2}{c}{Item} \\ \cmidrule(r){1-2} + Animal & Description & Price (\$)\\ \midrule + Gnat & per gram & 13.65 \\ + & each & 0.01 \\ + Gnu & stuffed & 92.50 \\ + Emu & stuffed & 33.33 \\ + Armadillo & frozen & 8.99 \\ \bottomrule + \end{tabular} +} +\end{table} +\end{lcode} + +\begin{table} +\centering +\caption{Two views of one table} \label{tab:2views} +\subtop[Before]{\label{tab:before}% + \begin{tabular}{||l|lr||} \hline + gnats & gram & \$13.65 \\ \cline{2-3} + & each & .01 \\ \hline + gnu & stuffed & 92.50 \\ \cline{1-1} \cline{3-3} + emu & & 33.33 \\ \hline + armadillo & frozen & 8.99 \\ \hline + \end{tabular}} +\hfill +\subtop[After]{\label{tab:after}% + \begin{tabular}{@{}llr@{}} \toprule + \multicolumn{2}{c}{Item} \\ \cmidrule(r){1-2} + Animal & Description & Price (\$)\\ \midrule + Gnat & per gram & 13.65 \\ + & each & 0.01 \\ + Gnu & stuffed & 92.50 \\ + Emu & stuffed & 33.33 \\ + Armadillo & frozen & 8.99 \\ \bottomrule + \end{tabular} +} +\end{table} + +\subsection{Fear's rules} \label{sec:fear} + + Simon Fear disapproves of the default LaTeX table rules and + wrote the \Lpack{booktabs} package~\cite{BOOKTABS} to provide + better horizontal rules. Like many typographers, he abhors vertical rules. + + In a simple case a table begins with a \cmd{\toprule}, has + a single row of column headings, then a dividing rule called + here a \cmd{\midrule}; after the columns of data the table is +finished off with + a \cmd{\bottomrule}. Most book publishers set the \cmd{\toprule} and + \cmd{\bottomrule} heavier (i.e., thicker, or darker) + than the intermediate \cmd{\midrule}. + +\begin{syntax} +\cmd{\toprule}\oarg{wd} +\cmd{\bottomrule}\oarg{wd} +\lnc{\heavyrulewidth} \\ +\cmd{\midrule}\oarg{wd} +\lnc{\lightrulewidth} \\ +\end{syntax} + + The rule commands here all take a default width (thickness) + which may be reset within the document. +For the top and bottom rules this + is \lnc{\heavyrulewidth} and for midrules it is \lnc{\lightrulewidth} + (fully described below). In very rare cases where you need to have +a special width, you may use the optional argument \meta{wd} length +argument. + + The rule commands go immediately after the closing +\cmd{\\} of the preceding row (except of course \cmd{\toprule}, which + comes right after the =\tabular{}= command); in other words, + exactly where plain \ltx{} allows \cmd{\hline} or \cmd{\cline}. + +\begin{syntax} +\cmd{\cmidrule}\oarg{wd}=(=\meta{trim}=)=\marg{a--b} +\lnc{\cmidrulewidth} \\ +\end{syntax} +Similar to the normal \cmd{\cline} macro, \cmd{\cmidrule} draws a +rule across the columns (numbered) \meta{a--b}. +Generally, this rule + should not come to the full width of the end columns, and this + is especially the case when we need to begin a \cmd{\cmidrule} + straight after the end of another one. +The optional `trimming' commands, which are =(r)=, =(l)= and =(rl)= + or =(lr)=, indicate whether the right and/or left ends of the + rule should be trimmed. Note the exceptional use of parentheses + instead of braces or brackets for this optional argument. For example, +the code +\begin{lcode} +\cmidrule(r){1-2} +\end{lcode} +is used for \tref{tab:after}. + +The default width is \lnc{\cmidrulewidth} but the optional +\meta{wd} argument can be used to override this. + + An example of the commands in use is given by the code used to + produce the `after' example in \tref{tab:after} above. + + Occasionally extra space is required between certain rows + of a table; for example, before the last row when it is a + total of numbers above. +This is simply a matter of inserting \cmd{\addlinespace} + after the \cmd{\\} alignment marker. + +\begin{syntax} +\cmd{\addlinespace}\oarg{wd} +\lnc{\defaultaddspace} \\ +\end{syntax} +Think of \cmd{\addlinespace} as being a white rule of width \meta{wd}. + The default space is \cmd{\defaultaddspace} which gives rather + less than a whole line space. + +\begin{syntax} +\cmd{\specialrule}\marg{wd}\marg{abovespace}\marg{belowspace} \\ +\end{syntax} + You should not use double rules in a table; use rules with different +thicknesses instead. The \cmd{specialrule} can be used for drawing +rules with special thickness and spacing. +However, the rules already described should be sufficient without +having to resort to \cmd{\specialrule}. + +\begin{syntax} +\cmd{\morecmidrules} \\ +\end{syntax} +Nevertheless, if you insist on having +double \cmd{\cmidrule}s you will need the extra command + \cmd{\morecmidrules} to do so properly, because two + \cmd{\cmidrule}s in a row calls for two rules on the same `rule row'. +Thus in +\begin{lcode} +\cmidrule{1-2}\cmidrule{1-2} +\end{lcode} + the second command writes a rule that just overwrites the first + one. Use +\begin{lcode} +\cmidrule{1-2}\morecmidrules\cmidrule{1-2} +\end{lcode} + which gives you a double rule between columns one and two, + separated by \cmd{\cmidrulesep}. +Finish off a whole row of rules before giving the + \cmd{\morecmidrules} command. Note that \cmd{\morecmidrules} has no + effect whatsoever if it does not immediately follow a + \cmd{\cmidrule} (i.e., it is not a general space-generating command). + + The new rule commands are not guaranteed to work with \cmd{\hline} + or \cmd{\cline}. + More significantly the rules generated by the new commands are pretty +well guaranteed not to connect with verticals generated by ={|}= + characters in the preamble. This is a feature --- you + should not use vertical rules in tables. + +\subsection{Tabular environments} + +\begin{syntax} +\senv{tabular}\oarg{pos}\marg{preamble} rows \eenv{tabular} \\ +\senv{tabular*}\marg{width}\oarg{pos}\marg{preamble} rows \eenv{tabular*} \\ +\senv{tabularx}\marg{width}\oarg{pos}\marg{preamble} rows \eenv{tabularx} \\ +\end{syntax} + + A table created using the \Ie{tabular} environment comes out as +wide as it has to be to accomodate the entries. On the other hand, +both the \Ie{tabular*} and \Ie{tabularx} environments let you specify +the overall width of the table via the additional \meta{width} atrgument. + + The \Ie{tabular*} environment makes any necessary adjustment by altering +the intercolumn spaces while the \Ie{tabularx} environment alters +the column widths. Those columns that can be adjusted are noted by +using the letter \texttt{X} as the column specifier in the \meta{preamble}. +Once the correct column widths have been calculated the \texttt{X} +columns are converted to \texttt{p} columns. + + The following code is used for a regular \Ie{tabular}. +\begin{lcode} +\begin{center} +\begin{tabular}{|c|p{5.5pc}|c|p{5.5pc}|} \hline +\multicolumn{2}{|c|}{Multicolumn entry!} & THREE & FOUR \\ \hline +one & +\raggedright\arraybackslash The width of this column is fixed (5.5pc). & +three & +\raggedright\arraybackslash Column four will act in the same way as + column two, with the same width.\\ +\hline +\end{tabular} +\end{center} +\end{lcode} + +\begin{center} +\begin{tabular}{|c|p{5.5pc}|c|p{5.5pc}|} \hline +\multicolumn{2}{|c|}{Multicolumn entry!} & THREE & FOUR \\ \hline +one & +\raggedright\arraybackslash The width of this column is fixed (5.5pc). & +three & +\raggedright\arraybackslash Column four will act in the same way as + column two, with the same width.\\ + \hline +\end{tabular} +\end{center} + + The following examples use virtually the same contents, the major +differences are the specifications of the environment. + + The following \Ie{tabularx} is set with +\begin{lcode} +\begin{tabularx}{250pt}{|c|X|c|X|} +\end{lcode} +and the result is: + + \begin{center} + \begin{tabularx}{250pt}{|c|X|c|X|} + \hline + \multicolumn{2}{|c|}{Multicolumn entry!}& + THREE& + FOUR\\ + \hline + one& + \raggedright\arraybackslash The width of this column depends on the + width of the table.\footnote{You can use footnotes in a \texttt{tabularx}!} +& + three& + \raggedright\arraybackslash Column four will act in the same way as + column two, with the same width.\\ + \hline + \end{tabularx} + \end{center} + +The following \Ie{tabular*} is set with +\begin{lcode} + \begin{tabular*}{250pt}{|c|p{5.5pc}|c|p{5.5pc}|} +\end{lcode} +Notice that there is no \texttt{X} column; the total width required +for the tabular is less than the specfied width and hence the horizontal +lines spill over the right hand end of the apparent tabular width. + \begin{center} + \begin{tabular*}{250pt}{|c|p{5.5pc}|c|p{5.5pc}|} + \hline + \multicolumn{2}{|c|}{Multicolumn entry!}& + THREE& + FOUR\\ + \hline + one& + \raggedright\arraybackslash The width of this column is fixed (5.5pc). & + three & + \raggedright\arraybackslash Column four will act in the same way as + column two, with the same width.\\ + \hline + \end{tabular*} + \end{center} + +The next \Ie{tabular*} table is set with +\begin{lcode} + \begin{tabular*}{300pt}{|@{\extracolsep{\fill}}c|p{5.5pc}|c|p{5.5pc}|} +\end{lcode} + + \begin{center} + \begin{tabular*}{300pt}{|@{\extracolsep{\fill}}c|p{5.5pc}|c|p{5.5pc}|} + \hline + \multicolumn{2}{|c|}{Multicolumn entry!}& + THREE& + FOUR\\ + \hline + one& + \raggedright\arraybackslash The width of this column's text is fixed (5.5pc). & + three & + \raggedright\arraybackslash Column four will act in the same way as + column two, with the same width.\\ + \hline + \end{tabular*} + \end{center} + + +The following \Ie{tabularx} is set with +\begin{lcode} +\begin{tabularx}{300pt}{|c|X|c|X|} +\end{lcode} +the result is: + + \begin{center} + \begin{tabularx}{300pt}{|c|X|c|X|} + \hline + \multicolumn{2}{|c|}{Multicolumn entry!}& + THREE& + FOUR\\ + \hline + one& + \raggedright\arraybackslash The width of this column depends on the + width of the table.& + three& + \raggedright\arraybackslash Column four will act in the same way as + column two, with the same width.\\ + \hline + \end{tabularx} + \end{center} + + The main differences between the \Ie{tabularx} and \Ie{tabular*} +environments are: + \begin{itemize} + \item \Ie{tabularx} modifies the widths of the \emph{columns}, + whereas \Ie{tabular*} modifies the widths of the inter-column + \emph{spaces}. + \item \Ie{tabular} and \Ie{tabular*} environments may be + nested with no restriction, however if one \Ie{tabularx} + environment occurs inside another, then the inner one \emph{must} be + enclosed by ={ }=. + \item The body of the \Ie{tabularx} environment is in fact the + argument to a command, and so certain constructions which are not + allowed in command arguments (like \cmd{\verb}) may not be used.\footnote + {Actually, \texttt{verb} and \texttt{verb*} may be used, but they may + treat spaces incorrectly, and the + argument can not contain an unmatched {\ttfamily\char`\{} or + {\ttfamily\char`\}}, or a {\ttfamily\char`\%} character.} + \item \Ie{tabular*} uses a primitive capability of \tx{} to + modify the inter column space of an alignment. \Ie{tabularx} + has to set the table several times as it searches for the best column + widths, and is therefore much slower. Also the fact that the body is + expanded several times may break certain \tx{} constructs. + \end{itemize} + +\begin{syntax} +\cmd{\tracingtabularx} \\ +\end{syntax} +Following the \cmd{\tracingtabularx} declaration all +later \Ie{tabularx} environments will print information + about column widths as they repeatedly re-set the tables to find the + correct widths. + + By default the \texttt{X} specification is turned into + =p{=\meta{some value}=}=. Such narrow columns often + require a special format, which can be achieved by using the =>= syntax. +For example, =>{\small}X=. Another format which is useful in narrow +columns is ragged right, however \ltx's \cmd{\raggedright} macro redefines +\cmd{\\} in a way which conflicts with its use in \Ie{tabular} or +\Ie{array} environments. + +\begin{syntax} +\cmd{\arraybackslash} \\ +\end{syntax} + For this reason the command \cmd{\arraybackslash} is provided; +this may be used after a \cmd{\raggedright}, \cmd{\raggedleft} or +\cmd{\centering} declaration. Thus a \Ie{tabularx} preamble may include +\begin{lcode} +>{\raggedright\arraybackslash}X +\end{lcode} + These preamble specifications may of course be saved using the + command, \cmd{\newcolumntype}. After specifying, say, +\begin{lcode} +\newcolumntype{Y}{>{\small\raggedright\arraybackslash}X} +\end{lcode} +then \texttt{Y} could be used in the \Ie{tabularx} preamble + argument. + +\begin{syntax} +\cmd{\tabularxcolumn} \\ +\end{syntax} + The \texttt{X} columns are set using the \texttt{p} column, which + corresponds to \cmd{\parbox}=[t]=. You may want them set using, say, the +\texttt{m} column, which corresponds to \cmd{\parbox}=[c]=. It is not + possible to change the column type using the \texttt{>} syntax, so another + system is provided. \cmd{\tabularxcolumn} should be defined to be a macro + with one argument, which expands to the \Ie{tabular} preamble + specification that you want to correspond to \texttt{X}. The + argument will be replaced by the calculated width of a column. + + The default definition is +\begin{lcode} +\newcommand{\tabularxcolumn}[1]{p{#1}} +\end{lcode} +This may be changed, for instance +\begin{lcode} +\renewcommand{\tabularxcolumn}[1]{>{\small}m{#1}} +\end{lcode} +so that \texttt{X} columns will be typeset as \texttt{m} columns using +the \cmd{\small} font. + + Normally all \texttt{X} columns in a single table are set to the + same width, however it is possible to make \Ie{tabularx} set + them to different widths. + A preamble argument of +\begin{lcode} +{>{\hsize=.5\hsize}X>{\hsize=1.5\hsize}X} +\end{lcode} + specifies two columns, the second will be three times as wide as the + first. However if you want to play games like this you should follow + the following two rules. + \begin{enumerate} + \item Make sure that the sum of the widths of all the \texttt{X} + columns is unchanged. (In the above example, the new widths still add + up to twice the default width, the same as two standard \texttt{X} + columns.) + \item Do not use \cmd{\multicolumn} entries which cross any \texttt{X} + column. + \end{enumerate} + As with most rules, these may be broken if you know what you are + doing. + + It may be that the widths of the `normal' columns of the table + already total more than the requested total + width. \Ie{tabularx} refuses to set the + \texttt{X} columns to a negative width, so in this case you get a + warning ``X Columns too narrow (table too wide)''. + + The \texttt{X} columns will in this case be set to a width of 1em + and so the table itself will be wider than the requested total width + given in the argument to the environment. +% This behaviour of the package can be customised slightly +% as noted in the documentation of the code section. + + The standard \cmd{\verb} macro does not work inside a \Ie{tabularx}, +just as it does not work in the argument to any macro. + +\begin{syntax} +\cmd{\TX@verb} \\ +\end{syntax} +\cmd{\TX@verb} is the `poor man's \cmd{\verb}' +and is based on page 382 of the \tx Book. As + explained there, doing verbatim this way means that spaces are not + treated correctly, and so a \cmd{\verb*} version may well be useless. + The mechanism is quite general, and any macro which wants to allow a + form of \cmd{\verb} to be used within its argument may +\begin{lcode} +\let\verb=\TX@verb +\end{lcode} +It must ensure that the real definition is restored afterwards. + + This version of \cmd{\verb} is subject to the +following restictions: + \begin{enumerate} + \item Spaces in the argument are not read verbatim, but may be skipped + according to \tx's usual rules. + \item Spaces will be added to the output after control words, even if + they were not present in the input. + \item Unless the argument is a single space, any trailing space, + whether in the original argument, or added as in (2), + will be omitted. + \item The argument must not end with =\=, so =\verb|\|= is not + allowed, however, because of (3), =\verb|\ |= produces + =\=. + \item The argument must be balanced with respect to ={= and =}=. So + =\verb|{|= is not allowed. + \item A comment character like \verb?%? will not appear verbatim. It will + act as usual, commenting out the rest of the input line! + \item The combinations =?`= and =!`= will appear as + {\ttfamily?`} and {\ttfamily!`} if the \texttt{cmtt} font is + being used. + \end{enumerate} + +\section{Free tabulars} + + All the tabular environments described so far put the table +into a box, which \ltx{} treats like a large, even though complex, + character, and characters are not broken across pages. If you +have a long table that runs off the bottom of the page you can turn +to, say, the \Lpack{longtable}~\cite{LONGTABLE} or \Lpack{xtab}~\cite{XTAB} +packages which will automatically break tables across page boundaries. +These have various bells and whistles, such as automatically putting +on a caption at the top of each page, repeating the column heads, and +so forth. + +\subsection{Continuous tabulars} + +\begin{syntax} +\senv{ctabular}\oarg{pos}\marg{preamble} rows \eenv{ctabular} \\ +\senv{ctabular*}\oarg{pos}\marg{width}\marg{preamble} rows \eenv{ctabular*} \\ +\end{syntax} +The \Ie{ctabular} environment is similar to \Ie{tabular}, but with a few +differences, the main one +being that the table will merrily continue across page breaks. +The \meta{preamble} argument is the same as for the previous \Ie{array} +and \Ie{tabular} environments, but the optional \meta{pos} argument +controls the horizontal position of the table, not the vertical. The +possible argument values are +\texttt{l} (left justified), +\texttt{c} (centered), or +\texttt{r} (right justified); the default is \texttt{c}. + +\begin{lcode} +\begin{ctabular}{lcr} \toprule +LEFT & CENTER & RIGHT \\ \midrule +l & c & r \\ +l & c & r \\ +l & c & r \\ +l & c & r \\ \bottomrule +\end{ctabular} +\end{lcode} + +\begin{ctabular}[c]{lcr} \toprule +LEFT & CENTER & RIGHT \\ \midrule +l & c & r \\ +l & c & r \\ +l & c & r \\ +l & c & r \\ \bottomrule +\end{ctabular} + + The \Ie{ctabular} environment will probably not be used within +a \Ie{table} environment (which defeats the possibility of the table +crossing page boundaries). To caption a \Ie{ctabular} you can define a +fixed caption. For example: +\begin{lcode} +\newfixedcaption{\freetabcaption}{table} +\end{lcode} +And then \cmd{\freetabcaption} can be used like the normal \cmd{\caption} +within a \Ie{table} float. +\newfixedcaption{\freetabcaption}{table} + +\subsection{Automatic tabulars} + + A tabular format may be used just to list things, for example the +names of the members of a particular organisation, or the names of +\ltx{} environments. + + Especially when drafting a document, or when the number of entries +is likely to change, it is convenient to be able to tabulate a list +of items without having to explicitly mark the end of each row. + +\begin{syntax} +\cmd{\autorows}\oarg{width}\marg{pos}\marg{num}\marg{style}\marg{entries} \\ +\end{syntax} +The \cmd{\autorows} macro lists the \meta{entries} in rows; that is, +the entries are typeset left to right and top to bottom. +The table below was set by \cmd{\autorows} using: +\begin{lcode} +\freetabcaption{Example automatic row ordered table} +\autorows{c}{5}{c}{one, two, three, four, five, + six, seven, eight, nine, ten, + eleven, twelve, thirteen, fourteen } +\end{lcode} + +\freetabcaption{Example automatic row ordered table} +\autorows{c}{5}{c}{one, two, three, four, five, + six, seven, eight, nine, ten, + eleven, twelve, thirteen, fourteen } + + The \meta{pos} (\texttt{l}, \texttt{c}, or \texttt{r}) +argument controls the horizontal position of the +tabular and \meta{num} is the number of columns. The \meta{style} +(\texttt{l}, \texttt{c}, or \texttt{r}) argument specifies the location +of the entries in the columns; each column is treated identically. +The \meta{entries} argument is a comma-separated list of the names to be +tabulated; there must be no comma after the last of the names before the +closing brace. + + Each column is normaly the same width which is large enough to accomodate +the widest entry in the list. +A positive \meta{width} (e.g., \verb?[0.8\textwidth]?), defines the overall +width of the table, and the column width is calculated by dividing \meta{width} +by the number of columns. Any negative value for the \meta{width} width lets +each column be wide enough for the widest entry in that column; the column width +is no longer a constant. + + The next examples illustrate the effect of the \meta{width} argument +(the default value is 0pt). + +\begin{lcode} +\freetabcaption{Changing the width of a row ordered table} +\autorows[-1pt]{c}{5}{c}{one, two, three, four, five, + six, seven, eight, nine, ten, + eleven, twelve, thirteen, fourteen } +\autorows[0pt]{c}{5}{c}{one, two, three, four, five, ... } +\autorows[0.9\textwidth]{c}{5}{c}{one, two, three, four, five, ... } +\end{lcode} + +\freetabcaption{Changing the width of a row ordered table} +\autorows[-1pt]{c}{5}{c}{one, two, three, four, five, + six, seven, eight, nine, ten, + eleven, twelve, thirteen, fourteen } + + \autorows[0pt]{c}{5}{c}{one, two, three, four, five, + six, seven, eight, nine, ten, + eleven, twelve, thirteen, fourteen } + +\autorows[0.9\textwidth]{c}{5}{c}{one, two, three, four, five, + six, seven, eight, nine, ten, + eleven, twelve, thirteen, fourteen } + + +\begin{syntax} +\cmd{\autocols}\oarg{width}\marg{pos}\marg{num}\marg{style}\marg{entries} \\ +\end{syntax} +The \cmd{\autocols} macro lists its \meta{entries} in columns, proceeding +top to bottom and left to right. The arguments, except for \meta{width}, +are the same as for \cmd{\autorows}. The column width is always constant throughout +the table and is normally sufficient for the +widest entry. A positive \meta{width} has the same effect as for \cmd{\autorows} +but a negative value is ignored. + + If you need to include a comma within one of the entries in the list +for either \cmd{\autorows} or \cmd{\autocols} you have to use a macro. +For instance: +\begin{lcode} +\newcommand*{\comma}{,} +\end{lcode} +\newcommand*{\comma}{,} + +The following examples illustrate these points. + +\begin{lcode} +\freetabcaption{Changing the width of a column ordered table} +\autocols{c}{5}{c}{one\comma{} two, three, four, five, + six, seven, eight, nine, ten, + eleven, twelve, thirteen, fourteen } +\autocols[0.9\textwidth]{c}{5}{c}{one\comma{} two, three, four, five, + six, seven, eight, nine, ten, + eleven, twelve, thirteen, fourteen } +\end{lcode} + +\freetabcaption{Changing the width of a column ordered table} +\autocols{c}{5}{c}{one\comma{} two, three, four, five, + six, seven, eight, nine, ten, + eleven, twelve, thirteen, fourteen } + +\autocols[0.9\textwidth]{c}{5}{c}{one\comma{} two, three, four, five, + six, seven, eight, nine, ten, + eleven, twelve, thirteen, fourteen } + + +\section{Spacing} + + Sometimes tabular rows appear vertically challenged. +\begin{syntax} +\lnc{\extrarowheight} \\ +\end{syntax} +The length called \lnc{\extrarowheight} can be set to modify +the normal height of \Ie{tabular} (and \Ie{array}) rows. +If it is a positive + length, the value is added to the normal height of + every row of the table, while + the depth will remain the same. This is important for tables + with horizontal lines because those lines normally touch the + capital letters. + For example, =\setlength{\extrarowheight}{1pt}= was used in the +definition of \tref{tab:tabpream}. + + \subsection{Special variations of \texttt{\textbackslash hline}} + + The family of \Ie{tabular} environments allows + vertical positioning with respect to the baseline of + the text in which the environment appears. By default the + environment appears centered, but this can be changed to + align with the first or last line in the environment by + supplying a \texttt{t} or \texttt{b} value to the + optional position argument. However, this does not work + when the first or last element in the environment is a + \cmd{\hline} command---in that case the environment is + aligned at the horizontal rule. + + \pagebreak[3] + + Here is an example: + \begin{center} + \begin{minipage}[t]{.4\linewidth} + Tables + \begin{tabular}[t]{l} + with no\\ hline \\ commands \\ used + \end{tabular} versus \\ tables + \begin{tabular}[t]{|l|} + \hline + with some \\ hline \\ commands \\ + \hline + \end{tabular} used. + \end{minipage} + \begin{minipage}[t]{.5\linewidth} + \begin{verbatim} + Tables + \begin{tabular}[t]{l} + with no\\ hline \\ commands \\ used + \end{tabular} versus tables + \begin{tabular}[t]{|l|} + \hline + with some \\ hline \\ commands \\ + \hline + \end{tabular} used. + \end{verbatim} + \end{minipage} +\end{center} + +\begin{syntax} +\cmd{\firsthline} \cmd{\lasthline} \\ +\lnc{\extratabsurround} \\ +\end{syntax} + Using \cmd{\firsthline} and \cmd{\lasthline} will + cure the problem, and the tables will align properly as long + as their first or last line does not contain extremely large + objects. + \begin{center} + \begin{minipage}[t]{.4\linewidth} + Tables + \begin{tabular}[t]{l} + with no\\ line \\ commands \\ used + \end{tabular} versus \\ tables + \begin{tabular}[t]{|l|} + \firsthline + with some \\ line \\ commands \\ + \lasthline + \end{tabular} used. + \end{minipage} + \begin{minipage}[t]{.5\linewidth} + \begin{verbatim} + Tables + \begin{tabular}[t]{l} + with no\\ line \\ commands \\ used + \end{tabular} versus tables + \begin{tabular}[t]{|l|} + \firsthline + with some \\ line \\ commands \\ + \lasthline + \end{tabular} used. + \end{verbatim} + \end{minipage} + \end{center} + + The implementation of these two commands contains an extra + dimension, which is called \cmd{\extratabsurround}, to add some + additional space at the top and the bottom of such an environment. + This is useful if such tables are nested. + + + \subsection{Handling of rules} + + There are two possible approaches to the handling of horizontal and + vertical rules in tables: + \begin{enumerate} + \item rules can be placed into the available space without + enlarging the table, or + \item rules can be placed between columns or rows thereby enlarging + the table. + \end{enumerate} + This class implements the second possibility while the + default implementation in the \ltx{} kernel implements the first + concept. + + With standard \ltx{} adding rules to a table will not affect the + width or height of the table (unless double rules are used), e.g., + changing a preamble from \verb=lll= to \verb=l|l|l= does not + affect the document other than adding rules to the table. In + contrast, with this class a table that just fitted the + \verb=\textwidth= might now produce an overfull box. (But you shouldn't + have vertical rules in the first place.) + + +%%%%%%%%%%%%%%%%%%%%%%%% +% end of tabman.tex +%%%%%%%%%%%%%%%%%%%%%%% + +\DeleteShortVerb{\=} +\MakeShortVerb{\|} +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + + +\chapter{Margin and foot notes} \label{chap:mnotes} + + The standard classes provide the \cmd{\marginpar} command for putting +things into the margin. The class supports two extra kinds of side notes. +It also provides extended footnoting capabilities. + + +\section{Footnotes} + + A footnote can be considered to be a special kind of float\index{float} +that is put at the bottom of a page. + +\begin{syntax} +\cmd{\footnote}\oarg{num}\marg{text} \\ +\cmd{\footnotemark}\oarg{num} \cmd{\footnotetext}\oarg{num}\marg{text} \\ +\end{syntax} +In the main text, the \cmd{\footnote} command puts a marker at the +point where it is called, and puts the \meta{text}, preceded by the same +mark, at the bottom of the page. If the optional \meta{num} is used +then its value is used for the mark, otherwise the \Icn{footnote} + counter is stepped and provides the mark's value. + + You can use \cmd{\footnotemark} to put a marker in the main text; the value +is determined just like that for \cmd{\footnote}. Footnote text can be put +at the bottom of the page via \cmd{\footnotetext}; if the optional \meta{num} +is given it is used as the mark's value, otherwise the value of the +\Icn{footnote} counter is used. + It may be helpful, but completely untrue, to think of \cmd{\footnote} being +defined like: +\begin{lcode} +\newcommand{\footnote}[1]{\footnotemark\footnotetext{#1}} +\end{lcode} + + +\begin{syntax} +\cmd{\footref}\marg{label} \\ +\end{syntax} + On occasions it may be desireable to make more than one reference +to the text of a footnote\index{footnote!reference}. This can be done by putting a \cmd{\label} +in the footnote and then using \cmd{\footref} to refer to the label; this +prints the footnote label. For example: +\begin{lcode} +...\footnote{... adults or babies.\label{fn:rabbits}} +... +... The footnote\footref{fn:rabbits} on \pref{fn:rabbits} ... +\end{lcode} +In this manual, the last line above prints: +\begin{syntax} +... The footnote\footref{fn:rabbits} on \pref{fn:rabbits} ... \\ +\end{syntax} + + The parameters provided by the standard classes for controlling +footnotes are illustrated in \fref{fig:fn}. + +\begin{figure} +\centering +\drawparameterstrue +\setlayoutscale{0.4} +\drawfootnote +\caption{Footnote layout parameters for the standard classes}\label{fig:fn} +\end{figure} + +\begin{syntax} +\lnc{\footnotesep} \\ +\verb!\skip\footins! \\ +\end{syntax} +The length \lnc{\footnotesep} controls the vertical spacing between footnotes\index{footnote} +(and thanks notes), +and is initialised by the class to give no extra spacing for a +\cmd{\footnotesize} font. You can change the spacing by +\begin{lcode} +\addtolength{\footnotesep}{...} +\end{lcode} +The length |\skip\footins| defines the vertical spacing between the +bottom of the main text and the top of the first line of the first +footnote\index{footnote}. Likewise this can be changed by +\begin{lcode} +\addtolength{\skip\footins}{...} +\end{lcode} +The total vertical distance between the bottom of the main text and +the baseline of the first line of the first footnote\index{footnote} is +|\footnotesep + \skip\footins|. + +\begin{syntax} +\cmd{\footnoterule} \\ +\end{syntax} + The \cmd{\footnoterule} macro is defined in the LaTeX kernel and +redefined in the standard classes. An `\texttt{@}less' definition, which is slightly +less efficient than that in the classes, is: +\begin{lcode} +\renewcommand{\footnoterule}{% + \kern -3pt % call this kerna + \hrule height 0.4pt width 0.4\columnwidth + \kern 2.6pt % call this kernb +} +\end{lcode} +This produces a horizontal rule from the left margin\index{margin} to 40\% of the +\cmd{\columnwidth} with thickness 0.4pt. The rule must not take up any +vertical space, which means that |kerna + kernb| must equal the thickness +of the rule. The rule is located a distance |\skip\footins + kerna| +below the bottom of the main text. So, to move the rule upwards, decrease +the value of |kerna| and increase that of |kernb|, and the reverse to +move the rule downwards. + + This class provides some additional parameters but for a wider +variety of footnote styles you may like to use the \Lpack{footmisc} +package~\cite{FOOTMISC}. + The additional class parameters have been chosen so as not to clash with +the \Lpack{footmisc} package. Similar concepts apply to the +\cmd{\thanks} command described in \Sref{sec:thanks} +starting on \pref{sec:thanks}. + + The \cmd{\footnote} macro essentially does three things: +\begin{itemize} +\item Typesets a marker at the point where \cmd{\footnote} is called; +\item Typesets a marker at the bottom of the page on which \cmd{\footnote} + is called; +\item Following the marker at the bottom of the page, typesets the text + of the footnote. +\end{itemize} + +\begin{syntax} +\cmd{\@makefnmark} \\ +\end{syntax} +The \cmd{\footnote} macro calls the kernel command \cmd{\@makefnmark} to +typeset the footnote marker at the point where \cmd{\footnote} is called +(the value of the marker is kept in the macro \cmd{\@thefnmark}). The default +definition typesets the mark as a superscript and is essentially +\begin{lcode} +\def\@makefnmark{\hbox{\textsuperscript{\@thefnmark}}} +\end{lcode} +To get, say, the marker to be typeset on the baseline in the normal font +and enclosed in brackets --- +\begin{lcode} +\renewcommand*{\@makefnmark}{ [\@thefnmark]} +\end{lcode} + +\begin{syntax} +\cmd{\footfootmark} \\ +\lnc{\footmarkwidth} \cmd{\footmarkstyle}\marg{arg} \\ +\end{syntax} +The class macro for typesetting the marker at the foot of the page is +\cmd{\footfootmark}. The mark is set in a box of width +\lnc{\footmarkwidth}. If this is negative, the mark is outdented +into the margin, if zero the mark is flush left, and when positive +the mark is indented. The appearance of the mark is contolled by +\cmd{\footmarkstyle}. The default specification is +\begin{lcode} +\footmarkstyle{\textsuperscript{#1}} +\end{lcode} +where the |#1| indicates the position of \cmd{\@thefnmark} in the style. +The default results in the mark being set as a superscript. +For example, to have the marker set on the baseline +and followed by a right parenthesis, do +\begin{lcode} +\footmarkstyle{#1) } +\end{lcode} + +\begin{syntax} +\lnc{\footmarksep} \lnc{\footparindent} \\ +\end{syntax} +The mark is typeset in a box of width \lnc{\footmarkwidth} and this is +then followed by the text of the footnote. Second and later lines of the +text are offset by the length \lnc{\footmarksep} from the end of the box. +The first line of a paragraph within a footnote is indented by +\lnc{\footparindent}. + +\begin{syntax} +\cmd{\foottextfont} \\ +\end{syntax} +The text in the footnote is typeset using the \cmd{\foottextfont} font. +The default is \cmd{\footnotesize}. + + Altogether, the class specifies +\begin{lcode} +\footmarkstyle{\textsuperscript{#1}} +\setlength{\footmarkwidth}{1.8em} +\setlength{\footmarksep}{-1.8em} +\setlength{\footparindent}{1em} +\newcommand{\foottextfont}{\footnotesize} +\end{lcode} +to replicate the standard footnote layout. + + You might like to try the +following combinations of \lnc{\footmarkwidth} and \lnc{\footmarksep} +to see if you prefer the layout produced by one of them to the standard +layout (which is produced by the first pairing in the list below): +\begin{lcode} +\setlength{\footmarkwidth}{1.8em} \setlength{\footmarksep}{-1.8em} +\setlength{\footmarkwidth}{1.8em} \setlength{\footmarksep}{0em} +\setlength{\footmarkwidth}{0em} \setlength{\footmarksep}{0em} +\setlength{\footmarkwidth}{-1.8em} \setlength{\footmarksep}{1.8em} +\setlength{\footmarkwidth}{0em} \setlength{\footmarksep}{1.8em} \footmarkstyle{#1)\hfill} +\end{lcode} +% width = 1.8, sep = 0 -> indented block para & hung number +% width = sep = 0 -> block paragraph at margin +% width = -1.8, sep = -width -> mark in margin, block para at margin + + +\begin{syntax} +\cmd{\makefootmarkhook} \\ +\end{syntax} +Just before a footnote is typeset the macro \cmd{\makefootmarkhook} is +called, which by default does nothing, but you can renew it to do something. +For example: +\begin{lcode} +\renewcommand{\makefootmarkhook}{\raggedright} +\end{lcode} +will cause footnotes to be typeset raggedright. + + Any footnotes after this point will be set according to: +\begin{lcode} +\setlength{\footmarkwidth}{-1.0em} +\setlength{\footmarksep}{-\footmarkwidth} +\footmarkstyle{#1} +\end{lcode} +\setlength{\footmarkwidth}{-1.0em} +\setlength{\footmarksep}{-\footmarkwidth} +\footmarkstyle{#1} + + + +\begin{syntax} +\cmd{\multfootsep} \\ +\end{syntax} +In the standard classes if two or more footnotes are applied +sequentially\footnote{One footnote}\footnote{Immediately followed by another} +then the markers in the text are just run together. The class, like the +\Lpack{footmisc}~\cite{FOOTMISC} and \Lpack{ledmac}~\cite{LEDMAC} packages, +inserts a separator +between the marks. In the class the macro \cmd{\multfootsep} is used as +the separator. Its default definition is: +\begin{lcode} +\newcommand*{\multfootsep}{\textsuperscript{\normalfont,}} +\end{lcode} + +\begin{syntax} +\cmd{\feetabovefloat} \\ +\cmd{\feetbelowfloat} \\ +\end{syntax} +In the standard classes, footnotes on a page that has a float at the +bottom are typeset before the float. I think that this looks +peculiar. Following the \cmd{\feetbelowfloat} declaration footnotes will be +typeset at the bottom of the page below any bottom floats; they will also +be typeset at the bottom of \cmd{\raggedbottom} pages as opposed to being +put just after the bottom line of text. The standard positioning is +used following the \cmd{\feetabovefloat} declaration, which is the default. + +\begin{syntax} +\cmd{\plainfootnotes} \\ +\cmd{\twocolumnfootnotes} \\ +\cmd{\threecolumnfootnotes} \\ +\cmd{\paragraphfootnotes} \\ +\end{syntax} +Normally, each footnote starts a new paragraph. The class provides three +other styles, making four in all. Following the \cmd{\twocolumnfootnotes} +declaration footnotes will be typeset in two columns, and similarly +they are typeset in three columns after the \cmd{\threecolumnfootnotes} +declaration. Footnotes are run together as a single paragraph after the +\cmd{\paragraphfootnotes} declaration. The default style is used after +the \cmd{\plainfootnotes} declaration. + + The style can be changed at any +time but there may be odd effects if the change is made in the middle of +a page when there are footnotes before and after the declaration. You may +find it interesting to try changing styles in an article type document +that uses \cmd{\maketitle} and \cmd{\thanks}, and some footnotes on the +page with the title: +\begin{lcode} +\title{...\thanks{...}} +\author{...\thanks{...}...} +... +\begin{document} +\paragraphfootnotes +\maketitle +\plainfootnotes +... +\end{lcode} + +\begin{syntax} +\cmd{\newfootnoteseries}\marg{series} \\ +\cmd{\plainfootstyle}\marg{series} \\ +\cmd{\twocolumnfootstyle}\marg{series} \\ +\cmd{\threecolumnfootstyle}\marg{series} \\ +\cmd{\paragraphfootstyle}\marg{series} \\ +\end{syntax} + + The class provides for additional series of footnotes; perhaps the +normal footnotes are required, flagged with arabic numerals, and another +kind of footnote flagged with roman numerals. A new footnote series is +created by the \cmd{\newfootseries} macro, where \meta{series} is an +alphabetic identifier for the series. This is most conveniently a +single (upper case) letter, for example \texttt{P}. + + Calling, say, \verb?\newfootnoteseries{Q}? creates a set of macros +equivalent to those for the normal \cmd{\footnote} but with the \meta{series} +appended. These include \cs{footnoteQ}, \cs{footnotemarkQ}, +\cs{footnotetextQ} and so on. These are used just like the normal +\cmd{\footnote} and companions. + + By default, a series is set to typeset using the normal style +of a paragraph per note. The series' style can be changed by using one +of the \cs{...footstyle} commands. + + For example, to have a `P' (for paragraph) series using roman numerals +as markers which, in the main text are superscript with a closing parenthesis +and at the foot are on the baseline followed by an endash, and the text is +set in italics at the normal footnote size: +\begin{lcode} +\newfootnoteseries{P} +\paragraphfootstyle{P} +\renewcommand{\thefootnoteP}{\roman{footnoteP}} +\footmarkstyleP{#1--} +\renewcommand{\@makefnmarkS}{\hbox{\textsuperscript{\@thefnmarkP)}}} +\renewcommand{\foottextfont}{\itshape\footnotesize} +\end{lcode} +This can then be used like: +\begin{lcode} +.... this sentence\footnoteP{A `p' footnote\label{fnp}} +includes footnote~\footrefP{fnp}. +\end{lcode} +In a minipage a different counter (\texttt{mpfootn...}) is used for a footnote +than in the main text (\texttt{footn...}). +By default its value is a letter. To change it to, say, a numeral for the +`P' series, do: +\begin{lcode} +\renewcommand{\thempfootnoteP}{\arabic{mpfootnoteP}} +\end{lcode} + + The \cmd{\newfootnoteseries} macro does not create series versions +of the footnote-related length commands, such as \lnc{\footmarkwidth} +and \lnc{\footmarksep}, nor does it create versions of \cmd{\footnoterule}. + + At the foot of the page footnotes are grouped according to their series; +all ordinary footnotes are typeset, then all the first series footnotes +(if any), then the second series, and so on. The ordering corresponds to +the order of \cmd{\newfootnoteseries} commands. + +\begin{syntax} +\cmd{\footfudgefiddle} \\ +\end{syntax} +For paragraphed footnotes \tx{} has to estimate the amount of space they +will take. Unfortunately this \emph{is} an estimate and if it is an +underestimate then the footnotes will flow too low on the page, for example +below the page number. Increasing \cmd{\footfudgefiddle} from its default +vaue of 64, causes \tx{} to allot more space. For instance +\begin{lcode} +\renewcommand{\footfufgefiddle}{70} +\end{lcode} +will at least go some way to curing the problem. You will probably have +to do some experimentation to get a good value. + +\begin{syntax} +\cmd{\fnsymbol}\marg{counter} \\ +\cmd{\@fnsymbol}\marg{num} \\ +\end{syntax} +The \cmd{\fnsymbol} macro typesets the representation of the counter \meta{counter} +like a footnote symbol. Internally it uses the kernel \cmd{\@fnsymbol} macro +which converts a positive integer \meta{num} to a symbol. If you are not fond of +the standard ordering of the footnote symbols, this is the macro to change. Its +original definition is: +\begin{lcode} +\def\@fnsymbol#1{\ensuremath{\ifcase#1\or *\or \dagger\or \ddagger\or + \mathsection\or \mathparagraph\or \|\or **\or \dagger\dagger + \or \ddagger\ddagger \else\@ctrerr\fi}} +\end{lcode} +This, as shown by \verb?\@fnsymbol{1},...\@fnsymbol{9}? produces the series: \makeatletter +\@fnsymbol{1}, +\@fnsymbol{2}, +\@fnsymbol{3}, +\@fnsymbol{4}, +\@fnsymbol{5}, +\@fnsymbol{6}, +\@fnsymbol{7}, +\@fnsymbol{8}, and +\@fnsymbol{9}. +%\@fnsymbol{10} % out of bounds +\makeatother + +\makeatletter +\let\m@mold@fnsymbol\@fnsymbol +\renewcommand{\@fnsymbol}[1]{\ensuremath{% + \ifcase#1\or *\or \dagger\or \ddagger\or + \mathsection\or \|\or \mathparagraph\or **\or \dagger\dagger + \or \ddagger\ddagger \else\@ctrerr\fi}} +\makeatother + Robert Bringhurst quotes +the following as the traditional ordering (at least up +to \makeatletter\@fnsymbol{6}\makeatother): \makeatletter +\@fnsymbol{1}, +\@fnsymbol{2}, +\@fnsymbol{3}, +\@fnsymbol{4}, +\@fnsymbol{5}, +\@fnsymbol{6}, +\@fnsymbol{7}, +\@fnsymbol{8}, and +\@fnsymbol{9}. +\makeatother +You can obtain this sequence by redefining \cmd{\@fnsymbol} as: +\begin{lcode} +\renewcommand{\@fnsymbol}[1]{\ensuremath{% + \ifcase#1\or *\or \dagger\or \ddagger\or + \mathsection\or \|\or \mathparagraph\or **\or \dagger\dagger + \or \ddagger\ddagger \else\@ctrerr\fi}} +\end{lcode} +not forgetting judicious use of \cmd{\makeatletter} and \cmd{\makeatother} +if you do this in the preamble\index{preamble}. Other authorities or publishers +may prefer other sequences and symbols. +\makeatletter\let\@fnsymbol\m@mold@fnsymbol\makeatother + + + + + + + +\section{Verbatim footnotes} + + The macro \cmd{\verbfootnote} can typeset a footnote that includes +some verbatim text. + +\begin{syntax} +\cmd{\verbfootnote}\oarg{num}\marg{text} \\ +\end{syntax} + + The next two paragraph are typeset by this code: +\begin{lcode} + Below, footnote\footref{fn1} is a \cmd{\footnote} while +footnote~\ref{fn2} is a \cmd{\verbfootnote}. + + The \cmd{\verbfootnote} command should +appear\footnote{There may be some problems if color is + used.\label{fn1}} +to give identical results as the normal \cmd{\footnote}, +but it can include some verbatim +text\verbfootnote{The \verb?\footnote? macro, like all others + except for \verb?\verbfootnote?, can not + contain verbatim text in its argument.\label{fn2}} +in the \meta{text} argument. +\end{lcode} + + Below, footnote\footref{fn1} is a \cmd{\footnote} while +footnote~\ref{fn2} is a \cmd{\verbfootnote}. + + The \cmd{\verbfootnote} command should +appear\footnote{There may be some problems if color is + used.\label{fn1}} +to give identical results as the normal \cmd{\footnote}, +but it can include some verbatim +text\verbfootnote{The \verb?\footnote? macro, like all others + except for \verb?\verbfootnote?, can not + contain verbatim text in its argument.\label{fn2}} +in the \meta{text} argument. + + + +\section{Sidebars} + + It appears that the \cmd{\sidebar} command, which was originally noted +as being experimental, has been used successfully for a variety of tasks. + +\begin{syntax} +\cmd{\sidebar}\marg{text} \\ +\cmd{\sidebarfont} \\ +\end{syntax} +The \cmd{\sidebar} command is like the \cmd{\marginpar} command in that +it typesets its \meta{text} argument, using the font specified +by \cmd{\sidebarfont}, in the margin. Unlike |\marginpar|, +the \meta{text} will start near the top of the page and may continue onto +later pages if it is too long to go on a single page. + + The default definition of \cmd{\sidebarfont} is +\begin{lcode} +\newcommand{\sidebarfont}{\normalfont} +\end{lcode} + + +\begin{syntax} +\cmd{\sidebarform} \\ +\end{syntax} + + Sidebars are normally narrow so text is set ragged right. More +accurately, the text is set according to \cmd{\sidebarform} which is defined +as: +\begin{lcode} +\newcommand{\sidebarform}{\rightskip=\z@ \@plus 2em} +\end{lcode} +which is ragged right but with less raggedness than \cmd{\raggedright} +would allow. As usual, you can change \cmd{\sidebarform}, for example: +\begin{lcode} +\renewcommand{\sidebarform}{} % justified text +\end{lcode} + + You are likely to run into problems if the \cmd{\sidebar} command comes +near a pagebreak, or if the sidebar text gets typeset alongside main +text that has non-uniform line spacing (e.g., around a \cmd{\section}). +Also, the contents of sidebars may not be typeset if they are too near +to the end of the document. + +\begin{syntax} +\lnc{\sidebarwidth} \\ +\lnc{\sidebarhsep} \\ +\lnc{\sidebarvsep} \\ +\end{syntax} +The \meta{text} of a \cmd{\sidebar} is typeset in a column of width +\lnc{\sidebarwidth} and there will be a horizontal gap of length +\lnc{\sidebarhsep} between the typeblock and the \meta{text}. The +length \lnc{\sidebarvsep} is the vertical gap between sidebars that fall +on the same page. + +\begin{syntax} +\cmd{\setsidebarheight}\marg{length} \\ +\end{syntax} +The macro \cmd{\setsidebarheight} can be used to specify the height +of a sidebar. The \meta{length} argument should be equivalent to +an integral number of lines. For example: +\begin{lcode} +\setsidebarheight{15\onelineskip} +\end{lcode} + + +Currently the alignment of the text in a sidebar with the main text +is not particularly good and you may want to do some +experimentation (possibly through a combination of +\lnc{sidebarvsep} and \cmd{\setsidebarheight}) to make it +better.\footnote{If you do improve the alignment, +please let me know how you did it.} + +\section{Side notes} + + The vertical position of side notes specified via \cmd{\marginpar} +is flexible so that adjacent notes are prevented from overlapping. + +\begin{syntax} +\cmd{\sidepar}\oarg{left}\marg{right} \\ +\lnc{\sideparvshift} \\ +\end{syntax} + + The \cmd{\sidepar} macro is similar to \cmd{\marginpar} except that +it produces side notes that do not float --- they may overlap. The same +spacing is used for both \cmd{\marginpar} and \cmd{\sidepar}, namely +the lengths \lnc{\marginparsep} and \lnc{\marginparwidth}. The length +\lnc{\sideparvshift} can be used to make vertical adjustments to the +position of \cmd{\sidepar} notes. By default this is set to a value +of -2.08ex which seems to be the magical length that aligns the top of +the note with the text line. + + By default the \meta{right} argument is put in the right margin. When +the \Lopt{twoside} option is used the \meta{right} argument is put into +the left margin on the verso (even numbered) pages; however, for these pages +the optional \meta{left} argument is used instead if it is present. For +two column text the relevent argument is put into the `outer' margin with +respect to the column. + +\begin{syntax} +\cmd{\sideparswitchtrue} \cmd{\sideparswitchfalse} \\ +\cmd{\reversesidepartrue} \cmd{\reversesideparfalse} \\ +\cmd{\parnopar} \\ +\end{syntax} + + The default placement can be changed by judicious use of the +\cs{reversidepar*} and \cs{sideparswitch*} declarations. For two sided +documents the default is \cmd{\sideparswitchtrue}, which specifies that +notes should be put into the outer margins; in one sided documents +the default is \cmd{\sideparswitchfalse} which specifies that notes +should always be put into the right hand margin. Following the +declaration \cmd{\reversesidepartrue} notes are put into opposite margin +than that described above +(the default declaration is \cmd{\reversesideparfalse}). + + When LaTeX is deciding where to place the side notes it checks whether +it is on an odd or even page and sometimes TeX doesn't realise that it has just +moved onto the next page. Effectively TeX typesets paragraph by paragraph +(including any side notes) and at the end of each paragraph sees if there +should have been a page break in the middle of the paragraph. If there was +it outputs the first part of the paragraph, inserts the page break, and retains +the second part of the paragraph, without retypesetting it, for eventual +output at the top of the new page. This means that side notes for any given +paragraph are in the same margin, either left or right. A side note at the +end of a paragraph may then end up in the wrong margin. The macro +\cmd{\parnopar} forces a new paragraph but without appearing to (the first +line in the following paragraph follows immediately after the last element +in the prior paragraph with no line break). You can use \cmd{\parnopar} +to make TeX to do its page break calculation when you want it to, by splitting +what appears to be one paragraph into two paragraphs. + + Bastiaan Veelo has kindly provided example code for another +form of a side note, as follows. +\begin{lcode} +%% A new command that allows you to note down ideas or annotations in +%% the margin of the draft. If you are printing on a stock that is wider +%% than the final page width, we will go to some length to utilise the +%% paper that would otherwise be trimmed away, assuming you will not be +%% trimming the draft. These notes will not be printed when we are not +%% in draft mode. +\makeatletter + \ifdraftdoc + \newlength{\draftnotewidth} + \newlength{\draftnotesignwidth} + \newcommand{\draftnote}[1]{\@bsphack% + {%% do not interfere with settings for other marginal notes + \strictpagechecktrue% + \checkoddpage% + \setlength{\draftnotewidth}{\foremargin}% + \addtolength{\draftnotewidth}{\trimedge}% + \addtolength{\draftnotewidth}{-3\marginparsep}% + \ifoddpage + \setlength{\marginparwidth}{\draftnotewidth}% + \marginpar{\flushleft\textbf{\textit{\HUGE !\ }}\small #1}% + \else + \settowidth{\draftnotesignwidth}{\textbf{\textit{\HUGE\ !}}}% + \addtolength{\draftnotewidth}{-\draftnotesignwidth}% + \marginpar{\raggedleft\makebox[0pt][r]{%% hack around + \parbox[t]{\draftnotewidth}{%%%%%%%%% funny behaviour + \raggedleft\small\hspace{0pt}#1% + }}\textbf{\textit{\HUGE\ !}}% + }% + \fi + }\@esphack} + \else + \newcommand{\draftnote}[1]{\@bsphack\@esphack} + \fi +\makeatother +\end{lcode} + + Bastiaan also noted that it provided an example of using the +\lnc{\foremargin} length. + If you want to try it out, either put the code in your preamble, +or put it into a package (i.e., \file{.sty} file) without the +\cs{makeat...} commands. + + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\clearpage +\pagestyle{companion} +\chapterstyle{companion} +\defaultsecnum +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\chapter{Signposts and decoration} \label{chap:signposts} + + +\newcommand{\tepi}[2]{\epigraph{#1}{#2}} + + \tepi{My soul, seek not the life of immortals; but enjoy to the full + the resources that are within your reach} + {\textit{Pythian Odes \\ Pindar}} + + This chapter is typeset using the \cstyle{companion} chapterstyle +and the \pstyle{companion} pagestyle. + +\section{Introduction} + + By now we have covered most aspects of typesetting. As far as +the class is concerned this chapter describes the remaining major element, +namely headers\index{header} and footers\index{footer}, and the slightly more fun task of typesetting +epigraphs\index{epigraph}. + + +\section{Page styles} + + The class provides a selection of pagestyles that you can use and if +they don't suit, then there are means to define your own. + + These facilities were inspired by the \Lpack{fancyhdr} +package~\cite{FANCYHDR}, although the command set is different. + + The standard classes provide for a footer\index{footer} and header\index{header} for odd and even +pages. Thus there are four elements to be specified for a pagestyle. +This class partitions the headers\index{header} and footers\index{footer} into left, center and right +portions, so there are a total of 12 elements that have to be specified +for a pagestyle. You may find, though, that one of the built in pagestyles +meets your needs so you don't have to worry about all these specifications. + +\begin{syntax} +\cmd{\pagestyle}\marg{style} \\ +\cmd{\thispagestyle}\marg{style} \\ +\end{syntax} + \cmd{\pagestyle} sets the current pagestyle to \meta{style}. On a particular +page \cmd{\thispagestyle} can be used to override the cuurent pagestyle for +the one page. + + Some of the class' commands automatically call \cmd{\thispagestyle}: +\begin{itemize} +\item \cmd{\part} calls |\thispagestyle{part}|; +\item \cmd{\chapter} calls |\thispagestyle{chapter}|; +\item if \cmd{\cleardoublepage} will result in an empty verso page it calls + |\thispagestyle{cleared}| for the empty page. +\end{itemize} + + The page styles provided by the class are: +\begin{itemize} +\item[\pstyle{empty}] The headers\index{header} and footers\index{footer} + are empty. +\item[\pstyle{plain}] The header\index{header} is empty and the + folio\index{folio} (page number) is centered at the bottom of the page. +\item[\pstyle{headings}] The footer\index{footer} is empty and the + header\index{header} contains the the folio\index{folio} at the outer + side of the page, and either the chapter or section title. + Chapter~\ref{chap:starting} uses this style. +\item[\pstyle{myheadings}] This is like the \pstyle{headings} style except you + have to specify the titles, if any, to go into the header\index{header}. +\item[\pstyle{ruled}] The footer\index{footer} contains the + folio\index{folio} at the outside. The header\index{header} contains + either the chapter or section titles, and a line is drawn underneath the + header\index{header}. + This style is used in \Cref{chap:layingpage}. +\item[\pstyle{Ruled}] This is like the \pstyle{ruled} style except that + the headers\index{header} and footers\index{footer} extend into the + \foredge{} margin\index{margin}. + Chapter~\ref{chap:verse} uses this style. +\item[\pstyle{companion}] This is like the pagestyle in the + \textit{Companion} series (e.g., see~\cite{GOOSSENS94}). + For an example, see \Cref{chap:signposts}. +\item[\pstyle{part}] This is the same as the \pstyle{plain} pagestyle. +\item[\pstyle{chapter}] This is the same as the \pstyle{plain} pagestyle. +\item[\pstyle{cleared}] This is the same as the \pstyle{empty} pagestyle. +\item[\pstyle{title}] This is the same as the \pstyle{plain} pagestyle. +\item[\pstyle{titlingpage}] This is the same as the \pstyle{empty} pagestyle. +\end{itemize} + + For the \pstyle{headings} pagestyle above, you have to define your own +titles to go into the header\index{header}. Each sectioning command, say |\sec|, +calls a macro called |\secmark|. The pagestyles usually define this command +so that it picks up the title, and perhaps the number, of the |\sec|. + +\begin{syntax} +\cmd{\markboth}\marg{left}\marg{right} \\ +\cmd{\markright}\marg{right} \\ +\end{syntax} + \cmd{\markboth} sets the values of two \emph{markers}\index{markers} +to \meta{left} and \meta{right} respectively, at the point in the text +where it is called. Similarly, \cmd{\markright} sets the value of a +marker to \meta{right}. + +\begin{syntax} +\cmd{\leftmark} \cmd{\rightmark} \\ +\end{syntax} +The macro \cmd{\leftmark} contains the value of the \meta{left} argument +of the \emph{last} \cmd{\markboth} on the page. The macro \cmd{\rightmark} +contains the value of the \meta{right} argument of the \emph{first} +\cmd{\markboth} or \cmd{\markright} on the page, or if there is not one it +contains the value of the most recent \meta{right} argument. + + So, a pagestyle can define the |\secmark| commands in terms of +\cmd{\markboth} or \cmd{\markright}, and then use \cmd{\leftmark} and/or +\cmd{\rightmark} in the headers\index{header} or footers\index{footer}. I'll show examples of how this +works later, and this is often how the \pstyle{myheadings} style gets +implemented. + + +\section{Making headers and footers} + + As mentioned, the class provides for left, center, and right slots in +even and odd headers\index{header} and footers\index{footer}. This section describes how you can make +your own pagestyle using these 12 slots. + +\begin{syntax} +\cmd{\makepagestyle}\marg{style} \\ +\cmd{\aliaspagestyle}\marg{alias}\marg{original} \\ +\cmd{\copypagestyle}\marg{new}\marg{original} \\ +\end{syntax} +The command \cmd{\makepagestyle} specifies a pagestyle \meta{style} which +is initially equivalent to the \pstyle{empty} pagestyle. +The \cmd{\aliaspagestyle} macro defines the \meta{alias} pagestyle to be +the same as the \meta{original} pagestyle. As an example of the latter, +the class includes the code +\begin{lcode} +\aliaspagestyle{part}{plain} +\aliaspagestyle{chapter}{plain} +\aliaspagestyle{cleared}{empty} +\end{lcode} +The macro \cmd{\copypagestyle} creates a \meta{new} pagestyle with the +definitions being copies of those for the \meta{original} pagestyle. + + +\begin{syntax} +\cmd{\makeevenhead}\marg{style}\marg{left}\marg{center}\marg{right} \\ +\cmd{\makeoddhead}\marg{style}\marg{left}\marg{center}\marg{right} \\ +\cmd{\makeevenfoot}\marg{style}\marg{left}\marg{center}\marg{right} \\ +\cmd{\makeoddfoot}\marg{style}\marg{left}\marg{center}\marg{right} \\ +\end{syntax} +The macro \cmd{\makeevenhead} defines the \meta{left}, \meta{center}, and +\meta{right} portions of the \meta{style} pagestyle header\index{header} for even numbered +(verso) pages. Similarly \cmd{\makeoddhead}, \cmd{\makeevenfoot}, and +\cmd{\makeoddfoot} define the \meta{left}, \meta{center} and \meta{right} +portions of the \meta{style} header\index{header} for odd numbered (recto) pages, +and the footers\index{footer} for verso and recto pages. These commmands for \meta{style} +should be used after the corresponding \cmd{\makepagestyle} for \meta{style}. + +\begin{syntax} +\cmd{\makerunningwidth}\marg{style}\marg{length} \\ +\lnc{\headwidth} \\ +\end{syntax} +The macro \cmd{\makerunningwidth} sets the width of the \meta{style} +pagestyle headers\index{header} and footers\index{footer} to be \meta{length}. The \cmd{\makepagestyle} +sets the width to be the textwidth, so the macro need only be used if some +other width is desired. The length \lnc{\headwidth} is provided as a +(scratch) length that may be used for headers\index{header} or footers\index{footer}, or any other +purpose. + +\begin{syntax} +\cmd{\makeheadrule}\marg{style}\marg{width}\marg{thickness} \\ +\cmd{\makefootrule}\marg{style}\marg{width}\marg{thickness}\marg{skip} \\ +\end{syntax} +A header\index{header} may have a rule drawn between it and the top of the typeblock\index{typeblock}, +and similarly a rule may be drawn between the bottom of the typeblock\index{typeblock} +and the footer\index{footer}. The \cmd{\makeheadrule} macro specifies the the \meta{width} +and \meta{thickness} of the rule below the \meta{style} pagestyle header\index{header}, and +the \cmd{\makefootrule} does the same for the rule above the footer\index{footer}; the +additional \meta{skip} argument is a distance that specifies the vertical +positioning of the foot rule (see \cmd{\footruleskip}). +The \cmd{\makepagestyle} macro initialises the \meta{width} to the +\lnc{\textwidth} and the \meta{thickness} to 0pt, so by default no rules +are visible. + +\begin{syntax} +\lnc{\normalrulethickness} \\ +\end{syntax} +\lnc{\normalrulethickness} is the normal thickness of a visible rule, by +default 0.4pt. It can be changed using \cmd{\setlength}, although I suggest +that you do not unless perhaps when using the \Lopt{14pt} or \Lopt{17pt} +class options. + +\begin{syntax} +\cmd{\footruleheight} \\ +\cmd{\footruleskip} \\ +\end{syntax} +The macro \cmd{\footruleheight} is the height of a normal +rule above a footer\index{footer} (default zero). \cmd{\footruleskip} is a distance +sufficient to ensure that a foot rule will be placed between the bottom +of the typeblock\index{typeblock} and the footer\index{footer}. Despite appearing to be lengths, if +you really need to change the values use \cmd{\renewcommand}, +not \cmd{\setlength}. + +\begin{syntax} +\cmd{\makeheadposition}\marg{style}\\ + \marg{eheadpos}\marg{oheadpos}\marg{efootpos}\marg{ofootpos} \\ +\end{syntax} +The \cmd{\makeheadposition} macro specifies the horizontal positioning +of the even and odd headers\index{header} and footers\index{footer}, respectively, for the \meta{style} +pagestyle. Each of the \meta{...pos} arguments may be |flushleft|, |center|, +or |flushright|, with the obvious meanings. An empty, or unrecognised, argument +is equivalent to |center|. This macro is really only of use if the +header/footer\index{header}\index{footer} width is not the same as the \lnc{\textwidth}. + +\begin{syntax} +\cmd{\makepsmarks}\marg{style}\marg{code} \\ +\end{syntax} +The last thing that the \cmd{\pagestyle}\marg{style} does is call the +\meta{code} argument of the \cmd{\makepsmarks} for \meta{style}. +This is normally used for specifying non-default code +(i.e., code not specifiable via any of the previous macros) for the particular +pagestyle. The code normally defines the marks, if any, that will be used in +the headers\index{header} and footers\index{footer}. + + +\subsection{Example pagestyles} + + This first example demonstrates most of the page styling commands. +In the \textit{LaTeX Companion} series of +books~\cite{GOOSSENS94,GOOSSENS97,GOOSSENS99} the header\index{header} is wider +than the typeblock\index{typeblock}, sticking out into the foredge margin\index{margin}, and has a rule +underneath it. The page number is in bold and at the outer end of the header\index{header}. +Chapter titles are in verso headers\index{header} and section titles in recto headers\index{header}, both +in bold font and at the spine margin\index{margin}. The footers\index{footer} are empty. + + The first thing to do in implementing this style is to calculate +the width of the headers\index{header}, which extend to cover any marginal\index{marginalia} notes. +\begin{lcode} +\setlength{\headwidth}{\textwidth} + \addtolength{\headwidth}{\marginparsep} + \addtolength{\headwidth}{\marginparwidth} +\end{lcode} +Now we can set up an empty \pstyle{companion} pagestyle and start to change +it by specifying the new header\index{header} and footer\index{footer} width: +\begin{lcode} +\makepagestyle{companion} +\makerunningwidth{companion}{\headwidth} +\end{lcode} +and specify the width and thickness for the header\index{header} rule, otherwise it will +be invisible. +\begin{lcode} +\makeheadrule{companion}{\headwidth}{\normalrulethickness} +\end{lcode} + + In order to get the header\index{header} to stick out into the foredge margin\index{margin}, +verso headers\index{header} have to be flushright (raggedleft) and recto headers\index{header} +to be flushleft (raggedright). As the footers\index{footer} are empty, their position +is immaterial. +\begin{lcode} +\makeheadposition{companion}{flushright}{flushleft}{}{} +\end{lcode} + + The current chapter and section titles are obtained from the +\cmd{\leftmark} and \cmd{\rightmark} macros which are defined via the +\cmd{\chaptermark} and \cmd{\sectionmark} macros. Remember that +\cmd{\leftmark} is the last \meta{left} marker and \cmd{\rightmark} +is the first \meta{right} marker\index{markers} on the page. + +Chapter numbers are not +put into the header\index{header} but the section number, if there is one, is put into +the header\index{header}. We have to make sure that +the correct definitions are used for these, and this is where the +\cmd{\makepsmarks} macro comes into play. +\begin{lcode} +\makepsmarks{companion}{% + \let\@mkboth\markboth + \def\chaptermark##1{\markboth{##1}{##1}}% % left & right marks + \def\sectionmark##1{\markright{% % right mark + \ifnum \c@secnumdepth>\z@ + \thesection. \% % section number + \fi + ##1}} +} +\end{lcode} + + The preliminaries have all been completed, and it just remains to specify +what goes into each header\index{header} and footer\index{footer} slot (but the footers\index{footer} are empty). +\begin{lcode} +\makeevenhead{companion}% + {\normalfont\bfseries\thepage}{}{\normalfont\bfseries\leftmark} +\makeoddhead{companion}% + {\normalfont\bfseries\rightmark}{}{\normalfont\bfseries\thepage} +\end{lcode} + + Now issuing the command |\pagestyle{companion}| will produce pages +typeset with \pstyle{companion} pagestyle headers\index{header}. + + This definition is actually part of the class. If you want to alter it, or +use it as the basis for a style of your own, remember the caveats about +macros with |@| in their names. + +\subsection{Special headers} + + If you look at the Index\index{index} you will see that the header\index{header} shows the first and +last entries on the page. +A main entry in the index\index{index} looks like: +\begin{lcode} +\item \idxmark{entry}, page number(s) +\end{lcode} +and in the preamble\index{preamble} to this manual \cmd{\idxmark} is defined as +\begin{lcode} +\newcommand{\idxmark}[1]{#1\markboth{#1}{#1}} +\end{lcode} +This typesets the entry and also uses the entry as markers so that +the first entry on a page is held in \cmd{\rightmark} and the last +is in \cmd{\leftmark}. + + As index\index{index} entries are usually very short, the Index\index{index} is set in +two columns\index{column!double}. Unfortunately LaTeX's marking mechanism can be a little +fragile on twocolumn\index{column!double} pages, but the standard +\Lpack{fixltx2e} package~\cite{FIXLTX2E} corrects this. + + The index\index{index} itself is called by\index{indexing} +\begin{lcode} +\clearpage +\pagestyle{index} +\renewcommand{\preindexhook}{% +The first page number is usually, but not always, the primary reference to +the indexed topic.\vskip\onelineskip} +\printindex +\end{lcode} + +\makepagestyle{index} + \makeheadrule{index}{\textwidth}{\normalrulethickness} + \makeevenhead{index}{\rightmark}{}{\leftmark} + \makeoddhead{index}{\rightmark}{}{\leftmark} + \makeevenfoot{index}{\thepage}{}{} + \makeoddfoot{index}{}{}{\thepage} + + The \pstyle{index} pagestyle, which is the crux of +this example, is defined here as: +\begin{lcode} +\makepagestyle{index} + \makeheadrule{index}{\textwidth}{\normalrulethickness} + \makeevenhead{index}{\rightmark}{}{\leftmark} + \makeoddhead{index}{\rightmark}{}{\leftmark} + \makeevenfoot{index}{\thepage}{}{} + \makeoddfoot{index}{}{}{\thepage} +\end{lcode} +This, as you can hopefully see, puts the first and last index\index{index} entries +on the page into the header\index{header} at the left and right, with the folios\index{folio} +in the footers\index{footer} at the \foredge{} margin\index{margin}. + + I used Pehong Chen's +\textit{MakeIndex}\index{MakeIndex?\textit{MakeIndex}} program~\cite{CHEN88} +for converting the raw index\index{index} +data in the \file{.idx} file into the form expected by LaTeX in +the \file{.ind} file. \textit{MakeIndex} can be configured via an +\file{.ist} file, and the \file{memman.ist} file that I created for +this manual includes the mysterious lines +\begin{lcode} +% output main entry <entry> as: \item \idxmark{<entry>}, +item_0 "\n\\item \\idxmark{" +delim_0 "}," +\end{lcode} +Look up either Chen's paper~\cite{CHEN88} or Chapter~12 in~\cite{GOOSSENS94} +for an explanation of this cryptic code. + +\index{float!page|(} + +\begin{syntax} +\piif{ifonlyfloats}\marg{yes}\marg{no} \\ +\end{syntax} + There are occasions when it is desireable to have different headers\index{header} on +pages that only contain figures\index{figure} or tables\index{table}. If the command \piif{ifonlyfloats} +is issued on a page that contains no text and only floats then the \meta{yes} +argument is processed, otherwise on a normal page the \meta{no} argument +is processed. The command is most useful when defining a pagestyle that +should be different on a float-only page\index{page!of floats}. + + For example, assume that the \pstyle{companion} pagestyle is to be +generally used, but on float-only pages all that is required is a pagestyle +similar to \pstyle{plain}. Borrowing some code from the \pstyle{companion} +specification this can be accomplished like: +\begin{lcode} +\makepagestyle{floatcomp} +% \headwidth has already been defined for the companion style +\makeheadrule{floatcomp}{\headwidth}% + {\ifonlyfloats{0pt}{\normalrulethickness}} +\makeheadposition{floatcomp}{flushright}{flushleft}{}{} +\makepsmarks{floatcomp}{\companionpshook} +\makeevenhead{floatcomp}{\ifonlyfloats{}{\normalfont\bfseries\thepage}}% + {}{\ifonlyfloats{}{\normalfont\bfseries\leftmark}} +\makeoddhead{floatcomp}{\ifonlyfloats{}{\normalfont\bfseries\rightmark}}% + {}{\ifonlyfloats{}{\normalfont\bfseries\thepage}} +\makeevenfoot{floatcomp}{}{\ifonlyfloats{\thepage}{}}{} +\makeoddfoot{floatcomp}{}{\ifonlyfloats{\thepage}{}}{} +\end{lcode} +The code above for the \pstyle{floatcomp} style should be compared with +that for the earlier \pstyle{companion} style. + + The headrule is invisible on float pages by giving it zero thickness, +otherwise it has the \cmd{\normalrulethickness}. The head position is +identical for both pagestyles. However, the headers\index{header} are empty for +\pstyle{floatcomp} and the footers\index{footer} have centered page numbers +on float pages; on ordinary pages the footers\index{footer} are empty while the headers\index{header} +are the same as the \pstyle{companion} headers\index{header}. + + The code includes one `trick'. The macro \cmd{\makepsmarks}|{X}{code}| +is equivalent to +\begin{lcode} +\newcommand{\Xpshook}{code} +\end{lcode} +I have used this knowledge in the line: +\begin{lcode} +\makepsmarks{floatcomp}{\companionpshook} +\end{lcode} +which avoids having to retype the code from |\makepsmarks{companion}{...}|, +and ensures that the code is actually the same for the two pagestyles. + + +\begin{syntax} +\cmd{\mergepagefloatstyle}\marg{style}\marg{textstyle}\marg{floatstyle} \\ +\end{syntax} + If you have two pre-existing pagestyles, one that will be used for +text pages and the other that can be used for float pages, then the +\cmd{\mergepagefloatstyle} command provides a simpler means of combining +them than the above example code for \pstyle{floatcomp}. The argument +\meta{style} is the name of the pagestyle being defined. The +argument \meta{textstyle} +is the name of the pagestyle for text pages and \meta{floatstyle} is the +name of the pagestyle for float-only pages. Both of these must have been +defined before calling \cmd{\mergepagefloatstyle}. So, instead of the long +winded, and possibly tricky, code I could have simply said: +\begin{lcode} +\mergepagefloatstyle{floatcomp}{companion}{plain} +\end{lcode} + +\index{float!page|)} + + + \section{Epigraphs} +\index{epigraph|(} + + \tepi{The whole is more than the sum of the parts.} + {\textit{Metaphysica \\ Aristotle}} + + Some authors like to add an interesting quotation\index{quotation} at either the start + or end of a chapter. The class provides commands + to assist in the typesetting of a single epigraph. Other authors like to + add many such quotations\index{quotation} and the class provides environments to + cater for these as well. + Epigraphs can be typeset at either the left, the center or the right of + the typeblock\index{typeblock}. A few example eipgraphs are exhibited here, and + others can be found in an article by + Christina Thiele~\cite{TTC199} where she reviewed the \Lpack{epigraph} +package~\cite{EPIGRAPH} which is included in the class. + + \subsection{The \texttt{epigraph} command} + + The original inspiration for \cmd{\epigraph} was Doug Schenck's + for the epigraphs in our book~\cite{EBOOK}. That was hard wired for + the purpose at hand. The version here provides much more flexibility. + + +\begin{syntax} +\cmd{\epigraph}\marg{text}\marg{source} \\ +\end{syntax} + The command \cmd{\epigraph} + typesets + an epigraph using \meta{text} as the main text of the epigraph and + \meta{source} being the original author (or book, article, etc.) + of the quoted text. By default the epigraph is placed at the right hand + side of the typeblock\index{typeblock}, and the \meta{source} is typeset at the bottom + right of the \meta{text}. + + + \subsection{The \texttt{epigraphs} environment} + +\begin{syntax} +\senv{epigraphs} \\ + \cmd{\qitem}\marg{text}\marg{source} \\ + ... \\ +\eenv{epigraphs} \\ +\end{syntax} + The \Ie{epigraphs} environment typesets a list of epigraphs, and by default + places them at the right hand side of the typeblock\index{typeblock}. + Each epigraph in an \Ie{epigraphs} environment is specified by a + \cmd{\qitem} (analagous to the \cmd{\item} + command in ordinary list environments). + By default, the \meta{source} is typeset at the bottom right of the + \meta{text}. + + + + \subsection{General} + + \tepi{Example is the school of mankind, and they will learn at no other.} + {\textit{Letters on a Regicide Peace}\\ \textsc{Edmund Burke}} + + The commands described in this section apply to both the \cmd{\epigraph} + command and the |epigraphs| environment. But first of all, note that an + epigraph immediately after a heading\index{heading} will cause the first paragraph\index{paragraph!indentation} + of the following text to be indented. If you want the initial paragraph + to have no indentation, then start it with the \cmd{\noindent} command. + +\begin{syntax} + \lnc{\epigraphwidth} \\ +\cmd{\epigraphtextposition}\marg{flush} \\ +\end{syntax} + The epigraphs are typeset in a minipage of width \lnc{\epigraphwidth}. +The default + value for this can be changed using the \cmd{\setlength} command. Typically, + epigraphs are typset in a measure much less than the width of the typeblock\index{typeblock}. + In order to avoid bad line breaks, the \meta{text} is normally typeset + raggedright. + + The \meta{flush} argument to the \cmd{\epigraphtextposition} +declaration +controls the \meta{text} typesetting style. By default this is +\texttt{flushleft} (which produces raggedright text). The sensible values +are \texttt{center} for centered text, \texttt{flushright} for raggedleft +text, and \texttt{flushleftright} for normal justified text. + + If by any chance you want the \meta{text} to be typeset in some +other layout style, the easiest +way to do this is by defining a new environment which sets the paragraphing +parameters to your desired values. For example, as the \meta{text} is +typeset in a minipage, there is no paragraph indentation. If you +want the paragraphs to be indented and justified then define +a new environment like: +\begin{lcode} +\newenvironment{myparastyle}{\setlength{\parindent}{1em}}{} +\end{lcode} + and use it as: +\begin{lcode} +\epigraphtextposition{myparastyle} +\end{lcode} + +\begin{syntax} + \cmd{\epigraphposition}\marg{flush} \\ +\end{syntax} + As noted, the default position of epigraphs is at the right hand side + of the typeblock\index{typeblock}. The positioning is +controlled by +the \meta{flush} argument to the \cmd{\epigraphposition} declaration. +The default value is \texttt{flushright}. This can be changed + to \texttt{flushleft} for positioning at the left hand side or to + \texttt{center} for positioning at the center of the typeblock\index{typeblock}. + +\begin{syntax} + \cmd{\epigraphsourceposition}\marg{flush} \\ +\end{syntax} + The \meta{flush} argument to the \cmd{\epigraphsourceposition} +declaration controls the position +of the \meta{source}. + The default value is \texttt{flushright}. It can be changed to + \texttt{flushleft}, \texttt{center} or \texttt{flushleftright}. + + For example, to have epigraphs centered with the \meta{source} at the left, + add the following to your document. + \begin{lcode} + \epigraphposition{center} + \epigraphsourceposition{flushleft} + \end{lcode} + +\begin{syntax} +\cmd{\epigraphfontsize}\marg{fontsize} \\ +\end{syntax} + Epigraphs are often typeset in a smaller font than the main text. The +\meta{fontsize} argument to the \cmd{\epigraphfontsize} +declaration sets the font size to be used. + If you don't like the default value (\cmd{\small}), you can easily change +it to, say \cmd{\footnotesize} by: +\begin{lcode} +\epigraphfontsize{\footnotesize} +\end{lcode} + +\begin{syntax} + \lnc{\epigraphrule} \\ +\end{syntax} + By default, a rule is drawn between the \meta{text} and \meta{source}, + with the rule thickness being given by the value of \lnc{\epigraphrule}. + The value can be changed by using \cmd{\setlength}. + A value of \texttt{0pt} will eliminate the rule. Personally, I dislike + the rule in the list environments. + +\begin{syntax} + \lnc{\beforeepigraphskip} \\ + \lnc{\afterepigraphskip} \\ +\end{syntax} + The two |...skip| commands specify the amount of vertical space inserted + before and after typeset epigraphs. Again, these can be changed by + \cmd{\setlength}. It is desireable that the sum of their values should be an + integer multiple of the \lnc{\baselineskip}. + + Note that you can use normal LaTeX commands in the \meta{text} and + \meta{source} arguments. You may wish to use different fonts for the + \meta{text} (say roman) and the \meta{source} (say italic). + + The epigraph at the start of this section was specified as: + \begin{lcode} + \epigraph{Example is the school of mankind, + and they will learn at no other.} + {\textit{Letters on a Regicide Peace}\\ \textsc{Edmund Burke}} + \end{lcode} + + \subsection{Epigraphs before chapter headings} + + The \cmd{\epigraph} command and the |epigraphs| environment typeset + an epigraph at the point in the text where they are placed. The + first thing that a \cmd{\chapter} command does is to start off a new page, + so another mechanism is provided for placing an epigraph just before + a chapter heading\index{heading!chapter}. + +\begin{syntax} + \cmd{\epigraphhead}\oarg{distance}\marg{text} \\ +\end{syntax} + The \cmd{\epigraphhead} macro stores \meta{text} + for printing at \meta{distance} below the header\index{header} on a page. + \meta{text} can be ordinary text or, more likely, can be either an + \cmd{\epigraph} command or an |epigraphs| environment. By default, the + epigraph will be typeset at the righthand margin\index{margin}. + If the command is immediately preceded by a \cmd{\chapter} or \cmd{\chapter*} + command, the epigraph is typeset on the chapter title page. + + The default value for the optional \meta{distance} argument is set so + that an \cmd{\epigraph} consisting of a single line of quotation\index{quotation} and a single + line denoting the source is aligned with the bottom of the `Chapter X' + line produced by the \cmd{\chapter} command. In other cases you will + have to experiment with the \meta{distance} value. The value for + \meta{distance} can be either a integer or a real number. The units + are in terms of the current value for \lnc{\unitlength}. A typical value + for \meta{distance} for a single line quotation\index{quotation} and source for + a \cmd{\chapter*} might be about 70 (points). A positive value + of \meta{distance} places the epigraph below the page heading and a negative + value will raise it above the page heading. + + Here's some example code: + \begin{lcode} + \chapter*{Celestial navigation} + \epigraphhead[70]{\epigraph{Star crossed lovers.}{\textit{The Bard}}} + \end{lcode} + + + The \meta{text} argument is put into a minipage of width \lnc{\epigraphwidth}. + If you use something other than \cmd{\epigraph} or |epigraphs| for the + \meta{text} argument, you may have to so some positioning of the text + yourself so that it is properly located in the minipage. For example + \begin{lcode} + \chapter{Short} + \renewcommand{\epigraphflush}{center} + \epigraphhead{\centerline{Short quote}} + \end{lcode} + + The \cmd{\epigraphhead} command changes the page style for the page on + which it is specified, so there should be no text between the + \cmd{\chapter} and the \cmd{\epigraphhead} commands. The page style +is identical to the \pstyle{plain} page style except for the inclusion of +the epigraph. + If you want a more fancy style for epigraphed chapters you will have +to do some work yourself. + +\begin{syntax} +\cmd{\epigraphforheader}\oarg{distance}\marg{text} \\ +\cmd{\epigraphpicture} \\ +\end{syntax} +The \cmd{\epigraphforheader} macro takes the same arguments as +\cmd{\epigraphhead} but puts \meta{text} into a zero-sized picture at +the coordinate position |(0,-<distance>)|; the macro \cmd{\epigraphpicture} +holds the resulting picture. This can then be used as part of a +chapter pagestyle, as in +\begin{lcode} +\makepagestyle{mychapterpagestyle} +... +\makeoddhead{mychapterpagestyle}{}{}{\epigraphpicture} +\end{lcode} + + +\begin{syntax} + \cmd{\dropchapter}\marg{length} \\ + \cmd{\undodrop} \\ +\end{syntax} + If a long epigraph is placed before a chapter title it is possible that the + bottom of the epigraph may interfere with the chapter title. The command + \cmd{\dropchapter} will lower any subsequent chapter titles by + \meta{length}; a negative \meta{length} will raise the titles. + The command \cmd{\undodrop} restores subsequent chapter titles to their default + positions. For example: + \begin{lcode} + \dropchapter{2in} + \chapter{Title} + \epigraphhead{long epigraph} + \undodrop + \end{lcode} + +\index{epigraph|)} + +\begin{syntax} + \cmd{\cleartoevenpage}\oarg{text} \\ +\end{syntax} + On occasions it may be desirable to put something (e.g., an epigraph, a map, + a picture) on the page facing the start + of a chapter, where the something belongs to the chapter that is about to + start rather than the chapter that has just ended. In order to do this + in a document that is going to be printed + doublesided, the chapter must start on an odd numbered page and the + pre-chapter material put on the immediately preceding even numbered page. + The \cmd{\cleartoevenpage} command is like \cmd{\cleardoublepage} except + that the page following the command will be an even numbered page, and the + command takes an optional argument + which is applied to the skipped page (if any). + + Here is an example: +\begin{lcode} + ... end previous chapter. + \cleartoevenpage + \begin{center} + \begin{picture}... \end{picture} + \end{center} + \chapter{Next chapter} +\end{lcode} + If the style is such that chapter headings\index{heading!chapter} are put at the top of the pages, + then it would be advisable to include |\thispagestyle{empty}| (or |plain|) + immediately after |\cleartoevenpage| to avoid a heading related to the + previous chapter from appearing on the page. + + If the something is like a figure\index{figure} with a numbered caption and the numbering + depends on the chapter numbering, then the numbers have to be hand set (unless + you define a special chapter command for the purpose). For example: +\begin{lcode} + ... end previous chapter. + \cleartoevenpage[\thispagestyle{empty}] % skipped page, if any, to be empty + \thispagestyle{plain} + \addtocounter{chapter}{1} % increment the chapter number + \setcounter{figure}{0} % initialise figure counter + \begin{figure} + ... + \caption{Pre chapter figure} + \end{figure} + + \addtocounter{chapter}{-1} % decrement the chapter number + \chapter{Next chapter} % increments chapter & initialises figure numbers + \addtocounter{figure}{1} % to account for pre-chapter figure +\end{lcode} + + + \subsection{Epigraphs on part pages} + +\index{epigraph|(} + + The \Lpack{epigraph} package as it stands cannot put an epigraph on the + same page as a |\part| or |\part*| title page in + a \Lclass{book} or \Lclass{report} class. This is because the |\part| command + internally does some page flipping before and after the title page. + However, it is easy enough to put epigraphs on part\index{part} pages. + + \begin{itemize} + \item Create a file called, say, \file{epipart.sty} which looks like this: + \begin{verbatim} + % epipart.sty + \let\@epipart\@endpart + \renewcommand{\@endpart}{\thispagestyle{epigraph}\@epipart} + \endinput + \end{verbatim} + + \item Start your document like: + \begin{verbatim} + \documentclass[...]{...} + \usepackage{epigraph} + \usepackage{epipart} + \end{verbatim} + + \item Immediately \emph{before} each |\part| command put an + |\epigraphhead| command. For example: + \begin{verbatim} + \epigraphhead[300]{Epigraph text} + \part{Part title} + \end{verbatim} + The value of the optional argument may need changing to vertically adjust + the position of the epigraph. If there is any |\part| that does not have an + epigraph then an empty |\epigraphhead| command (i.e., |\epigraphhead{}|) + must be placed immediately before the |\part| command. + + \end{itemize} + + A similar scheme may be used for epigraphs on other kinds of pages. + The essential + trick is to make sure that the \pstyle{epigraph} pagestyle is used for + the page. + For an epigraphed bibliography\index{bibliography} +or index\index{index}, the macros \cmd{\prebibhook} +or \cmd{\preindexhook} can be appropriately modified to do this. + +\index{epigraph|)} + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\clearpage +\pagestyle{Ruled} +\chapterstyle{demo} +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\chapter{Typesetting verse} \label{chap:verse} + + This chapter uses the \cstyle{demo} chapterstyle and the \pstyle{Ruled} +pagestyle. + +\section{Introduction} + + The typesetting of a poem should be really be dependent on the +particular poem. Individual problems do not usually admit of a +general solution, so this manual and code should be used more +as a guide towards some solutions rather than providing a ready +made solution for any particular piece of verse. + + The doggerel used as illustrative material has been taken +from~\cite{RUMOUR}. + + Note that for the examples in this section I have made no attempt +to do other than use the minimal (La)TeX capabilities; in particular +I have made no attempt to do any special page breaking so some stanzas +may cross onto the next page --- most undesireable for publication. + + The standard LaTeX classes provide the \Ie{verse} environment which +is defined as a particular +kind of list. Within the environment you use \cmd{\\} to end a line, +and a blank line will end a stanza. For example, here is a single +stanza poem: +\begin{lcode} +\newcommand{\garden}{ +I used to love my garden \\ +But now my love is dead \\ +For I found a bachelor's button \\ +In black-eyed Susan's bed. +} +\end{lcode} +\newcommand{\garden}{ +I used to love my garden \\ +But now my love is dead \\ +For I found a bachelor's button \\ +In black-eyed Susan's bed. +} +When this is typeset as a normal LaTeX paragraph\index{paragraph} (with no paragraph +indentation) it looks like: \\[\baselineskip] +\garden{} + +\vspace*{\onelineskip} + + Typesetting it within the \Ie{verse} environment produces:% \\[\baselineskip] + +\begin{verse} +\garden +\end{verse} + +%\ablankline + +The stanza could also be typeset within the \Ie{alltt} environment, defined +in the standard \Lpack{alltt} package~\cite{ALLTT}, +using a normal font and no \cmd{\\} line endings. +\begin{lcode} +\begin{alltt}\normalfont +I used to love my garden +But now my love is dead +For I found a bachelor's button +In black-eyed Susan's bed. +\end{alltt} +\end{lcode} +which produces: + +\begin{alltt}\normalfont +I used to love my garden +But now my love is dead +For I found a bachelor's button +In black-eyed Susan's bed. +\end{alltt} + +The \Ie{alltt} environment is like the \Ie{verbatim} environment except that +you can use LaTeX macros inside it. + In the \Ie{verse} environment long lines will be wrapped and indented +but in the \Ie{alltt} environment there is no indentation. + +Some stanzas have certain lines indented, often alternate ones. To +typeset stanzas like this you have to add your own spacing. For +instance: +\begin{lcode} +\begin{verse} +There was an old party of Lyme \\ +Who married three wives at one time. \\ +\hspace{2em} When asked: `Why the third?' \\ +\hspace{2em} He replied: `One's absurd, \\ +And bigamy, sir, is a crime.' +\end{verse} +\end{lcode} +is typeset as: + +\begin{verse} +There was an old party of Lyme \\ +Who married three wives at one time. \\ +\hspace{2em} When asked: `Why the third?' \\ +\hspace{2em} He replied: `One's absurd, \\ +And bigamy, sir, is a crime.' +\end{verse} + +%\ablankline + +Using the \Ie{alltt} environment you can put in the spacing via ordinary +spaces. That is, this: +\begin{lcode} +\begin{alltt}\normalfont +There was an old party of Lyme +Who married three wives at one time. + When asked: `Why the third?' + He replied: `One's absurd, +And bigamy, sir, is a crime.' +\end{alltt} +\end{lcode} +is typeset as + +\begin{alltt} +\normalfont +There was an old party of Lyme +Who married three wives at one time. + When asked: `Why the third?' + He replied: `One's absurd, +And bigamy, sir, is a crime.' +\end{alltt} + +More exotically you could use the TeX \cmd{\parshape} +command\footnote{See the \textit{TeXbook} for how to use this.}: +\begin{lcode} +\parshape = 5 0pt \linewidth 0pt \linewidth + 2em \linewidth 2em \linewidth 0pt \linewidth +\noindent There was an old party of Lyme \\ +Who married three wives at one time. \\ +When asked: `Why the third?' \\ +He replied: `One's absurd, \\ +And bigamy, sir, is a crime.' \par +\end{lcode} +which will be typeset as: + +\vspace*{\onelineskip} + +\parshape = 5 0pt \linewidth 0pt \linewidth + 2em \linewidth 2em \linewidth 0pt \linewidth +\noindent There was an old party of Lyme \\ +Who married three wives at one time. \\ +When asked: `Why the third?' \\ +He replied: `One's absurd, \\ +And bigamy, sir, is a crime.' \par + + +\vspace*{\onelineskip} + + This is about as much assistance as standard (La)TeX provides, except +to note that in the \Ie{verse} environment the \cmd{\\*} version of \cmd{\\} +will prevent a following page break. You can also make judicious use +of the \cmd{\needspace} macro to keep things together. + + Some books of poetry, and especially anthologies, have two or more +indexes\index{index}, one, say for the poem titles and another for the first lines. +The \Lpack{index}~\cite{INDEX} and \Lpack{multind}~\cite{MULTIND} +packages provide support for multiple indexes\index{index} in one document. + +%\clearpage +\section{Classy verse} + + The code provided by the \Lclass{memoir} class is meant to help +with some aspects of typesetting poetry but does not, and cannot, +provide a comprehensive solution to all the requirements that +will arise. + + The main aspects of typesetting poetry that differ from typesetting +plain text are: +\begin{itemize} +\item Poems are usually visually centered on the page. +\item Some lines are indented, and often there is a pattern to the + indentation. +\item When a line is too wide for the page it is broken and the + remaining portion indented with respect to the original start + of the line. +\end{itemize} +These are the ones that the class attempts to deal with. + +\begin{syntax} +\senv{verse}\oarg{length} ... \eenv{verse} \\ +\lnc{\versewidth} \\ +\lnc{\stanzaskip} \\ +\end{syntax} +The \Ie{verse} environment provided by the class is an extension +of the usual LaTeX environment. The environment takes one optional +parameter, which is a length; for example |\begin{verse}[4em]|. +You may have noticed that the earlier verse examples are all +near the left margin\index{margin}, whereas verses usually look better if they +are typeset about the center of the page. The length parameter, +if given, should be about the length of an average line, and then +the entire contents will be typeset with the mid point of the length +centered horizontally on the page. + +The length \lnc{\versewidth} is provided as a convenience. It may be used, +for example, to calculate the length of a line of text for use +as the optional argument to the \Ie{verse} environment: +\begin{lcode} +\settowidth{\versewidth}{This is the average line,} +\begin{verse}[\versewidth] +\end{lcode} + + The vertical space between stanzas is the length \lnc{\stanzaskip}. +It can be changed by the usual methods. + +\begin{syntax} +\cmd{\\} \cmd{\\*} \cmd{\\>} \verb?\\!? \\ +\end{syntax} +Each line in the \Ie{verse} environment, except possibly for the last line +in a stanza, +must be ended with either \cmd{\\} or \cmd{\\*}. The starred +version prevents a page break before the following line. + The \cmd{\\>} command causes a break in the line (see the +description of the \cmd{\verselinebreak} macro). + +The \pixslashbang{} macro +may be used at the end of a line to signal the end of the stanza. This +would normally be followed by a blank line before the next stanza. + + Each of the |\\...| macros take an optional length argument. In the +case of the \cmd{\\}, \cmd{\\*} and \pixslashbang{} macros it introduces +the specified amount of vertical space. For \cmd{\\>} it specifies +a horizontal space. + +\begin{syntax} +\cmd{\vin} \\ +\lnc{\vgap} \\ +\lnc{\vindent} \\ +\end{syntax} +The command \cmd{\vin} is shorthand for |\hspace*{\vgap}| for use +at the start of an indented line of verse. The length \lnc{\vgap} +(initially 1.5em) can be changed by \cmd{\setlength} or \cmd{\addtolength}. + + Verse lines are sometimes indented according to the space taken by +the text on the previous line. +\begin{syntax} +\cmd{\vinphantom}\marg{text} \\ +\end{syntax} +The macro \cmd{\vinphantom} can be used at the start of a line of verse to +give an indentation as though the line started with \meta{text}. For example: +\begin{verse} +\ldots \\ +Come away with me. +\end{verse} +\begin{verse} +\vinphantom{Come away with me.} Impossible! \\ +\ldots +\end{verse} +The above fragment from a poem was typeset by: +\begin{lcode} +\begin{verse} +\ldots \\ +Come away with me. +\end{verse} +\begin{verse} +\vinphantom{Come away with me.} Impossible! \\ +\ldots +\end{verse} +\end{lcode} + + \cmd{\vinphantom} may also be used in the middle of any line to +leave some blank space. For example, compare the two lines below, +which are produced by this code: +\begin{lcode} +\noindent Come away with me and be my love --- Impossible. \\ + Come away with me \vinphantom{and be my love} --- Impossible. +\end{lcode} + +\noindent Come away with me and be my love --- Impossible. \\ +Come away with me \vinphantom{and be my love} --- Impossible. + + +When a verse line is too long to fit within the typeblock\index{typeblock} it is +wrapped onto the next line with a space, given by the value of the +length \lnc{\vindent}. The initial value of \lnc{\vindent} is twice +\lnc{\vgap}. + +\begin{syntax} +\cmd{\verselinebreak}\oarg{length} \\ +\end{syntax} +Using the command \cmd{\verselinebreak} will cause +later text in the +line of the verse to be typeset indented on the following line. +If the optional length argument is given then its value is added +to the normal indentation. +The broken +line will count as a single line as far as the \Ie{altverse}, +\Ie{patverse}, and \Ie{patverse*} environments are concerned. +The \cmd{\\>} macro is shorthand for \cmd{\verselinebreak}. + +\begin{syntax} +\senv{altverse} ... \eenv{altverse} \\ +\end{syntax} +Within the \Ie{verse} environment stanzas are separated by a blank line +in the input. Individual stanzas within \Ie{verse} may, however, +be enclosed in the \Ie{altverse} environment. This has the effect of +indenting the 2nd, 4th, etc., lines of the stanza by the length \lnc{\vgap}. + +\begin{syntax} +\senv{patverse} ... \eenv{patverse} \\ +\senv{patverse*} ... \eenv{patverse*} \\ +\cmd{\indentpattern}\marg{digits} \\ +\end{syntax} +As an alternative to the \Ie{altverse} environment, +individual stanzas within the \Ie{verse} environment may be enclosed +in the \Ie{patverse} environment. Within this environment the indentation +of each line is specified by an indentation pattern, which consists +of an array of digits, $d_{1}$ to $d_{n}$, and the $n^{th}$ line is +indented by $d_{n}$ times |\vgap|. The first line is +not indented, irrespective of the value of $d_{1}$ and if the number of +lines is greater than the pattern length, the trailing lines are not indented. + + The \Ie{patverse*} environment is similar to \Ie{patverse} except +that the indentation pattern will keep repeating until the end of the +environment. + + The indentation pattern for a \Ie{patverse} environment is specified +via the \cmd{\indentpattern} command, where \meta{digits} is a string +of digits (e.g., |3213245281|). + +\begin{syntax} +\cmd{\linenumberfrequency}\marg{nth} \\ +\cmd{\thepoemline} \\ +\cmd{\linenumberfont}\marg{font-decl} \\ +\lnc{\vrightskip} \\ +\end{syntax} + The lines in a poem may be numbered. The \cmd{\linenumberfrequency} +declaration +specifies that every \meta{nth} line is to be numbered. If \meta{nth} is +less than 1 then line numbering is switched off, if \meta{nth} is 1 then +every line will be numbered, and if \meta{nth} is, say 5, every fifth +line will be numbered. The default is |\linenumberfrequency{0}|. + + The counter for the lines is \Icn{poemline}, so the typeset form of the +line number is specified via \cmd{\thepoemline} +which defaults to arabic numbers. The number is positioned +in the right hand margin at a distance \lnc{\vrightskip} +(default 1em) from the edge +of the typeblock. The font used for the line numbers is specified +by \cmd{\linenumberfont}. The default definition is: \\ +|\linenumberfont{\small\rmfamily}| \\ +to produce small numbers in the roman font. + + +\begin{syntax} +\cmd{\flagverse}\marg{text} \\ +\lnc{\vleftskip} \\ +\end{syntax} +The \cmd{\flagverse} macro can be used at the start of a verse line, and +it typesets its \meta{text} argument at a distance \lnc{\vleftskip} +(default 3em) to the +left of the verse line. This could be used, for example, to number stanzas. + +\begin{syntax} +\cmd{\poemtitle}\oarg{short}\marg{long} \\ +\cmd{\poemtitle*}\marg{long} \\ +\cmd{\poemtitlefont}\marg{font} \\ +\end{syntax} +\cmd{\poemtitle} typesets the title +of a poem and makes an entry into the \toc. The starred version, +\cmd{\poemtitle*}, makes no \toc{} entry. +The \cmd{\poemtitlefont} macro specifies the font and positioning of +the poem title. Its initial definition is: \\ +|\newcommand{\poemtitlefont}{\normalfont\bfseries\large\centering}| \\ +to give a large bold centered title. This can of course be renewed +if you want something else. + +\begin{syntax} +\lnc{\beforepoemtitleskip} \\ +\lnc{\afterpoemtitleskip} \\ +\end{syntax} +These two lengths are the vertical space before and after the +\cmd{\poemtitle} +title text. They are initially defined to give the same spacing +as for a \cmd{\section} title. They can be changed by \cmd{\setlength} or +\cmd{\addtolength} for different spacings. + +\begin{syntax} +\cmd{\poemtitlemark}\marg{title} \\ +\end{syntax} +The \cmd{\poemtitle} macro, but not \cmd{\poemtitle*}, +calls the \cmd{\poemtitlemark}\marg{title} macro, +which is defined to do nothing. This would probably be changed by a +pagestyle definition (like \cmd{\sectionmark} or \cmd{\chaptermark} may be +modified). + +\begin{syntax} +\cmd{\poemtoc}\marg{sec} \\ +\end{syntax} +The kind of entry made in the \toc{} by the \cmd{\poemtitle} command is +defined by \cmd{\poemtoc}. The initial definition is: \\ +|\newcommand{\poemtoc}{section}| \\ +for a section-like \toc{} entry. This can be changed to, say, |chapter| +or |subsection| or \ldots. + + +%\clearpage +\subsection{Examples} + + Here are some sample verses using the class facilities. + +First our old Limerick friend, but titled and centered: +\begin{lcode} +\renewcommand{\poemtoc}{subsection} +\settocdepth{subsection} +\poemtitle{A Limerick} +\settowidth{\versewidth}{There was an old party of Lyme} +\begin{verse}[\versewidth] +There was an old party of Lyme \\ +Who married three wives at one time. \\ +\vin When asked: `Why the third?' \\ +\vin He replied: `One's absurd, \\ +And bigamy, sir, is a crime.' +\end{verse} +\end{lcode} +which gets typeset as below. The \cmd{\poemtoc} is redefined +to |subsection| so that the \cmd{\poemtitle} titles +are entered into the \toc{} as unnumbered subsections. +However, the \toc{} normally only lists sections and above, so +I also used \cmd{\settocdepth} to change this to subsections and +above\footnote{It is changed back at the end of this chapter.}. + +\renewcommand{\poemtoc}{subsection} +\settocdepth{subsection} +\poemtitle{A Limerick} +\settowidth{\versewidth}{There was an old party of Lyme} +\begin{verse}[\versewidth] +There was an old party of Lyme \\ +Who married three wives at one time. \\ +\vin When asked: `Why the third?' \\ +\vin He replied: `One's absurd, \\ +And bigamy, sir, is a crime.' +\end{verse} + +%\ablankline + + Next is the Garden verse within the |altverse| environment. It +is titled and centered. +\begin{lcode} +\settowidth{\versewidth}{But now my love is dead} +\poemtitle{Loves Lost} +\begin{verse}[\versewidth] +\begin{altverse} +\garden +\end{altverse} +\end{verse} +\end{lcode} +Note how the alternates lines are automatically indented in the +typeset result below. + +\settowidth{\versewidth}{But now my love is dead} +\poemtitle{Loves Lost} +\begin{verse}[\versewidth] +\begin{altverse} +\garden +\end{altverse} +\end{verse} + +% \ablankline + +It is left up to you how you might want to add information about +the author of a poem. Here is one example of a macro for this: +\begin{lcode} +\newcommand{\attrib}[1]{% + \nopagebreak{\raggedleft\footnotesize #1\par}} +\end{lcode} +\newcommand{\attrib}[1]{% + \nopagebreak{\raggedleft\footnotesize #1\par}} + + This can be used as in the next bit of doggerel. +\begin{lcode} +\poemtitle{Fleas} +\settowidth{\versewidth}{What a funny thing is a flea} +\begin{verse}[\versewidth] +What a funny thing is a flea. \\ +You can't tell a he from a she. \\ +But he can. And she can. \\ +Whoopee! +\end{verse} +\attrib{Anonymous} +\end{lcode} + +\poemtitle{Fleas} +\settowidth{\versewidth}{What a funny thing is a flea} +\begin{verse}[\versewidth] +What a funny thing is a flea. \\ +You can't tell a he from a she. \\ +But he can. And she can. \\ +Whoopee! +\end{verse} +\attrib{Anonymous} + +%\ablankline + +The next example demonstrates the automatic line wrapping for overlong +lines. +\begin{lcode} +\poemtitle{In the Beginning} +\settowidth{\versewidth}{And objects at rest tended to remain at rest} +\begin{verse}[\versewidth] +Then God created Newton, \\ +And objects at rest tended to remain at rest, \\ +And objects in motion tended to remain in motion, \\ +And energy was conserved + and momentum was conserved + and matter was conserved \\ +And God saw that it was conservative. +\end{verse} +\attrib{Possibly from \textit{Analog}, circa 1950} +\end{lcode} + +%%\enlargethispage{\baselineskip} +\poemtitle{In the Beginning} +\settowidth{\versewidth}{And objects at rest tended to remain at rest} +\begin{verse}[\versewidth] +Then God created Newton, \\ +And objects at rest tended to remain at rest, \\ +And objects in motion tended to remain in motion, \\ +And energy was conserved + and momentum was conserved + and matter was conserved \\ +And God saw that it was conservative. +\end{verse} +\attrib{Possibly from \textit{Analog}, circa 1950} + +%\ablankline + +The following verse demonstrates the use of a forced linebreak. It also +has a slightly different title style. +\begin{lcode} +\renewcommand{\poemtitlefont}{\normalfont\large\itshape\centering} +\poemtitle{Mathematics} +\settowidth{\versewidth}{Than Tycho Brahe, or Erra Pater:} +\begin{verse}[\versewidth] +In mathematics he was greater \\ +Than Tycho Brahe, or Erra Pater: \\ +For he, by geometric scale, \\ +Could take the size of pots of ale;\\ \settowidth{\versewidth}{Resolve by} +Resolve, by sines \\>[\versewidth] and tangents straight, \\ +If bread or butter wanted weight; \\ +And wisely tell what hour o' the day \\ +The clock does strike, by Algebra. +\end{verse} +\attrib{Samuel Butler (1612--1680)} +\end{lcode} + +\renewcommand{\poemtitlefont}{\normalfont\large\itshape\centering} +\poemtitle{Mathematics} +\settowidth{\versewidth}{Than Tycho Brahe, or Erra Pater:} +\begin{verse}[\versewidth] +In mathematics he was greater \\ +Than Tycho Brahe, or Erra Pater: \\ +For he, by geometric scale, \\ +Could take the size of pots of ale;\\ \settowidth{\versewidth}{Resolve by} +Resolve, by sines \\>[\versewidth] and tangents straight, \\ +If bread or butter wanted weight; \\ +And wisely tell what hour o' the day \\ +The clock does strike, by Algebra. +\end{verse} +\attrib{Samuel Butler (1612--1680)} + +%\ablankline +%\clearpage + +Another limerick, but this time taking advantage of the |patverse| +environment. If you are typesetting a series of limericks you only +need specify one \cmd{\indentpattern} for all of them. +\begin{lcode} +\settowidth{\versewidth}{There was a young lady of Ryde} +\indentpattern{00110} +\poemtitle{The Young Lady of Ryde} +\begin{verse}[\versewidth] +\begin{patverse} +There was a young lady of Ryde \\ +Who ate some apples and died. \\ +The apples fermented \\ +Inside the lamented \\ +And made cider inside her inside. +\end{patverse} +\end{verse} +\end{lcode} + +\settowidth{\versewidth}{There was a young lady of Ryde} +\indentpattern{00110} +\poemtitle{The Young Lady of Ryde} +\begin{verse}[\versewidth] +\begin{patverse} +There was a young lady of Ryde \\ +Who ate some apples and died. \\ +The apples fermented \\ +Inside the lamented \\ +And made cider inside her inside. +\end{patverse} +\end{verse} + + +The next example is a song that I have known since childhood. +The `forty-niner' in line~\ref{vs:1} refers to the 1849 gold rush. + +\clearpage + +\begin{lcode} +\settowidth{\versewidth}{Oh my darling, Clementine} +\poemtitle{Clementine} +\begin{verse}[\versewidth] +\linenumberfrequency{3} +\flagverse{1.} In a cavern, in a canyon, \\ +Excavating for a mine, \\ +Lived a miner, forty-niner, \label{vs:1} \\ +And his daughter, Clementine. \\! +\flagverse{\textsc{chorus}} Oh my darling, Oh my darling, \\ +Oh my darling, Clementine. \\ +Thou art lost and gone for ever. \\ +Dreadful sorry, Clementine. \\! +\linenumberfrequency{0} +\end{verse} +\end{lcode} + +\settowidth{\versewidth}{Oh my darling, Clementine} +\poemtitle{Clementine} +\begin{verse}[\versewidth] +\linenumberfrequency{3} +\flagverse{1.} In a cavern, in a canyon, \\ +Excavating for a mine, \\ +Lived a miner, forty-niner, \label{vs:1} \\ +And his daughter, Clementine. \\! +\flagverse{\textsc{chorus}} Oh my darling, Oh my darling, \\ +Oh my darling, Clementine. \\ +Thou art lost and gone for ever. \\ +Dreadful sorry, Clementine. \\! +\linenumberfrequency{0} +\end{verse} + + + The last example is a much more ambitious use of |\indentpattern|. In +this case it is defined as: \\ +|\indentpattern{0135554322112346898779775545653222345544456688778899}| \\ +and the result is shown on the next page. + + +\clearpage +\poemtitle{Mouse's Tale} +\settowidth{\versewidth}{a mouse that morning} +\indentpattern{0135554322112346898779775545653222345544456688778899} +\begin{verse}[\versewidth] +\setlength{\vgap}{1em} +\begin{patverse} +\large Fury said to \\ + a mouse, That \\ + he met \\ + in the \\ + house, \\ +\normalsize `Let us \\ + both go \\ + to law: \\ + \emph{I} will \\ + prosecute \\ + \textit{you.} --- \\ + Come, I'll \\ +\small take no \\ + denial; \\ + We must \\ + have a \\ + trial: \\ + For \\ +\footnotesize really \\ + this \\ + morning \\ + I've \\ + nothing \\ + to do.' \\ + Said the \\ + mouse to \\ +\scriptsize the cur, \\ + Such a \\ + trial, \\ + dear sir, \\ + With no \\ + jury or \\ + judge, \\ + would be \\ + wasting \\ + our breath.' \\ +\tiny `I'll be \\ + judge, \\ + I'll be \\ + jury.' \\ + Said \\ + cunning \\ + old Fury; \\ + `I'll try \\ + the whole \\ + cause \\ + and \\ + condemn \\ + you \\ + to \\ + death.' \par +\end{patverse} +\end{verse} +\attrib{Lewis Carrol, \textit{Alice's Adventures in Wonderland}, 1865} + +%%%%%%%%%%%%%%%%%%%%%%%%% +\settocdepth{section} +%%%%%%%%%%%%%%%%%%%%%%%% + +\chapter{Verbatims, boxes, and files} + +\section{Introduction} + + This chapter describes some new facilities for handling verbatim +text; new boxes to go around things, including verbatims; and a more +friendly interface for writing to and reading from files and in some +cases being able to read files verbatim, while putting them +into a box with line numbers. + +\section{Verbatims} + + I have included in the class the code for the \Lpack{shortvrb} +package~\cite{SHORTVRB} and an extended version of the \Lpack{verbatim} +package~\cite{VERBATIM}. I have also borrowed from the \Lpack{moreverb} +package~\cite{MOREVERB}. + + When processing text verbatim LaTeX ignores any special meaning +that a character may have. As a special case of this, LaTeX ignores +\emph{any} character in a comment. +\begin{syntax} +\cmd{\newcomment}\marg{comenv} \\ +\end{syntax} +The macro \cmd{\newcomment} creates a new comment environment called +\meta{comenv}. All text within the \meta{comenv} environment will be ignored. +\begin{syntax} +\senv{comment} anything \eenv{comment} \\ +\end{syntax} +The class provides one comment environment, namely the \Ie{comment} +environment which is specified by +\begin{lcode} +\newcomment{comment} +\end{lcode} +This may be useful for `commenting out' large chunks of +a source document. + +\begin{syntax} +\cmd{\commentsoff}\marg{comenv} \\ +\cmd{\commentson}\marg{comenv} \\ +\end{syntax} +The declaration \cmd{\commentsoff} switches off the commenting within +the \meta{comenv} comment environment, and the declaration +\cmd{\commentson} switches on commenting within the \meta{comenv} +comment environment. In either case, \meta{comenv} must have been previously +defined as a comment environment via \cmd{\newcomment}. + + Suppose, for example, that you are preparing a draft document for +review by some others and you want to include some notes for the reviewers. +Also, you want to include some private comments in the source for yourself. +You could use the \Ie{comment} environment for your private comments and +create another environment for the notes to the reviewers. These notes +should not appear in the final document. Your source might then look like: +\begin{lcode} +\newcomment{review} +\ifdraftdoc\else + \commentsoff{review} +\fi +... +\begin{comment} +Remember to finagle the wingle! +\end{comment} +... +\begin{review} +\textit{REVIEWERS: Please pay particular attention to this section.} +\end{review} +... +\end{lcode} + + LaTeX provides the \cmd{\verb} command for +typesetting short pieces of text verbatim; `short' means less than one +line. If you have to type a lot of verbatim bits, like macro names, +it becomes very tedious to keep on doing \verb!\verb?\amacro?!. +The \cmd{\verb*} macro is similar to \cmd{\verb} except that it +typesets the symbol \verb*? ? in place of a space. + +\begin{syntax} +\cmd{\MakeShortVerb}\marg{verbchar} \\ +\cmd{\DeleteShortVerb}\marg{verbchar} \\ +\end{syntax} + + With the \cmd{\MakeShortVerb} declaration you can use a single +character instead of |\verb|\meta{char}. The \meta{verbchar} +argument to \cmd{\MakeShortVerb} is a backslash followed by a single +character, for example |\MakeShortVerb{\?}|. +You can then use |?...?| instead of |\verb?...?|. To turn off +the use of |?| in this special manner, call |\DeleteShortVerb{\?}|. + +\begin{syntax} +\senv{verbatim} anything \eenv{verbatim} \\ +\senv{verbatim*} anything \eenv{verbatim*} \\ +\end{syntax} +The \Ie{verbatim} and \Ie{verbatim*} environments are used for +typesetting any length of verbatim text. + +\begin{syntax} +\cmd{\setverbatimfont}\marg{font-decl} \\ +\end{syntax} +The font that is used for \emph{all} verbatim text is specified +by \cmd{\setverbatimfont}. The default is: \\ +|\setverbatimfont{\normalfont\ttfamily}| \\ +If you wanted verbatims to be set in a smaller size, then this will +do the trick: +\begin{lcode} +\setverbatimfont{\normalfont\small\ttfamily} +\end{lcode} + +\begin{syntax} +\cmd{\tabson}\oarg{num} \\ +\cmd{\tabsoff} \\ +\end{syntax} +The standard \Ie{verbatim} environment ignores any TABs, or rather +treats a sequence of TABs as a single space. In the class, +if you use the declaration \cmd{\tabson} then TABs will not be ignored +in subsequent verbatims. The declaration \cmd{\tabsoff} turns off +tabbing inside verbatims. The default is |\tabsoff|. By default the class +uses four spaces for each tab. The optional \meta{num} argument to +\cmd{\tabson} will use \meta{num} spaces for each TAB. + +\begin{syntax} +\cmd{\wrappingon} \\ +\cmd{\wrappingoff} \\ +\lnc{\verbatimindent} \\ +\cmd{\verbatimbreakchar} \\ +\end{syntax} +Very occasionally it may be useful to wrap long verbatim lines round onto +the following line. After the declaration \cmd{\wrappingon}, verbatim lines +that would extend into the margin will be wrapped (\cmd{\wrappingoff} +returns the behaviour to normal). The second and later parts of a +wrapped line are indented by the length \lnc{\verbatimindent} which +can be altered in the usual manner. + + It may be desireable to indicate that a line is continued on the +next line. That is the role of \cmd{\verbatimbreakchar}. By default +this is defined as: \\ +|\newcommand*{\verbatimbreakchar}{\char`\%}| \\ +which typesets \% at the end of each line that is wrapped. To have +|/| at the end of each line instead, do: +\begin{lcode} +\renewcommand*{\verbatimbreakchar}{\char`\/} +\end{lcode} + + Note that trying both tabbing and wrapping together does not +always work well. It is best to do only one out of the two, and make +that tabbing. + + There is some more on verbatims in later sections. + +\section{Framed boxes} + + You can use framed boxes, looking like the syntax boxes here, +in the standard LaTeX classes but they cannot break over a page. + + The \Ie{framed}, \Ie{shaded} and \Ie{leftbar} environments, which +can break over a page, are from the \Lpack{framed} package~\cite{FRAMED}. + +\begin{syntax} +\senv{framed} text \eenv{framed} \\ +\senv{shaded} text \eenv{shaded} \\ +\senv{leftbar} text \eenv{leftbar} \\ +\end{syntax} +The \Ie{framed} environment puts the text into an \cmd{\fbox}-like +framed box the same width as the text width. The +\Ie{shaded} environment puts the text into a coloured box, and the +\Ie{leftbar} environment draws a vertical line at the left of the text. +In all cases the text and boxes can include page breaks. + +\begin{syntax} +\lnc{\FrameRule} \lnc{\FrameSep} \cmd{\FrameHeightAdjust} \\ +\Itt{shadecolor} \\ +\end{syntax} +The thickness of the rules is the length \lnc{\FrameRule} and the separation +between the text and the box is given by the length \lnc{\FrameSep}. +The height of the frame above the baseline at the top of a page is specified +by the macro \cmd{\FrameHeightAdjust}. The default definitions being: +\begin{lcode} +\setlength{\FrameRule}{\fboxrule} +\setlength{\FrameSep}{3\fboxsep} +\newcommand{\FrameHeightAdjust}{0.6em} +\end{lcode} +The background color in the \Ie{shaded} environment is specified by +\Itt{shadecolor} which you have to specify using the \Lpack{color} +package~\cite{COLOR}. For example: +\begin{lcode} +\usepackage{color} +\definecolor{shadecolor}{gray}{0.75} +\end{lcode} + +\begin{syntax} +\cmd{\frameasnormaltrue} \cmd{\frameasnormalfalse} \\ +\end{syntax} +Following the declaration \cmd{\frameasnormaltrue} paragraphing within +the environments will be as specified for the main text. After the declaration +\cmd{\frameasnormalfalse} paragraphing will be as though the environments +were like a \Ie{minipage}. The initial declaration is +\cmd{\frameasnormaltrue}. + + There is one known problem with framing: when framing is used on +a page where the page header is in a smaller type than the body, the +header may be moved slightly up or down. This can be avoided by putting +the font size change in a group, but it seems that a larger font does not need +to be grouped. For example: +\begin{lcode} +\makeoddhead{myheadings}{{\tiny Tiny header}}{}{\LARGE Large header} +\end{lcode} +The environments are a little +delicate. You cannot use floats, footnotes or marginpars inside them, +and they do not work in two column mode except for the standard +LaTeX supplied one. + + You can use the \Lpack{framed} package with the \Lclass{memoir} class, in +which case you will get whatever functionality is provided by the package as +it will override the class' code. + +\begin{syntax} +\senv{fboxverbatim} anything \eenv{fboxverbatim} \\ +\end{syntax} +The \Ie{fboxverbatim} environment is, except for its name, +identical to the \Ie{boxedverbatim} environment from the \Lpack{moreverb} +package~\cite{MOREVERB}. It puts a close fitting rectangular box +around its contents, which are typeset verbatim. + + +\begin{syntax} +\senv{boxedverbatim} anything \eenv{boxedverbatim} \\ +\end{syntax} +The \Ie{boxedverbatim} environment has the flavour of both the +\Ie{framed} and \Ie{fboxverbatim} environments, but it adds its +own bells and whistles. In its simplest usage the contents of the +environment are typeset verbatim in a rectangular box (or boxes as +it allows pagebreaks) like a \Ie{framed} box. + +\begin{syntax} +\cmd{\bvbox} \cmd{\bvsides} \cmd{\bvtopandtail} \cmd{\nobvbox} \\ +\end{syntax} +Four different kinds of framing styles are provided for the +\Ie{boxedverbatim} environment. After a \cmd{\bvbox} +declaration the default framing style is used, which draws rectangular +boxes. After the \cmd{\bvsides} declarations, rules are drawn on each +side but there are no top or bottom rules; the converse is +the \cmd{\bvtopandtail} declaration when only an initial and final +horizontal rule is drawn and no side rules. No rules at all are +drawn after \cmd{\nobvbox}. + +\begin{syntax} +\cmd{\bvtopofpage}\marg{text} \\ +\end{syntax} +With the default framing style (\cmd{\bvbox}) a heading can be put +at the top of continuation boxes if there is too much to fit onto +a page. The heading is the \meta{text} of \cmd{\bvtopofpage}. +The default specification is |\bvtopofpage{}| but if you wanted, say, to +indicate that the verbatim was a continuation from the previous +page you could do +\begin{lcode} +\bvtopofpage{\begin{center}\normalfont (Continued)\end{center}} +\end{lcode} + +\begin{syntax} +\cmd{\linenumberfrequency}\marg{nth} \\ +\cmd{\linenumberfont}\marg{font-decl} \\ +\cmd{\resetbvlinenumber} \\ +\end{syntax} +Exactly +as in the \Ie{verse} environment line numbers are printed +if the \meta{nth} argument to |\linenumberfrequency| is greater +than zero, and the numbers are set in the font defined via +\cmd{\linenumberfont}. +At any point outside the environment the line numbers may be reset +to the initial value by \cmd{\resetbvlinenumber}. + +\begin{syntax} +\cmd{\bvnumbersinside} \\ +\cmd{\bvnumbersoutside} \\ +\end{syntax} +If the lines are numbered, the numbers can be put inside the box +(\cmd{\bvnumbersinside}) or outside (\cmd{\bvnumbersoutside}). +In either case, numbers are set at the left of the lines. +The default is for numbers inside the box. + + Verbatim tabbing, but not wrapping, applies to the \Ie{boxedverbatim} +environment. + +\section{Files} + + Latex gives you the \cmd{\input} command to read a file but is really +not much obvious help if you want to write stuff out to a file. + + TeX has 16 `streams' that can be open simultaneously for writing +out, and there are also 16 input streams. These streams can be attached +to files so that data can be read out and read in from external files. + +\begin{syntax} +\cmd{\newoutputstream}\marg{stream} \\ +\cmd{\newinputstream}\marg{stream} \\ +\end{syntax} + The command \cmd{\newoutputstream} creates a new stream +called \meta{stream} for writing out text and commands. +The \meta{stream} argument must be just alphabetic characters with +no spaces; for example |myout|. +Similarly, the command \cmd{\newinputstream} creates a new stream for +reading from a file. The \meta{stream} names must be unique --- you cannot +use the same name for both an input and an output stream. + + If you try and create too many streams, TeX will tell you via an error +message. + +\begin{syntax} +\cmd{\IfStreamOpen}\marg{stream}\marg{true-code}\marg{false-code} \\ +\end{syntax} +You can check if a stream \meta{stream} is currently open +by \cmd{\IfStreamOpen}. +If the stream is open then the \meta{true-code} argument will be processed, +otherwise the stream is closed and the \meta{false-code} argument +is processed. + + +\begin{syntax} +\cmd{\openoutputfile}\marg{filename}\marg{stream} \\ +\cmd{\closeoutputstream}\marg{stream} \\ +\end{syntax} + The macro \cmd{\openoutputfile} opens the +file called \meta{filename} and the output stream \meta{stream}. It +then attaches the file to the stream for writing. Any pre-existing +contents of \meta{filname} are deleted. + + The macro \cmd{\closeoutputstream} closes the output stream +\meta{stream} and closes whatever file is currently attached to +\meta{stream}. It then detaches the file from + the stream. + +\begin{syntax} +\senv{writeverbatim}\marg{stream} anything \eenv{writeverbatim} \\ +\end{syntax} + The \Ie{writeverbatim} environment takes one argument, +the name of an output stream, which must be open. +The contents of the environment are written +out verbatim to the file currently attached to the stream. + +\begin{syntax} +\cmd{\addtostream}\marg{stream}\marg{text} \\ +\end{syntax} + The command \cmd{\addtostream} writes \meta{text} +to the file currently attached to the output stream \meta{stream}, which +must be open. Any commands within \meta{text} will be processed before +being written. To prevent this, put \cmd{\protect} before any command that +you do not want expanding. + +\begin{syntax} +\cmd{\openinputfile}\marg{filename}\marg{stream} \\ +\cmd{\closeinputstream}\marg{stream} \\ +\end{syntax} + + The macro \cmd{\openinputfile} opens the +file called \meta{filename} and the input stream \meta{stream}. It +then attaches the file to the stream for reading. +It is an error if \meta{filename} can not be found. + + The macro \cmd{\closeinputstream}closes the input stream +\meta{stream} and closes whatever file +is currently attached to \meta{stream}. It then detaches the file from +the stream. + +\begin{syntax} +\cmd{\readstream}\marg{stream} \\ +\cmd{\readaline}\marg{stream} \\ +\end{syntax} + The macro \cmd{\readstream} reads the contents of the file that +is currently associated with the input stream \meta{stream}. This provides +the same functionality as \cmd{\input}\marg{filename} does. + + The macro \cmd{\readaline} reads what TeX considers to be +one line from the file that +is currently associated with the input stream \meta{stream}. Multiple lines +can be read by calling \cmd{\readaline} multiple times. A warning is issued +if there are no more lines to be read (i.e., the end of the file has +been reached). + +\begin{syntax} +\cmd{\verbatiminput}\marg{filename} \\ +\cmd{\readverbatim}\marg{stream} \\ +\cmd{\boxedverbatiminput}\marg{filename} \\ +\cmd{\readboxedverbatim}\marg{stream} \\ +\end{syntax} +The macro \cmd{\verbatiminput} is similar to \cmd{\input} except +that it inputs the contents of the file \meta{filename} as verbatim text. +Similarly, \cmd{\readverbatim} reads the contents of the file that +is currently associated with the input stream \meta{stream} as verbatim +text. These two commands are equivalent to +\begin{lcode} +\begin{verbatim} + \input{...} + \readstream{...} +\end{verbatim} +\end{lcode} +except, of course, that you cannot do that. + + To round things out, \cmd{\boxedverbatiminput} inputs the contents +of the \meta{filename} file as boxed verbatim text, and +\cmd{\readboxedverbatim} reads the contents +of the file attached to \meta{stream} as a boxed verbatim. If you could +do it, these commands are equivalent to +\begin{lcode} +\begin{boxedverbatim} + \input{...} + \readstream{...} +\end{boxedverbatim} +\end{lcode} + + Tabbing, wrapping and numbering are just as applicable to verbatim +input texts as they are to the corresponding verbatim environments. + + + + + + + + + + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\clearpage +\pagestyle{Ruled} +\chapterstyle{demo} +%\chapterstyle{veelo} +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\chapter{Miscellaneous} \label{chap:misc} + +\chapterprecis{In which we talk of many things, but not ships + or shoes or sealing wax, nor cabbages and kings.} + + This chapter uses the \cstyle{demo} chapterstyle and the \pstyle{Ruled} +pagestyle. It started with the \cmd{\chapterprecis} command. + +\section{Introduction} + + The class provides some minor additional facilities, which are described +here. + +\section{Draft documents} + + The \Lopt{draft} option marks any overfull lines with black rectangles, +otherwise the appearance is the same as for a \Lopt{final} document. + +\begin{syntax} +\piif{ifdraftdoc} \\ +\end{syntax} +The \piif{ifdraftdoc} macro is provided so that you can add extra +things that you might want to happen when processing a draft; for example +you might want to have each page header\index{header} (or footer\index{footer}) include the word `DRAFT'. +The code to do this can be put into a construct like the following: +\begin{lcode} +\ifdraftdoc + % special things for a draft document +\else + % perhaps special things for a non-draft document +\fi +\end{lcode} + + +\section{Change marks} + + When preparing a manuscript it normally goes through several iterations. +The macros described in this section can be used to identify changes made to +a document throughout its lifecycle. + + The commands below implement a simplified version of the change +marking in the \Lclass{iso} class~\cite{ISOCLASS}. + +\begin{syntax} +\cmd{\changemarkstrue} \cmd{\changemarksfalse} \\ +\end{syntax} +The change marking macros only work properly when the \Lopt{draft} class +option is used. Additionaly, the marks are only printed when the +\cmd{\changemarkstrue} declaration is in effect. Using \cmd{\changemarksfalse} +switches off any marking. + +\begin{syntax} +\cmd{\added}\marg{change-id} \\ +\cmd{\deleted}\marg{change-id} \\ +\cmd{\changed}\marg{change-id} \\ +\end{syntax} +Each of these macros puts a mark and \meta{change-id} into the margin\index{margin} near +where the command is given. The \cmd{\added} macro indicates that something +has been added to the manuscript and uses $\oplus$ as its symbol. The +\cmd{\deleted} macro is for indicating that something has been deleted and uses +the $\neq$ symbol. The macro \cmd{\changed} uses the $\Leftrightarrow$ symbol +to indicate that something has been changed. + + These marking commands should be attached to some word or punctuation +mark in the text otherwise extraneous spaces may creep into the typeset +document. + +\section{Trim marks} + + When the \Lclass{memoir} class \Lopt{showtrims} option is used, trim +marks can be placed on each page, usually to indicate where the stock should +be trimmed to obtain the planned page size. + + Trim marks can be placed at each corner of the (trimmed) page, and also +at the middle of each side of the page. + +\begin{syntax} +\cmd{\trimXmarks} \\ +\cmd{\trimLmarks} \\ +\cmd{\trimFrame} \\ +\cmd{\trimNone} \\ +\end{syntax} +Some predefined trimming styles are provided. After the declaration +\cmd{\trimXmarks} marks in the shape of a cross are placed at the four +corners of the page. The declaration \cmd{\trimLmarks} calls for corner marks +in the shape of an `L', in various orientations depending on the particular +corner. After \cmd{\trimFrame} a frame will be drawn around each page, +coinciding with the page boundaries. The declaration \cmd{\trimNone} +disables all kinds of trim marking. + +\begin{syntax} +\cmd{\trimmarks} \\ +\cmd{\tmarktl} \cmd{\tmarktr} \cmd{\tmarkbr} \cmd{\tmarkbl} \\ +\cmd{\tmarktm} \cmd{\tmarkmr} \cmd{\tmarkbm} \cmd{\tmarkml} \\ +\end{syntax} +The \cmd{\trimmarks} macro is responsible for displaying up to 8 marks. The +marks are defined as zero-sized pictures which are placed strategically +around the borders of the page. + + The command \cmd{\trimmarks} places the pictures \cmd{\tmarktl}, +\cmd{\tmarktr}, +\cmd{\tmarkbl}, and \cmd{\tmarkbr} at the top left, top right, +bottom right and bottom left corners of the page. The pictures +\cmd{\tmarktm}, \cmd{\tmarkmr}, \cmd{\tmarkbm}, and \cmd{\tmarkml} are placed +at the top middle, middle right, bottom middle and middle left of the +edges of the page. All these |\tmark..| macros should expand to zero-sized +pictures. + +\begin{syntax} +\cmd{\trimmark} \\ +\end{syntax} +The declaration \cmd{\trimXmarks} uses \cmd{\trimmark} for the corner +crosses. This is defined as +\begin{lcode} +\newcommand{\trimmark}{% + \begin{picture}(0,0) + \setlength{\unitlength}{1cm}\thicklines + \put(-2,0){\line(1,0){4}} + \put(0,-2){\line(0,1){4}} + \end{picture}} +\end{lcode} +which produces a zero-sized picture of a 4cm cross. + + As an example, to draw short lines marking the half-height of the page, +try this: +\begin{lcode} +\providecommand{\tmarkml}{} +\renewcommand{\tmarkml}{% + \begin{picture}(0,0){% + \unitlength 1mm + \thinlines + \put(-2,0){\line(-1,0){10}} + \end{picture}}} +\providecommand{\tmarkmr}{} +\renewcommand{\tmarkmr}{% + \begin{picture}(0,0){% + \unitlength 1mm + \thinlines + \put(2,0){\line(1,0){10}} + \end{picture}}} +\end{lcode} +Thin horizontal lines of length 10mm will be drawn at the middle left and +middle right of the page, starting 2mm outside the page boundary. + +\section{Sheet numbering} + + One purpose of trim marks is to show a printer where the stock +should be trimmed. In this application it can be useful to also note the +sheet number on each page, where the sheet number is 1 for the first page +and increases by 1 for each page thereafter. The sheet number is independent +of the page number. + +\begin{syntax} +\cmd{\thesheetsequence} \\ +\end{syntax} +The macro \cmd{\thesheetsequence} typesets the current sheet sequence number +and is analogous to the \cmd{\thepage} macro. + +\begin{syntax} +\Icn{lastsheet} \\ +\Icn{lastpage} \\ +\end{syntax} +The counter \Icn{lastsheet} holds the number of sheets processed during +the \emph{previous} run of LaTeX. Similarly, the counter \Icn{lastpage} +holds the number of the last page processed during the previous run. +Note that the last page number is not necessarily the same as the last +sheet number. For example: \\ +\textit{In this document this is + sheet \thesheetsequence\ of \thelastsheet\ sheets, + and page \thepage\ of \thelastpage.} + +The previous sentence was the result of processing the following +code +\begin{lcode} +\textit{In this document this is + sheet \thesheetsequence\ of \thelastsheet\ sheets, + and page \thepage\ of \thelastpage.} +\end{lcode} + + You may wish to use the sheet and/or page numbers as part of some +trim marks. The following will note the sheet numbers above the page. +\begin{lcode} +\newcommand{\trimseqpage}{% + \begin{picture}(0,0) + \unitlength 1mm + \put(0,2){\makebox(0,0)[b]{Sheet: \thesheetsequence\ of \thelastsheet}} + \end{picture}} +\let\tmarktm\trimseqpage +\end{lcode} + + +\section{Page breaks before lists} + + A sentence or two may be used to introduce a list (e.g., |itemize|) +and it can be annoying if there is a page break between the introduction +and the first item. +\begin{syntax} +\cmd{\noprelistbreak} \\ +\end{syntax} +Putting \cmd{\noprelistbreak} immediately before the |\begin{itemize}| +should prevent a page break. Ideally, there sould be no blank lines +between the end of the introduction and the start of the list. + +\section{Changing counters} + + This is effectively a bundling of the \Lpack{chngcntr} +package~\cite{CHNGCNTR}. + +\begin{syntax} +\cmd{\newcounter}\marg{ctr}\oarg{within} \\ +\cmd{\thectr} \\ +\end{syntax} + In LaTeX a new counter called, say |ctr|, is created by the +\cmd{\newcounter} command as |\newcounter{ctr}|. If the optional \meta{within} +argument is given, the counter \meta{ctr} is reset to zero each time the +counter called |within| is changed; the |within| counter must exist before +it is used as the optional argument. The command |\thectr| typesets the value +of the counter |ctr|. This is automatically defined for you by the +\cmd{\newcounter} command to typeset arabic numerals. + +\begin{syntax} +\cmd{\counterwithin}\marg{ctr}\marg{within} \\ +\cmd{\counterwithin*}\marg{ctr}\marg{within} \\ +\end{syntax} +The \cmd{\counterwithin} macro makes a \meta{ctr} that has been initially +defined by |\newcounter{ctr}| act as though it had been defined by +|\newcounter{ctr}[within]|. It also redefines the |\thectr| command +to be |\thewithin.\arabic{ctr}|. The starred version of the command +does nothing to the original definition of |\thectr|. + +\begin{syntax} +\cmd{\counterwithout}\marg{ctr}\marg{within} \\ +\cmd{\counterwithout*}\marg{ctr}\marg{within} \\ +\end{syntax} +The \cmd{\counterwithout} macro makes a \meta{ctr} that has been initially +defined by |\newcounter{ctr}[within]| act as though it had been defined by +|\newcounter{ctr}|. It also redefines the |\thectr| command +to be |\arabic{ctr}|. The starred version of the command +does nothing to the original definition of |\thectr|. + + Any number of |\counterwithin{ctr}{...}| and |\counterwithout{ctr}{...}| +commands can be issued for a given counter |ctr| if you wish to toggle +between the two styles. The current value of |ctr| is unaffected by these +commands. If you want to change the value use \cmd{\setcounter}, and to change +the typesetting style use \cmd{\renewcommand} on |\thectr|. + +\section{New new and provide commands} + +\begin{syntax} +\cmd{\newloglike}\marg{cmd}\marg{string} \\ +\cmd{\newloglike*}\marg{cmd}\marg{string} \\ +\end{syntax} +The class provides means of creating new math log-like functions. For +example you might want to do +\begin{lcode} +\newloglike{\Ei}{Ei} +\end{lcode} +if you are using the exponential integral function in your work. +The starred version of the command creates a function that takes limits +(like the \cmd{\max} function). + + The LaTeX kernel defines the \cmd{\providecommand} macro that acts +like \cmd{\newcommand} if the designated macro has not been defined +previously, otherwise it does nothing. The class adds to that limited +repetoire. + +\begin{syntax} +\cmd{\provideenvironment}\marg{name}\oarg{numargs}\oarg{optarg}\marg{begindef}\marg{enddef} \\ +\cmd{\providelength}\marg{cmd} \\ +\cmd{\providecounter}\marg{ctr}\oarg{within} \\ +\cmd{\provideloglike}\marg{cmd}\marg{string} \\ +\cmd{\provideloglike*}\marg{cmd}\marg{string} \\ +\end{syntax} + + The macros \cmd{\provideenvironment}, \cmd{\providelength} +and \cmd{\providecounter} take the same arguments as their |\new...| +counterparts. If the environment, length or counter has not been defined +then it is defined accordingly, otherwise the macros do nothing except +produce a warning message for information purposes. + + The \cmd{\provideloglike} commands are for math log-like functions, +but they do not produce any warning messages. + +\section{Changing macros} \label{sec:addtodef} + + Commands are provided for extending simple macro definitions. +Get the \Lpack{patchcmd} package~\cite{PATCHCMD} if you need +to make other additions to definitions. + +\begin{syntax} +\cmd{\addtodef}\marg{macro}\marg{prepend}\marg{append} \\ +\cmd{\addtoiargdef}\marg{macro}\marg{prepend}\marg{append} \\ +\end{syntax} +The macro \cmd{\addtodef} inserts \meta{prepend} at the start of the +current definition of \meta{macro} and puts \meta{append} at the end, +where \meta{macro} is the name of a macro (including the backslash) which +takes no arguments. The \cmd{\addtoiargdef} macro is similar except that +\meta{macro} is the name of a macro that takes one argument. + + For example the following are two equivalent +definitions of |\mymacro|: +\begin{lcode} +\newcommand{\mymacro}[1]{# is a violinist in spite of being tone deaf} +\end{lcode} +and +\begin{lcode} +\newcommand{\mymacro}[1]{#1 is a violinist} +\addtoiargdef{\mymacro}{}{ in spite of being tone deaf} +\end{lcode} + + The \cmd{\addtoiargdef} (and \cmd{\addtodef}) commands +can be applied several times to the same \meta{macro}. Revising the +previous example we could have +\begin{lcode} +\newcommand{\mymacro}[1]{#1 is a violinist} +\addtoiargdef{\mymacro}{Although somewhat elderly, }% + { in spite of being tone deaf} +\addtoiargdef{\mymacro}{}{ and a bagpiper} +\end{lcode} +which is equivalent to +\begin{lcode} +\newcommand{\mymacro}[1]{% + Although somewhat elderly, #1 is a violinist + in spite of being tone deaf and a bagpiper} +\end{lcode} + +The \meta{prepend} and \meta{append} arguments may include LaTeX code, +as shown in this extract from the class code: +\begin{lcode} +\addtoiargdef{\date}{}{% + \begingroup + \renewcommand{\thanks}[1]{} + \renewcommand{\thanksmark}[1]{} + \renewcommand{\thanksgap}[1]{} + \protected@xdef\thedate{#1} + \endgroup} +\end{lcode} +Note that in the case of \cmd{\addtoiargdef} an argument can also refer +to the original argument of the \meta{macro}. + +\begin{syntax} +\cmd{\addtodef*}\marg{macro}\marg{prepend}\marg{append} \\ +\cmd{\addtoiargdef*}\marg{macro}\marg{prepend}\marg{append} \\ +\end{syntax} +These starred versions are for use when the original \meta{macro} +was defined via \cmd{\newcommand*}. Using the starred versions is +like using \cmd{\renewcommand*} and the unstarred versions are like +having used \cmd{\renewcommand}. It is the version (starred or unstarred) +of a sequence of |\addto...| commands that counts when determining whether +the equivalent |\renew...| is treated as starred or unstarred. + + The |\addto...| macros cannot be used to delete any code from +\meta{macro} nor to add anything except at the start and end. Also, +in general, they cannot be used to change the definition of a macro that +takes an optional argument, or that is starred. + +\section{String arguments} + + In the code for the class I have sometimes used macro arguments +that consist of a `string', like the |*| arguments in the page layout +macros (e.g., \cmd{\settypeblocksize}), or the |flushleft|, |center| and +|flushright| strings for the \cmd{\makeheadposition} macro. + +\begin{syntax} +\cmd{\nametest}\marg{str1}\marg{str2} \\ +\piif{ifsamename} \\ +\end{syntax} +The macro \cmd{\nametest} takes two strings +as the arguments \meta{str1} and \meta{str2}. It sets \piif{ifsamename} +TRUE if \meta{str1} is the same as \meta{str2}, otherwise it sets +\piif{ifsamename} FALSE. For the purposes of \cmd{\nametest}, a string is a +sequence of characters which may include spaces and may include +the |\| backslash character; strings are equal if and only if their +character sequences are identical. + + + Typically, I have used it within macros for checking on argument +values. For example: +\begin{lcode} +\newcommand{\amacro}[1]{% + \nametest{#1}{green} + \ifsamename +% code for green + \fi + \nametest{#1}{red} + \ifsamename +% code for red + \fi + ... +} +\end{lcode} + +\section{Odd/even page checking} + + It is difficult to check robustly if the current page is odd or even but +the class does provide a robust method based on writing out a label and then +checking the page reference for the label. This requires at least two LaTeX +runs to stabilise. This has been extracted from the original +\Lpack{chngpage} package~\cite{CHNGPAGE}. + +\begin{syntax} +\cmd{\checkoddpage} \\ +\piif{ifoddpage} \\ +\cmd{\strictpagechecktrue} \cmd{\strictpagecheckfalse} \\ +\end{syntax} +The macro \cmd{\checkoddpage} sets +\piif{ifoddpage} +to TRUE if the page number +is odd, otherwise it sets it to FALSE (the page number is even). The robust +checking methos involves writing and reading labels, which is what is done +after the command \cmd{\strictpagechecktrue} is issued. The simple method is just +to check the current page number which, because of TeX's asynchronous page +breaking algorithm, may not correspond to the actual page number where the +\cmd{\checkoddpage} commmand was issued. The simple, but faster, page checking +method is used after the \cmd{\strictpagecheckfalse} command is issued. + +\begin{syntax} +\cmd{\cplabel} \\ +\end{syntax} +When strict page checking is used the labels consist of a number preceded +by the value of \cmd{\cplabel}, whose default definition is |^_| (e.g., +a label may consist of the characters |^_21|). If this +might clash with any of your labels, change \cmd{\cplabel} with \cmd{\renewcommand}, but +the definition of \cmd{\cplabel} must be constant for any given document. + +\section{Moving to another page} \label{sec:moving} + + Standard LaTeX provides the \cmd{\newpage}, \cmd{\clearpage} +and \cmd{\cleardoublepage} commands for discontinuing the current +page and starting a new one. The following is a bundling of the +\Lpack{nextpage} package~\cite{NEXTPAGE}. + +\begin{syntax} +\cmd{\needspace}\marg{length} \\ +\end{syntax} +This macro decides if there is \meta{length} space at the bottom of the +current page. If there is it does nothing, otherwise it starts a new page. +This is useful if \meta{length} amount of material is to be kept together +on one page. The \cmd{\needspace} macro +depends on penalties for deciding what to do which means that the reserved +space is an approximation. However, except for the odd occasion, the +macro gives adequate results. + +\begin{syntax} +\cmd{\Needspace}\marg{length} \\ +\cmd{\Needspace*}\marg{length} \\ +\end{syntax} + Like \cmd{\needspace}, the \cmd{\Needspace} macro checks if there is +\meta{length} space at the bottom of the current page and if there is not +it starts a new page. The command should only be used between paragraphs; +indeed, the first thing it does is to call \cs{par}. The \cmd{\Needspace} +command checks for the actual space left on the page and is more exacting +than \cmd{\needspace}. + + If either \cmd{\needspace} or \cmd{\Needspace} produce a short page it +will be ragged bottom even if \cmd{\flushbottom} is in effect. With +the starred \cmd{\Needspace*} version, short pages will be flush bottom +if \cmd{\flushbottom} is in effect and will be ragged bottom +when \cmd{\raggedbottom} is in effect. + + Generally speaking, use \cmd{\needspace} in preference to \cmd{\Needspace} +unless it gives a bad break or the pages must be flush bottom. + + +\begin{syntax} +\cmd{\movetoevenpage}\oarg{text} \\ +\cmd{\cleartoevenpage}\oarg{text} \\ +\end{syntax} +The \cmd{\movetoevenpage} stops the current page and starts typesetting on the +next even numbered page. The |\clear...| version flushes out all +floats\index{float} before +going to the next even page. The optional \meta{text} is put on the skipped +page (if there is one). + +\begin{syntax} +\cmd{\movetooddpage}\oarg{text} \\ +\cmd{\cleartooddpage}\oarg{text} \\ +\end{syntax} +These macros are similar to the |\...evenpage| ones except that they jump +to the next odd numbered page. + + A likely example for the optional \meta{text} argument is +\begin{lcode} +\cleartooddpage[\vspace*{\vfill}THIS PAGE LEFT BLANK\vspace*{\vfill}] +\end{lcode} +which will put `THIS PAGE LEFT BLANK' in the centre of any +potential skipped (empty) even numbered page. + +\begin{syntax} +\cmd{\cleartorecto} \cmd{\cleartoverso} \\ +\end{syntax} +These are slightly simpler forms\footnote{Perhaps more robust.} of +\cmd{\cleartooddpage} and \cmd{\cleartoevenpage}. For example, if you wanted +the Table of Contents to start on a verso page, like in +\textit{The TeXbook} \cite{KNUTH84a}, then do this: +\begin{lcode} +\cleartoverso +\tableofcontents +\end{lcode} + +\section{Number formatting} + + Several methods are provided for formatting numbers. Two classes +of number representations are catered for. A `numeric number' is +typeset using arabic digits and a `named number' is typeset using +words. + + The argument to the number formatting macros is a `number', +essentially something that resolves to a series of arabic digits. Typical +arguments might be: +\begin{itemize} +\item Some digits, e.g., \verb?\ordinal{123} ->? + \ordinal{123} +\item A macro expanding to digits, e.g., \verb?\def\temp{3}\ordinal{\temp} ->? + \begingroup\def\temp{3}\ordinal{\temp}\endgroup % \\ + +% Or even, for example, \verb?\ordinal{\pageref{chap:numf}} ->? +% \ordinal{\pageref{chap:numf}} +\item The value of a counter, e.g., \verb?\ordinal{\value{page}} ->? + \ordinal{\value{page}} +\item The arabic representation of a counter, e.g., \verb?\ordinal{\thepage} ->? + \ordinal{\thepage} + +However, if the representation of a counter is not completely in arabic +digits, such as \verb?\thesection? which here prints as \thesection, it will +produce odd errors or peculiar results if it is used as the argument. +For instance: \\ +\verb?\ordinal{\thesection} ->? \ordinal{\thesection} + +\end{itemize} + +\subsection{Numeric numbers} + +\begin{syntax} +\cmd{\cardinal}\marg{number} \\ +\cmd{\fcardinal}\marg{number} \\ +\cmd{\fnumbersep} \\ +\end{syntax} +The macro \cmd{\fcardinal} prints its \meta{number} argument formatted using +\cmd{\fnumbersep} between each triple of digits. The default definition +of \cmd{\fnumbersep} is: +\begin{lcode} +\newcommand{\fnumbersep}{,} +\end{lcode} + + Here are some examples: \\ +\verb?\fcardinal{12} ->? \fcardinal{12} \\ +\verb?\fcardinal{1234} ->? \fcardinal{1234} \\ +\verb?\fcardinal{1234567} ->? \fcardinal{1234567} \\ +\verb?\renewcommand{\fnumbersep}{ }\fcardinal{12345678} ->? + \renewcommand{\fnumbersep}{ }\fcardinal{12345678} +\renewcommand{\fnumbersep}{,} + + The \cmd{\cardinal} macro is like \cmd{\fcardinal} except that there +is no separation between any of the digits. + +\begin{syntax} +\cmd{\ordinal}\marg{number} \\ +\cmd{\fordinal}\marg{number} \\ +\cmd{\ordscript}\marg{chars} \\ +\end{syntax} +The \cmd{\fordinal} macro typesets its \meta{number} argument as a formatted +ordinal, using \cmd{\fnumbersep} as the separator. The macro \cmd{\ordinal} +is similar except that there is no separation between any of the digits. + + Some examples are: \\ +\verb?\fordinal{3} ->? \fordinal{3} \\ +\verb?\fordinal{12341} ->? \fordinal{12341} \\ +\verb?\renewcommand{\ordscript}[1]{\textsuperscript{#1}}\fordinal{2} ->? + \renewcommand{\ordscript}[1]{\textsuperscript{#1}}\fordinal{2} \\ +\verb?\ordinal{1234567} ->? \ordinal{1234567} \\ +\verb?This is the \ordinal{\value{chapter}} chapter. ->? + This is the \ordinal{\value{chapter}} chapter. + + + The characters denoting the ordinal (ordination?) are typeset as +the argument of \cmd{\ordscript}, whose default definition is: +\begin{lcode} +\newcommand{\ordscript}[1]{#1} +\end{lcode} +As the above examples show, this can be changed to give a different +appearance. + +\begin{syntax} +\cmd{\nthstring} \cmd{\iststring} \cmd{\iindstring} \cmd{\iiirdstring} \\ +\end{syntax} +The ordinal characters are the values of the macros \cmd{\nthstring} +(default: th) for most ordinals, \cmd{\iststring} (default: st) for +ordinals ending in 1 like \ordinal{21}, \cmd{\iindstring} (default: nd) +for ordinals like \ordinal{22}, and \cmd{\iiirdstring} (default: rd) +for ordinals like \ordinal{23}. + + +\subsection{Named numbers} + + + +\begin{syntax} +\cmd{\numtoname}\marg{number} \\ +\cmd{\numtoName}\marg{number} \\ +\cmd{\NumToName}\marg{number} \\ +\end{syntax} +The macro \cmd{\numtoname} typesets its \meta{number} argument using +lowercase words. The other two macros are similar, except that +\cmd{\numtoName} uses uppercase for the initial letter of the first word and +\cmd{\NumToName} uses uppercase for the initial letters of all the words. + + As examples: \\ +\verb?\numtoname{12345} ->? \numtoname{12345} \\ +\verb?\numtoName{12345} ->? \numtoName{12345} \\ +\verb?\NumToName{12345} ->? \NumToName{12345} \\ +\verb?The minimum number in TeX is \numtoname{-2147483647}? \\ +\verb? (i.e., \fcardinal{-2147483647}) ->? \\ + The minimum number in TeX is \numtoname{-2147483647} + (i.e., \fcardinal{-2147483647}) + +\begin{syntax} +\cmd{\ordinaltoname}\marg{number} \\ +\cmd{\ordinaltoName}\marg{number} \\ +\cmd{\OrdinalToName}\marg{number} \\ +\end{syntax} +These three macros are similar to \cmd{\numtoname}, etc., except that they +typeset the argument as a wordy ordinal. + + For example: \\ +\verb?This is the \ordinaltoname{\value{chapter}} chapter. ->? + This is the \ordinaltoname{\value{chapter}} chapter. + +\begin{syntax} +\cmd{\namenumberand} \cmd{\namenumbercomma} \cmd{\tensunitsep} \\ +\end{syntax} +By default some punctuation and conjunctions are used in the representation +of named numbers. According to both American and English practice, a hyphen +should be inserted between a `tens' name (e.g., fifty) and a following +unit name (e.g., two). This is represented by the value of \cmd{\tensunitsep}. +English practice, but not American, is to include commas (the value of +\cmd{\namenumbercomma}) and conjunctions (the value of \cmd{\namenumberand}) +in strategic positions in the typesetting. These macros are initially +defined as: +\begin{lcode} +\newcommand*{\namenumberand}{ and } +\newcommand*{\namenumbercomma}{, } +\newcommand*{\tensunitsep}{-} +\end{lcode} +The next example shows how to achieve American typesetting. +\begin{lcode} +\renewcommand*{\namenumberand}{ } +\renewcommand*{\namenumbercomma}{ } +The maximum number in TeX is \numtoname{2147483647} (i.e., \cardinal{2147483647}). -> +\end{lcode} +\renewcommand*{\namenumberand}{ }\renewcommand*{\namenumbercomma}{ }% +The maximum number in TeX is \numtoname{2147483647} (i.e., \cardinal{2147483647}). +\renewcommand*{\namenumberand}{ and } +\renewcommand*{\namenumbercomma}{, } + +\begin{syntax} +\cmd{\minusname} \cmd{\lcminusname} \cmd{\ucminusname} \\ +\end{syntax} + When a named number is negative, \cmd{\minusname} is put before the +spelled out number. The definitions of the above three comands are: +\begin{lcode} +\newcommand*{\lcminusname}{minus } +\newcommand*{\ucminusname}{Minus } +\let\minusname\lcminusname +\end{lcode} +which means that `minus' is normally all lowercase. To get `minus' +typeset with an initial uppercase letter simply: +\begin{lcode} +\let\minusname\ucminusname +\end{lcode} + + Only one version of \cmd{\namenumberand} is supplied as I consider that +it is unlikely that `and' would ever be typeset as `And'. If the initial +uppercase is required, renew the macro when appropriate. + + There is a group of macros that hold the names for the numbers. To +typeset named numbers in a language other than English these will have to be +changed as appropriate. You can find them in the class and patch code. +The actual picking and ordering of the names is done by an internal macro +called \cmd{\n@me@number}. If the ordering is not appropriate for a +particular language, that is the macro to peruse and modify. Be prepared, +though, for the default definitions to be changed in a later release in case +there is a more efficient way of implementing their functions. + +\subsection{Fractions} + + When typesetting a simple fraction in text there is usually a choice +of two styles, like 3/4 or $\frac{3}{4}$, which do not necessarily look +as though they fit in with their surroundings. These fractions were +typeset via: +\begin{lcode} +... like 3/4 or $\frac{3}{4}$ ... +\end{lcode} + +\begin{syntax} +\cmd{\slashfrac}\marg{top}\marg{bottom} \\ +\cmd{\slashfracstyle}\marg{num} \\ +\end{syntax} +The class provides the \cmd{\slashfrac} command which typesets its +arguments like \slashfrac{3}{4}. Unlike the \cmd{\frac} command which +can only be used in math mode, the \cmd{\slashfrac} command can be +used in text and math modes. + + The \cmd{\slashfrac} macro calls the \cmd{\slashfracstyle} command to +reduce the size of the numbers in the fraction. You can also use +\cmd{\slashfracstyle} by itself. +\begin{lcode} +In summary, fractions can be typeset like 3/4 or $\frac{3}{4}% +or \slashfrac{3}{4} or \slashfracstyle{3/4} because several choices +are provided. +\end{lcode} +In summary, fractions can be typeset like 3/4 or $\frac{3}{4}$ +or \slashfrac{3}{4} or \slashfracstyle{3/4} because several choices +are provided. + +\begin{syntax} +\cmd{\textsuperscript}\marg{super} \\ +\cmd{\textsubscript}\marg{sub} \\ +\end{syntax} +While on the subject of moving numbers up and down, the kernel provides +the \cmd{\textsuperscript} macro for typesetting its argument as though it +is a superscript. The class also provides the \cmd{\textsubscript} macro +for typesetting its argument like a subscript. +\begin{lcode} +You can typeset superscripts like \textsuperscript{3}/4 and +subscripts like 3/\textsubscript{4}, +or both like \textsuperscript{3}/\textsubscript{4}. +\end{lcode} +You can typeset superscripts like \textsuperscript{3}/4 and +subscripts like 3/\textsubscript{4}, +or both like \textsuperscript{3}/\textsubscript{4}. + + +\section{An array data structure} + + The class includes some macros for supporting the \Ie{patverse} +environment which may be more generally useful. + +\begin{syntax} +\cmd{\newarray}\marg{arrayname}\marg{low}\marg{high} \\ +\end{syntax} +\cmd{\newarray} defines +the \meta{arrayname} array, where \meta{arrayname} is a name like +|MyArray|. The lowest and highest array indices are set to +\meta{low} and \meta{high} respectively, where both are integer numbers. + +\begin{syntax} +\cmd{\setarrayelement}\marg{arrayname}\marg{index}\marg{text} \\ +\cmd{\getarrayelement}\marg{arrayname}\marg{index}\marg{result} \\ +\end{syntax} +The \cmd{\setarrayelement} macro +sets the \meta{index} location in the \meta{arrayname} array to be +\meta{text}. Conversely, \cmd{\getarrayelement} sets the parameterless +macro \meta{result} to the contents of +the \meta{index} location in the \meta{arrayname} array. +For example: +\begin{lcode} +\setarrayelement{MyArray}{23}{$2^{23}$} +\getarrayelement{MyArray}{23}{\result} +\end{lcode} +will result in |\result| being defined as |\def\result{$2^{23}$}|. + +\begin{syntax} +\cmd{\checkarrayindex}\marg{arrayname}\marg{index} \\ +\piif{ifbounderror} \\ +\end{syntax} +\cmd{\checkarrayindex} checks if +\meta{arrayname} is an array and if \meta{index} is a valid index for +the array. If both conditions hold then \piif{ifbounderror} is set +FALSE, but if either \meta{arrayname} is not an array or, if it is, +\meta{index} is out of range then \piif{ifbounderror} is set TRUE. + +\begin{syntax} +\cmd{\stringtoarray}\marg{arrayname}\marg{string} \\ +\cmd{\arraytostring}\marg{arrayname}\marg{result} \\ +\end{syntax} +The macro \cmd{\stringtoarray} puts each character +from \meta{string} sequentially into the \meta{arrayname} array, starting +at index 1. +The macro \cmd{\arraytostring} assumes +that \meta{arrayname} is an array of characters, and defines the macro +\meta{result} to be that sequence of characters. For example: \\ +\begin{lcode} +\stringtoarray{MyArray}{Chars} +\arraytostring{MyArray}{\MyString} +\end{lcode} +is equivalent to |\def\MyString{Chars}|. + +\begin{syntax} +\cmd{\checkifinteger}\marg{num} \\ +\piif{ifinteger} \\ +\end{syntax} +The command \cmd{\checkifinteger} ckecks if \meta{num} is an integer +(not less than zero). If it is then \piif{ifinteger} is set TRUE, +otherwise it is set FALSE. + + +\section{pdfLaTeX} + + Both LaTeX and pdfLaTeX can be run on the same document. LaTeX produces +a \file{.dvi} file as output, while pdfLaTeX can produce either a +\file{.dvi} or a \file{.pdf} file. + + By default pdfLaTeX produces a \file{.dvi} file but there may be a +configuration file on your system that makes pdfLaTeX default to +producing a \file{.pdf} instead. To ensure a \file{.pdf} output file +you have to put the incantation \cmd{\pdfoutput}\texttt{=1} near the start +of the preamble\index{preamble}. Conversely, to ensure a \file{.dvi} +file put \cmd{\pdfoutput}\texttt{=0} instead. +Unfortunately this command is unknown to LaTeX so if you used LaTeX it +would hiccup. + +\begin{syntax} +\piif{ifpdf} ... |\fi| \\ +\end{syntax} +The class provides \piif{ifpdf} which is true when the document is +being processed by pdfLaTeX and false otherwise. You can use it like this: +\begin{lcode} +\ifpdf + code for pdfLaTeX only e.g., \pdfoutput=1 or \pdfoutput=0 +\else + code for LaTeX only +\fi +\end{lcode} +If there is no LaTeX specific code then don't write the |\else| part. + + +\section{Leading} + + LaTeX automatically uses different leading\index{leading} for different +font sizes. +\begin{syntax} +\lnc{\baselineskip} \lnc{\onelineskip} \\ +\end{syntax} + +At any point in a document the standard LaTeX \lnc{\baselineskip} length +contains the current value of the leading\footnote{This statement ignores +any attempts to stretch the baseline.}. The class provides the length +\lnc{\onelineskip} which contains the initial leading for the normal +font. This value is useful if you are wanting to specify length values +in terms of numbers of lines of text. + +\section{Minor space adjustment} + + The kernel provides the \cmd{\,} macro for inserting a thin space in both +text and math mode. There are +other space adjustment commands, such as \pixabang{} for negative thin space, and +\cmd{\:} and \cmd{\;} for medium +and thick spaces, which can only be used in math mode. + +\begin{syntax} +\cmd{\thinspace} \cmd{\medspace} \cmd{\:} \pixabang \\ +\end{syntax} +On occasions I have found it useful to be able to tweak spaces in text by some +fixed amount, just as in math mode. The kernel macro \cmd{\thinspace} +specifies a thin space, which is 3/18\,em. +The class \cmd{\medspace} specifies a medium space of 4/18\,em. +As mentioned, the kernel macro \cmd{\:} inserts +a medium space in math mode. The class version can be used in both math and +text mode to insert a medium space. Similarly, the class version of +\pixabang{} +can be used to insert a negative thin space in both text and math mode. + + The math thick space is 5/18\,em. +To specify this amount of space +in text mode you can combine spacing commands as: +\begin{lcode} +\:\:\! +\end{lcode} +which will result in an overall space of 5/18\,em +(from $(4 + 4 - 3)/18$). + + +\section{Cross references}\label{sec:xrefthis} \label{sec:xref} + + LaTeX supplies the \cmd{\ref} and \cmd{\pageref} commands for cross +referencing to a label or a page which has a label on it. + +\begin{syntax} +\cmd{\fref}\marg{label} \cmd{\figurerefname} \\ +\cmd{\tref}\marg{label} \cmd{\tablerefname} \\ +\cmd{\pref}\marg{label} \cmd{\pagerefname} \\ +\end{syntax} + + The class provides these more particular named references to a figure\index{figure!reference}, +table\index{table!reference} or page\index{page!reference}. For example the default definitions of \cmd{\fref} and +\cmd{\pref} are +\begin{lcode} +\newcommand{\fref}[1]{\figurerefname~\ref{#1}} +\newcommand{\pref}[1]{\pagerefname~\pageref{#1}} +\end{lcode} +and can be used as +\begin{lcode} +\ldots footnote parameters are shown in~\fref{fig:fn} on~\pref{fig:fn}. +\end{lcode} +which in this document prints as: +\begin{syntax} +\ldots footnote parameters are shown in~\fref{fig:fn} on~\pref{fig:fn}. \\ +\end{syntax} + +\begin{syntax} +\cmd{\Pref}\marg{label} \cmd{\partrefname} \\ +\cmd{\Cref}\marg{label} \cmd{\chapterrefname} \\ +\cmd{\Sref}\marg{label} \cmd{\sectionrefname} \\ +\end{syntax} + + Also provided are named references to labelled +Part (\cmd{\Pref}), +Chapter (\cmd{\Cref}) and +sectional (\cmd{\Sref}) divisions. +These are all defined like +\begin{lcode} +\newcommand{\Sref}[1]{\sectionrefname\ref{#1}} +\end{lcode} +with no tie between the name and the \cmd{\ref}. + + In this document +\begin{lcode} +`In \Cref{chap:misc} there is a section +(\Sref{sec:xrefthis}) about cross references.' +\end{lcode} +is typeset as: +\begin{syntax} +`In \Cref{chap:misc} there is a section +(\Sref{sec:xrefthis}) about cross references.' \\ +\end{syntax} + + It can be useful to refer to parts of a document by name rather than +number, as in +\begin{lcode} +The chapter \textit{\titleref{chap:bringhurst}} describes \ldots +\end{lcode} +The chapter \textit{\titleref{chap:bringhurst}} describes \ldots + + There are two packages, \Lpack{nameref}~\cite{NAMEREF} and +\Lpack{titleref}~\cite{TITLEREF}, + that let you refer to things by name instead of number. + + Name references were added to the class as a consequence of adding +a second optional argument to the sectioning commands. I found +that this broke the \Lpack{nameref} package, and hence the +\Lpack{hyperref} package as well, so they had to be fixed. The change +also broke Donald Arseneau's \Lpack{titleref} package, and it turned out +that \Lpack{nameref} also clobbered \Lpack{titleref}. The class also +provides titles, like \cmd{\poemtitle}, that are not recognised by +either of the packages. From my viewpoint the most efficient +thing to do was to enable the class itself to provide name +referencing. + +\begin{syntax} +\cmd{\label}\marg{key} \cmd{\ref}\marg{key} \cmd{\pageref}\marg{key} \\ +\cmd{\titleref}\marg{key} \\ +\cmd{\headnamereftrue} \cmd{\headnamereffalse} \\ +\end{syntax} +The macro \cmd{\titleref} is an addition to the usual set of cross referencing +commands. Instead of typesetting a number it typesets the title associated +with the labelled number. This is, of course, only useful if there is an +associated title, such as from a \cmd{\caption} or \cmd{\section} command. +As a bad example: +\begin{lcode} +Labelling for \verb?\titleref? may be applied to: +\begin{enumerate} +\item Chapters, sections, etc. \label{sec:xref:item1} +... +\item Items in numbered lists, etc. \ldots \label{sec:xref:item3} +\end{enumerate} +Item \ref{sec:xref:item2} in section~\ref{sec:xref} mentions captions +while item \titleref{sec:xref:item3} in the same section +\textit{\titleref{sec:xref}} lists other things. +\end{lcode} +Labelling for \verb?\titleref? may be applied to: +\begin{enumerate} +\item Chapters, sections, etc. \label{sec:xref:item1} +\item Captions \label{sec:xref:item2} +\item Legends +\item Poem titles +\item Items in numbered lists, etc. \label{sec:xref:item3} +\end{enumerate} +Item \ref{sec:xref:item2} in section~\ref{sec:xref} mentions captions +while item \titleref{sec:xref:item3} in the same section +\textit{\titleref{sec:xref}} lists other things. + + + As the above example shows, you have to be a little careful in using +\cmd{\titleref}. +Generally speaking, \cmd{\titleref}\marg{key} produces the last named +thing before the \cmd{\label} that defines the \meta{key}. + + Chapters, and the lower level sectional divisions, may have three +different title texts --- the main title, the title in the ToC, and a third +in the page header. By default (\cmd{\headnamereffalse}) the ToC title +is produced by \cmd{\titleref}. Following the declaration +\cmd{\headnamereftrue} the text intended for page headers will be produced. + +\Note{} Specifically with the \Lclass{memoir} class, +do not put a \cmd{\label} command inside an +argument to a \cmd{\chapter} or \cmd{\section} or \cmd{\caption}, etc., +command. Most likely it will either be ignored or referencing it will +produce incorrect values. This restriction does not apply to the standard +classes, but in any case I think it is good practice not to embed any +\cmd{\label} commands. + +\begin{syntax} +\cmd{\currenttitle} \\ +\end{syntax} + If you just want to refer to the current title you can do so with +\cmd{\currenttitle}. This acts as though there had been a label associated +with the title and then \cmd{\titleref} had been used to refer to that label. +For example: +\begin{lcode} +This sentence in the section titled `\currenttitle' is an example of the +use of the command \verb?\currenttitle?. +\end{lcode} +This sentence in the section titled `\currenttitle' is an example of the +use of the command \verb?\currenttitle?. + + +\begin{syntax} +\cmd{\theTitleReference}\marg{num}\marg{text} \\ +\end{syntax} +Both \cmd{\titleref} and \cmd{\currenttitle} use the \cmd{\theTitleReference} +to typeset the title. This is called with two arguments --- +the number, \meta{num}, and the text, \meta{text}, of the title. The +default definition is: +\begin{lcode} +\newcommand{\theTitleReference}[2]{#2} +\end{lcode} +so that only the \meta{text} argument is printed. You could, for example, +change the definition to +\begin{lcode} +\renewcommand{\theTitleReference}[2]{#1\space \textit{#2}} +\end{lcode} +to print the number followed by the title in italics. If you do this, only use +\cmd{\titleref} for numbered titles, as a printed number for an +unnumbered title (a) makes no sense, and (b) will in any case be +incorrect. + + The commands \cmd{\titleref}, \cmd{\theTitleReference} and +\cmd{\currenttitle} are direct equivalents of those in the \Lpack{titleref} +package~\cite{TITLEREF}. + +\begin{syntax} +\cmd{\namerefon} \cmd{\namerefoff} \\ +\end{syntax} + Implementing name referencing has had an unfortunate side effect of +turning some arguments into moving ones; the argument to the \cmd{\legend} +command is one example. If you don't need name referencing you can turn +it off by the \cmd{\namerefoff} declaration; the \cmd{\namerefon} +declaration enables name referencing. + + + +\section{Words and phrases} + + The class provides several macros that expand into English words or +phrases. To typeset in another language these need to be changed, or an +author or publisher may want some changes made to the English versions. +The following lists the macros and their default values. +\begin{itemize} +\item[\cmd{\contentsname}] \contentsname +\item[\cmd{\listfigurename}] \listfigurename +\item[\cmd{\listtablename}] \listtablename +\item[\cmd{\abstractname}] \abstractname +\item[\cmd{\partname}] \partname +\item[\cmd{\chaptername}] \chaptername +\item[\cmd{\appendixname}] \appendixname +\item[\cmd{\appendixtocname}] \appendixtocname +\item[\cmd{\appendixpagename}] \appendixpagename +\item[\cmd{\bibname}] \bibname +\item[\cmd{\indexname}] \indexname +\item[\cmd{\figurename}] \figurename +\item[\cmd{\tablename}] \tablename +\item[\cmd{\figurerefname}] \figurerefname +\item[\cmd{\tablerefname}] \tablerefname +\item[\cmd{\pagename}] \pagename +\item[\cmd{\pagerefname}] \pagerefname +\item[\cmd{\partrefname}] \partrefname + (defined as |\newcommand{\partrefname}{Part~}|) +\item[\cmd{\chapterrefname}] \chapterrefname + (defined as |\newcommand{\chapterrefname}{Chapter~}|) +\item[\cmd{\sectionrefname}] \sectionrefname + (defined as |\newcommand{\sectionrefname}{\S}|) +\end{itemize} +The above definitions are simple --- for example +\begin{lcode} +\newcommand{\partname}{Part} +\end{lcode} +and so can be also changed simply. + + The definitions of the macros for the names of numbers are more complex +--- for example for the number 11 (eleven) +\begin{lcode} +\newcommand*{\nNamexi}{\iflowertonumname e\else E\fi leven} +\end{lcode} +That is, each definition includes both a lowercase and an uppercase initial +letter, so a bit more care has to be taken when changing these. For specifics +read the documentation of the class code. + +\section{Symbols} + + LaTeX lets you typeset an enormous variety of symbols.\index{symbol} +The class adds +nothing to the standard LaTeX capabilities in this respect. +If you want to see what symbols are available then get a copy +of Scott Pakin's +\textit{The Comprehensive LaTeX Symbol List}~\cite{SYMBOLS}. +You may have to do a little experimentation to get what you want, though. + + For example, the \cmd{\texttrademark} command +produces the trademark\index{trademark} symbol\texttrademark, +but the \cmd{\textregistered} command produces\textregistered. +When I wanted to use the registered trademark\index{registered trademark} + symbol it needed to be +typeset like a superscript +instead of on the baseline. The \cmd{\textsuperscipt} macro typesets +its argument like a superscript\index{superscript}, so using +\begin{lcode} +\textsuperscript{\textregistered} +\end{lcode} +gave the required result\textsuperscript{\textregistered}. + +\clearpage + +\makeatletter +%% Bringhurst chapter style +\makechapterstyle{bringhurst}{% + \renewcommand{\chapterheadstart}{} + \renewcommand{\printchaptername}{} + \renewcommand{\chapternamenum}{} + \renewcommand{\printchapternum}{} + \renewcommand{\afterchapternum}{} + \renewcommand{\printchaptertitle}[1]{% + \raggedright\Large\scshape\MakeLowercase{##1}} + \renewcommand{\afterchaptertitle}{% + \vskip\onelineskip \hrule\vskip\onelineskip} +} + +\setsecheadstyle{\raggedright\scshape\MakeLowercase} + \setbeforesecskip{-\onelineskip} + \setaftersecskip{\onelineskip} + +%%\setsubsecheadstyle{\renewcommmand\@hangfrom[1]{\noindent ##1}\raggedright\itshape} +\setsubsecheadstyle{\sethangfrom{\noindent ##1}\raggedright\itshape} + \setbeforesubsecskip{-\onelineskip} + \setaftersubsecskip{\onelineskip} + +%% Bringhurst page style +\makepagestyle{bringhurst} +\makeevenfoot{bringhurst}{\thepage}{}{} +\makeoddfoot{bringhurst}{}{}{\thepage} +\setlength{\pwlayi}{\headsep} % \verb?\setlength{\pwlayi}{\headsep}? headsep=\printlength{\headsep}, pwlayi = \printlength{\pwlayi}. +\addtolength{\pwlayi}{\topskip} % \verb?\addtolength{\pwlayi}{\topskip}? topskip=\printlength{\topskip}, pwlayi=\printlength{\pwlayi}. +\addtolength{\pwlayi}{7.3\onelineskip} % \verb?\addtolength{\pwlayi}{7.3\onelineskip}? onelineskip=\printlength{\onelineskip}, pwlayi=\printlength{\pwlayi}. +\newcommand{\bringpicr}[1]{% + \setlength{\unitlength}{1pt} + \begin{picture}(0,0) + \put(\strip@pt\marginparsep, -\strip@pt\pwlayi){% + \begin{minipage}[t]{\marginparwidth} + \raggedright\itshape #1 + \end{minipage}} + \end{picture} +} + +\setlength{\pwlayii}{\marginparsep} % \verb?\setlength{\pwlayii}{\marginparsep}? marginparsep=\printlength{\marginparsep}, pwlayii=\printlength{\pwlayii}. +\addtolength{\pwlayii}{\marginparwidth} % \verb?\addtolength{\pwlayii}{\marginparwidth}? marginparwidth=\printlength{\marginparwidth}, pwlayii=\printlength{\pwlayii}. +\newcommand{\bringpicl}[1]{% + \setlength{\unitlength}{1pt} + \begin{picture}(0,0) + \put(-\strip@pt\pwlayii, -\strip@pt\pwlayi){% + \begin{minipage}[t]{\marginparwidth} + \raggedleft\itshape #1 + \end{minipage}} + \end{picture} +} + +\makepsmarks{bringhurst}{% + \let\@mkboth\markboth + \def\chaptermark##1{\markboth{##1}{##1}} + \def\sectionmark##1{\markright{##1}} +} +\makeevenhead{bringhurst}{\bringpicl{\rightmark}}{}{} +\makeoddhead{bringhurst}{}{}{\bringpicr{\leftmark}} + + +\renewcommand{\cftchapterfont}{\normalfont} +\renewcommand{\cftchapterpagefont}{\normalfont} +\renewcommand{\cftchapterpresnum}{\bfseries} +\renewcommand{\cftchapterleader}{} +\renewcommand{\cftchapterafterpnum}{\cftparfillskip} +%%%\settocdepth{chapter} + +\makeatother + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\cleardoublepage +\pagestyle{bringhurst} +\chapterstyle{bringhurst} +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\chapter{An example design} \label{chap:bringhurst} + +%unitlength=\printlength{\unitlength}, \\ +%pwlayi=\printlength{\pwlayi}, \\ +%pwlayii=\printlength{\pwlayii}. + +\section{Introduction} + + In this chapter I will work through a reasonably complete design +exercise. The chapter is typeset using the results of the exercise. + + Rather than trying to invent something myself I am taking the design +of Bringhurst's +\textit{The Elements of Typographic Style}~\cite{BRINGHURST92} +as the basis of the +exercise. This is sufficiently different from the normal LaTeX appearance +to demonstrate most of the class capabilities, and also it is a design by +a leading proponent of good typography. + + As much as possible, this chapter is typeset according to the results +of the exercise to provide both a coding and a graphic example. + +\section{Design requirements} + + The \textit{Elements of Typographic Style} is typeset using Minion as the +text font and Syntax (a sans font) for the captions. The page layout has been + shown diagramatically in \fref{fb:1} on \pref{fb:1}, but further details need +to be described for those not fortunate enough to have a copy of their own. + + The trimmed size of a page is 23 by 13.3cm. The foredge is 3.1cm and the +top margin\index{margin} is 1.9cm. + + As already noted, the font for the main text is Minion, with 12pt leading +on a 21pc measure with 42 lines per page. For the purposes of this exercise +I will assume that Minion can be replaced by Computer Modern Roman at 10pt +(like this manual). The captions to figures\index{figure} and tables\index{table} are unnamed and +unnumbered and typeset in Syntax. The captions give the appearance of being +in a smaller font size than the main text, which is often the case. I'll +assume that the |\small| |\sfseries| CMR font will reasonably do for the +captions. + + The footer\index{footer} is the same width as the typeblock\index{typeblock} and the folio\index{folio} is placed +in the footer\index{footer} at the foredge. There are two blank lines between the bottom +of the typeblock\index{typeblock} and the folio\index{folio}. + + There is no header\index{header} in the usually accepted sense of the term but the +chapter title is put on recto pages and section titles are on verso pages. +The running titles are placed in the foredge margin\index{margin} level with the seventh +line of the text in the typeblock\index{typeblock}. The recto headers\index{header} are typeset raggedright +and the verso ones raggedleft. + +Bringhurst also uses many marginal\index{marginalia} notes, +their maximum width being about 51pt, and typeset raggedright in a smaller +version of the textfont. + + Chapter titles are in small caps, lowercase, in a larger font than for +the main text, and a rule is placed between the title and the typeblock\index{typeblock}. +The total vertical space used by a chapter title is three text lines. +Chapters are not numbered in the text but are in the Table of Contents. + + Section titles are again in small caps, lowercase, in the same size as the +text font. The titles are numbered, with both the chapter and section number. + + A subsection title, which is the lowest subdivision in the book, is in +the italic form of the textfont and is typeset as a numbered non-indented +paragraph\index{paragraph}. These are usually multiline as Bringhurst sometimes uses them +like an enumerated list, so on occasion there is a +subsection title with no following text. + + Only chapter titles are put into the \toc, and these are set raggedright +with the page numbers immediately after the titles. There is no \lof{} or +\lot. + + Note that unlike the normal LaTeX use of fonts, essentially only three +sizes of fonts are used --- the textfont size, one a bit larger for the +chapter titles, and one a bit smaller for marginal\index{marginalia} notes and captions. +Also, bold fonts are not used except on special occasions, such as when he +is comparing font families and uses large bold +versions to make the differences easier to see. + +\section{Specifying the page and typeblock} + + The first and second things to do are to specify the sizes of the page +after trimmming and the typeblock\index{typeblock}. The trimmed size is easy as we have +the dimensions. +\begin{lcode} +\settrimmedsize{23cm}{13.3cm}{*} +\end{lcode} +However, there is a trick to setting the height of the typeblock\index{typeblock} in terms +of lines of text. The +height calculation ensures that an integral number of lines can fit in +the typeblock\index{typeblock}, and as well as the specified height for the block some more +height is added so that the final height is approximately measured from +the base of the bottom line of text to the top of the first line of text. +This is a complicated way of saying that if you want $N$ lines of text, only +ask for $N-1$. We want 42 lines so we give the height of the typeblock\index{typeblock} +as 41 times the distance between two normal text lines +(i.e., times \lnc{\onelineskip}) +\begin{lcode} +\settypeblocksize{41\onelineskip}{21pc}{*} +\end{lcode} + + To make life easier, we'll do no trimming of the top of the stock\index{stock} +\begin{lcode} +\setlength{\trimtop}{0pt} +\end{lcode} +but will trim the foredge. The next set of calculations first sets the +value of the \lnc{\trimedge} to be the \lnc{\stockwidth}; subtracting the +trimmed \lnc{\paperwidth} then results in \lnc{\trimedge} being the amount +to trim off the foredge. +\begin{lcode} +\setlength{\trimedge}{\stockwidth} +\addtolength{\trimedge}{-\paperwidth} +\end{lcode} + + The sizes of the trimmed page and the typeblock\index{typeblock} have now been specified. +The typeblock\index{typeblock} is now positioned on the page. The sideways positioning is +easy as we know the foredge margin\index{margin} to be 3.1cm. +\begin{lcode} +\setlrmargins{*}{3.1cm}{*} +\end{lcode} +The top margin\index{margin} is specified as 1.9cm, which is very close to four and a half +lines of text. Just in case someone might want to use a different font size, +I'll specify the top margin\index{margin} so that it is dependent on the font size. The +\lnc{\footskip} can be specified now as well (it doesn't particularly matter +what we do about the header-related lengths as there isn't anything above +the typeblock\index{typeblock}). +\begin{lcode} +\setulmargins{4.5\onelineskip}{*}{*} +\setheadfoot{\onelineskip}{3\onelineskip} +\setheaderspaces{\onelineskip}{*}{*} +\end{lcode} + + Lastly define the dimensions for any marginal\index{marginalia} notes. +\begin{lcode} +\setmarginnotes{17pt}{51pt}{\onelineskip} +\end{lcode} + + If this was for real, the page layout would have to be checked and +implemented. +\begin{lcode} +\checkandfixthelayout +\end{lcode} + + It is possible to implement this layout just for this chapter but +I'm not going to tell you either how to do it, or demonstrate it. Except +under exceptional circumstances it is not good to make such drastic changes +to the page layout in the middle of a document. However, the picture on +\pref{fig:bplayout} illustrates +how this layout would look on US letterpaper\index{paper!size!letterpaper} stock\index{stock}. Looking at the illustration +suggests that the layout would look rather odd unless the stock\index{stock} was trimmed down +to the page size --- another reason for not switching the layout here. + +\begin{figure} +\captiontitlefont{\small\sffamily} +\captionstyle{\centerlastline} +\setstocksize{11in}{8.5in} +\settrimmedsize{23cm}{13.3cm}{*} +\settypeblocksize{41\onelineskip}{21pc}{*} +\setlength{\trimtop}{0pt} +\setlength{\trimedge}{\stockwidth} +\addtolength{\trimedge}{-\paperwidth} +\setlrmargins{*}{3.1cm}{*} +\setulmargins{4.5\onelineskip}{*}{*} +\setheadfoot{\onelineskip}{3\onelineskip} +\setheaderspaces{\onelineskip}{*}{*} +\setmarginnotes{17pt}{51pt}{\onelineskip} +\checkandfixthelayout +\currentstock +\oddpagelayouttrue +\twocolumnlayoutfalse +\drawmarginparstrue +\drawparametersfalse +\drawstock +\legend{An illustration of Bringhurst's page layout style when printed +on US letter paper stock. Also shown are the values used for the +page layout parameters for this design.} \label{fig:bplayout} +\end{figure} + +\section{Specifying the sectional titling styles} + +\subsection{The chapter style} + + Recapping, + chapter titles are in small caps, lowercase, in a larger font than for +the main text, and a rule is placed between the title and the typeblock\index{typeblock}. +The total vertical space used by a chapter title is three text lines. +Chapters are not numbered in the text but are in the Table of Contents. +Titles in the \toc{} are in mixed case. + + The definition of the chapterstyle is remarkably simple, as shown below. +\begin{lcode} +%% Bringhurst chapter style +\makechapterstyle{bringhurst}{% + \renewcommand{\chapterheadstart}{} + \renewcommand{\printchaptername}{} + \renewcommand{\chapternamenum}{} + \renewcommand{\printchapternum}{} + \renewcommand{\afterchapternum}{} + \renewcommand{\printchaptertitle}[1]{% + \raggedright\Large\scshape\MakeLowercase{##1}} + \renewcommand{\afterchaptertitle}{% + \vskip\onelineskip \hrule\vskip\onelineskip} +} +\end{lcode} + + Most of the specification consists of nulling the majority of the normal +LaTeX specification, and modifying just two elements. + +The chapter title (via \cmd{\printchaptertitle}) +is typeset raggedright using the \cmd{\Large} smallcaps fonts. The +\cmd{\MakeLowercase} macro is used to ensure that the entire title is +lowercase before typesetting it. Titles are input in mixed case. + + After the title is typeset the \cmd{\afterchaptertitle} macro +specifies that one line is skipped, a horizontal rule +is drawn and then another line is skipped. + +\subsection{Lower level divisions} + + Section titles are in small caps, lowercase, in the same size as the +text font. The titles are numbered, with both the chapter and section number. + +The specification is: +\begin{lcode} +\setsecheadstyle{\raggedright\scshape\MakeLowercase} + \setbeforesecskip{-\onelineskip} + \setaftersecskip{\onelineskip} +\end{lcode} + + The macro \cmd{\setsecheadstyle} lowercases the title and typesets it +small caps. + +The default skips before and after titles are rubber lengths but this does +not bode well if we are trying to line something up with a particular line +of text --- the presence of section titles may make slight vertical +adjustments to the text lines because of the flexible spacing. So, we have +to try and have fixed spacings. +A single blank line is used before (\cmd{\setbeforesecskip)} +and after (\cmd{\setaftersecskip}) the title text. + + A subsection title, which is the lowest subdivision in the book, is in +the italic form of the textfont and is typeset as a numbered non-indented +paragraph\index{paragraph}. The code for this is below. + +\begin{lcode} +\setsubsecheadstyle{\sethangfrom{\noindent ##1}\raggedright\itshape} + \setbeforesubsecskip{-\onelineskip} + \setaftersubsecskip{\onelineskip} +\end{lcode} + + As in the redefinition of the \cmd{\section} style, there are fixed +spaces before and after the title text. The title is typeset +(\cmd{\setsubsecheadstyle}) raggedright in a normal sized italic font. +The macro \cmd{\sethangfrom} is used to to redefine the internal +\cmd{\@hangfrom} macro so that the title and number are typeset as a block +paragraph\index{paragraph!block} instead of the default hanging +paragraph\index{paragraph!hanging} style. Note the use of +the double |##| mark for denoting the position of the argument to +\cmd{\@hangfrom}. + +\section{Specifying the pagestyle} + + The pagestyle is perhaps the most interesting aspect of the exercise. +Instead of the chapter and section titles being put at the top of the +pages they are put in the margin\index{margin} starting about seven lines below the +top of the typeblock\index{typeblock}. The folios\index{folio} are put at the bottom of the page +aligned with the outside of the typeblock\index{typeblock}. + + As the folios\index{folio} are easy, we'll deal with those first. +\begin{lcode} +%% Bringhurst page style +\makepagestyle{bringhurst} +\makeevenfoot{bringhurst}{\thepage}{}{} +\makeoddfoot{bringhurst}{}{}{\thepage} +\end{lcode} + + Putting text at a fixed point on a page is typically done by +first putting the text into a zero width picture (which as far as LaTeX +is concerned takes up zero space) and then placing the picture at the +required point on the page. This can be done by hanging it from the +header\index{header}. + + We might as well treat the titles so that they will align with any +marginal\index{marginalia} notes, which are \lnc{\marginparsep} (17pt) into the margin\index{margin} +and \lnc{\marginparwidth} (51pt) wide. Earlier in the manual I defined +two lengths called |\pwlayi| and |\pwlayii| which are no longer used. +I will use these as scratch lengths in +performing some of the necessary calculations. + + For the recto page headers\index{header} the picture will be the \meta{right} part of +the header\index{header} and for the verso pages the picture will be the \meta{left} +part of the header\index{header}, all other parts being empty. + + For the picture on the \meta{right} the text must be 17pt to +the right of the origin, and some distance below the origin. +From some experiments, this distance turns out to be the \lnc{\headsep} +plus the \cmd{\topskip} plus 7.3 lines, which is calculated as follows: +\begin{lcode} +\setlength{\pwlayi}{\headsep} +\addtolength{\pwlayi}{\topskip} +\addtolength{\pwlayi}{7.3\onelineskip} +\end{lcode} + + There is a nifty internal LaTeX macro called \cmd{\strip@pt} which you +probably haven't heard about, and I have only recently come across. What it +does is strip the `pt' from a following length, reducing it to a plain +real number. Remembering that the default \lnc{\unitlength} is 1pt we can +do the following, while making sure that the current \lnc{\unitlength} +\emph{is} 1pt: +\begin{lcode} +\makeatletter +\newcommand{\bringpicr}[1]{% + \setlength{\unitlength}{1pt} + \begin{picture}(0,0) + \put(\strip@pt\marginparsep, -\strip@pt\pwlayi){% + \begin{minipage}[t]{\marginparwidth} + \raggedright\itshape #1 + \end{minipage}} + \end{picture} +} +\makeatother +\end{lcode} +The new macro \cmd{\bringpicr}\marg{text} puts \meta{text} +into a \Ie{minipage} of width \lnc{\marginparwidth}, +typeset raggedright in an italic font, and puts the top +left of the minipage at the position (|\marginparsep|, -|\pwlayi|) +in a zero width picture. + + We need a different picture for the \meta{left} as the text needs to be +typeset raggedleft with the right of the text 17pt from the left of the +typeblock\index{typeblock}. I will use the length |\pwlayii| +to calculate the sum of \lnc{\marginparsep} +and \lnc{\marginparwidth}. Hence: +\begin{lcode} +\makeatletter +\setlength{\pwlayii}{\marginparsep} +\addtolength{\pwlayii}{\marginparwidth} +\newcommand{\bringpicl}[1]{% + \setlength{\unitlength}{1pt} + \begin{picture}(0,0) + \put(-\strip@pt\pwlayii, -\strip@pt\pwlayi){% + \begin{minipage}[t]{\marginparwidth} + \raggedleft\itshape #1 + \end{minipage}} + \end{picture} +} +\makeatother +\end{lcode} +The new macro \cmd{\bringpicl}\marg{text} puts \meta{text} +into a \Ie{minipage} of width \lnc{\marginparwidth}, +typeset raggedleft in an italic font, and puts the top +left of the minipage at the position +(-|(\marginparsep+\marginparwidth)|, -|\pwlayi|) +in a zero width picture. + + + Now we can proceed with the remainder of the pagestyle specification. +The next bit puts the chapter and section titles into the |\...mark| macros. +\begin{lcode} +\makeatletter +\makepsmarks{bringhurst}{% + \let\@mkboth\markboth + \def\chaptermark##1{\markboth{##1}{##1}} + \def\sectionmark##1{\markright{##1}} +} +\makeatother +\end{lcode} + + Finally, specify the evenhead using \cmd{\bringpicl} with the section +title as its argument, and the oddhead using \cmd{\bringpicr} with the +chapter title as its argument. +\begin{lcode} +\makeevenhead{bringhurst}{\bringpicl{\rightmark}}{}{} +\makeoddhead{bringhurst}{}{}{\bringpicr{\leftmark}} +\end{lcode} + + +\section{Captions and the \prtoc} + + The captions to figures\index{figure} and tables\index{table} are set in a small sans font and +are neither named nor numbered, and there is no \lof{} or \lot. +Setting the caption titles in the desired font is simple: +\begin{lcode} +\captiontitlefont{\small\sffamily} +\end{lcode} + + There are two options regarding table\index{table} and figure\index{figure} captioning: either +use the \cmd{\legend} command (which produces an anonymous unnumbered title) +instead of the \cmd{\caption} command, or +use the \cmd{\caption} command with a modified definition. Just in case +the design might change at a later date to required numbered captions, +it's probably best to use +a modified version of \cmd{\caption}. In this case this is simple, just give +the \cmd{\caption} command the same definition as the \cmd{\legend} command. +\begin{lcode} +\let\caption\legend +\end{lcode} + + + An aside: I initially used the default caption style (block paragraph) for +the diagram on \pref{fig:bplayout}, but this looked unbalanced so now it +has the last line centered. As a float\index{float} environment, like any other environment, +forms a group, you can make local changes within the float\index{float}. I actually did it +like this: +\begin{lcode} +\begin{figure} +\captiontitlefont{\small\sffamily} +\captionstyle{\centerlastline} +... +\legend{...} \label{...} +\end{figure} +\end{lcode} +For fine typesetting you may wish to change the style of particular captions. +The default style for a single line caption works well, but for a caption with +two or three lines either the centering or centerlastline style might look +better. A very long caption is again probably best done in a block paragraph style. + + Only chapter titles are included in the \toc. To specify this we +use the \cmd{\settocdepth} command. +\begin{lcode} +\settocdepth{chapter} +\end{lcode} + + The \toc{} is typeset raggedright with no leaders and the page numbers +coming immediately after the chapter title. This is specified via: +\begin{lcode} +\renewcommand{\cftchapterfont}{\normalfont} +\renewcommand{\cftchapterpagefont}{\normalfont} +\renewcommand{\cftchapterpresnum}{\bfseries} +\renewcommand{\cftchapterleader}{} +\renewcommand{\cftchapterafterpnum}{\cftparfillskip} +\end{lcode} + +\section{Preamble or package?} + + + When making changes to the document style, or just defining a new +macro or two, there is the question of where to put the changes --- in +the preamble\index{preamble} of the particular document or into a separate package\index{package}? + + If the same changes/macros are likely to be used in more than one +document then I suggest that they be put into a package. +If just for the single document then the choice remains open. + + I have presented the code in this chapter as though it would be put +into the preamble\index{preamble}, hence the use of \cmd{\makeatletter} and +\cmd{\makeatother} to surround macros that include the |@| character. The +code could just as easily be put into a package\index{package} called, say, +\Lpack{bringhurst}. That is, by putting all the code, except for the +\cmd{\makeatletter} and \cmd{\makeatother} commands, into a file called +\file{bringhurst.sty}. It is a good idea also to end the code in the file +with \cmd{\endinput}; LaTeX stops reading the file at that point and +will ignore any possible garbage after \cmd{\endinput}. + + You then use the \Lpack{bringhurst} package just like any other by +putting +\begin{lcode} +\usepackage{bringhurst} +\end{lcode} +in your document's preamble\index{preamble}. + +\appendix +\appendixpage* + +\chapterstyle{normal} +\chapterstyle{section} + +\chapter{Packages and macros} +%%%%\pagestyle{ruled} +This chapter is typeset with the \cstyle{section} chapterstyle, otherwise +it uses the layout defined in \Cref{chap:bringhurst}. + +\section{Introduction} + + The \Lclass{memoir} class does not provide for everything that you +have seen in the manual. I have used some packages that you are very likely +to have in your LaTeX distribution, and have supplemented these with some +additional macros, some of which I will show you. + +\section{Packages} + + The packages that I have used that you are likely to have, and if +you do not have them please consider getting them, are: +\begin{itemize} +\item \Lpack{url}~\cite{URL} is for typesetting URL's without worrying + about special characters or line breaking. +\item \Lpack{fixltx2e}~\cite{FIXLTX2E} eliminates some infelicities + of the original LaTeX kernel. In particular it maintains the order + of floats\index{float} on a twocolumn\index{column!double} page and ensures the correct marking + on a twocolumn\index{column!double} page. +\item \Lpack{alltt}~\cite{ALLTT} is a basic package which provides a + verbatim-like environment but |\|, |{|, and |}| have their + usual meanings (i.e., LaTeX commands are not disabled). +\item \Lpack{graphicx}~\cite{GRAPHICX} is a required package for + performing various kinds of graphical functions. +\end{itemize} + + The package that I used and you most likely do not have is +\Lpack{layouts}~\cite{LAYOUTS}. I used it for all the layout diagrams. +For example, \fref{fig:displaysechead} and \fref{fig:runsechead} +were drawn simply by: +\begin{lcode} +\begin{figure} +\centering +\setlayoutscale{1} +\drawparameterstrue +\drawheading{} +\caption{Displayed sectional headings} \label{fig:displaysechead} +\end{figure} + +\begin{figure} +\centering +\setlayoutscale{1} +\drawparameterstrue +\runinheadtrue +\drawheading{} +\caption{Runin sectional headings} \label{fig:runsechead} +\end{figure} +\end{lcode} +The package also lets you try experimenting with different layout +parameters and draw diagrams showing what the results would be in a document. + + The version of \Lpack{layouts} used for this manual is +v2.4 dated 2001/04/30. Earlier versions will fail when attempting +to draw some figures +( e.g., to draw \fref{fig:oddstock}). + +\section{Macros} + + The preamble\index{preamble} of the manual contains many macro definitions, probably +more than most documents would because: +\begin{itemize} +\item I am having to typeset many LaTeX commands, which require + some sort of special processing; +\item I have tried to minimize the number of external packages needed + to LaTeX this manual satisfactorily, and so have copied various + macros from elsewhere; +\item I wanted to do some automatic indexing\index{index}; +\item I wanted to set off the syntax specifications and the code examples + from the main text. +\end{itemize} +To get the whole glory you will have to read the preamble\index{preamble}, but I show a +few of the macros below as they may be of more general interest. + +\begin{syntax} +\cmd{\pstyle}\marg{style} \\ +\end{syntax} +The command \cmd{\pstyle} prints its argument in the slanted +font used for pagestyles +and also makes a pagestyle entry in the index\index{index}. Its definition is +\begin{lcode} +\newcommand{\pstyle}[1]{\textsl{#1}\index{#1pages@\textsl{#1} (pagestyle)}} +\end{lcode} +The first part prints the argument in the text and the second adds an +entry to the \file{.idx} file. The fragment |#1pages| is what +the \textsc{makeindex} program will use for sorting entries, and the fragment following the |@| character is what will be put into the index\index{index}. + +\begin{syntax} +\cmd{\cstyle}\marg{style} \\ +\end{syntax} +The command \cmd{\cstyle} prints its argument in the slanted +font used for chapterstyles +and also makes a chapterstyle entry in the index\index{index}. Its definition is +\begin{lcode} +\newcommand{\cstyle}[1]{\textsl{#1}\index{#1chaps@\textsl{#1} (chapterstyle)}} +\end{lcode} +which is almost identical to \cmd{\pstyle}. + + There is both a \cstyle{companion} chapterstyle and a \pstyle{companion} +pagestyle. The strings used for sorting the index\index{index} entries for these are +\texttt{companionchaps} and \texttt{companionpages} respectively, so +the chapterstyle will come before the pagestyle in the index\index{index}. The reason for distinguishing between the string used for sorting and the actual entry is +partly to distinguish between different kinds of entries for a single name +and partly to avoid any formatting commands messing up the sorted order. + + + +\begin{syntax} +\senv{syntax} syntax \eenv{syntax} \\ +\end{syntax} +The \Ie{syntax} environment is for specifying command and environment +syntax. Its definition is +\begin{lcode} +\newenvironment{syntax}{\begin{center} + \begin{tabular}{|p{0.9\linewidth}|} \hline}% + {\hline + \end{tabular} + \end{center}} +\end{lcode} +It is implemented in terms of the \Ie{tabular} environment, which forms +a box that will not be broken across a pagebreak. The box frame +is just the normal horizontal and vertical lines that you can use with +a \Ie{tabular}. The width is fixed at 90\% of the text width. As it +is a \Ie{tabular} environment, each line of syntax must be ended with +\cmd{\\}. Note that normal LaTeX processing occurs within the \Ie{syntax} +environment, so you can effectively put what you like inside it. + +\begin{syntax} +\senv{lcode} LaTeX code \eenv{lcode} \\ +\end{syntax} +I use the \Ie{lcode} environment for showing examples of LaTeX code. It +is a special kind of \Ie{verbatim} environment where the font size is +\cmd{\small} but the normal \lnc{\baselineskip} is used, and each line +is indented. It is defined with the help of the \Lpack{verbatim} package. + + At the bottom the environment is defined in terms of a \Ie{list}, +although that is not obvious from the code; for details see the +\Lpack{verbatim} package documentation~\cite{VERBATIM}. I wanted +the environment to be a tight list so started off by defining some +two helper items. +\begin{lcode} +% \@zeroseps sets list before/after skips to minimum values +\newcommand{\@zeroseps}{\setlength{\topsep}{\z@} + \setlength{\partopsep}{\z@} + \setlength{\parskip}{\z@}} +% \gparindent is the \parindent for the body text +\newlength{\gparindent} \setlength{\gparindent}{\parindent} +\end{lcode} +The macro \cmd{\@zeroseps} sets the before, after and middle skips in +a list to 0pt (\cmd{\z@} is shorthand for 0pt). The value of \lnc{\parindent} +is saved in \lnc{\gparindent}, because this will be the line indentation +in the environment. +\begin{lcode} +% Now we can do the new lcode verbatim environment. +% This has no extra before/after spacing. +\newenvironment{lcode}{\@zeroseps + \renewcommand{\verbatim@startline}% + {\verbatim@line{\hskip\gparindent}} + \small\setlength{\baselineskip}{\onelineskip}\verbatim}% + {\endverbatim + \vspace{-\baselineskip}\noindent +} +\end{lcode} + + The fragment |{\hskip\gparindent}| puts \lnc{\gparindent} space at +the start of each line. + + The fragment |\small\setlength{\baselineskip}{\onelineskip}| sets the +font size to be \cmd{\small}, which has a smaller \lnc{\baselineskip} +than the normal font, but this is corrected for by changing the local +\lnc{\baselineskip} to the normal skip, \lnc{\onelineskip}. At the end +of the environment there is a negative space of one line to compensate +for a one line space that LaTeX inserts. + + The two versals in \S\ref{sec:versal} were typeset with macros defined +in the preamble\index{preamble}. The first and poorer of the two used the \cmd{\versal} +macro. The second used the \cmd{\drop} macro which was written for +LaTeX v2.09 by David Cantor and Dominik Wujastyk in 1998. Now, if you want +to try your hand at this sort of thing there are some more packages +on CTAN. I have found that the \Lpack{lettrine} package~\cite{LETTRINE} +serves my needs. + + + +% back end +\backmatter +\clearpage +\pagestyle{ruled} +\chapterstyle{section} + +\renewcommand{\prebibhook}{% +CTAN is the Comprehensive TeX Archive Network. Information on how to +access CTAN is available at \url{http://www.tug.org}. +\par\vspace{\onelineskip}} + +\begin{thebibliography}{GMS94A} + +\bibitem[Ado01]{ADOBEBOOK} + \emph{How to Create Adobe PDF eBooks}. + \newblock Adobe Systems Inc., + \newblock 2001. + \newblock (Available from + \url{http://www.adobe.com/epaper/tips/acr5ebook/pdfs/eBook.pdf}) + +\bibitem[Ars99]{URL} + Donald Arseneau. + \newblock \emph{The url package}. + \newblock February, 1999. + \newblock (Available from CTAN as + \url{/macros/latex/contrib/misc/url.sty}) + +\bibitem[Ars01a]{TITLEREF} + Donald Arseneau. + \newblock \emph{The titleref package}. + \newblock April, 2001. + \newblock (Available from CTAN as + \url{/macros/latex/contrib/misc/titleref.sty}) + +\bibitem[Ars01b]{FRAMED} + Donald Arseneau. + \newblock \emph{The framed package}. + \newblock July, 2001. + \newblock (Available from CTAN as + \url{/macros/latex/contrib/misc/framed.sty}) + +\bibitem[Ars01b]{CHAPTERBIB} + Donald Arseneau. + \newblock \emph{The chapterbib package}. + \newblock September, 2001. + \newblock (Available from CTAN as + \url{/macros/latex/contrib/cite/chapterbib.sty}) + +\bibitem[Bar92]{BAROLINI92} + Helen Barolini. + \newblock \emph{Aldus and his Dream Book}. + \newblock Italica Press + \newblock (ISBN 0--934977--22--4), 1992. + +\bibitem[BDG89]{BIGELOW89} + Charles Bigelow, Paul Hayden Duensing and Linnea Gentry (Eds). + \newblock \emph{Fine Print on Type}. 1989. + \newblock Fine Print, CA (ISBN 0--9607290-X) or + \newblock Bedford Arts, CA (ISBN 0--938491--17--2). + +\bibitem[Boh90]{BOHLE90} + Robert Bohle. + \newblock \emph{Publication Design for Editors}. + \newblock Prentice-Hall, + \newblock 1990. + +\bibitem[Ber02]{JURABIB} + Jens Berger. + \newblock \emph{The titlesec and titletoc packages}. + \newblock September, 2002. + \newblock (Available from CTAN in + \url{/macros/latex/contrib/titlesec}) + +\bibitem[Bez99]{TITLESEC} + Javier Bezos. + \newblock \emph{The titlesec and titletoc packages}. + \newblock February, 1999. + \newblock (Available from CTAN in + \url{/macros/latex/contrib/titlesec}) + +\bibitem[Bra94]{MAKEIDX} + Johannes Braams \textit{et al}. + \newblock \emph{Standard LaTeX2e packages makeidx and showidx}. + \newblock November, 1994. + \newblock (Available from CTAN as + \url{/macros/latex/base/makeindx.dtx(ins)}) + +\bibitem[Bra97]{ALLTT} + Johannes Braams. + \newblock \emph{The alltt environment}. + \newblock June, 1997. + \newblock (Available from CTAN as + \url{/macros/latex/base/alltt.dtx(ins)}) + +\bibitem[Bri92]{BRINGHURST92} + Robert Bringhurst. + \newblock \emph{The Elements of Typographic Style}. + \newblock Hartley \& Marks + \newblock (ISBN 0--88179--033--8), 1992. + +\bibitem[Bur59]{BURT59} + C.~L.~Burt. + \newblock \emph{A Psychological Study of Typography}. + \newblock Cambridge University Press, + \newblock 1959. + +\bibitem[Car94]{DELARRAY} + David Carlisle. + \newblock \emph{The delarray package}. + \newblock March, 1994. + \newblock (Available from CTAN in + \url{/macros/latex/required/tools}) + +\bibitem[Car95]{AFTERPAGE} + David Carlisle. + \newblock \emph{The afterpage package}. + \newblock October, 1995. + \newblock (Available from CTAN in + \url{/macros/latex/required/tools}) + +\bibitem[Car98a]{COLOR} + David Carlisle. + \newblock \emph{The color package}. + \newblock May, 1998. + \newblock (Available from CTAN in + \url{/macros/latex/required/tools}) + +\bibitem[Car98b]{LONGTABLE} + David Carlisle. + \newblock \emph{The longtable package}. + \newblock May, 1998. + \newblock (Available from CTAN in + \url{/macros/latex/required/tools}) + +\bibitem[Car98c]{ENUMERATE} + David Carlisle. + \newblock \emph{The enumerate package}. + \newblock August, 1998. + \newblock (Available from CTAN in + \url{/macros/latex/required/tools}) + +\bibitem[Car98d]{REMRESET} + David Carlisle. + \newblock \emph{The remreset package}. + \newblock August, 1998. + \newblock (Available from CTAN in + \url{/macros/latex/contrib/carlisle}) + +\bibitem[Car99a]{TABULARX} + David Carlisle. + \newblock \emph{The tabularx package}. + \newblock January, 1999. + \newblock (Available from CTAN in + \url{/macros/latex/required/tools}) + + +\bibitem[Car01]{DCOLUMN} + David Carlisle. + \newblock \emph{The dcolumn package}. + \newblock May, 2001. + \newblock (Available from CTAN in + \url{/macros/latex/required/tools}) + +\bibitem[CR99]{GRAPHICX} + David Carlisle and Sebastian Rahtz. + \newblock \emph{The graphicx package}. + \newblock February, 1999. + \newblock (Available from CTAN in + \url{/macros/latex/required/graphics}) + +\bibitem[CB99]{CHAPPELL99} + Warren Chappell and Robert Bringhurst. + \newblock \emph{A Short History of the Printed Word}. + \newblock Hartley \& Marks, 1999. + \newblock ISBN 0--88179--154--7. + +\bibitem[CH88]{CHEN88} + Pehong Chen and Michael A.~Harrison. + \newblock `Index Preparation and Processing'. + \newblock \emph{Software: Practice and Experience}, 19:8, pp. 897--915, + September, 1988. + \newblock (Available from CTAN in + \url{/indexing/makeindex/paper}) + +\bibitem[Chi93]{CMS93} + \newblock \emph{The Chicago Manual of Style}, Fourteenth Edition. + \newblock The University of Chicago + \newblock (ISBN 0--226--10389--7) 1993. + + +\bibitem[Coc02]{SUBFIGURE} + Steven Douglas Cochran. + \newblock \emph{The subfigure package}. + \newblock March, 2002. + \newblock (Available from CTAN in + \url{/macros/latex/contrib/subfigure}) + +\bibitem[CG96]{CONWAY96} + John H.~Conway and Richard K.~Guy. + \newblock \emph{The Book of Numbers}. + \newblock Copernicus, Springer-Verlag + \newblock (ISBN 0--387--97993--X), 1996. + +\bibitem[Cra92]{CRAIG92} + James Craig. + \newblock \emph{Designing with Type: A Basic Course in Typography}. + \newblock Watson-Guptill, NY, + \newblock 1992. + +\bibitem[Dal99]{NATBIB} + Patrick W.~Daly. + \newblock \emph{Natural Sciences Citations and References}. + \newblock May, 1999. + \newblock (Available from CTAN in + \url{/macros/latex/contrib/natbib}) + +\bibitem[Deg92]{DEGANI92} + Asaf Degani. + \newblock \emph{On the Typography of Flight-Deck Documentation}. + \newblock NASA Contractor Report \# 177605. + \newblock December, 1992. + \newblock (Available from + \url{http://members.aol.com/willadams/typgrphy.htm#NASA}) + + +\bibitem[Dow96]{DOWDING96} + Geoffrey Dowding. + \newblock \emph{Finer Points in the Spacing \& Arrangement of Type}. + \newblock Hartley \& Marks + \newblock (ISBN 0--88179--119--9), 1996. + +\bibitem[Dow98]{DOWDING98} + Geoffrey Dowding. + \newblock \emph{An Introduction to the History of Printing Types}. + \newblock The British Library and Oak Knoll Press + \newblock (ISBN 0--7123--4563--9 \textsc{uk}, + 1--884718--44--2 \textsc{usa}), 1998. + +\bibitem[Dow00]{PATCHCMD} + Michael J.~Downes. + \newblock \emph{The patchcmd package}. + \newblock July, 2000. + \newblock (Available from CTAN in + \url{/macros/latex/contrib/patchcmd}) + +\bibitem[Eij92]{EIJKHOUT92} + Victor Eijkhout. + \newblock \emph{TeX by Topic}. + \newblock Addison-Wesley, 1992. + \newblock ISBN 0--201--56882--9. + \newblock (Available from \url{http://www.eijkhout.net/tbt/}). + +\bibitem[Fai00]{FOOTMISC} + Robin Fairbairns. + \newblock \emph{footmisc --- a portmanteau package for customising + footnotes in LaTeX2e}. + \newblock March, 2000. + \newblock (Available from CTAN in + \url{/macros/latex/contrib/footmisc}) + +\bibitem[Fai98]{MOREVERB} + Robin Fairbairns. + \newblock \emph{The moreverb package}. + \newblock December, 1998. + \newblock (Available from CTAN in + \url{/macros/latex/contrib/moreverb}) + +\bibitem[FAQ]{FAQ} + Robin Fairbairns. + \newblock \emph{The UK TeX FAQ}. + \newblock (Available from CTAN in + \url{/help/uk-tex-faq}) + +\bibitem[Fea03]{BOOKTABS} + Simon Fear. + \newblock \emph{Publication quality tables in LaTeX}. + \newblock March, 2003. + \newblock (Available from CTAN in + \url{/macros/latex/contrib/booktabs}) + +\bibitem[Fli98]{LETTRINE} + Daniel Flipo. + \newblock \emph{Typesetting `lettrines' in LaTeX2e documents}. + \newblock March, 1998. + \newblock (Available from CTAN in + \url{/macros/latex/contrib/lettrine}) + +\bibitem[Fra00]{CROP} + Melchior Franz. + \newblock \emph{The crop package}. + \newblock February, 2000. + \newblock (Available from CTAN in + \url{/macros/latex/contrib/crop}) + +\bibitem[FOS98]{FRIEDL98} + Friedrich Friedl, Nicolaus Ott and Bernard Stein. + \newblock \emph{Typography: An Encyclopedic Survey of Type Designs and + Techniques throughout History}. + \newblock Black Dog \& Leventhal Publishers Inc. + \newblock (ISBN 1--57912--023--7), 1998. + +\bibitem[Gar66]{GARDNER66} + Martin Gardner. + \newblock \emph{More Mathematical Puzzles and Diversions}. + \newblock Penguin Books + \newblock (ISBN 0--14--020748--1), 1966. + +\bibitem[GMS94]{GOOSSENS94} + Michel Goossens, Frank Mittelbach and Alexander Samarin. + \newblock \emph{The LaTeX Companion}. + \newblock Addison-Wesley Publishing Company + \newblock (ISBN 0--201--54199--8), 1994. + +\bibitem[GRM97]{GOOSSENS97} + Michel Goossens, Sebastian Rahtz and Frank Mittelbach. + \newblock \emph{The LaTeX Graphics Companion: Illustrating Documents + with TeX and PostScript}. + \newblock Addison-Wesley Publishing Company + \newblock (ISBN 0--201--85469--4), 1997. + +\bibitem[GR99]{GOOSSENS99} + Michel Goossens and Sebastian Rahtz (with Eitan Gurari, + Ross Moore and Robert Sutor). + \newblock \emph{The LaTeX Web Companion: Integrating TeX, HTML and XML}. + \newblock Addison-Wesley Publishing Company + \newblock (ISBN 0--201--43311--7), 1999. + +\bibitem[Gou87]{GOULD87} + J.~D.~Gould \textit{et al}. + \newblock `Reading from CRT displays can be as fast as reading from paper'. + \newblock \emph{Human Factors}, pp 497--517, 29:5, 1987. + +\bibitem[HR83]{HARTLEY83} + J.~Hartley and D.~Rooum. + \newblock `Sir Cyril Burt and typography'. + \newblock \emph{British Journal of Psychology}, pp 203--212, 74:2, 1983. + +\bibitem[HM01]{HELLER01} + Steven Heller and Philip B.~Maggs (Eds). + \newblock \emph{Texts on Type: Critical Writings on Typography}. + \newblock Allworth Press + \newblock (ISBN 1--58115--082--2), 2001. + +\bibitem[Hoe98]{HOENIG98} + Alan Hoenig. + \newblock \emph{TeX Unbound: LaTeX and TeX strategies for fonts, + graphics, and more}. + \newblock Oxford University Press + \newblock (ISBN 0--19--509686--X), 1998. + +\bibitem[HK75]{HVISTENDAHL75} + J.~K.~Hvistendahl and M.~R.~Kahl. + \newblock `Roman vs. sans serif body type: Readability and reader prference'. + \newblock \emph{AANPA News Research Bulletin}, pp 3--11, 17 Jan., 1975. + + +\bibitem[Jon95]{INDEX} + David M.~Jones. + \newblock \emph{A new implementation of LaTeX's indexing commands}. + \newblock September, 1995. + \newblock (Available from CTAN in \url{/macros/latex/contrib/camel}) + +\bibitem[Knu84]{KNUTH84a} + Donald E.~Knuth. + \newblock \emph{The TeXbook}. + \newblock Addison-Wesley Publishing Company + \newblock (ISBN 0--201--13448--9), 1984. + +\bibitem[Lam94]{LAMPORT94} + Leslie Lamport. + \newblock \emph{LaTeX: A Document Preparation System}. + \newblock Addison-Wesley Publishing Company + \newblock (ISBN 0--201--52983--1), 1994. + +\bibitem[LMB99]{CLASSES} + Leslie Lamport, Frank Mittelbach and Johannes Braams. + \newblock \emph{Standard document classes for LaTeX version 2e}. + \newblock September, 1999. + \newblock (Available from CTAN as \url{/macros/latex/base/classes.dtx}) + +\bibitem[Law90]{LAWSON90} + Alexander Lawson. + \newblock \emph{Anatomy of a Typeface}. + \newblock David R.~Godine + \newblock (ISBN 0--87923--333--8), 1990. + +\bibitem[Leu92]{LEUNEN92} + Mary-Claire van Leunen. + \newblock \emph{A Handbook for Scholars}. + \newblock Oxford University Press + \newblock (ISBN 0--19--506954--4), 1992. + +\bibitem[Lon91]{MULTIND} + F.~W.~Long. + \newblock \emph{multind}. + \newblock August, 1991. + \newblock (Available from CTAN as \url{/macros/latex209/contrib/misc/multind.sty}) + +\bibitem[McD98]{SECTSTY} + Rowland McDonnell. + \newblock \emph{The sectsty package}. + \newblock November, 1998. + \newblock (Available from CTAN in + \url{/macros/latex/contrib/secsty}) + +\bibitem[McL75]{MCLEAN75} + Ruari McLean. + \newblock \emph{Jan Tschichold: Typographer}. + \newblock David R.~Godine + \newblock (ISBN 0--87923--841--0), 1975. + +\bibitem[McL80]{MCLEAN80} + Ruari McLean. + \newblock \emph{The Thames \& Hudson Manual of Typography}. + \newblock Thames \& Hudson + \newblock (ISBN 0--500--68022--1), 1980. + +\bibitem[McL95]{MCLEAN95} + Ruari McLean (Ed). + \newblock \emph{Typographers on Type}. + \newblock W.~W.~Norton \& Co. + \newblock (ISBN 0--393--70201--4), 1995. + +\bibitem[Mit95]{DOC} + Frank Mittelbach. + \newblock \emph{The doc and shortvrb packages}. + \newblock May, 1995. + \newblock (Available from CTAN in + \url{/macros/latex/base}) + +\bibitem[Mit95]{SHORTVRB} + Frank Mittelbach. + \newblock \emph{The doc and shortvrb packages}. + \newblock May, 1995. + \newblock (Available from CTAN in + \url{/macros/latex/base}) + +\bibitem[Mit98]{MULTICOL} + Frank Mittelbach. + \newblock \emph{An environment for multicolumn output}. + \newblock January, 1998. + \newblock (Available from CTAN in + \url{/macros/latex/required/tools}) + +\bibitem[MC98]{ARRAY} + Frank Mittelbach and David Carlisle. + \newblock \emph{A new implementation of LaTeX's tabular and array environment}. \newblock May, 1998. + \newblock (Available from CTAN in + \url{/macros/latex/required/tools}) + +\bibitem[MC00]{FIXLTX2E} + Frank Mittelbach and David Carlisle. + \newblock \emph{The fixltx2e package}. + \newblock September, 2000. + \newblock (Available from CTAN in + \url{/macros/latex/base}) + +\bibitem[Mor99]{MORISON99} + Stanley Morison. + \newblock \emph{A Tally of Types}. + \newblock David R. Godine + \newblock (ISBN 1--56792--004--7), 1999. + +\bibitem[NG98]{SIDECAP} + Rolf Niespraschk and Hubert G\"{a}\ss{}lein. + \newblock \emph{The sidecap package}. + \newblock June, 1998. + \newblock (Available from CTAN in + \url{/macros/latex/contrib/sidecap}) + +\bibitem[Oet]{LSHORT} + Tobias Oetiker. + \newblock \emph{The Not So Short Introduction to LaTeX2e}. + \newblock (Available from CTAN in + \url{/info/lshort/english}) + +\bibitem[Oos96]{FANCYHDR} + Piet van Oostrum. + \newblock \emph{Page Layout in LaTeX}. + \newblock June, 1996. + \newblock (Available from CTAN in + \url{/macros/latex/contrib/fancyhdr}) + +\bibitem[Pak01]{SYMBOLS} + Scott Pakin. + \newblock \emph{The Comprehensive LaTeX Symbol List}. + \newblock July, 2001. + \newblock (Available from CTAN in + \url{/info/symbols/comprehensive}) + +\bibitem[Pug02]{MATHPAZO} + Diego Puga. + \newblock \emph{The Pazo Math fonts for mathematical typesetting + with the Palatino fonts}. + \newblock May, 2002. + \newblock (Available from CTAN in + \url{/fonts/mathpazo}) + +\bibitem[Rahtz01]{NAMEREF} + Sebastian Rahtz. + \newblock \emph{Section name references in LaTeX}. + \newblock January, 2001. + \newblock (Available from CTAN in + \url{/macros/latex/contrib/hyperref}) + +\bibitem[Rahtz02]{HYPERREF} + Sebastian Rahtz. + \newblock \emph{Hypertext marks in LaTeX}. + \newblock May, 2002. + \newblock (Available from CTAN in + \url{/macros/latex/contrib/hyperref}) + +\bibitem[Rec97]{EPSLATEX} + Keith Reckdahl. + \newblock \emph{Using Imported Graphics in LaTeX2e}. + \newblock December, 1997. + \newblock (Available from CTAN as + \url{/info/epspatex.ps} or \url{/info/epslatex.pdf}) + +\bibitem[Reh72]{REHE72} + Rolf Rehe. + \newblock `Type and how to make it most legible'. + \newblock \emph{Design Research International}, 1972. + +\bibitem[RAE71]{ROBINSON71} + D.~O.~Robinson, M.~Abbamonte and S.~H.~Evans. + \newblock `Why serifs are important: The perception of small print'. + \newblock \emph{Visible Language}, pp 353--359, 4, 1971. + +\bibitem[Rog43]{ROGERS43} + Bruce Rogers. + \newblock \emph{Paragraphs on Printing}. + \newblock William E. Rudge's Sons, Inc. + \newblock (no ISBN), 1943. + \newblock (Reissued by Dover, 1979, ISBN 0--486--23817--2) + +\bibitem[Rog49]{ROGERS49} + Bruce Rogers. + \newblock \emph{Centaur Types}. + \newblock October House + \newblock (no ISBN), 1949. + +\bibitem[SW94]{EBOOK} + Douglas Schenck and Peter Wilson. + \newblock \emph{Information Modeling the EXPRESS Way}. + \newblock Oxford University Press + \newblock (ISBN 0--19--508714--3), 1994. + +\bibitem[SRR99]{VERBATIM} + Rainer Sch\"{o}pf, Bernd Raichle and Chris Rowley. + \newblock \emph{A New Implementation of LaTeX's verbatim + and verbatim* Environments}. + \newblock December, 1999. + \newblock (Available from CTAN in + \url{/macros/latex/required/tools}) + +\bibitem[Sch97]{SCHRIVER97} + Karen A.~Schriver. + \newblock \emph{Dynamics in Document Design}. + \newblock Wiley \& Sons, 1997. + +\bibitem[Thi99]{TTC199} + Christina Thiele. + \newblock `The Treasure Chest: Package tours from CTAN', + \newblock \emph{TUGboat}, + \newblock vol. 20, no. 1, pp 53--58, March 1999. + +\bibitem[Tin63]{TINKER63} + Miles A.~Tinker. + \newblock \emph{Legibility of Print}. + \newblock Books on Demand (University Microfilms International), 1963. + +\bibitem[Tsc91]{TSCHICHOLD91} + Jan Tschichold. + \newblock \emph{The Form of the Book}. + \newblock Lund Humphries + \newblock (ISBN 0--85331--623--6), 1991. + +\bibitem[Ume99]{GEOMETRY} + Hideo Umeki. + \newblock \emph{The geometry package}. + \newblock November, 1999. + \newblock (Available from CTAN in + \url{/macros/latex/contrib/geometry}) + + +\bibitem[Whe95]{WHEILDON95} + Colin Wheildon. + \newblock \emph{Type \& Layout}. + \newblock Strathmore Press + \newblock (ISBN 0--9624891--5--8), 1995. + +\bibitem[Wil93]{ADRIANWILSON93} + Adrian Wilson. + \newblock \emph{The Design of Books}. + \newblock Chronicle Books + \newblock (ISBN 0--8118--0304--X), 1993. + + + +\bibitem[Wil99a]{LAYOUTS} + Peter Wilson. + \newblock \emph{The layouts package}. + \newblock January, 1999. + \newblock (Available from CTAN in + \url{/macros/latex/contrib/layouts}) + +\bibitem[Wil99b]{TOCVSEC2} + Peter Wilson. + \newblock \emph{The tocvsec2 package}. + \newblock January, 1999. + \newblock (Available from CTAN in + \url{/macros/latex/contrib/tocvsec2}) + +\bibitem[Wil00a]{EPIGRAPH} + Peter Wilson. + \newblock \emph{The epigraph package}. + \newblock February, 2000. + \newblock (Available from CTAN in + \url{/macros/latex/contrib/epigraph}) + +\bibitem[Wil00b]{ISOCLASS} + Peter Wilson. + \newblock \emph{LaTeX files for typesetting ISO standards}. + \newblock February, 2000. + \newblock (Available from CTAN in + \url{/macros/latex/contrib/isostds/iso}) + +\bibitem[Wil00c]{NEXTPAGE} + Peter Wilson. + \newblock \emph{The nextpage package}. + \newblock February, 2000. + \newblock (Available from CTAN as + \url{/macros/latex/contrib/misc/nextpage.sty}) + +\bibitem[Wil00d]{NEEDSPACE} + Peter Wilson. + \newblock \emph{The needspace package}. + \newblock March, 2000. + \newblock (Available from CTAN as + \url{/macros/latex/contrib/misc/needspace.sty}) + +\bibitem[Wil00e]{XTAB} + Peter Wilson. + \newblock \emph{The xtab package}. + \newblock April 2000. + \newblock (Available from CTAN in + \texttt{macros/latex/contrib/xtab}) + +\bibitem[Wil01a]{ABSTRACT} + Peter Wilson. + \newblock \emph{The abstract package}. + \newblock February, 2001. + \newblock (Available from CTAN in + \url{/macros/latex/contrib/abstract}) + +\bibitem[Wil01b]{CHNGPAGE} + Peter Wilson. + \newblock \emph{The chngpage package}. + \newblock February, 2001. + \newblock (Available from CTAN as + \url{/macros/latex/contrib/misc/chngpage.sty}) + +\bibitem[Wil01c]{APPENDIX} + Peter Wilson. + \newblock \emph{The appendix package}. + \newblock March, 2001. + \newblock (Available from CTAN in + \url{/macros/latex/contrib/appendix}) + +\bibitem[Wil01d]{CCAPTION} + Peter Wilson. + \newblock \emph{The ccaption package}. + \newblock March, 2001. + \newblock (Available from CTAN in + \url{/macros/latex/contrib/ccaption}) + +\bibitem[Wil01e]{CHNGCNTR} + Peter Wilson. + \newblock \emph{The chngcntr package}. + \newblock April, 2001. + \newblock (Available from CTAN as + \url{/macros/latex/contrib/misc/chngcntr.sty}) + +\bibitem[Wil01f]{HANGING} + Peter Wilson. + \newblock \emph{The hanging package}. + \newblock March, 2001. + \newblock (Available from CTAN in + \url{/macros/latex/contrib/hanging}) + +\bibitem[Wil01g]{TITLING} + Peter Wilson. + \newblock \emph{The titling package}. + \newblock March, 2001. + \newblock (Available from CTAN in + \url{/macros/latex/contrib/titling}) + +\bibitem[Wil01h]{TOCBIBIND} + Peter Wilson. + \newblock \emph{The tocbibind package}. + \newblock April, 2001. + \newblock (Available from CTAN in + \url{/macros/latex/contrib/tocbibind}) + + +\bibitem[Wil01i]{TOCLOFT} + Peter Wilson. + \newblock \emph{The tocloft package}. + \newblock April, 2001. + \newblock (Available from CTAN in + \url{/macros/latex/contrib/tocloft}) + + +\bibitem[Wil01j]{MEMOIR} + Peter Wilson. + \newblock \emph{The LaTeX memoir class for configurable book + typesetting: Source code}. + \newblock July, 2001. + \newblock (Available from CTAN in + \url{/macros/latex/contrib/memoir}) + +\bibitem[Wil01k]{VERSE} + Peter Wilson. + \newblock \emph{Typesetting simple verse with LaTeX} + \newblock July, 2001. + \newblock (Available from CTAN in + \url{/macros/latex/contrib/verse}) + +\bibitem[Wil01l]{BOOKLET} + Peter Wilson. + \newblock \emph{Printing booklets with LaTeX} + \newblock August, 2001. + \newblock (Available from CTAN in + \url{/macros/latex/contrib/booklet}) + +\bibitem[Wil03]{LEDMAC} + Peter Wilson. + \newblock \emph{ledmac: A presumptuous attaempt to port EDMAC and TABMAC + to LaTeX} + \newblock November, 2003. + \newblock (Available from CTAN in + \url{/macros/latex/contrib/ledmac}) + +\bibitem[Wil??]{RUMOUR} +Peter Wilson. +\newblock \emph{A Rumour of Humour: A scientist's commonplace book}. +\newblock To be published? + + +\bibitem[Zac69]{ZACHRISSOM69} + B.~Zachrissom. + \newblock \emph{Studies in the Legibility of Printed Text}. + \newblock Almqvist \& Wiksell, Stockholm, 1969. + +\bibitem[Zap00]{ZAPF00} + Hermann Zapf. + \newblock \emph{The Fine Art of Letters}. + \newblock The Grolier Club + \newblock (ISBN 0--910672--35--0), 2000. + + + +\end{thebibliography} + +\clearpage +\pagestyle{index} +%\renewcommand{\chaptermark}[1]{} +\renewcommand{\preindexhook}{% +The first page number is usually, but not always, the primary reference to +the indexed topic.\vskip\onelineskip} +\indexintoc +\printindex + +\cleardoublepage +\pagestyle{empty} +\null\vfil + +\begin{adjustwidth}{1in}{1in} +\begin{center} +{\Large\textsf{Colophon}} +\end{center} +\begin{center} +This manual was typeset using the LaTeX typesetting system +created by Leslie Lamport and the memoir class. +The body text is set 10/12pt on a +33pc measure with Computer +Modern Roman designed by Donald Knuth. Other fonts include +Sans, Smallcaps, Italic, Slanted and Typewriter, all from Knuth's +Computer Modern family. + +\end{center} + +\end{adjustwidth} + +\vfil + +\end{document} + +\endinput + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +%%%%%%%%%%%% +patchit The addendum +%%%%%%%%%%% + +% memmanadd.tex Addendum to the Memoir class user manual +% Author: Peter Wilson +% Copyright 2002, 2003 Peter R. Wilson +% All rights reserved + + + +%\AtBeginDocument{% +% \ifpdf +% \ifnum\pdfoutput>0\relax +% \pdfpageheight=\the\stockheight +% \pdfpagewidth=\the\stockwidth +% \pdfvorigin=1in +% \pdfhorigin=1in +% \fi +% \fi} + +%%%%%%%%%%%%%%%%%% change fonts +%\renewcommand{\rmdefault}{ppl} % palatino +\usepackage{mempalatino} +%%\usepackage{pifont} + +%%%%%%\usepackage{amsmath} + +\ifpdf + \pdfoutput=1 + \usepackage[pdftex, + plainpages=false, + pdfpagelabels, + hyperfootnotes=false, + bookmarksnumbered + ]{hyperref} + \usepackage{memhfixc} +\else + \usepackage[plainpages=false, + pdfpagelabels, + hyperfootnotes=false, + bookmarksnumbered + ]{hyperref} + \usepackage{memhfixc} +\fi + + +%\showindexmarktrue + +\newcommand{\theclass}{memoir} + +\providecommand{\tx}{TeX} +\providecommand{\ltx}{LaTeX} + +\newsubfloat{table} + + +\makeatletter + +%%% Print and Index macros +\newcommand{\Ppstyle}[1]{\textsl{#1}} +\newcommand{\pstyle}[1]{\Ppstyle{#1}% + \index{#1 pages?\Ppstyle{#1} (pagestyle)}% + \index{pagestyle!#1?\Ppstyle{#1}}} % pagestyle +\newcommand{\Pcstyle}[1]{\textsl{#1}} +\newcommand{\cstyle}[1]{\Pcstyle{#1}% + \index{#1 chaps?\Pcstyle{#1} (chapterstyle)}% + \index{chapterstyle!#1?\Pcstyle{#1}}} % chapterstyle +\newcommand{\Pclass}[1]{\textsf{#1}} +\newcommand{\Lclass}[1]{\Pclass{#1}% + \index{#1 class?\Pclass{#1} (class)}% + \index{class!#1?\Pclass{#1}}} % class name +\newcommand{\Ppack}[1]{\textsf{#1}} +\newcommand{\Lpack}[1]{\Ppack{#1}% + \index{#1 pack?\Ppack{#1} (package)}% + \index{package!#1?\Ppack{#1}}} % package name +\newcommand{\Popt}[1]{\textsf{#1}} +\newcommand{\Lopt}[1]{\Popt{#1}% + \index{#1 opt?\Popt{#1} (option)}% + \index{option!#1?\Popt{#1}}} % option name +\newcommand{\Ie}[1]{\texttt{#1}\index{#1 env?\texttt{#1} (environment)}% + \index{environment!#1?\texttt{#1}}} +\newcommand{\Icn}[1]{\texttt{#1}\index{#1 cou?\texttt{#1} (counter)}% + \index{counter!#1?\texttt{#1}}} +\newcommand{\Itt}[1]{\texttt{#1}\index{#1tt?\texttt{#1}}} + +% print and index an \if... \piif{if...} +\newcommand{\piif}[1]{\cs{#1}\index{#1?\cs{#1}}} + +% index command \! +\newcommand{\iexcl}{\index{"!?\cs{!}}} + +%%%\newcommand{\seealso}[2]{\emph{see also} #1} + +\newcommand{\listofx}{`List of\ldots'} + +% print a begin environment +\newcommand{\senv}[1]{\texttt{\bs begin\{#1\}}} + +% print an end environment +\newcommand{\eenv}[1]{\texttt{\bs end\{#1\}}} + +% print a file name +\newcommand{\file}[1]{\texttt{#1}} + +% print and index a file name +\newcommand{\ixfile}[1]{\file{#1}% + \index{#1 file?\file{#1} (file)}% + \index{file!#1?\file{#1}}} + +% print CTT +\newcommand{\ctt}{\textsc{ctt}} +% print & index CTT +\newcommand{\pictt}{\ctt\index{CTT?\ctt}} + +% index marking +\newcommand{\idxmark}[1]{#1\markboth{#1}{#1}} + +\newcommand{\foredge}{foredge} +\newlength{\pwlayi}\setlength{\pwlayi}{0.45\textwidth} % +\newlength{\pwlayii}\setlength{\pwlayii}{0.45\pwlayi} + +%% definition of \meta is taken from doc.dtx +\begingroup +\obeyspaces% +\catcode`\^^M\active% +\gdef\meta{\begingroup\obeyspaces\catcode`\^^M\active% +\let^^M\do@space\let \do@space% +\def\-{\egroup\discretionary{-}{}{}\hbox\bgroup\itshape}% +\m@ta}% +\endgroup +\def\m@ta#1{\leavevmode\hbox\bgroup$\langle$\itshape#1\/$\rangle$\egroup + \endgroup} +\def\do@space{\egroup\space + \hbox\bgroup\itshape\futurelet\next\sp@ce} +\def\sp@ce{\ifx\next\do@space\expandafter\sp@@ce\fi} +\def\sp@@ce#1{\futurelet\next\sp@ce} +%% end of \meta and supports + + +%% The definition of \MakeShortVerb & \DeleteShortVerb +%% are now in the memoir class. + +%% The macros \cmd, \cs, \marg, \oarg, \parg are taken from ltxdoc.dtx +% \cmd{\fred} typesets \fred +\def\cmd#1{\cs{\expandafter\cmd@to@cs\string#1}} +\def\cmd@to@cs#1#2{\char\number`#2\relax} +% \cs{fred} typesets \fred +\DeclareRobustCommand{\cs}[1]{\texttt{\char`\\#1}} +% \marg{arg} typesets {<arg>} +\providecommand{\marg}[1]{% + {\ttfamily\char`\{}\meta{#1}{\ttfamily\char`\}}} +% \oarg{arg} typesets [<arg>] +\providecommand{\oarg}[1]{% + {\ttfamily\char`\[}\meta{#1}{\ttfamily\char`\]}} +% \parg{x,y} typesets (<x,y>) +\providecommand{\parg}[1]{% + {\ttfamily\char`\(}\meta{#1}{\ttfamily\char`\)}} + +\def\bs{\texttt{\char`\\}} + +%%% macro \cmd from Heiko Oberdiek CTT 2001/05/26 (prints and indexes a command) +\newcommand*{\cmdprint}[1]{\texttt{\string#1}} +\def\cmd#1{\cmdprint{#1}% + \index{\expandafter\@gobble\string#1?\string\cmdprint{\string#1}}} + +% print and index \\! +\newcommand{\pixslashbang}{\cmdprint{\\!}\index{"\"\"!?\string\cmdprint{\\}\texttt{"!}}} + +% print and index \! +\newcommand{\pixabang}{\cmdprint{\!}\index{"!?\string\cs{}\texttt{"!}}} + +% print and index a length +\newcommand{\lnc}[1]{\cmdprint{#1}% + \index{\expandafter\@gobble\string#1len?\string\cmdprint{\string#1} (length)}% + \index{length!\expandafter\@gobble\string#1len?\string\cmdprint{\string#1}}} + +%%%%%% stuff for new LaTeX code environment + +% \zeroseps sets list before/after skips to minimum values +\newcommand{\@zeroseps}{\setlength{\topsep}{\z@} + \setlength{\partopsep}{\z@} + \setlength{\parskip}{\z@}} +\newlength{\gparindent} \setlength{\gparindent}{\parindent} +\setlength{\gparindent}{0.5\parindent} +% now we can do the new environment. This has no extra before/after spacing. +\newenvironment{lcode}{\@zeroseps + \renewcommand{\verbatim@startline}{\verbatim@line{\hskip\gparindent}} + \small\setlength{\baselineskip}{\onelineskip}\verbatim}% + {\endverbatim + \vspace{-\baselineskip}% + \noindent +} + +%%%% this is the code environment for the book +\newenvironment{bcode}{\@zeroseps + \renewcommand{\verbatim@processline}{% + \hskip\gparindent\the\verbatim@line\par}% + \small\setlength{\baselineskip}{\onelineskip}\verbatim}% + {\endverbatim\noindent} + +%%%%%%%%%%%% for experiments + +%\renewenvironment{lcode}{\@zeroseps +% \renewcommand{\verbatim@startline}{\verbatim@line{ * }} +% \small\setlength{\baselineskip}{\onelineskip}\verbatim}% +% {\endverbatim +% \vspace{-\baselineskip} +% \noindent % need the \noindent +%} + +%\renewenvironment{bcode}{\@zeroseps +% \renewcommand{\verbatim@processline}{% +% * \the\verbatim@line\par}% +% \small\setlength{\baselineskip}{\onelineskip}\verbatim}% +% {\endverbatim\noindent} % need the \noindent + + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +%%%%% LaTeX syntax +\newenvironment{syntax}{\begin{center} + \begin{tabular}{|p{0.9\linewidth}|} \hline}% + {\hline + \end{tabular} + \end{center}} + +%%%%%%%%%%%%%%%%%% index pagestyle +\makepagestyle{index} + \makeheadrule{index}{\textwidth}{\normalrulethickness} + \makeevenhead{index}{\rightmark}{}{\leftmark} + \makeoddhead{index}{\rightmark}{}{\leftmark} + \makeevenfoot{index}{\thepage}{}{} + \makeoddfoot{index}{}{}{\thepage} + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%Date: Tue, 22 Jul 2003 19:27:13 +0200 +%From: Bastiaan Veelo <Bastiaan.N.Veelo@immtek.ntnu.no> +%Newsgroups: comp.text.tex +%CC: "Wilson, Peter R" <peter.r.wilson@boeing.com> +%Subject: [memoir] [contrib] New chapter style +% +%Hello all, +% +%In case anyone is interested, I thought I'd share a new chapter style to +%be used with the memoir class by Peter Wilson. The style is tailored at +%documents that are to be trimmed to a smaller width. When the binded +%document is bent, black tabs will appear on the fore side at the places +%where new chapters start, as a navigational aid. Sample attached. +% +%Regards, +%Bastiaan. + +%% A new chapter style, that suits well for trimmed documents. +%% We are scaling the chapter number, which most DVI viewers +%% will not display accurately. +\makeatletter + \newlength{\numberheight} + \newlength{\barlength} +%\makechapterstyle{trim}{% +\makechapterstyle{veelo}{% + \setlength{\beforechapskip}{40pt} + \setlength{\midchapskip}{25pt} + \setlength{\afterchapskip}{40pt} + \renewcommand{\chapnamefont}{\normalfont\LARGE\flushright} + \renewcommand{\chapnumfont}{\normalfont\HUGE} + \renewcommand{\chaptitlefont}{\normalfont\HUGE\bfseries\flushright} + \renewcommand{\printchaptername}{% + \chapnamefont\MakeUppercase{\@chapapp}} + \renewcommand{\chapternamenum}{} +% \newlength{\numberheight} +% \newlength{\barlength} + \setlength{\numberheight}{18mm} + \setlength{\barlength}{\paperwidth} + \addtolength{\barlength}{-\textwidth} + \addtolength{\barlength}{-\spinemargin} + \renewcommand{\printchapternum}{% + \makebox[0pt][l]{% + \hspace{.8em}% + \resizebox{!}{\numberheight}{\chapnumfont \thechapter}% + \hspace{.8em}% + \rule{\barlength}{\numberheight} + } + } + \makeoddfoot{plain}{}{}{\thepage} +} +\makeatother + +%%\chapterstyle{veelo} + + +\MakeShortVerb{\|} +% \DeleteShortVerb{\|} + + +%%% need more space for ToC page numbers +\setpnumwidth{2.55em} +\setrmarg{3.55em} + +%%% need more space for ToC section numbers +\cftsetindents{section}{1.5em}{3.0em} +\cftsetindents{subsection}{4.5em}{3.9em} +\cftsetindents{subsubsection}{8.4em}{4.8em} +\cftsetindents{paragraph}{10.7em}{5.7em} +\cftsetindents{subparagraph}{12.7em}{6.7em} + +%%% need more space for LoF numbers +\cftsetindents{figure}{0em}{3.0em} + +%%% and do the same for the LoT +\cftsetindents{table}{0em}{3.0em} + + +%%% set up the page layout +\settrimmedsize{11in}{210mm}{*} +\setlength{\trimtop}{0pt} +\setlength{\trimedge}{\stockwidth} +\addtolength{\trimedge}{-\paperwidth} +\settypeblocksize{7.75in}{33pc}{*} +\setulmargins{4cm}{*}{*} +\setlrmargins{1.25in}{*}{*} +\setmarginnotes{17pt}{51pt}{\onelineskip} +\setheadfoot{\onelineskip}{2\onelineskip} +\setheaderspaces{*}{2\onelineskip}{*} +\checkandfixthelayout + + +\bibliographystyle{alpha} + +\newcommand{\prtoc}{ToC} % print ToC +\newcommand{\prlof}{LoF} +\newcommand{\prlot}{LoT} +\newcommand{\ixtoc}{\index{ToC}} % index ToC +\newcommand{\ixlof}{\index{LoF}} +\newcommand{\ixlot}{\index{LoT}} +\newcommand{\toc}{\prtoc\ixtoc} % print & index ToC +\newcommand{\lof}{\prlof\index{LoF}} +\newcommand{\lot}{\prlot\index{LoT}} + +\newcommand{\noidxnum}[1]{} + +\newcommand{\Note}{\textbf{NOTE:}} + +%%% subfigures +\newsubfloat{figure} +\tightlists + +%% end preamble +\typeout{The end of the preamble, begin document is next} +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\begin{document} +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +%% list subfigures +\setcounter{lofdepth}{2} + +\index{counter|noidxnum} +\index{file|noidxnum} +\index{environment|noidxnum} +\index{length|noidxnum} +\index{package|noidxnum} +\index{option|noidxnum} + +\index{pagestyle|noidxnum} +\index{chapterstyle|noidxnum} + +\begin{comment} +\index{table of contents|see{ToC}} +\index{list!of figures|see{LoF}} +\index{figure!list of|see{LoF}} +\index{list!of tables|see{LoT}} +\index{table!list of|see{LoT}} +\index{marginal note|see{marginalia}} +\index{footnote!in title|see{thanks}} +\index{counter|noidxnum} +\index{length|noidxnum} +\index{list|noidxnum} +\index{illustration|seealso{float, figure}} +\index{figure|seealso{float}} +\index{table|seealso{float}} +\index{chapter!style|see{chapterstyle}} +\index{chapter!heading|see{heading}} +\index{page!style|see{pagestyle}} +\index{part!heading|see{heading}} +\index{subfloat|noidxnum} +\end{comment} + +%%% ToC down to subsections +\settocdepth{subsection} +\frontmatter +\pagestyle{empty} + + +% ToC, etc +\pagenumbering{roman} +%%\pagestyle{headings} +\pagestyle{ruled} +\chapterstyle{demo} +%%\chapterstyle{veelo} + +% change sections and subsections +\setsecheadstyle{\bfseries\raggedright} +\setsubsecheadstyle{\scshape\raggedright} +\setsubsubsecheadstyle{\itshape\raggedright} + + +%% Short contents and Different ToC style +\renewcommand{\contentsname}{Short contents} +\let\oldchangetocdepth\changetocdepth +\renewcommand{\changetocdepth}[1]{} +\setcounter{tocdepth}{0} % chapters +\renewcommand{\cftchapterfont}{\hfill\sffamily} +\renewcommand{\cftchapterleader}{ \textperiodcentered\space} +\renewcommand{\cftchapterafterpnum}{\cftparfillskip} +\setpnumwidth{0pt} +\setrmarg{0.3\textwidth} +\tableofcontents +\clearpage + +%%% have subsections as a paragraph in the ToC +\makeatletter +\let\oldnumberline\numberline +\renewcommand{\cftsubsectionfont}{\itshape} +\renewcommand{\cftsubsectionpagefont}{\itshape} +\renewcommand{\l@subsection}[2]{\relax + \def\numberline##1{\textit{##1}~}% + \leftskip=\cftsubsectionindent + \rightskip=\@tocrmarg +% \advance\rightskip \z@ plus \hsize % uncomment this for raggedright +% \advance\rightskip \z@ plus 2em % uncomment this for semi-raggedright + \parfillskip=\fill + \ifhmode ,\ \else\noindent\fi + \ignorespaces {\cftsubsectionfont #1}~{\cftsubsectionpagefont #2}%\ignorespaces + \let\numberline\oldnumberline\ignorespaces +} +\AtEndDocument{\addtocontents{toc}{\par}} +\makeatother + + + +%% Default contents +\renewcommand{\contentsname}{Contents} +\let\changetocdepth\oldchangetocdepth +\renewcommand{\cftchapterfont}{\normalfont\sffamily} +\renewcommand{\cftchapterleader}{\sffamily\cftdotfill{\cftchapterdotsep}} +\renewcommand{\cftchapterafterpnum}{} +\makeatletter +\renewcommand{\cftchapterbreak}{\par\addpenalty{-\@highpenalty}} +\makeatother +\setpnumwidth{2.55em} +\setrmarg{3.55em} +\setcounter{tocdepth}{2} +\tableofcontents +%\clearpage +%\listoffigures +%\clearpage +%\listoftables + + +\cleardoublepage +\pagenumbering{arabic} +\mainmatter + + + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\DeleteShortVerb{\|} +\MakeShortVerb{\=} +\input{tabmanbody} %% rows & columns +\DeleteShortVerb{\=} +\MakeShortVerb{\|} +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + + +\chapterstyle{veelo} +\chapter{Miscellaneous} \label{chap:misc} + +\section{Chapter style} + + Bastiaan Veelo\footnote{\texttt{Bastiaan.N.Veelo@immtek.ntnu.no}} +posted the code for a new chapter style to \pictt{} on 2003/07/22 under the +title \textit{[memoir] [contrib] New chapter style}. His code, which +I have slightly modified and changed the name to \cstyle{veelo}, +is below. I have also exercised editorial privilege on his comments. + +\begin{quote} + I thought I'd share a new chapter style to be used with the memoir class + The style is tailored for documents that are to be trimmed to a smaller + width. When the bound document is bent, black tabs will appear on the + fore side at the places where new chapters start as a navigational aid. + We are scaling the chapter number, which most DVI viewers + will not display accurately. \\[0.5\onelineskip] +Bastiaan. +\end{quote} + +\begin{lcode} +\makeatletter +\newlength{\numberheight} +\newlength{\barlength} +\makechapterstyle{veelo}{% + \setlength{\beforechapskip}{40pt} + \setlength{\midchapskip}{25pt} + \setlength{\afterchapskip}{40pt} + \renewcommand{\chapnamefont}{\normalfont\LARGE\flushright} + \renewcommand{\chapnumfont}{\normalfont\HUGE} + \renewcommand{\chaptitlefont}{\normalfont\HUGE\bfseries\flushright} + \renewcommand{\printchaptername}{% + \chapnamefont\MakeUppercase{\@chapapp}} + \renewcommand{\chapternamenum}{} +% \newlength{\numberheight} +% \newlength{\barlength} + \setlength{\numberheight}{18mm} + \setlength{\barlength}{\paperwidth} + \addtolength{\barlength}{-\textwidth} + \addtolength{\barlength}{-\spinemargin} + \renewcommand{\printchapternum}{% + \makebox[0pt][l]{% + \hspace{.8em}% + \resizebox{!}{\numberheight}{\chapnumfont \thechapter}% + \hspace{.8em}% + \rule{\barlength}{\numberheight} + } + } + \makeoddfoot{plain}{}{}{\thepage} +} +\makeatother +\end{lcode} + + The style requires the \Lpack{graphicx} package because of the +\cmd{\resizebox} macro. I have removed the two \cmd{\newlength} macros to +outside the \cmd{\makechapterstyle} code just in case the style is called more +than once in a document (otherwise there will be `command already defined' +complaints). + + As a demonstration, this chapter uses the \cstyle{veelo} chapterstyle. +The style works best for chapters that start on recto pages. + + +\section{Cross referencing} \label{sec:xref} + +%This is section \currenttitle. + + The class provides the normal \cmd{\label} and \cmd{\ref} macros +for numeric cross-referencing. For example, the following code and typeset +result +\begin{lcode} +Chapter~\ref{chap:mempack} starts on page~\pageref{chap:mempack}. +\end{lcode} +Chapter~\ref{chap:mempack} starts on page~\pageref{chap:mempack}. + + + It can be useful to refer to parts of a document by name rather than +number, as in +\begin{lcode} +The chapter \textit{\titleref{chap:mempack}} describes \ldots +\end{lcode} +The chapter \textit{\titleref{chap:mempack}} describes \ldots + + There are two packages, \Lpack{nameref} and \Lpack{titleref}, + that let you refer to things by name instead of number. + + Name references were added to the class as a consequence of adding +a second optional argument to the sectioning commands. I found +that this broke the \Lpack{nameref} package, and hence the +\Lpack{hyperref} package as well, so they had to be fixed. The change +also broke Donald Arseneau's \Lpack{titleref} package, and it turned out +that \Lpack{nameref} also clobbered \Lpack{titleref}. The class also +provides titles, like \cmd{\poemtitle}, that are not recognised by +either of the packages. From my viewpoint the most efficient +thing to do was to enable the class itself to provide name +referencing. + +\begin{syntax} +\cmd{\label}\marg{key} \cmd{\ref}\marg{key} \cmd{\pageref}\marg{key} \\ +\cmd{\titleref}\marg{key} \\ +\cmd{\headnamereftrue} \cmd{\headnamereffalse} \\ +\end{syntax} +The macro \cmd{\titleref} is an addition to the usual set of cross referencing +commands. Instead of typesetting a number it typesets the title associated +with the labelled number. This is, of course, only useful if there is an +associated title, such as from a \cmd{\caption} or \cmd{\section} command. +As a bad example: +\begin{lcode} +Labelling for \verb?\titleref? may be applied to: +\begin{enumerate} +\item Chapters, sections, etc. \label{sec:xref:item1} +... +\item Items in numbered lists, etc. \ldots \label{sec:xref:item3} +\end{enumerate} +Item \ref{sec:xref:item2} in section~\ref{sec:xref} mentions captions +while item \titleref{sec:xref:item3} in the same section +\textit{\titleref{sec:xref}} lists other things. +\end{lcode} +Labelling for \verb?\titleref? may be applied to: +\begin{enumerate} +\item Chapters, sections, etc. \label{sec:xref:item1} +\item Captions \label{sec:xref:item2} +\item Legends +\item Poem titles +\item Items in numbered lists, etc. \label{sec:xref:item3} +\end{enumerate} +Item \ref{sec:xref:item2} in section~\ref{sec:xref} mentions captions +while item \titleref{sec:xref:item3} in the same section +\textit{\titleref{sec:xref}} lists other things. + + + As the above example shows, you have to be a little careful in using +\cmd{\titleref}. +Generally speaking, \cmd{\titleref}\marg{key} produces the last named +thing before the \cmd{\label} that defines the \meta{key}. + + Chapters, and the lower level sectional divisions, may have three +different title texts --- the main title, the title in the ToC, and a third +in the page header. By default (\cmd{\headnamereffalse}) the ToC title +is produced by \cmd{\titleref}. Following the declaration +\cmd{\headnamereftrue} the text intended for page headers will be produced. + +\Note{} Specifically with the \Lclass{memoir} class, +do not put a \cmd{\label} command inside an +argument to a \cmd{\chapter} or \cmd{\section} or \cmd{\caption}, etc., +command. Most likely it will either be ignored or referencing it will +produce incorrect values. This restriction does not apply to the standard +classes, but in any case I think it is good practice not to embed any +\cmd{\label} commands. + +\begin{syntax} +\cmd{\currenttitle} \\ +\end{syntax} + If you just want to refer to the current title you can do so with +\cmd{\currenttitle}. This acts as though there had been a label associated +with the title and then \cmd{\titleref} had been used to refer to that label. +For example: +\begin{lcode} +This sentence in the section titled `\currenttitle' is an example of the +use of the command \verb?\currenttitle?. +\end{lcode} +This sentence in the section titled `\currenttitle' is an example of the +use of the command \verb?\currenttitle?. + + +\begin{syntax} +\cmd{\theTitleReference}\marg{num}\marg{text} \\ +\end{syntax} +Both \cmd{\titleref} and \cmd{\currenttitle} use the \cmd{\theTitleReference} +to typeset the title. This is called with two arguments --- +the number, \meta{num}, and the text, \meta{text}, of the title. The +default definition is: +\begin{lcode} +\newcommand{\theTitleReference}[2]{#2} +\end{lcode} +so that only the \meta{text} argument is printed. You could, for example, +change the definition to +\begin{lcode} +\renewcommand{\theTitleReference}[2]{#1\space \textit{#2}} +\end{lcode} +to print the number followed by the title in italics. If you do this, only use +\cmd{\titleref} for numbered titles, as a printed number for an +unnumbered title (a) makes no sense, and (b) will in any case be +incorrect. + + The commands \cmd{\titleref}, \cmd{\theTitleReference} and +\cmd{\currenttitle} are direct equivalents of those in the \Lpack{titleref} +package. + +\begin{syntax} +\cmd{\namerefon} \cmd{\namerefoff} \\ +\end{syntax} + Implementing name referencing has had an unfortunate side effect of +turning some arguments into moving ones; the argument to the \cmd{\legend} +command is one example. If you don't need name referencing you can turn +it off by the \cmd{\namerefoff} declaration; the \cmd{\namerefon} +declaration enables name referencing. + +\section{Needing space} + + There are two new macros in addition to the original \cmd{\needspace} +for reserving space at the bottom of a page. The \cmd{\needspace} macro +depends on penalties for deciding what to do which means that the reserved +space is an approximation. However, except for the odd occasion, the +macro gives adequate results. + +\begin{syntax} +\cmd{\Needspace}\marg{length} \\ +\cmd{\Needspace*}\marg{length} \\ +\end{syntax} + Like \cmd{\needspace}, the \cmd{\Needspace} macro checks if there is +\meta{length} space at the bottom of the current page and if there is not +it starts a new page. The command should only be used between paragraphs; +indeed, the first thing it does is to call \cs{par}. The \cmd{\Needspace} +command checks for the actual space left on the page and is more exacting +than \cmd{\needspace}. + + If either \cmd{\needspace} or \cmd{\Needspace} produce a short page it +will be ragged bottom even if \cmd{\flushbottom} is in effect. With +the starred \cmd{\Needspace*} version, short pages will be flush bottom +if \cmd{\flushbottom} is in effect and will be ragged bottom +when \cmd{\raggedbottom} is in effect. + + Generally speaking, use \cmd{\needspace} in preference to \cmd{\Needspace} +unless it gives a bad break or the pages must be flush bottom. + +\section{Minor space adjustment} + + The kernel provides the \cmd{\,} macro for inserting a thin space in both +text and math mode. There are +other space adjustment commands, such as \pixabang{} for negative thin space, and +\cmd{\:} and \cmd{\;} for medium +and thick spaces, which can only be used in math mode. + +\begin{syntax} +\cmd{\thinspace} \cmd{\medspace} \cmd{\:} \pixabang \\ +\end{syntax} +On occasions I have found it useful to be able to tweak spaces in text by some +fixed amount, just as in math mode. The kernel macro \cmd{\thinspace} +specifies a thin space, which is 3/18\,em. +The class \cmd{\medspace} specifies a medium space of 4/18\,em. +As mentioned, the kernel macro \cmd{\:} inserts +a medium space in math mode. The class version can be used in both math and +text mode to insert a medium space. Similarly, the class version of +\pixabang{} +can be used to insert a negative thin space in both text and math mode. + + The math thick space is 5/18\,em. +To specify this amount of space +in text mode you can combine spacing commands as: +\begin{lcode} +\:\:\! +\end{lcode} +which will result in an overall space of 5/18\,em +(from $(4 + 4 - 3)/18$). + +\section{Fractions} + + When typesetting a simple fraction in text there is usually a choice +of two styles, like 3/4 or $\frac{3}{4}$, which do not necessarily look +as though they fit in with their surroundings. These fractions were +typeset via: +\begin{lcode} +... like 3/4 or $\frac{3}{4}$ ... +\end{lcode} + +\begin{syntax} +\cmd{\slashfrac}\marg{top}\marg{bottom} \\ +\cmd{\slashfracstyle}\marg{num} \\ +\end{syntax} +The class provides the \cmd{\slashfrac} command which typesets its +arguments like \slashfrac{3}{4}. Unlike the \cmd{\frac} command which +can only be used in math mode, the \cmd{\slashfrac} command can be +used in text and math modes. + + The \cmd{\slashfrac} macro calls the \cmd{\slashfracstyle} command to +reduce the size of the numbers in the fraction. You can also use +\cmd{\slashfracstyle} by itself. +\begin{lcode} +In summary, fractions can be typeset like 3/4 or $\frac{3}{4}% +or \slashfrac{3}{4} or \slashfracstyle{3/4} because several choices +are provided. +\end{lcode} +In summary, fractions can be typeset like 3/4 or $\frac{3}{4}$ +or \slashfrac{3}{4} or \slashfracstyle{3/4} because several choices +are provided. + +\begin{syntax} +\cmd{\textsuperscript}\marg{super} \\ +\cmd{\textsubscript}\marg{sub} \\ +\end{syntax} +While on the subject of moving numbers up and down, the kernel provides +the \cmd{\textsuperscript} macro for typesetting its argument as though it +is a superscript. The class also provides the \cmd{\textsubscript} macro +for typesetting its argument like a subscript. +\begin{lcode} +You can typeset superscripts like \textsuperscript{3}/4 and +subscripts like 3/\textsubscript{4}, +or both like \textsuperscript{3}/\textsubscript{4}. +\end{lcode} +You can typeset superscripts like \textsuperscript{3}/4 and +subscripts like 3/\textsubscript{4}, +or both like \textsuperscript{3}/\textsubscript{4}. + + +\section{Framed boxes} + + Donald Arseneau's \Lpack{framed} package is currently at or beyond +v0.7 while +the original copy used in the class is from an earlier version. The class +version of the \Lpack{framed} functions has been updated to v0.7. + +\begin{syntax} +\senv{framed} text \eenv{framed} \\ +\senv{shaded} text \eenv{shaded} \\ +\senv{leftbar} text \eenv{leftbar} \\ +\end{syntax} +The \Ie{framed} environment puts the text into an \cmd{\fbox}-like +framed box, the +\Ie{shaded} environment puts the text into a coloured box, and the +\Ie{leftbar} environment draws a vertical line at the left of the text. +In all cases the text and boxes can include page breaks. + +\begin{syntax} +\lnc{\FrameRule} \lnc{\FrameSep} \cmd{\FrameHeightAdjust} \\ +\Itt{shadecolor} \\ +\end{syntax} +The thickness of the rules is the length \lnc{\FrameRule} and the separation +between the text and the box is given by the length \lnc{\FrameSep}. +The height of the frame above the baseline at the top of a page is specified +by the macro \cmd{\FrameHeightAdjust}. The default definitions being: +\begin{lcode} +\setlength{\FrameRule}{\fboxrule} +\setlength{\FrameSep}{3\fboxsep} +\newcommand{\FrameHeightAdjust}{0.6em} +\end{lcode} +The background color in the \Ie{shaded} environment is specified by +\Itt{shadecolor} which you have to specify using the \Lpack{color} +package. For example: +\begin{lcode} +\usepackage{color} +\definecolor{shadecolor}{gray}{0.75} +\end{lcode} + +\begin{syntax} +\cmd{\frameasnormaltrue} \cmd{\frameasnormalfalse} \\ +\end{syntax} +Following the declaration \cmd{\frameasnormaltrue} paragraphing within +the environments will be as specified for the main text. After the declaration +\cmd{\frameasnormalfalse} paragraphing will be as though the environments +were like a \Ie{minipage}. The initial declaration is +\cmd{\frameasnormaltrue}. + + There is one known problem with framing: when framing is used on +a page where the page header is in a smaller type than the body, the +header may be moved slightly up or down. This can be avoided by putting +the font size change in a group, but it seems that a larger font does not need +to be grouped. For example: +\begin{lcode} +\makeoddhead{myheadings}{{\tiny Tiny header}}{}{\LARGE Large header} +\end{lcode} + + You can use the \Lpack{framed} package with the \Lclass{memoir} class, in +which case you will get whatever functionality is provided by the package as +it will override the class' code. + +\section{Captions} + + The \cmd{\captionstyle} macro has been extended so that it is now +possible to separately specify the style for short and long +captions. + +\begin{syntax} +\cmd{\captionstyle}\oarg{short}\marg{normal} \\ +\cmd{\raggedleft} \cmd{\centering} \cmd{\raggedright} \cmd{centerlastline} \\ +\end{syntax} +Caption styles are set according to the \cmd{\captionstyle} declaration. +Unless the optional \meta{short} argument is given all captions are typeset +according to \meta{normal}. If the optional \meta{short} argument +is specififed, captions that are less than one line in length are typeset +according to \meta{short}. + + Permissable values for the arguments include, but are not limited to, +\cmd{\raggedleft}, \cmd{\centering}, \cmd{\raggedright}, and + \cmd{centerlastline}. The class initially specifies +\begin{lcode} +\captionstyle{} +\end{lcode} +which gives the normal block paragraph style. + +\section{Hung paragraphs} + + As noted eleswhere the sectioning commands use the internal +\cmd{\@hangfrom} as part of the formatting of the titles. + +\begin{syntax} +\cmd{\hangfrom}\marg{text} \\ +\end{syntax} + +\hangfrom{Simple hung paragraphs }(like this one) can be specified +using the \cmd{\hangfrom} macro. The macro puts \meta{text} in a box +and then makes a hanging paragraph of the following material. This +paragraph commenced with \\ +\verb?\hangfrom{Simple hung paragraphs }(like ...? \\ +and you are now reading the result. + +\chapterstyle{demo} +\chapter{Memoir and packages} \label{chap:mempack} + + The \Lclass{memoir} class does some things differently from the standard +classes. Some packages that might be used with \Lclass{memoir} rely on +the standard methods, and change them to suit their own purposes. Some such +changes may not work with \Lclass{memoir} and the package may not recognize +that it is being used with \Lclass{memoir} and not with a standard class. + + From my viewpoint, the ideal solution is for the packages to be changed +so that they cooperate with \Lclass{memoir}. However, until that happy +day arrives I have provided the \Lpack{memhfixc} package that attempts to +make these packages cooperate with the class. + + Currently, if you use either the \Lpack{hyperref} or the \Lpack{nameref} +package you will also need to use the \Lpack{memhfixc} package. +The ordering of the \Lpack{memhfixc} and other packages can be important: +\begin{itemize} +\item \Lpack{memhfixc} must be used \emph{after} the \Lpack{hyperref} package. +\item The ordering of \Lpack{memhfixc} and \Lpack{nameref} is immaterial. +\end{itemize} + + There is a basic incompatability between the \Lpack{hyperref} package +and sequential footnotes --- the \cmd{\multfootsep} macro is essentially +ignored. If that is important to you and you don't mind not having +hyperreferences to footnotes, call \Lpack{hyperref} like: +\begin{lcode} +\usepackage[hyperfootnotes=false, ...]{hyperref} +\end{lcode} +A similar \Lpack{hyperref} incompatibily also occurs with at least +the \Lpack{footmisc} package. + + Thinking of the \Lpack{footmisc} package, for some of its options it +changes the kernel output routine. The class itself changes the output routine +in order to add sidebars. Packages, like the version of \Lpack{footmisc} +current at the date of writing (2003/04/28), which change the output +routine without specifically catering for the \Lclass{memoir} class +are likely to cause problems. As an alternative to the \Lpack{footmisc} +package, the \Lpack{ledmac} package understands \Lclass{memoir} and provides +further multiple classes of footnotes. + + + +% back end +\backmatter +\clearpage +%\pagestyle{ruled} +%\chapterstyle{section} + + + + \bibliographystyle{alpha} + \begin{thebibliography}{WWW99} + \bibitem[ABH90]{bk:Impatient} + Paul W.~Abrahams, Karl Berry and Kathryn A.~Hargreaves. + \newblock \emph{TeX{} for the Impatient}. + \newblock + Addison-Wesley, Reading, Massachusetts, 1990. + \newblock (Available from CTAN in \texttt{info/impatient}) + \bibitem[Car94]{DELARRAY} + David Carlisle. + \newblock \emph{The delarray package}. + \newblock March 1994. + \newblock (Available from CTAN in + \texttt{macros/latex/required/tools}) + \bibitem[Car98]{LONGTABLE} + David Carlisle. + \newblock \emph{The longtable package}. + \newblock May 1998. + \newblock (Available from CTAN in + \texttt{macros/latex/required/tools}) + \bibitem[Car99]{TABULARX} + David Carlisle. + \newblock \emph{The tabularx package}. + \newblock January 1999. + \newblock (Available from CTAN in + \texttt{macros/latex/required/tools}) + \bibitem[Car01]{DCOLUMN} + David Carlisle. + \newblock \emph{The dcolumn package}. + \newblock May 2001. + \newblock (Available from CTAN in + \texttt{macros/latex/required/tools}) + \bibitem[Fea03]{BOOKTABS} + Simon Fear. + \newblock \emph{Publication quality tables in \ltx}. + \newblock March 2003. + \newblock (Available from CTAN in + \texttt{macros/latex/contrib/booktabs}) + \bibitem[GMS94]{bk:GMS94} + M.~Goossens, F.~Mittelbach and A.~Samarin. + \newblock \emph{The \ltx{} Companion}. + \newblock + Addison-Wesley, Reading, Massachusetts, 1994. + \bibitem[Knu84]{bk:knuth} + Donald E. Knuth. + \newblock \emph{The \TeX{}book}. + \newblock + Addison-Wesley, Reading, Massachusetts, 1984. + \bibitem[Lam94]{bk:lamport} + Leslie Lamport. + \newblock \emph{\ltx\ --- A Document Preparation System}. + \newblock + Addison-Wesley, Reading, Massachusetts, 1994. + \bibitem[MC98]{ARRAY} + Frank Mittelbach and David Carlisle. + \newblock \emph{A new implementation of LaTeX's tabular and array + environment}. + \newblock May 1998. + \newblock (Available from CTAN in + \texttt{macros/latex/required/tools}) + \bibitem[Wil00]{XTAB} + Peter Wilson. + \newblock \emph{The xtab package}. + \newblock April 2000. + \newblock (Available from CTAN in + \texttt{macros/latex/contrib/xtab}) + \end{thebibliography} + + +\clearpage +\pagestyle{index} +%\renewcommand{\chaptermark}[1]{} +\renewcommand{\preindexhook}{% +The first page number is usually, but not always, the primary reference to +the indexed topic.\vskip\onelineskip} +\indexintoc +\printindex + + +\end{document} + + + + + + |