diff options
Diffstat (limited to 'contrib/mom/momdoc/tables-of-contents.html')
| -rw-r--r-- | contrib/mom/momdoc/tables-of-contents.html | 1224 |
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’ 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 “i”, 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 > doc.pdf +</span> +</p> + +<h3 id="positioning" class="docs">Positioning the Table of Contents</h3> + +<p> +Because a table of contents can’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—French, for example—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’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 <page list> <file>.ps > <new-file>.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">"<single line TOC heading>"</kbd> +</div> +<p class="requires"> +• 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 “Part I” and a “Part II”. +</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> – base family for tables of contents</li> + <li><a href="#toc-pt-size">TOC_PT_SIZE</a> – base point size for tables of contents</li> + <li><a href="#toc-lead">TOC_LEAD</a> – 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> – turn table of contents pagination on or off</li> + <li><a href="#toc-pagenum-style">TOC_PAGENUM_STYLE</a> – table of contents page numbering style</li> + </ul></li> + <li><a href="#toc-header">Header string (e.g. “Contents”) 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"><family></kbd> +</div> + +<p> +TOC_FAMILY establishes the default family for every page element in +a table of contents, including the table of contents’ header +string (by default, “Contents”) 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"><base type size of the toc></kbd> +</div> + +<p class="requires"> +• 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"><leading of the toc> [ ADJUST ]</kbd> +</div> + +<p class="requires"> +• 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 OFF</kbd> command, +she will still, by default, adjust the leading of the table of +contents. You <i>must</i> enter +<kbd>TOC_LEAD <lead></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’ 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"><toggle></kbd> +</div> + +<p> +By default, mom paginates tables of contents. If you’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 OFF</kbd> +or +<kbd>.PAGINATE 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 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"><DIGIT | ROMAN | roman | ALPHA | alpha></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’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’s “Contents”.</p> + +<div id="toc-header-string" class="box-macro-args"> +Macro: <b>TOC_HEADER_STRING</b> <kbd class="macro-args"><string></kbd> +</div> + +<p> +If you’d like the title of the table of contents to read +something other than “Contents”, 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"><distance from top of page></kbd> +</div> +<p class="requires"> +• 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’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> +“Entries” 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"> +“Reference page numbers” means the page numbers +associated with entries. Macros to control their style take the +form <kbd>.TOC_PN_<SPEC></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"><see below for args></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 <family> + FONT <font> + SIZE +|-<n> + COLOR <color> + INDENT <amount> + 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"><level> <see below for remaining args></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><level></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 <family> + FONT <font> + SIZE +|-<n> + COLOR <color> + INDENT <amount> + 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’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 +“2”, 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"><none> <anything></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"><number of chapters></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"><FULL> <TRUNCATE> <NONE></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’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 NONE</kbd>. If +you’d like to include numbering, but not the full, +concatenated numbering used in the body of the document, issue +<kbd>.TOC_ENTRY_NUMBERS TRUNCATE</kbd>. +</p> + +<p> +Assuming numbering is enabled for HEADINGs 1, 2, and 3, +<kbd>.TOC_ENTRY_NUMBERS FULL</kbd> (mom’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"><none> | "<name(s) of authors>"</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’ 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—Joe Blough, Jane Doe, and John Deere—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">"<alternate wording for a title entry in the toc>"</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’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 — 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 — Maybe God Was Right" + .TOC_TITLE_ENTRY "Burning Bush" + .DOCTYPE CHAPTER +</span> + +would identify chapter 6 in the table of contents simply as +“Burning Bush”. +</p> + +<!-- -SPACE_TOC_ITEMS- --> + +<div id="space-toc-items" class="box-macro-args"> +Macro: <b>SPACE_TOC_ITEMS</b> +</div> + +<p> +If you’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’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"><number of placeholders to allow for page number listings></kbd> +</div> + +<p> +By default, mom allows room for 3 digits in the page number +references of table of contents entries. If you’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’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’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’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 “Contents” in italics on the right, and +furthermore adjust the footer margin and footer gap, this is how +you’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> |