summaryrefslogtreecommitdiffstats
path: root/contrib/mom/momdoc/tables-of-contents.html
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-15 19:44:05 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-15 19:44:05 +0000
commitd318611dd6f23fcfedd50e9b9e24620b102ba96a (patch)
tree8b9eef82ca40fdd5a8deeabf07572074c236095d /contrib/mom/momdoc/tables-of-contents.html
parentInitial commit. (diff)
downloadgroff-upstream.tar.xz
groff-upstream.zip
Adding upstream version 1.23.0.upstream/1.23.0upstream
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'contrib/mom/momdoc/tables-of-contents.html')
-rw-r--r--contrib/mom/momdoc/tables-of-contents.html1224
1 files changed, 1224 insertions, 0 deletions
diff --git a/contrib/mom/momdoc/tables-of-contents.html b/contrib/mom/momdoc/tables-of-contents.html
new file mode 100644
index 0000000..1f9affb
--- /dev/null
+++ b/contrib/mom/momdoc/tables-of-contents.html
@@ -0,0 +1,1224 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+This file is part of groff, the GNU roff type-setting system.
+
+Copyright (C) 2004-2020 Free Software Foundation, Inc.
+Written by Peter Schaffter (peter@schaffter.ca).
+
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.3 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
+Texts.
+
+A copy of the Free Documentation License is included as a file called
+FDL in the main directory of the groff source package.
+-->
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+
+<head>
+ <meta http-equiv="content-type" content="text/html;charset=utf-8"/>
+ <title>Mom -- Document processing, tables of contents</title>
+ <link rel="stylesheet" type="text/css" href="stylesheet.css" />
+</head>
+
+<body style="background-color: #f5faff;">
+
+<!-- ==================================================================== -->
+
+<div id="top" class="page">
+
+<!-- Navigation links -->
+<table style="width: 100%;">
+<tr>
+ <td><a href="toc.html">Back to Table of Contents</a></td>
+ <td style="text-align: right;"><a href="refer.html#top">Next: Bibliographies and references</a></td>
+</tr>
+</table>
+
+<h1 class="docs">Tables of contents</h1>
+
+<div style="width: 68%; margin: auto;">
+<ul class="no-enumerator">
+ <li><a href="#toc-intro">Introduction to tables of contents</a></li>
+ <li><a href="#toc-appearance">Tables of contents appearance and behaviour</a></li>
+ <li><a href="#pdf-output">PDF output</a>
+ <ul style="margin-left: -.5em; list-style-type: disc;">
+ <li><a href="#positioning">Positioning the table of contents</a></li>
+ <li><a href="#auto-relocate-toc">AUTO_RELOCATE_TOC</a></li>
+ <li><a href="#psselect"><kbd>psselect</kbd></a></li>
+ </ul></li>
+ <li><a href="#toc">The TOC macro</a>
+ <ul style="margin-left: -.5em; list-style-type: disc;">
+ <li><a href="#toc-heading">TOC_HEADING</a></li>
+ </ul></li>
+ <li><a href="#toc-control-top">Control macros for tables of contents</a>
+ <ul style="margin-left: -.5em; list-style-type: disc;">
+ <li><a href="#index-toc-control">Table of contents control macros</a></li>
+ </ul></li>
+</ul>
+</div>
+
+<div class="rule-medium"><hr/></div>
+
+<h2 id="toc-intro" class="docs">Introduction to tables of contents</h2>
+
+<p>
+Want a table of contents for your document? Easy. Just enter
+<br/>
+<span class="pre-in-pp">
+ .TOC
+</span>
+as the very last macro of your input file. Mom will have picked
+up all document titles (in
+<a href="rectoverso.html#collate">collated</a>
+documents) and headings, as well as the endnotes section and
+bibliography, if they exist, and assigned them the appropriate page
+number. Talk about a no-brainer!
+</p>
+
+<p>
+That said, tables of contents have even more control macros than
+endnotes. As always, the reason for so many control macros is so
+that if you want to change just about any aspect of the table of
+contents&#8217; typographic appearance, you can.
+</p>
+
+<h2 id="toc-appearance" class="docs">Tables of contents appearance and behaviour</h2>
+
+<p>
+When you output a table of contents (with
+<kbd><a href="#toc">.TOC</a></kbd>),
+mom finishes processing the last page of your document then breaks
+to a new page for printing the table of contents.
+</p>
+
+<p>
+Mom follows standard typesetting conventions for tables of contents.
+To this end, if
+<a href="headfootpage.html#headers">HEADERS</a>
+are enabled for the document, the first page of the table of
+contents has no page header, but does have a first page number
+(roman numeral), always &#8220;i&#8221;, in the bottom margin. If
+<a href="headfootpage.html#footers">FOOTERS</a>
+are enabled for the document, the first page has neither a footer,
+nor a page number in the top margin. (If you absolutely must have
+a page footer on the first page of the table of contents, simply
+invoke
+<a href="headfootpage.html#footer-on-first-page"><kbd>.FOOTER_ON_FIRST_PAGE</kbd></a>
+immediately before <kbd>.TOC</kbd>.) Subsequent table of contents
+pages have both page headers or footers and a page number.
+</p>
+
+<p>
+Entries in a table of contents are hierarchically indented, as you
+would expect, and if headings are numbered in the body of the document,
+you can instruct mom to number them in the table of contents as
+well (see
+<a href="#toc-entry-numbers">TOC_ENTRY_NUMBERS</a>).
+</p>
+
+<p>
+Tables of contents are never set in columns, regardless of whether
+the rest of the document is. Lastly, if
+<a href="rectoverso.html#recto-verso">recto/verso</a>
+printing is enabled, the table of contents respects it. This
+sometimes leads to tables of contents that begin with the wrong
+margins, but the margins can be corrected either by outputting a
+<a href="headfootpage.html#blank-pages">BLANKPAGE</a>
+or by using the control macro
+<a href="#toc-rv-switch">TOC_RV_SWITCH</a>.
+</p>
+
+<p>
+The overall table of contents
+<a href="definitions.html#family">family</a>,
+<a href="definitions.html#ps">point size</a>
+and
+<a href="definitions.html#leading">lead</a>
+can be altered with
+<a href="definitions.html#controlmacro">control macros</a>,
+as can the family,
+<a href="definitions.html#font">font</a>,
+point size and indent of each level of entry. Furthermore, the page
+numbering style can be changed, as can the amount of visual space
+reserved for entry page numbers.
+</p>
+
+<h2 id="pdf-output" class="docs">PDF output</h2>
+
+<p>
+When files containing a table of contents are processed with
+<a href="using.html#pdfmom" style="font-weight: bold">pdfmom</a>,
+entries in the table of contents are clickable links when the
+document is viewed at the screen. The colour of the links is the
+last <kbd>.PDF_LINK_COLOR</kbd> in effect, so if you wish another
+colour, it should be set just before issuing <kbd>.TOC</kbd>.
+</p>
+
+<p>
+When preparing files for printing, coloured links in both the table
+of contents and elsewhere in the document may not be desirable.
+You can disable the colour by passing
+<a href="using.html#pdfmom" style="font-weight: bold">pdfmom</a>
+the <kbd>-c</kbd> option, like this: <br/>
+<span class="pre-in-pp">
+ pdfmom -c doc.mom &gt; doc.pdf
+</span>
+</p>
+
+<h3 id="positioning" class="docs">Positioning the Table of Contents</h3>
+
+<p>
+Because a table of contents can&#8217;t be generated until the
+end of a document (hence the last macro in the file), it is also
+the last page of the document. While this is desirable for some
+language conventions&mdash;French, for example&mdash;it is not
+desirable for others.
+</p>
+
+<h4 id="auto-relocate-toc" class="docs">Automatic PDF relocation of the Table of Contents</h4>
+
+<p>
+When
+<a href="using.html#pdfmom" style="font-weight: bold">pdfmom</a>
+is used to process files with a table of contents, the macro
+<kbd>.AUTO_RELOCATE_TOC</kbd> can be used to reposition the table
+of contents to the top of the output document, with the presence
+of a cover and/or title page sensibly taken into account. Full
+AUTO_RELOCATE_TOC usage is described in the manual,
+<a href="https://www.schaffter.ca/mom/pdf/mom-pdf.pdf"><span class="book-title">Producing PDFs with groff and mom</span></a>.
+</p>
+
+<p>
+In order to take advantage of automatic table of contents
+repositioning, you must use
+<a href="using.html#pdfmom" style="font-weight: bold">pdfmom</a>
+with groff&#8217;s native PDF driver (i.e. without the
+<strong>-Tps</strong> flag). Files that need to be processed with
+the <strong>-Tps</strong> flag require you to reposition the table
+of contents yourself with <strong>psselect</strong>, described
+below.
+</p>
+
+<div class="box-tip">
+<p class="tip">
+<span class="note">Note:</span>
+<kbd>AUTO_RELOCATE_TOC</kbd> must come before
+<a href="docprocessing.html#start">START</a>.
+</p>
+</div>
+
+<h4 id="psselect" class="docs"><span style="text-transform: none">Using psselect to relocate the Table of Contents in PostScript documents</span></h4>
+
+<p>
+To change the location of the table of contents in files
+processed with <kbd>pdfmom -Tps</kbd>, you have two choices:
+rearrange the pages by hand (okay for one or two hard copies),
+or use the <strong>psselect</strong> programme provided by the
+<strong>psutils</strong> suite of tools (which you may have to
+install as a package from your distribution if it is not already on
+your system).
+</p>
+
+<p>
+The procedure for using <strong>psselect</strong> to put the
+table of contents near the beginning of a document begins by
+you determining how many pages it contains. You can do this by
+previewing the document with the document viewer of your choice
+(gv, Okular, Evince, etc).
+</p>
+
+<p>
+Once you know the number of pages in the table of contents, you use
+<strong>psselect</strong> to place them where you want.
+</p>
+
+<p>
+Say, for example, the table of contents runs to just one page. The
+command to place a one-page table of contents at the start of a
+document is:
+<br/>
+<span class="pre-in-pp">
+ psselect -p _1,1-_2
+</span>
+The <kbd>-p</kbd> option instructs <kbd>psselect</kbd> that what
+follows is a comma-separated list of the order in which you want
+pages of a document rearranged. The underscore character means
+"counting backwards from the end of the document". Thus, the above
+says: "Put the last page first (i.e. the table of contents), followed
+by all pages from the original first page up to the second to last
+(i.e. the last page before the table of contents)."
+</p>
+
+<p>
+If your table of contents runs to two pages, the option to
+<kbd>psselect</kbd> would look like this:
+<br/>
+<span class="pre-in-pp">
+ psselect -p _1-_2,1-_3
+</span>
+If your table of contents runs to two pages and you have a cover
+page, the command would look like this:
+<br/>
+<span class="pre-in-pp">
+ psselect -p 1,_1-_2,2-_3
+</span>
+</p>
+
+<div class="box-tip">
+<p class="tip">
+<span class="note">Note:</span>
+<kbd>psselect</kbd> outputs to stdout, so you have to redirect the
+output to a new file.
+<br/>
+<span class="pre-in-pp" style="margin-bottom: -1em">
+ psselect -p &lt;page list&gt; &lt;file&gt;.ps &gt; &lt;new-file&gt;.ps
+</span>
+</p>
+</div>
+
+<!-- -TOC- -->
+
+<div class="macro-id-overline">
+<h3 id="toc" class="macro-id">The TOC macro</h3>
+</div>
+
+<div class="box-macro-args">
+Macro: <b>TOC</b> <kbd class="macro-args">[ INCLUDE_TITLE ]</kbd>
+</div>
+
+<p>
+If you want a table of contents, just place <kbd>.TOC</kbd> at the
+very end of your document. Mom takes care of the rest.
+</p>
+
+<p>
+The optional argument, <kbd>INCLUDE_TITLE</kbd>, is needed only
+if your document is standalone, i.e. is not collated, for example
+an essay. By default, mom does not include the title (and page
+number) of standalone documents in the Table of Contents since it
+is largely redundant. If you would like her to include the title,
+invoke <kbd>.TOC</kbd> with <kbd>INCLUDE_TITLE</kbd>.
+</p>
+
+<div class="box-tip">
+<p class="tip">
+<span class="note">Note:</span>
+If the last line of text in a document, before <kbd>.TOC</kbd>,
+falls too close to the bottom margin, or if the line is followed
+by a macro likely to cause a linebreak (e.g. <kbd>.LIST OFF</kbd> or
+<kbd>.IQ</kbd>), mom may output a superfluous blank page before the
+Table of Contents.
+</p>
+
+<p class="tip-bottom" style="margin-top: -1em">
+In order to avoid this, insert
+<a href="typesetting.html#el"><kbd>.EL</kbd></a>
+after the last line of text, before <kbd>.TOC</kbd> and/or any
+concluding macros. For example,
+<br/>
+<span class="pre-in-pp">
+ some concluding text.
+ .EL
+ .TOC
+</span>
+or
+<br/>
+<span class="pre-in-pp">
+ some concluding text.
+ .EL
+ .LIST OFF
+ .TOC
+</span>
+</p>
+</div>
+
+<div class="macro-id-overline">
+<h3 class="macro-id">TOC heading</h3>
+</div>
+
+<div id="toc-heading" class="box-macro-args">
+Macro: <b>TOC_HEADING</b> <kbd class="macro-args">&quot;&lt;single line TOC heading&gt;&quot;</kbd>
+</div>
+<p class="requires">
+&bull;&nbsp;Argument must be enclosed in double-quotes
+</p>
+
+<p>
+You may sometimes want to insert a line of text into the table of
+contents without it referring to a page number, for example to
+identify a &#8220;Part I&#8221; and a &#8220;Part II&#8221;.
+</p>
+
+<p>
+Placed before any instance of the
+<a href="docprocessing.html#start">START</a>
+macro, TOC_HEADING inserts its text into the table of contents
+before the next section title or heading. A modest amount of
+whitespace is introduced above and beneath to distinguish it easily
+from table of contents entries.
+</p>
+
+<p>
+The appearance of the heading may be controlled with
+the macro
+<a href="docprocessing.html#toc-heading-style">TOC_HEADING_STYLE</a>.
+</p>
+
+
+<div class="rule-short"><hr/></div>
+
+<h2 id="toc-control-top" class="macro-group">Control macros for tables of contents</h2>
+
+<p>
+Aside from allowing you to set the style of table of contents
+entries on a per-level basis, the control macros let you design
+the table of contents as if they were a complete document unto
+themselves (overall family, headers/footers, pagination, etc).
+</p>
+
+<div class="defaults-container" style="background-color: #ded4bd; border: none;">
+<h3 id="index-toc-control" class="docs defaults">Table of contents control macros</h3>
+
+<ol style="margin-top: .5em; padding-bottom: .5em;">
+ <li><a href="#toc-general">General table of contents style control</a>
+ <ul style="margin-left: -.5em;">
+ <li><a href="#toc-family">TOC_FAMILY</a> &ndash; base family for tables of contents</li>
+ <li><a href="#toc-pt-size">TOC_PT_SIZE</a> &ndash; base point size for tables of contents</li>
+ <li><a href="#toc-lead">TOC_LEAD</a> &ndash; leading of tables of contents</li>
+ </ul></li>
+ <li><a href="#toc-pagenumbering">Page numbering</a>
+ <ul style="margin-left: -.5em;">
+ <li><a href="#paginate-toc">PAGINATE_TOC</a> &ndash; turn table of contents pagination on or off</li>
+ <li><a href="#toc-pagenum-style">TOC_PAGENUM_STYLE</a> &ndash; table of contents page numbering style</li>
+ </ul></li>
+ <li><a href="#toc-header">Header string (e.g. &#8220;Contents&#8221;) and style</a>
+ <ul style="margin-left: -.5em;">
+ <li><a href="#toc-header-string">Changing the header string</a></li>
+ <li><a href="#toc-header-v-pos">Header string vertical placement</a></li>
+ <li><a href="#toc-header-style">Header string control macros and defaults</a></li>
+ </ul></li>
+ <li><a href="#toc-style">Entries and reference page number style</a>
+ <ul style="margin-left: -.5em;">
+ <li><a href="#toc-pn">Reference page numbers style control</a></li>
+ <li><a href="#toc-title-style">Title entry style control</a></li>
+ <li><a href="#toc-entry-style">Heading entry style control</a></li>
+ <li>Numbering table of contents items
+ <ul style="margin-left: -.75em; list-style: disc">
+ <li><a href="#toc-prefix-ch-number">Prefix chapter/section numbers</a>
+ <ul style="margin-left: -.75em;">
+ <li><a href="#toc-pad-ch-numbers">Pad chapter/section numbers</a></li>
+ </ul></li>
+ <li><a href="#toc-entry-numbers">Numbering heading entries</a></li>
+ </ul></li>
+ </ul></li>
+ <li><a href="#toc-additional">Additional table of contents control macros</a>
+ <ul style="margin-left: -.5em;">
+ <li><a href="#toc-appends-author">Append author(s) to table of contents title entries</a></li>
+ <li><a href="#toc-title-entry">Alter the wording of a table of contents title entry</a></li>
+ <li><a href="#space-toc-items">Space table of contents entries pleasingly</a></li>
+ <li><a href="#toc-padding">Establish the number of placeholders to leave for page reference numbers</a></li>
+ <li><a href="#toc-rv-switch">Switch tables of contents page margins</a></li>
+ </ul></li>
+ <li><a href="#toc-more">I still need more!</a></li>
+</ol>
+</div>
+
+<h4 id="toc-general" class="docs" style="margin-top: -1.5em; margin-bottom: .5em;">1. General tables of contents style control</h4>
+
+<!-- -TOC_FAMILY- -->
+
+<div id="toc-family" class="box-macro-args">
+Macro: <b>TOC_FAMILY</b> <kbd class="macro-args">&lt;family&gt;</kbd>
+</div>
+
+<p>
+TOC_FAMILY establishes the default family for every page element in
+a table of contents, including the table of contents&#8217; header
+string (by default, &#8220;Contents&#8221;) and the page
+number in the top or bottom margin. The default is the prevailing
+document family.
+</p>
+
+<p>
+All page elements in the table of contents also have their own
+_FAMILY control macros, which can be used on a case-by-case basis to
+override the default family set with TOC_FAMILY.
+</p>
+
+<!-- -TOC_PT_SIZE- -->
+
+<div id="toc-pt-size" class="box-macro-args">
+Macro: <b>TOC_PT_SIZE</b> <kbd class="macro-args">&lt;base type size of the toc&gt;</kbd>
+</div>
+
+<p class="requires">
+&bull;&nbsp;Does not require a <a href="definitions.html#unitofmeasure">unit of measure</a>; points is assumed
+</p>
+
+<p>
+Unlike most other control macros that deal with size of document
+elements, TOC_PT_SIZE takes as its argument an absolute value,
+relative to nothing. (Compare this with the
+<a href="docelement.html#point-size">_SIZE</a>
+control macros.) The argument represents the base point size
+of tables of contents from which the size of all other table of
+contents elements are calculated.
+</p>
+
+<p>
+The default for
+<a href="docprocessing.html#printstyle">PRINTSTYLE <kbd>TYPESET</kbd></a>
+is 12.5 points (the same default size used in the body of the
+document).
+</p>
+
+<!-- -TOC_LEAD- -->
+
+<div id="toc-lead" class="box-macro-args">
+Macro: <b>TOC_LEAD</b> <kbd class="macro-args">&lt;leading of the toc&gt; [ ADJUST ]</kbd>
+</div>
+
+<p class="requires">
+&bull;&nbsp;Does not require a <a href="definitions.html#unitofmeasure">unit of measure</a>; points is assumed
+</p>
+
+<p>
+Unlike most other control macros that deal with leading of document
+elements, TOC_LEAD takes as its argument an absolute value, relative
+to nothing. Therefore, the argument represents the
+<a href="definitions.html#leading">leading</a>
+of tables of contents in
+<a href="definitions.html#picaspoints">points</a>
+unless you append an alternative
+<a href="definitions.html#unitofmeasure">unit of measure</a>.
+For example,
+<br/>
+<span class="pre-in-pp">
+ .TOC_LEAD 14
+</span>
+sets the base leading of tables of contents to 14 points, whereas
+<br/>
+<span class="pre-in-pp">
+ .TOC_LEAD .5i
+</span>
+sets the base leading of tables of contents to 1/2 inch.
+</p>
+
+<p>
+If you want the leading of tables of contents adjusted to fill the
+page, pass TOC_LEAD the optional argument <kbd>ADJUST</kbd>. (See
+<a href="docprocessing.html#doc-lead-adjust">DOC_LEAD_ADJUST</a>
+for an explanation of leading adjustment.)
+</p>
+
+<p>
+The default for
+<a href="docprocessing.html#printstyle">PRINTSTYLE TYPESET</a>
+is the prevailing document lead (16 by default), adjusted.
+</p>
+
+<div class="box-tip">
+<p class="tip">
+<span class="note">Note:</span>
+Even if you give mom a <kbd>.DOC_LEAD_ADJUST&nbsp;OFF</kbd> command,
+she will still, by default, adjust the leading of the table of
+contents. You <i>must</i> enter
+<kbd>TOC_LEAD&nbsp;&lt;lead&gt;</kbd> with no <kbd>ADJUST</kbd>
+argument to disable this default behaviour.
+</p>
+
+<p class="tip-bottom">
+<span class="additional-note">Additional note:</span>
+Tables of contents are always double-spaced in
+<a href="docprocessing.html#printstyle">PRINTSTYLE <kbd>TYPEWRITE</kbd></a>,
+regardless of whether the body of the document is single-spaced.
+</p>
+</div>
+
+<h4 id="toc-pagenumbering" class="docs">2. Page numbering</h4>
+
+<p>
+The pagination style of tables of contents is controlled by the same
+macros that control
+<a href="headfootpage.html#pagination-intro">document page numbering</a>,
+except
+<a href="headfootpage.html#pagenum">PAGENUM</a>
+(tables of contents always start on page 1). The defaults are the
+same as for the rest of the document, with the exception that tables
+of contents, by default, have roman numeral page numbers.
+</p>
+
+<p>
+Therefore, if you wish to change some aspect of table of contents
+pagination style, use the
+<a href="headfootpage.html#index-pagination-control">document pagination control macros</a>
+immediately prior to <kbd>.TOC</kbd>.
+</p>
+
+<p>
+A special macro,
+<a href="#toc-pagenum-style">TOC_PAGENUM_STYLE</a>,
+controls the style of table of contents pagination (i.e. the actual
+table of contents pages&#8217; numbers, not the page number
+references of entries).
+</p>
+
+<!-- -PAGINATE_TOC- -->
+
+<div id="paginate-toc" class="box-macro-args">
+Macro: <b>PAGINATE_TOC</b> <kbd class="macro-args">&lt;toggle&gt;</kbd>
+</div>
+
+<p>
+By default, mom paginates tables of contents. If you&#8217;d like
+her not to, do
+<br/>
+<span class="pre-in-pp">
+ .PAGINATE_TOC OFF
+</span>
+(or <kbd>NO, X,</kbd> etc).
+</p>
+
+<div class="box-tip">
+<p class="tip">
+<span class="note">Note:</span>
+Simply invoking
+<kbd>.PAGINATION&nbsp;OFF</kbd>
+or
+<kbd>.PAGINATE&nbsp;OFF</kbd>
+disables table of contents pagination <i>for the first
+page of the table of contents only.</i> You must use
+<kbd>.PAGINATE_TOC&nbsp;OFF</kbd> to disable table of contents
+pagination completely, even if pagination is turned off elsewhere in
+your document.
+</p>
+</div>
+
+<!-- -TOC_PAGENUM_STYLE- -->
+
+<div id="toc-pagenum-style" class="box-macro-args">
+Macro: <b>TOC_PAGENUM_STYLE</b> <kbd class="macro-args">&lt;DIGIT | ROMAN | roman | ALPHA | alpha&gt;</kbd>
+</div>
+<p class="requires">
+See
+<a href="headfootpage.html#pagenum-style"><span style="font-style: normal;">PAGENUM_STYLE</span></a>
+for an explanation of the arguments.
+</p>
+
+<p>
+By default, mom uses roman numerals to number table of contents
+pages. Use TOC_PAGENUM_STYLE if you&#8217;d prefer something else.
+For example, to have standard digits instead of roman numerals, do
+the following:
+<br/>
+<span class="pre-in-pp">
+ .TOC_PAGENUM_STYLE DIGIT
+</span>
+</p>
+
+<h4 id="toc-header" class="docs" style="margin-top: -.5em;">3. Header string and style</h4>
+
+<p>
+The table of contents header string is the title that appears at the top of the
+table of contents. By default, it&#8217;s &#8220;Contents&#8221;.</p>
+
+<div id="toc-header-string" class="box-macro-args">
+Macro: <b>TOC_HEADER_STRING</b> <kbd class="macro-args">&lt;string&gt;</kbd>
+</div>
+
+<p>
+If you&#8217;d like the title of the table of contents to read
+something other than &#8220;Contents&#8221;, do, for
+example
+<br/>
+<span class="pre-in-pp">
+ .TOC_HEADER_STRING "Table of Contents"
+</span>
+</p>
+
+<h5 id="toc-header-v-pos" class="docs" style="margin-top: 1em; text-transform: none;">Header string vertical placement</h5>
+
+<div id="toc-header-v-pos1" class="box-macro-args" style="margin-top: 1em">
+Macro: <b>TOC_HEADER_V_POS</b> <kbd class="macro-args">&lt;distance from top of page&gt;</kbd>
+</div>
+<p class="requires">
+&bull;&nbsp;Requires a <a href="definitions.html#unitofmeasure">unit of measure</a>
+</p>
+
+<p>
+Normally, the TOC header string falls at the same vertical position
+as the
+<a href="definitions.html#docheader">docheader</a>.
+If you&#8217;d like it to fall at a different position, say 2 inches, use
+<br/>
+<span class="pre-in-pp">
+ .TOC_HEADER_V_POS 2i
+</span>
+</p>
+
+<h5 id="toc-header-style" class="docs" style="margin-top: -.5em; text-transform: none;">Header string control macros and defaults</h5>
+
+<div class="defaults-container" style="margin-top: 1em; padding-bottom: 8px;">
+<p class="defaults" style="padding-top: 6px;">
+See
+<a href="docelement.html#control-macro-args">Arguments to the control macros</a>.
+<br/>
+The following TOC_HEADER control macros may also be
+<a href="#grouping">grouped</a>
+using TOC_HEADER_STYLE.
+</p>
+<span class="pre defaults">
+.TOC_HEADER_FAMILY default = prevailing doc family
+.TOC_HEADER_FONT default = bold
+.TOC_HEADER_SIZE default = +4
+.TOC_HEADER_QUAD default = left
+.TOC_HEADER_COLOR default = black
+.TOC_HEADER_CAPS default = no
+.TOC_HEADER_SMALLCAPS default = no
+.TOC_HEADER_UNDERSCORE default = none
+</span>
+</div>
+
+<h4 id="toc-style" class="docs" style="margin-top: -.5em;">4. Entries and reference page numbers style</h4>
+
+<p>
+&#8220;Entries&#8221; refers to the hierarchical arrangement of
+section titles (in
+<a href="rectoverso.html#collate-intro">collated</a>
+documents) and headings as they appear in the table of contents:
+<span class="pre-in-pp">
+ Section title
+ Head level 1
+ Head level 2
+ Head level 3
+ ...
+</span>
+The style for title entries (e.g. chapter numbers or titles) and
+heading levels is controlled by
+<a href="#toc-title-style">TOC_TITLE_STYLE </a>
+and
+<a href="#toc-entry-style">TOC_ENTRY_STYLE</a>
+respectively.
+</p>
+
+<p id="toc-pn">
+&#8220;Reference page numbers&#8221; means the page numbers
+associated with entries. Macros to control their style take the
+form <kbd>.TOC_PN_&lt;SPEC&gt;</kbd>, and the defaults are listed
+here.
+</p>
+
+<div class="defaults-container" style="margin-top: 1em; padding-bottom: 8px;">
+<p class="defaults" style="padding-top: 6px;">
+See
+<a href="docelement.html#control-macro-args">Arguments to the control macros</a>.
+
+<span class="pre defaults">
+.TOC_PN_FAMILY default = prevailing doc family
+.TOC_PN_FONT default = roman
+.TOC_PN_SIZE default = 0
+</span>
+</p>
+</div>
+
+<!-- -TOC_TITLE_STYLE- -->
+
+<div id="toc-title-style" class="box-macro-args">
+Macro: <b>TOC_TITLE_STYLE</b> <kbd class="macro-args">&lt;see below for args&gt;</kbd>
+</div>
+
+<p>
+TOC_TITLE_STYLE allows you to set all the style parameters for
+title entries in the tables of contents with one macro. The
+number of arguments can run long, so you may want to break them into
+several lines with the backslash character (<kbd>\</kbd>). The
+arguments are:
+<br/>
+<span class="pre-in-pp">
+ FAMILY &lt;family&gt;
+ FONT &lt;font&gt;
+ SIZE +|-&lt;n&gt;
+ COLOR &lt;color&gt;
+ INDENT &lt;amount&gt;
+ CAPS | NO_CAPS
+</span>
+The arguments may be entered in any order.
+</p>
+
+<p>
+The family, font, size, and color arguments behave identically
+to the individual control macros that govern other tags, therefore see
+<a href="docelement.html#control-macro-args">Arguments to the control macros</a>
+for usage. Their defaults are the same as for paragraphs in
+<a href="definitions.html#running">running text</a>.
+</p>
+
+<p>
+<kbd>INDENT</kbd> lets you indent title entries by the amount specified, and
+requires a
+<a href="definitions.html#unitofmeasure">unit of measure</a>.
+The default is zero.
+</p>
+
+<p>
+<kbd>CAPS</kbd> instructs mom to capitalize title entries.
+Capitalization may be enabled or disabled on a per-entry-level
+basis.
+</p>
+
+<p>
+As an example, if you want title entries bold, slightly larger than other
+entries and capitalized, you could do either
+<br/>
+<span class="pre-in-pp">
+ .TOC_TITLE_ENTRY FONT B SIZE +.5 CAPS
+</span>
+or
+<br/>
+<span class="pre-in-pp">
+ .TOC_TITLE_ENTRY \
+ FONT B \
+ SIZE +.5 \
+ CAPS
+</span>
+</p>
+
+<!-- -TOC_ENTRY_STYLE- -->
+
+<div id="toc-entry-style" class="box-macro-args">
+Macro: <b>TOC_ENTRY_STYLE</b> <kbd class="macro-args">&lt;level&gt; &lt;see below for remaining args&gt;</kbd>
+</div>
+
+<p>
+TOC_ENTRY_STYLE allows you to set individually all the style
+parameters for any level of entry (beneath titles) in the tables
+of contents. The number of arguments can run long, so you may
+want to break them into several lines with the backslash character
+(<kbd>\</kbd>).
+</p>
+
+<p>
+<kbd>&lt;level&gt;</kbd> corresponds to a
+<a href="docelement.html#heading">HEADING</a>
+level assigned in the body of the document. The remaining arguments
+are as follows.
+<br/>
+<span class="pre-in-pp">
+ FAMILY &lt;family&gt;
+ FONT &lt;font&gt;
+ SIZE +|-&lt;n&gt;
+ COLOR &lt;color&gt;
+ INDENT &lt;amount&gt;
+ CAPS | NO_CAPS
+</span>
+The arguments may be entered in any order.
+</p>
+
+<p>
+The family, font, size, and color arguments behave identically
+to the individual control macros that govern other tags, therefore see
+<a href="docelement.html#control-macro-args">Arguments to the control macros</a>
+for usage. Their defaults are the same as for paragraphs in
+<a href="definitions.html#running">running text</a>.
+</p>
+
+<p>
+<kbd>INDENT</kbd> lets you indent entries by the amount specified, and
+requires a
+<a href="definitions.html#unitofmeasure">unit of measure</a>.
+Mom sensibly indents and aligns all levels of entry. If you change
+the indent for any level, all levels beneath it are still indented
+according to mom&#8217;s normal arrangement, but with the indent
+assigned to <kbd>level</kbd> taken into account. When you use
+<kbd>INDENT</kbd>, the indent is measured from the left edge of
+the text of the previous level, including numbering, if any.
+</p>
+
+<p>
+<kbd>CAPS</kbd> instructs mom to capitalize title entries.
+Capitalization may be enabled or disabled on a per-title basis.
+</p>
+
+<p>
+As an example, if you want a particular entry level, say
+&#8220;2&#8221;, to be in Helvetica, italics, and slightly larger
+than other entries, you could do either
+<br/>
+<span class="pre-in-pp">
+ .TOC_ENTRY_STYLE 2 FAMILY H FONT I SIZE +.25
+</span>
+or
+<br/>
+<span class="pre-in-pp">
+ .TOC_ENTRY_STYLE 2 \
+ FAMILY H
+ FONT I \
+ SIZE +.25
+</span>
+</p>
+
+<!-- -PREFIX_CHAPTER_NUMBERS- -->
+
+<div id="toc-prefix-ch-number" class="box-macro-args">
+Macro: <b>TOC_PREFIX_CHAPTER_NUMBER</b> <kbd class="macro-args">&lt;none&gt; &lt;anything&gt;</kbd>
+</div>
+<p class="alias" style="margin-bottom: 0;">
+<i>Alias:</i> <b>TOC_PREFIX_SECTION_NUMBER</b>
+</p>
+
+<p>
+By default, mom does not prefix a chapter number to chapters or
+section titles in the table of contents. If you would like her to
+do so, invoke <kbd>.TOC_PREFIX_CHAPTER_NUMBER</kbd> without an
+argument before
+<a href="docprocessing.html#start">START</a>.
+</p>
+
+<p>
+You may subsequently disable the prefixing of chapter numbers
+by supplying the macro with any argument (<kbd>OFF</kbd>,
+<kbd>QUIT</kbd>, <kbd>Q</kbd>, <kbd>X</kbd>...) prior to the
+<kbd>.START</kbd> that comes after
+<a href="rectoverso.html#collate"><kbd>.COLLATE</kbd></a>.
+</p>
+
+<p>
+This macro is useful you want chapters numbered in the table of
+contents but the chapters themselves are identified by title only.
+It can be used with both
+<a href="docprocessing.html#doctype">DOCTYPE CHAPTER</a>
+and
+<a href="docprocessing.html#doctype">DOCTYPE DEFAULT</a>.
+The alias <b>TOC_PREFIX_SECTION_NUMBER</b> may be preferable
+in the latter case.
+</p>
+
+<!-- -PAD_TOC_CHAPTER_NUMBERS- -->
+
+<div id="toc-pad-ch-numbers" class="box-macro-args">
+Macro: <b>PAD_TOC_CHAPTER_NUMBERS</b> <kbd class="macro-args">&lt;number of chapters&gt;</kbd>
+</div>
+<p class="alias" style="margin-bottom: 0;">
+<i>Alias:</i> <b>PAD_TOC_SECTION_NUMBERS</b>
+</p>
+
+
+<p>
+If the number of chapters or major sections
+(<a href="docprocessing.html#doctype">DOCTYPE DEFAULT</a>)
+exceeds 9, you can have mom pad the numbers so the rightmost
+numerals of the chapter numbers align. Simply invoke
+<kbd>PAD_TOC_CHAPTER_NUMBERS</kbd> with the number of chapters in
+the document.
+</p>
+
+<p>
+Without padding:
+<br/>
+<span class="pre-in-pp">
+ 9. Chapter Title.....................100
+ 10. Chapter Title....................123
+</span>
+With padding:
+<br/>
+<span class="pre-in-pp">
+ 9. Chapter Title....................100
+ 10. Chapter Title....................123
+</span>
+</p>
+
+<!-- -TOC_ENTRY_NUMBERS- -->
+
+<div id="toc-entry-numbers" class="box-macro-args">
+Macro: <b>TOC_ENTRY_NUMBERS</b> <kbd class="macro-args">&lt;FULL&gt; &lt;TRUNCATE&gt; &lt;NONE&gt;</kbd>
+</div>
+
+<p>
+If numbering is enabled for any level of
+<a href="docelement.html#heading">HEADING</a>,
+mom, by default, includes the numbering in that level&#8217;s
+entries in table of contents. If you would prefer that
+numbering not be included in the table of contents,
+issue <kbd>.TOC_ENTRY_NUMBERS&nbsp;NONE</kbd>. If
+you&#8217;d like to include numbering, but not the full,
+concatenated numbering used in the body of the document, issue
+<kbd>.TOC_ENTRY_NUMBERS&nbsp;TRUNCATE</kbd>.
+</p>
+
+<p>
+Assuming numbering is enabled for HEADINGs 1, 2, and 3,
+<kbd>.TOC_ENTRY_NUMBERS FULL</kbd> (mom&#8217;s default), would
+result in
+<br/>
+<span class="pre-in-pp">
+ 1. Level-1 entry
+ 1.1. Level-2 entry
+ 1.1.1. Level-3 entry
+ 2. Level-1 entry
+ 2.1. Level-2 entry
+ 2.1.1. Level-3 entry
+</span>
+whereas <kbd>.TOC_ENTRY_NUMBERS TRUNCATE</kbd> would produce
+<br/>
+<span class="pre-in-pp">
+ 1. Level-1 entry
+ 1. Level-2 entry
+ 1. Level-3 entry
+ 2. Level-1 entry
+ 1. Level-2 entry
+ 1. Level-3 entry
+</span>
+and <kbd>.TOC_ENTRY_NUMBERS NONE</kbd> would remove numbering
+completely.
+<br/>
+<span class="pre-in-pp">
+ Level-1 entry
+ Level-2 entry
+ Level-3 entry
+ Level-1 entry
+ Level-2 entry
+ Level-3 entry
+</span>
+</p>
+
+<div class="box-tip">
+<p class="tip">
+<span class="note">Note:</span>
+<kbd>.TOC_ENTRY_NUMBERS TRUNCATE</kbd> removes the numbering
+associated with table of contents chapter or section titles
+when
+<a href="docelement.html#prefix-chapter-number">PREFIX_CHAPTER_NUMBER</a>
+is enabled. To enable the numbering of chapter or section titles
+in this circumstance, use
+<a href="#toc-prefix-ch-number">TOC_PREFIX_CHAPTER_NUMBER</a>.
+</p>
+</div>
+
+<h4 id="toc-additional" class="docs" style="margin-top: -1em;">5. Additional table of contents control macros</h4>
+
+<p>
+The following five macros allow you to
+</p>
+<ul style="margin-top: -.5em; margin-left: -.5em;">
+ <li>instruct mom to <a href="#toc-appends-author">append author(s) to</a> <a href="docprocessing.html#title">TITLE</a> <a href="toc-appends-author">entries</a></li>
+ <li><a href="#toc-title-entry">alter the wording of</a> <a href="docprocessing.html#title">TITLE</a> <a href="#toc-title-entry">entries</a></li>
+ <li>instruct mom to <a href="#space-toc-items">space table of contents entries</a> pleasingly</li>
+ <li>establish <a href="#toc-padding">how many placeholders to leave for page number references</a></li>
+ <li><a href="#toc-rv-switch">switch table of contents page margins</a> should they be incorrect for recto/verso printing</li>
+</ul>
+
+<!-- -TOC_APPENDS_AUTHOR- -->
+
+<div id="toc-appends-author" class="box-macro-args">
+Macro: <b>TOC_APPENDS_AUTHOR</b> <kbd class="macro-args">&lt;none&gt; | &quot;&lt;name(s) of authors&gt;&quot;</kbd>
+</div>
+
+<p>
+In certain kinds of collated documents, different authors are
+responsible for the articles or stories contained within them. In
+such documents, you may wish to have the author or authors appended
+to the table of contents&#8217; title entry for each story or
+article.
+</p>
+
+<p>
+If you invoke <kbd>.TOC_APPENDS_AUTHOR</kbd> <i>without</i> an
+argument, mom appends the first argument you passed to
+<a href="docprocessing.html#author">AUTHOR</a>
+to table of contents title entries, separated by a front-slash.
+</p>
+
+<p>
+If you invoke <kbd>.TOC_APPENDS_AUTHOR</kbd> <i>with</i> an argument
+(surrounded by double-quotes), mom will append it to the table of
+contents title entries instead. This is useful if you have multiple
+authors you wish to identify by last name only. For example, if
+three authors&mdash;Joe Blough, Jane Doe, and John Deere&mdash;are
+responsible for a single article
+<br/>
+<span class="pre-in-pp">
+ .TOC_APPENDS_AUTHOR "Blough et al."
+</span>
+would be a good way to identify them in the table of contents.
+</p>
+
+<!-- -TOC_TITLE_ENTRY- -->
+
+<div id="toc-title-entry" class="box-macro-args">
+Macro: <b>TOC_TITLE_ENTRY</b> <kbd class="macro-args">&quot;&lt;alternate wording for a title entry in the toc&gt;&quot;</kbd>
+</div>
+
+<p>
+In
+<a href="rectoverso.html#collate">collated</a>
+documents, the title of each chapter appears in the table of
+contents. It may sometimes happen that you don&#8217;t want the
+title as it appears in the table of contents to be the same as what
+appears in the
+<a href="definitions.html#docheader">docheader</a>.
+You might, for example, want to shorten it. Or, in the case of
+chapters where the docheader contains both a chapter number and a
+chapter title, like this
+<br/>
+<span class="pre-in-pp">
+ Chapter 6
+ Burning Bush &mdash; Maybe God Was Right
+</span>
+you might want only the chapter title, not the chapter number, to
+show up in the table of contents. (By default, <kbd>.TOC</kbd>
+generates both.)
+</p>
+
+<p>
+If you want to change the wording of a title entry in the table of
+contents, simply invoke
+<br/>
+<span class="pre-in-pp">
+ .TOC_TITLE_ENTRY
+</span>
+with the desired wording, enclosed in double-quotes. Using the
+example, above,
+<br/>
+<span class="pre-in-pp">
+ .CHAPTER 6
+ .CHAPTER_TITLE "Burning Bush &mdash; Maybe God Was Right"
+ .TOC_TITLE_ENTRY "Burning Bush"
+ .DOCTYPE CHAPTER
+</span>
+
+would identify chapter 6 in the table of contents simply as
+&#8220;Burning Bush&#8221;.
+</p>
+
+<!-- -SPACE_TOC_ITEMS- -->
+
+<div id="space-toc-items" class="box-macro-args">
+Macro: <b>SPACE_TOC_ITEMS</b>
+</div>
+
+<p>
+If you&#8217;d like mom to add a small amount of space between table
+of contents entry levels, use <kbd>.SPACE_TOC_ITEMS</kbd>. Mom will
+visually group entry levels in a way that&#8217;s pleasing to the
+eye. The only catch to this macro is that the bottom margins of
+table of contents pages may not align perfectly.
+</p>
+
+<p>
+Please note that
+<kbd>SPACE_TOC_ITEMS</kbd> is only available with
+<a href="docprocessing.html#printstyle">PRINTSTYLE TYPESET</a>.
+</p>
+
+
+<!-- -TOC_PADDING- -->
+
+<div id="toc-padding" class="box-macro-args">
+Macro: <b>TOC_PADDING</b> <kbd class="macro-args">&lt;number of placeholders to allow for page number listings&gt;</kbd>
+</div>
+
+<p>
+By default, mom allows room for 3 digits in the page number
+references of table of contents entries. If you&#8217;d like some
+other number of placeholders, say 2 (if your document runs to less
+than 100 pages), do
+<br/>
+<span class="pre-in-pp">
+ .TOC_PADDING 2
+</span>
+</p>
+
+<!-- -TOC_RV_SWITCH- -->
+
+<div id="toc-rv-switch" class="box-macro-args">
+Macro: <b>TOC_RV_SWITCH</b>
+</div>
+
+<p>
+TOC_RV_SWITCH doesn&#8217;t take an argument. It simply instructs
+mom to switch the left and right margins of the first table of
+contents page in
+<a href="rectoverso.html#recto-verso">recto/verso</a>
+documents should the table of contents happen to begin on an even
+page when you want an odd, or vice versa.
+</p>
+
+<p>
+The same result can be accomplished by outputting a
+<a href="headfootpage.html#blank-pages">BLANKPAGE</a>.
+</p>
+
+<h4 id="toc-more" class="docs" style="margin-top: -.5em;">6. I still need more!</h4>
+
+<p>
+If there is some aspect of Table of Contents formatting for which
+no TOC control macros are provided, mom has a special
+<a href="definitions.html#toggle">toggle macro</a>
+to help out: TOC_PAGE_SETTINGS.
+</p>
+
+<p>
+TOC_PAGE_SETTINGS allows you to enter extra formatting changes for
+the Table of Contents as if it were simply another collated section
+or chapter of a document. Because it&#8217;s a toggle macro,
+invoking it by itself begins collecting your formatting directives,
+and invoking it with any argument (<kbd>OFF</kbd>, <kbd>QUIT</kbd>,
+<kbd>END</kbd>...) stops the collection.
+</p>
+
+<p>
+TOC_PAGE_SETTINGS is special in that the formatting commands
+contained within it must be preceded by <kbd>\!</kbd> (that&#8217;s
+backslash-exclamation point).
+</p>
+
+<p id="toc-page-settings-example">
+For example, say you want to redesign the default page headers for
+the Tables of Contents so that it only contains the document title
+on the left and &#8220;Contents&#8221; in italics on the right, and
+furthermore adjust the footer margin and footer gap, this is how
+you&#8217;d do it:
+<br/>
+<span class="pre-in-pp">
+ .TOC_PAGE_SETTINGS
+ \!.HEADER_RECTO L "^\E*[$TITLE]#\*[IT]Contents\*[PREV]^"
+ \!.FOOTER_MARGIN 3P
+ \!.B_MARGIN 6P+3p
+ .TOC_PAGE_SETTINGS END
+</span>
+(For an explanation of why the example uses <kbd>.B_MARGIN</kbd> to
+set/change the footer gap, see
+<a href="headfootpage.html#gap-note">here</a>.)
+</p>
+
+<p>
+TOC_PAGE_SETTINGS can be put in the stylesheet section of a document
+(i.e. after
+<a href="docprocessing.html#printstyle">PRINTSTYLE</a>
+and before
+<a href="docprocessing.html#start">START</a>)
+or invoked just before
+<a href="#toc">TOC</a>.
+</p>
+
+<div class="rule-long"><hr/></div>
+
+<!-- Navigation links -->
+<table style="width: 100%; margin-top: 12px;">
+<tr>
+ <td style="width: 33%;"><a href="toc.html">Back to Table of Contents</a></td>
+ <td style="width: 24%; text-align: center;"><a href="#top">Top</a></td>
+ <td style="width: 42%; text-align: right;"><a href="refer.html">Next: Bibliographies and references</a></td>
+</tr>
+</table>
+
+</div>
+
+<div class="bottom-spacer"><br/></div>
+
+</body>
+</html>