[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[groff] 06/06: Mom 2.4-4 doc updates
|
From: |
Peter Schaffter |
|
Subject: |
[groff] 06/06: Mom 2.4-4 doc updates |
|
Date: |
Thu, 2 Jan 2020 20:30:40 -0500 (EST) |
PTPi pushed a commit to branch master
in repository groff.
commit 1c789884e6e0af96d663bb3fc4687288a61bdd17
Author: Peter Schaffter <address@hidden>
Date: Thu Jan 2 20:29:08 2020 -0500
Mom 2.4-4 doc updates
General doc fixes and emendations.
Add entry for TOC_HEADING and associated _STYLE macros.
Update copyright info.
---
contrib/mom/momdoc/appendices.html | 2 +-
contrib/mom/momdoc/color.html | 72 +++++++-------
contrib/mom/momdoc/cover.html | 2 +-
contrib/mom/momdoc/definitions.html | 2 +-
contrib/mom/momdoc/docelement.html | 82 +++++++++------
contrib/mom/momdoc/docprocessing.html | 154 +++++++++++++++++++++++++----
contrib/mom/momdoc/goodies.html | 2 +-
contrib/mom/momdoc/graphical.html | 2 +-
contrib/mom/momdoc/headfootpage.html | 20 ++--
contrib/mom/momdoc/images.html | 2 +-
contrib/mom/momdoc/inlines.html | 2 +-
contrib/mom/momdoc/intro.html | 2 +-
contrib/mom/momdoc/letters.html | 2 +-
contrib/mom/momdoc/macrolist.html | 14 ++-
contrib/mom/momdoc/rectoverso.html | 2 +-
contrib/mom/momdoc/refer.html | 2 +-
contrib/mom/momdoc/reserved.html | 2 +-
contrib/mom/momdoc/stylesheet.css | 2 +-
contrib/mom/momdoc/tables-of-contents.html | 47 ++++++++-
contrib/mom/momdoc/toc.html | 5 +-
contrib/mom/momdoc/typesetting.html | 2 +-
contrib/mom/momdoc/using.html | 2 +-
contrib/mom/momdoc/version-2.html | 2 +-
23 files changed, 311 insertions(+), 115 deletions(-)
diff --git a/contrib/mom/momdoc/appendices.html
b/contrib/mom/momdoc/appendices.html
index 6fe71fc..7e7f359 100644
--- a/contrib/mom/momdoc/appendices.html
+++ b/contrib/mom/momdoc/appendices.html
@@ -2,7 +2,7 @@
<!--
This file is part of groff, the GNU roff type-setting system.
-Copyright (C) 2004-2018 Free Software Foundation, Inc.
+Copyright (C) 2004-2020 Free Software Foundation, Inc.
Written by Peter Schaffter (address@hidden).
Permission is granted to copy, distribute and/or modify this document
diff --git a/contrib/mom/momdoc/color.html b/contrib/mom/momdoc/color.html
index 40c6293..020a36c 100644
--- a/contrib/mom/momdoc/color.html
+++ b/contrib/mom/momdoc/color.html
@@ -2,7 +2,7 @@
<!--
This file is part of groff, the GNU roff type-setting system.
-Copyright (C) 2004-2018 Free Software Foundation, Inc.
+Copyright (C) 2004-2020 Free Software Foundation, Inc.
Written by Peter Schaffter (address@hidden).
Permission is granted to copy, distribute and/or modify this document
@@ -152,7 +152,7 @@ do so without confusing mom.
<li><a href="#newcolor">NEWCOLOR</a></li>
<li><a href="#xcolor">XCOLOR</a></li>
<li><a href="#color">COLOR</a></li>
- <li><a href="#color-inline">\*[<colorname>]</a> (inline escape)</li>
+ <li><a href="#color-inline">\*[<colourname>]</a> (inline escape)</li>
</ul>
</div>
@@ -178,7 +178,7 @@ mom doesn’t have a clue what you mean when you
reference a
colour (with
<a href="#color">COLOR</a>
or
-<a href="#color-inline"><kbd>\*[<color name>]</kbd></a>).
+<a href="#color-inline"><kbd>\*[<colour name>]</kbd></a>).
</p>
<p>
@@ -227,7 +227,7 @@ could enter one of the following:
After you’ve told mom about a colour, you can then get her to
set text in that colour either with the
<a href="definitions.html#inlines">inline escape</a>,
-<a href="#color-inline"><kbd>\*[<colorname>]</kbd></a>,
+<a href="#color-inline"><kbd>\*[<colourname>]</kbd></a>,
or the macro
<a href="#color">COLOR</a>.
(See the
@@ -238,21 +238,21 @@ above.)
<div class="box-tip">
<p class="tip-top">
<span class="note">Note:</span>
-The colorname you give to NEWCOLOR may be used with groff’s
-<kbd>\m[<colorname>]</kbd> inline escape (the <kbd>\m</kbd>
+The colourname you give to NEWCOLOR may be used with groff’s
+<kbd>\m[<colourname>]</kbd> inline escape (the <kbd>\m</kbd>
escape is used to set text and rule colours). Thus, assuming
-a colorname “blueblack” set with NEWCOLOR,
+a colourname “blueblack” set with NEWCOLOR,
<kbd>\*[blueblack]</kbd> and <kbd>\m[blueblack]</kbd> are
-equivalent. Furthermore, the colorname can be given as an argument
+equivalent. Furthermore, the colourname can be given as an argument
to <b>groff</b>’s
<a href="definitions.html#primitives">primitive</a>
request, <kbd>.gcolor</kbd> (which does the same thing as
-<kbd>\m[<colorname>]</kbd>).
+<kbd>\m[<colourname>]</kbd>).
</p>
<p class="tip-bottom">
-Equally, the colorname may be used with
-<kbd>\M[<colorname>]</kbd> and <kbd>.fcolor</kbd>, which set
+Equally, the colourname may be used with
+<kbd>\M[<colourname>]</kbd> and <kbd>.fcolor</kbd>, which set
the “fill” colour for solid graphical objects.
</p>
</div>
@@ -261,9 +261,9 @@ the “fill” colour for solid graphical objects.
<p id="color-tip" class="tip-top">
<span class="tip">Tips for newbies:</span>
Colour manipulation can be tremendously confusing if you don’t
-have a background in graphic arts or computing. My advice, if color
+have a background in graphic arts or computing. My advice, if colour
intimidates you, is to stick to using mom’s default RGB colour
-scheme, and to fire up a color chooser that gives you the RGB values
+scheme, and to fire up a colour chooser that gives you the RGB values
you want for the colour you select. Plug those values into the
components argument to NEWCOLOR, and you’ll get the colour
you want. Both the KDE and gnome desktops have colour selectors
@@ -279,7 +279,7 @@ sure to click the button “Display format” and
select
Alternatively, you can use mom’s simpler
<kbd><a href="#xcolor">XCOLOR</a></kbd>
macro to initialize one of the 256 pre-defined X colours by
-supplying the name of the color as an argument.
+supplying the name of the colour as an argument.
</p>
</div>
@@ -290,14 +290,14 @@ supplying the name of the color as an argument.
</div>
<div class="box-macro-args">
-Macro: <b>XCOLOR</b> <kbd class="macro-args"><X colorname>
[<alias>]</kbd>
+Macro: <b>XCOLOR</b> <kbd class="macro-args"><X colourname>
[<alias>]</kbd>
</div>
<p class="requires">
-<kbd style="font-style: normal"><X colorname></kbd> <i>must be all one
word, all lower case.</i>
+<kbd style="font-style: normal"><X colourname></kbd> <i>must be all one
word, all lower case.</i>
<br/>
(See
-<a href="#xcolor-names" style="font-style: normal;">Finding X color names</a>
+<a href="#xcolor-names" style="font-style: normal;">Finding X colour names</a>
for how to get a list of valid colour names.)
</p>
@@ -341,13 +341,13 @@ While some X colours have fanciful names (peachpuff,
papayawhip,
thistle, snow), many are self-explanatory and self-descriptive
in ordinary colour terms. “blue” is pure (rgb)
blue, “green” is pure (rgb) green, and so on.
-Furthermore, for many X colors, there exist four variants, each
+Furthermore, for many X colours, there exist four variants, each
representing increasingly darker shades of the same colour.
For example, “blue1” is a relatively bright blue;
“blue2”, “blue3” and “blue4” are
increasingly darker shades. For that reason, you may find XCOLOR is
a better choice than NEWCOLOR when it comes to initializing common
-colors.
+colours.
</p>
<p>
@@ -370,7 +370,7 @@ can use either <kbd>.COLOR mygreen</kbd> (or
<kbd>\*[mygreen]</kbd> (or <kbd>\*[MYGREEN]</kbd>.)
</p>
-<h3 id="xcolor-names" class="docs">Finding X color names</h3>
+<h3 id="xcolor-names" class="docs">Finding X colour names</h3>
<p>
There are two ways of finding the names of the pre-defined X
@@ -390,7 +390,7 @@ as well.
</p>
<p>
-Whichever method you use to find X color names, remember that the
+Whichever method you use to find X colour names, remember that the
names, passed as arguments to XCOLOR, must be all one word, all in
lower case.
</p>
@@ -398,43 +398,43 @@ lower case.
<div class="box-tip">
<p class="tip-top">
<span class="note">Note:</span>
-Both the colorname and the alias you give to XCOLOR may be
-used with groff’s <kbd>\m[<colorname>]</kbd>
+Both the colourname and the alias you give to XCOLOR may be
+used with groff’s <kbd>\m[<colourname>]</kbd>
inline escape (the <kbd>\m</kbd> escape is used to set
-text and rule colours). Thus, assuming an X-colorname
+text and rule colours). Thus, assuming an X-colourname
“mediumspringgreen” set with XCOLOR, and an alias,
“mygreen”, <kbd>\*[mediumspringgreen]</kbd>,
<kbd>\m[mediumspringgreen]</kbd>, <kbd>\*[mygreen]</kbd> and
<kbd>\m[mygreen]</kbd> are all equivalent. Furthermore, both the
-colorname and the alias can be given as an argument to groff’s
+colourname and the alias can be given as an argument to groff’s
<a href="definitions.html#primitives">primitive</a>
request, <kbd>.gcolor</kbd> (which does the same thing as
-<kbd>\m[<colorname>]</kbd>).
+<kbd>\m[<colourname>]</kbd>).
</p>
<p class="tip-bottom">
-The colorname initialized with XCOLOR <i>but not the
+The colourname initialized with XCOLOR <i>but not the
alias</i> may also be used with groff’s inline escape,
<kbd>\M[<colorname>]</kbd>, and the corresponding primitive,
<kbd>.fcolor</kbd>, both of which set the “fill” colour
for solid graphical objects. If you need a colour initialized with
XCOLOR for <kbd>\M</kbd> or <kbd>.fcolor</kbd>, you MUST give the
-full colorname; the alias won’t work.
+full colourname; the alias won’t work.
</p>
</div>
<!-- -COLOR- -->
<div class="macro-id-overline">
-<h3 id="color" class="macro-id">Invoking a color</h3>
+<h3 id="color" class="macro-id">Invoking a colour</h3>
</div>
<div class="box-macro-args">
-Macro: <b>COLOR</b> <kbd class="macro-args"><colorname></kbd>
+Macro: <b>COLOR</b> <kbd class="macro-args"><colourname></kbd>
</div>
<p id="color-inline" class="requires" style="font-style: normal;">
-Inline: <kbd>\*[<colorname>]</kbd>
+Inline: <kbd>\*[<colourname>]</kbd>
</p>
<p>
@@ -444,7 +444,7 @@ or
<a href="#xcolor">XCOLOR</a>,
you use either the macro COLOR or the
<a href="definitions.html#inlines">inline escape</a>,
-<kbd>\*[<colorname>]</kbd>, to cause mom to
+<kbd>\*[<colourname>]</kbd>, to cause mom to
set subsequent text in that colour. See the
<a href="#color-example2">example</a>,
above, which shows both in action.
@@ -453,7 +453,7 @@ above, which shows both in action.
<div class="box-tip">
<p class="tip-top">
<span class="note">Note:</span>
-You can use the <kbd>\*[<colorname>]</kbd> inline escape in
+You can use the <kbd>\*[<colourname>]</kbd> inline escape in
any
<a href="docprocessing.html#top">document processing</a>
macro that takes a
@@ -464,7 +464,7 @@ subsequent invocations of that particular macro to be
colourized.
</p>
<p>
-Furthermore, if you use <kbd>\*[<colorname>]</kbd> in the
+Furthermore, if you use <kbd>\*[<colourname>]</kbd> in the
string argument passed to
<a href="docelement.html#head">HEAD</a>,
<a href="docelement.html#subhead">SUBHEAD</a>
@@ -480,8 +480,8 @@ invoking the appropriate
</p>
<p class="tip-bottom">
-For colorizing underscored text, see
-<a href="goodies.html#underscore-color">Colorizing underscored text</a>
+For colourizing underscored text, see
+<a href="goodies.html#underscore-color">Colourizing underscored text</a>
in the notes at the end of
<a href="goodies.html#underscore">UNDERSCORE</a>.
</p>
diff --git a/contrib/mom/momdoc/cover.html b/contrib/mom/momdoc/cover.html
index 363e306..ad4ea16 100644
--- a/contrib/mom/momdoc/cover.html
+++ b/contrib/mom/momdoc/cover.html
@@ -2,7 +2,7 @@
<!--
This file is part of groff, the GNU roff type-setting system.
-Copyright (C) 2004-2018 Free Software Foundation, Inc.
+Copyright (C) 2004-2020 Free Software Foundation, Inc.
Written by Peter Schaffter (address@hidden).
Permission is granted to copy, distribute and/or modify this document
diff --git a/contrib/mom/momdoc/definitions.html
b/contrib/mom/momdoc/definitions.html
index 0d032fa..e5e9b88 100644
--- a/contrib/mom/momdoc/definitions.html
+++ b/contrib/mom/momdoc/definitions.html
@@ -2,7 +2,7 @@
<!--
This file is part of groff, the GNU roff type-setting system.
-Copyright (C) 2004-2018 Free Software Foundation, Inc.
+Copyright (C) 2004-2020 Free Software Foundation, Inc.
Written by Peter Schaffter (address@hidden).
Permission is granted to copy, distribute and/or modify this document
diff --git a/contrib/mom/momdoc/docelement.html
b/contrib/mom/momdoc/docelement.html
index 81336fe..7b1f20b 100644
--- a/contrib/mom/momdoc/docelement.html
+++ b/contrib/mom/momdoc/docelement.html
@@ -2,7 +2,7 @@
<!--
This file is part of groff, the GNU roff type-setting system.
-Copyright (C) 2004-2018 Free Software Foundation, Inc.
+Copyright (C) 2004-2020 Free Software Foundation, Inc.
Written by Peter Schaffter (address@hidden).
Permission is granted to copy, distribute and/or modify this document
@@ -1326,7 +1326,8 @@ which may be given in any order:
CAPS | NO_CAPS \
SMALLCAPS | NO_SMALLCAPS \
BASELINE_ADJUST <amount to raise heading from the baseline> \
- NEEDS <lines of text required beneath the heading >
+ NEEDS <lines of text required beneath the heading> \
+ PREFIX_CHAPTER [<n>] \
SPACE_AFTER | NO_SPACE_AFTER \
NUMBER | NO_NUMBER \
NO_SHIM | SHIM \
@@ -1393,6 +1394,19 @@ should not be appended to the argument.
</p>
<p class="defaults" style="margin-bottom: 1em">
+<kbd>PREFIX_CHAPTER</kbd> instructs mom to prefix the current
+chapter number to numbered headings. If mom is unable to determine
+a chapter number, she will ask for one.
+</p>
+
+<p class="defaults" style="margin-bottom: 1em">
+Note that using <kbd>PREFIX_CHAPTER</kbd> with an explicit chapter
+number will also set the chapter number for subsequent
+<a href="images.html#autolabel">automatically-generated image and
pre-processor labels</a>
+as well.
+</p>
+
+<p class="defaults" style="margin-bottom: 1em">
<kbd>SPACE_AFTER</kbd> inserts a blank line equal to the current
<a href="definitions.html#leading">leading</a> after a HEADING.
If you’d like a full linespace after a heading level, use
@@ -1453,15 +1467,24 @@ Macro: <b>PREFIX_CHAPTER_NUMBER</b> <kbd
class="macro-args"><none> | <c
</div>
<p>
-If you’ve requested numbering for any level of heading and
-you’d like mom, in addition, to prefix a chapter number to the
-numbering scheme, you can do so with PREFIX_CHAPTER_NUMBER.
+If, in addition to numbering heads, you want mom to prepend the
+chapter number, invoke <kbd>PREFIX_CHAPTER_NUMBER</kbd>.
+</p>
+
+<p>
+When you invoke <kbd>.PREFIX_CHAPTER_NUMBER</kbd> without an
+argument, mom checks to see whether the argument you passed to <a
+href="docprocessing.html#chapter">CHAPTER</a> (if it’s been
+called) is a digit. If it isn’t (say you’ve numbered your
+chapter “One” instead of “1”), mom will
+abort with a request that you pass PREFIX_CHAPTER_NUMBER a digit
+representing the chapter number.
</p>
<p>
After you invoke <kbd>.PREFIX_CHAPTER_NUMBER</kbd>, mom will prepend
-the current chapter number to all headings you have requested be
-numbered with
+the chapter number to all headings you have requested be numbered
+with
<a href="#heading-style"><kbd>.HEADING_STYLE <n> NUMBER</a>.
Thus, assuming chapter number twelve (12):
<br/>
@@ -1477,31 +1500,27 @@ would become
</span>
</p>
-<p>
-When you invoke <kbd>.PREFIX_CHAPTER_NUMBER</kbd> without an
-argument, mom checks to see whether the argument you passed to
-<a href="docprocessing.html#chapter">CHAPTER</a>
-is a digit. If it is, she immediately starts pre-pending the
-current chapter number to numbered head elements. If it isn’t
-(say you’ve called your chapter “One” instead
-of “1”), mom will abort with a request that you pass
-PREFIX_CHAPTER_NUMBER a digit representing the current chapter
-number.
+<div class="box-tip">
+<p class="tip">
+<span class="note">Note:</span>
+If a chapter number is given to PREFIX_CHAPTER_NUMBER, automatically
+generated labels with a prepended chapter number are also affected.
</p>
+</div>
<p>
-In collated documents, mom automatically increments
-the digit used by PREFIX_CHAPTER_NUMBER by one
-(current chapter digit + 1) every time you invoke <a
-href="rectoverso.html#collate"><kbd>.COLLATE</kbd></a>, even if
-you’ve (temporarily) turned off the prefixing of chapter
-numbers. Thus, even if you call your chapters “One”,
-“Two”, “Three” instead of “1”,
-“2”, “3”, mom will Do The Right Thing
-with respect to numbering head elements in all collated chapters
-following the first invocation of PREFIX_CHAPTER_NUMBER (assuming,
-of course, that the collated chapters are in incrementing order; if
-not, you must must put
+In collated documents, mom automatically increments the digit used
+by PREFIX_CHAPTER_NUMBER by one (current chapter digit + 1) every
+time you invoke
+<a href="rectoverso.html#collate"><kbd>.COLLATE</kbd></a>,
+even if you’ve (temporarily) turned off the prefixing
+of chapter numbers. Thus, even if you number your chapters
+“One”, “Two”, “Three” instead of
+“1”, “2”, “3”, mom will Do The
+Right Thing with respect to numbering head (and label) elements
+in all collated chapters following the first invocation of
+PREFIX_CHAPTER_NUMBER (assuming, of course, that the collated
+chapters are in incrementing order; if not, you must must put
<br/>
<span class="pre-in-pp">
.PREFIX_CHAPTER_NUMBER <chapter number>
@@ -1519,7 +1538,8 @@ prefixing of chapter numbers to numbered head elements
off and on
according to your needs or whims.
</p>
-<p>
+<div class="box-tip">
+<p class="tip">
<span class="note">Note:</span>
Because PREFIX_CHAPTER_NUMBER takes an (optional) digit representing
the chapter number, it’s use need not be restricted to
@@ -1533,7 +1553,7 @@ with a
<a href="definitions.html#numericargument">numeric argument</a>
in your document setup.
</p>
-
+</div>
<div class="rule-short"><hr/></div>
<!-- ==================================================================== -->
diff --git a/contrib/mom/momdoc/docprocessing.html
b/contrib/mom/momdoc/docprocessing.html
index a15b79f..7e4873a 100644
--- a/contrib/mom/momdoc/docprocessing.html
+++ b/contrib/mom/momdoc/docprocessing.html
@@ -2,7 +2,7 @@
<!--
This file is part of groff, the GNU roff type-setting system.
-Copyright (C) 2004-2018 Free Software Foundation, Inc.
+Copyright (C) 2004-2020 Free Software Foundation, Inc.
Written by Peter Schaffter (address@hidden).
Permission is granted to copy, distribute and/or modify this document
@@ -65,6 +65,7 @@ FDL in the main directory of the groff source package.
<li><a href="#covertitle">COVERTITLE</a></li>
<li><a href="#doc-covertitle">DOC_COVERTITLE</a></li>
<li><a href="#pdftitle">PDF_TITLE</a></li>
+ <li><a href="#toc-heading">TOC_HEADING</li>
</ul></li>
<li><a href="#docstyle-macros"><b>The docstyle macros (templates)</b></a>
<ul class="toc-docproc">
@@ -89,15 +90,15 @@ FDL in the main directory of the groff source package.
</ul></li>
</ul></li>
</ul>
+</div>
+<div class="mini-toc-col-2">
+<br/>
<h3 class="toc toc-docproc-header"><a class="header-link"
href="#start-macro">Initiate document processing</a></h3>
<ul class="toc-docproc" style="margin-top: .5em;">
<li><a href="#start"><b>The START macro</b></a></li>
</ul>
-</div>
-<div class="mini-toc-col-2">
-<br/>
<h3 class="toc toc-docproc-header"><a class="header-link"
href="#style-before-start">Establishing type and formatting<br/><span
style="display: block; margin-top: -.3em;">parameters before
START</span></a></h3>
-<ul class="toc-docproc" style="margin-top: .5em;">
+<ul class="toc-docproc">
<li><a href="#type-before-start"><b>Behaviour of the typesetting macros
before START</b></a>
<ul class="toc-docproc">
<li><a href="docprocessing.html#include">Including (sourcing) style sheets
and files</a></li>
@@ -887,6 +888,7 @@ processing macros.
<li><a href="#covertitle">COVERTITLE</a> – frontispiece, title page,
etc</li>
<li><a href="#doc-covertitle">DOC_COVERTITLE</a> – book cover,
collated document cover, etc</li>
<li><a href="#pdftitle">PDF_TITLE</a> – window title for PDF
viewers</li>
+ <li><a href="#toc-heading">TOC_HEADING</a> – single, non-pagenumbered
line of text in table of contents</li>
</ul>
</div>
@@ -1713,10 +1715,10 @@ itself has two optional arguments that accomplish the
same thing.
</div>
<div id="pdftitle" class="box-macro-args">
-Macro: <b>PDF_TITLE</b> <kbd class="macro-args">"<pdf viewer window
title>" </kbd>
+Macro: <b>PDF_TITLE</b> <kbd class="macro-args">"<pdf viewer window
title>"</kbd>
</div>
<p class="requires">
-• Arguments must be enclosed in double-quotes
+• Argument must be enclosed in double-quotes
</p>
<p>
@@ -1726,6 +1728,93 @@ mom does not, by default, provide PDF viewers with a
document title.
You may set one, if you like, with PDF_TITLE.
</p>
+<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>
+Mom generates tables of contents automatically (see
+<a href="tables-of-contents.html#toc">TOC</a>).
+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
+<a href="#start">START,</a>
+TOC_HEADING inserts its text into the table of contents with a
+modest amount of whitespace around it to distinguish it easily
+from table of contents entries.
+</p>
+
+<p>
+The appearance of the heading may be controlled with
+the macro
+<a href="#toc-heading-style">TOC_HEADING_STYLE</a>.
+</p>
+
+<div id="toc-heading-style" class="box-macro-args">
+Macro: <b>TOC_HEADING_STYLE</b> <kbd
class="macro-args">"<arguments>"</kbd>
+</div>
+
+<p>
+TOC_HEADING_STYLE controls the look of TOC headings. It is a
+<a href="docelement.html#grouping">“grouping”</a>
+style macro with multiple arguments. It is recommended that
+you use the backslash character to separate them into individual
+lines rather than entering a single, very long line.
+</p>
+
+<p>
+TOC_HEADING_STYLE accepts as many or as few arguments as you need:
+<span class="pre-in-pp">
+ FAMILY <family> \
+ FONT <font> \
+ SIZE <+|-n> \
+ COLOR <color name>* \
+ QUAD L | C | R \
+ SPACE_ABOVE <n>** \
+ SPACE_BENEATH <n>**
+</span>
+ * <kbd>COLOR</kbd> must be pre-initialized with
+<a href="color.html#newcolor">NEWCOLOR</a>
+or
+<a href="color.html#xcolor">XCOLOR</a>.
+</br>
+** <kbd>SPACE_ABOVE</kbd> and <kbd>SPACE_BENEATH</kbd> require a
+<a href="definitions.html#unitofmeasure">unit of measure</a>
+to be appended to their numeric argument.
+</p>
+
+<p>
+For example, if you want your TOC headings to be bold, slightly
+larger than the rest of the table of contents, centred, and with
+one linespace beforehand,
+<span class="pre-in-pp">
+ FONT B \
+ SIZE +.5 \
+ QUAD C \
+ SPACE_ABOVE 1v
+</span>
+</p>
+
+<p>
+ See
+<a href="docelement.html#control-macro-args">Arguments to the control
macros</a>
+for further information about the arguments. Note that
+<kbd>SPACE_ABOVE</kbd> and <kbd>SPACE_BENEATH</kbd> are unique to
+TOC_HEADING_STYLE.
+
+</p>
+
<div class="rule-short"><hr/></div>
<!-- ========================================================================
-->
@@ -1839,9 +1928,9 @@ for how mom outputs each part of the page header.)
<p id="copystyle-note" class="tip">
<span class="note">Note: version 2.1 change</span>
<br/>
-<kbd>DOCTYPE NAMED "string"</kbd> no longer accepts a color argument
-after <kbd>"string"</kbd>. Setting the color of the string is now
-done with <kbd>DOCTYPE_COLOR <color></kbd>. Default
+<kbd>DOCTYPE NAMED "string"</kbd> no longer accepts a colour argument
+after <kbd>"string"</kbd>. Setting the colour of the string is now
+done with <kbd>DOCTYPE_COLOR <colour></kbd>. Default
underscoring of <kbd>"string"</kbd> in the docheader and on covers
has been removed. Use <kbd>DOCTYPE_UNDERLINE</kbd>,
<kbd>DOC_COVER_DOCTYPE_UNDERLINE</kbd> and/or
@@ -2358,7 +2447,7 @@ To turn underlining of quotes back on, use
UNDERLINE_QUOTES without
an argument.
</p>
-<p class="tip-bottom">
+<p>
While most of the
<a href="docelement.html#docelement-control">control macros</a>
have no effect on <b>PRINTSTYLE TYPEWRITE</b>, there
@@ -2368,9 +2457,27 @@ is an important exception:
particularly useful for reducing the point size of
headers/footers should they become crowded (quite likely to
happen if the title of your document is long and your
-<kbd><a href="#copystyle">COPYSTYLE</a></kbd>
-is DRAFT).
+<a href="#copystyle">COPYSTYLE</a>
+is <kbd>DRAFT</kbd).
+</p>
+
+<p>
+Please note that colour is disabled if your
+<a href="#printstyle">PRINTSTYLE</a>
+is <kbd>TYPEWRITE</kbd>. If you would like it enabled, for example
+so PDF links are colourzed, invoke the groff
+<a href="definitions.html#primitives">primitive</a>
+'<kbd>.color</kbd>' after PRINTSTYLE.
</p>
+
+<p class="tip-bottom">
+Finally, note that colour is disabled for <kbd>TYPEWRITE</kbd>. If
+you would like it enabled, for example so PDF links are colourized,
+invoke the groff
+<a href="definitions.html#primitives">primitive</a>
+'<kbd>.color</kbd>' after PRINTSTYLE.
+</p>
+
</div>
<!-- -COPYSTYLE- -->
@@ -2787,7 +2894,7 @@ The macro
<a href="color.html#color">COLOR</a>
and the
<a href="definitions.html#inlines">inline escape</a>,
-<a href="color.html#color-inline"><kbd>\*[<colorname>]</kbd></a>
+<a href="color.html#color-inline"><kbd>\*[<colourname>]</kbd></a>
can be used at any time during document processing for occasional
colour effects. However, consistent and reliable colourizing of
various document elements (the docheader, heads, linebreaks,
@@ -2796,6 +2903,15 @@ of the
<a href="docelement.html#docelement-control">document element control
macros</a>.
</p>
+<p>
+Please note that colour is disabled if your
+<a href="#printstyle">PRINTSTYLE</a>
+is <kbd>TYPEWRITE</kbd>. If you would like it enabled, for example
+so PDF links are colourized, invoke the groff
+<a href="definitions.html#primitives">primitive</a>
+'<kbd>.color</kbd>' after PRINTSTYLE.
+</p>
+
<div class="box-tip">
<p class="tip">
<span class="note">Note:</span>
@@ -2803,7 +2919,7 @@ If you plan to have mom generate a
<a href="docelement.html#toc">table of contents</a>,
do not embed colour
<a href="definitions.html#inlines">inline escapes</a>
-(<a href="color.html#color-inline"><kbd>\*[<colorname>]</kbd></a>)
+(<a href="color.html#color-inline"><kbd>\*[<colourname>]</kbd></a>)
in the
<a href="definitions.html#stringargument">string arguments</a>
given to any of the
@@ -3169,13 +3285,13 @@ Please note that if you use DOCHEADER_FAMILY, you can
still alter
the family of individual parts of the docheader.
</p>
-<h5 id="docheader-color" class="docs">Change the color of the entire
docheader</h5>
+<h5 id="docheader-color" class="docs">Change the colour of the entire
docheader</h5>
<p>
-The default color for docheaders is black, as you’d expect.
+The default colour for docheaders is black, as you’d expect.
If you wish to change it, use
-<kbd>.DOCHEADER_COLOR <color></kbd>, where
-<kbd> <color></kbd> is a color pre-initialized with
+<kbd>.DOCHEADER_COLOR <colour></kbd>, where
+<kbd> <colour></kbd> is a colour pre-initialized with
<a href="color.html#xcolor">XCOLOR</a>
or
<a href="color.html#newcolor">NEWCOLOR</a>.
diff --git a/contrib/mom/momdoc/goodies.html b/contrib/mom/momdoc/goodies.html
index 3db71a6..ddff28e 100644
--- a/contrib/mom/momdoc/goodies.html
+++ b/contrib/mom/momdoc/goodies.html
@@ -2,7 +2,7 @@
<!--
This file is part of groff, the GNU roff type-setting system.
-Copyright (C) 2004-2018 Free Software Foundation, Inc.
+Copyright (C) 2004-2020 Free Software Foundation, Inc.
Written by Peter Schaffter (address@hidden).
Permission is granted to copy, distribute and/or modify this document
diff --git a/contrib/mom/momdoc/graphical.html
b/contrib/mom/momdoc/graphical.html
index fcd5741..0fb5f6e 100644
--- a/contrib/mom/momdoc/graphical.html
+++ b/contrib/mom/momdoc/graphical.html
@@ -2,7 +2,7 @@
<!--
This file is part of groff, the GNU roff type-setting system.
-Copyright (C) 2004-2018 Free Software Foundation, Inc.
+Copyright (C) 2004-2020 Free Software Foundation, Inc.
Written by Peter Schaffter (address@hidden).
Permission is granted to copy, distribute and/or modify this document
diff --git a/contrib/mom/momdoc/headfootpage.html
b/contrib/mom/momdoc/headfootpage.html
index a6b64fd..3d60c15 100644
--- a/contrib/mom/momdoc/headfootpage.html
+++ b/contrib/mom/momdoc/headfootpage.html
@@ -2,7 +2,7 @@
<!--
This file is part of groff, the GNU roff type-setting system.
-Copyright (C) 2004-2018 Free Software Foundation, Inc.
+Copyright (C) 2004-2020 Free Software Foundation, Inc.
Written by Peter Schaffter (address@hidden).
Permission is granted to copy, distribute and/or modify this document
@@ -437,8 +437,9 @@ END, X...</b>), e.g.,
<b>NOTE:</b> HEADERS automatically
disables
<a href="definitions.html#footer">footers</a>
-(you can’t have both), but not the page numbers that normally
-appear at the bottom of the page.
+but not the page numbers that normally appear at the bottom of the
+page. If you want both headers and footers, you must use the macro
+<a href="#headers-and-footers">HEADERS_AND_FOOTERS</a>.
</p>
<p>
@@ -470,22 +471,25 @@ Macro: <b>FOOTERS</b> <kbd class="macro-args">toggle</kbd>
<p>
<a href="definitions.html#footer">Page footers</a>
are off by default. If you want them instead of
-<a href="definitions.html#header">headers</a>
-(you can’t have both), turn them on by invoking
+<a href="definitions.html#header">headers</a>,
+turn them on by invoking
<kbd>.FOOTERS</kbd> without an argument, e.g.,
<br/>
<span class="pre-in-pp">
.FOOTERS
</span>
-</p>
-
-<p>
FOOTERS automatically disables headers, and
mom shifts the placement of page numbers from their
normal position at page bottom to the top of the page.
</p>
<p>
+<b>NOTE:</b> If you want both headers and footers, you must use the
+macro
+<a href="#headers-and-footers">HEADERS_AND_FOOTERS</a>.
+</p>
+
+<p>
<b>NOTE:</b> By default, when footers are on,
mom does not print a page number on the first
page of a document, nor on first pages after
diff --git a/contrib/mom/momdoc/images.html b/contrib/mom/momdoc/images.html
index 2a72adc..b24377c 100644
--- a/contrib/mom/momdoc/images.html
+++ b/contrib/mom/momdoc/images.html
@@ -2,7 +2,7 @@
<!--
This file is part of groff, the GNU roff type-setting system.
-Copyright (C) 2004-2018 Free Software Foundation, Inc.
+Copyright (C) 2004-2020 Free Software Foundation, Inc.
Written by Peter Schaffter (address@hidden).
Permission is granted to copy, distribute and/or modify this document
diff --git a/contrib/mom/momdoc/inlines.html b/contrib/mom/momdoc/inlines.html
index 6ced83e..c01f260 100644
--- a/contrib/mom/momdoc/inlines.html
+++ b/contrib/mom/momdoc/inlines.html
@@ -2,7 +2,7 @@
<!--
This file is part of groff, the GNU roff type-setting system.
-Copyright (C) 2004-2018 Free Software Foundation, Inc.
+Copyright (C) 2004-2020 Free Software Foundation, Inc.
Written by Peter Schaffter (address@hidden).
Permission is granted to copy, distribute and/or modify this document
diff --git a/contrib/mom/momdoc/intro.html b/contrib/mom/momdoc/intro.html
index bd02e17..014a265 100644
--- a/contrib/mom/momdoc/intro.html
+++ b/contrib/mom/momdoc/intro.html
@@ -2,7 +2,7 @@
<!--
This file is part of groff, the GNU roff type-setting system.
-Copyright (C) 2004-2018 Free Software Foundation, Inc.
+Copyright (C) 2004-2020 Free Software Foundation, Inc.
Written by Peter Schaffter (address@hidden).
Permission is granted to copy, distribute and/or modify this document
diff --git a/contrib/mom/momdoc/letters.html b/contrib/mom/momdoc/letters.html
index 3c85e54..ed90e7e 100644
--- a/contrib/mom/momdoc/letters.html
+++ b/contrib/mom/momdoc/letters.html
@@ -2,7 +2,7 @@
<!--
This file is part of groff, the GNU roff type-setting system.
-Copyright (C) 2004-2018 Free Software Foundation, Inc.
+Copyright (C) 2004-2020 Free Software Foundation, Inc.
Written by Peter Schaffter (address@hidden).
Permission is granted to copy, distribute and/or modify this document
diff --git a/contrib/mom/momdoc/macrolist.html
b/contrib/mom/momdoc/macrolist.html
index 00e9944d..fe165dd 100644
--- a/contrib/mom/momdoc/macrolist.html
+++ b/contrib/mom/momdoc/macrolist.html
@@ -2,7 +2,7 @@
<!--
This file is part of groff, the GNU roff type-setting system.
-Copyright (C) 2004-2018 Free Software Foundation, Inc.
+Copyright (C) 2004-2020 Free Software Foundation, Inc.
Written by Peter Schaffter (address@hidden).
Permission is granted to copy, distribute and/or modify this document
@@ -681,6 +681,12 @@ elsewhere in the documentation.
<tr>
<td><a
href="docprocessing.html#revision-string">REVISION_STRING</a></td><td>-- what
to use in place of “Revision”</td>
</tr>
+<tr>
+<td><a href="docprocessing.html#pdftitle">PDF_TITLE</a></td><td>-- PDF viewer
window title</td>
+</tr>
+<tr>
+<td><a href="docprocessing.html#toc-heading">TOC_HEADING</a></td><td>--
non-pagenumbered line inserted into the TOC</td>
+</tr>
</table>
<table class="quick-ref">
@@ -1202,6 +1208,9 @@ elsewhere in the documentation.
<td><a href="docprocessing.html#no-toc-entry">NO_TOC_ENTRY</a></td><td>-- omit
a document section from the TOC</td>
</tr>
<tr>
+<td><a href="docprocessing.html#toc-heading">TOC_HEADING</a></td><td>-- insert
a heading into the TOC</td>
+</tr>
+<tr>
<td><a href="tables-of-contents.html#index-toc-control">Control macros</a></td>
</tr>
</table>
@@ -1226,6 +1235,9 @@ elsewhere in the documentation.
<td><a href="tables-of-contents.html#toc-entry-style">TOC_ENTRY_STYLE</a></td>
</tr>
<tr>
+<td><a href="docprocessing.html#toc-heading-style">TOC_HEADING_STYLE</a></td>
+</tr>
+<tr>
<td><a href="tables-of-contents.html#toc-additional">Additional table of
contents control macros</a></td>
</tr>
</table>
diff --git a/contrib/mom/momdoc/rectoverso.html
b/contrib/mom/momdoc/rectoverso.html
index d644dec..27b7f2b 100644
--- a/contrib/mom/momdoc/rectoverso.html
+++ b/contrib/mom/momdoc/rectoverso.html
@@ -2,7 +2,7 @@
<!--
This file is part of groff, the GNU roff type-setting system.
-Copyright (C) 2004-2018 Free Software Foundation, Inc.
+Copyright (C) 2004-2020 Free Software Foundation, Inc.
Written by Peter Schaffter (address@hidden).
Permission is granted to copy, distribute and/or modify this document
diff --git a/contrib/mom/momdoc/refer.html b/contrib/mom/momdoc/refer.html
index 0ff9afb..ed50f4b 100644
--- a/contrib/mom/momdoc/refer.html
+++ b/contrib/mom/momdoc/refer.html
@@ -2,7 +2,7 @@
<!--
This file is part of groff, the GNU roff type-setting system.
-Copyright (C) 2004-2018 Free Software Foundation, Inc.
+Copyright (C) 2004-2020 Free Software Foundation, Inc.
Written by Peter Schaffter (address@hidden).
Permission is granted to copy, distribute and/or modify this document
diff --git a/contrib/mom/momdoc/reserved.html b/contrib/mom/momdoc/reserved.html
index 7f271b2..5097815 100644
--- a/contrib/mom/momdoc/reserved.html
+++ b/contrib/mom/momdoc/reserved.html
@@ -2,7 +2,7 @@
<!--
This file is part of groff, the GNU roff type-setting system.
-Copyright (C) 2004-2018 Free Software Foundation, Inc.
+Copyright (C) 2004-2020 Free Software Foundation, Inc.
Written by Peter Schaffter (address@hidden).
Permission is granted to copy, distribute and/or modify this document
diff --git a/contrib/mom/momdoc/stylesheet.css
b/contrib/mom/momdoc/stylesheet.css
index ff3315f..46dc214 100644
--- a/contrib/mom/momdoc/stylesheet.css
+++ b/contrib/mom/momdoc/stylesheet.css
@@ -1,4 +1,4 @@
-/* Copyright (C) 2004-2018 Free Software Foundation, Inc. */
+/* Copyright (C) 2004-2020 Free Software Foundation, Inc. */
/* This file is part of mom, which is part of groff, a free software */
/* project. */
diff --git a/contrib/mom/momdoc/tables-of-contents.html
b/contrib/mom/momdoc/tables-of-contents.html
index b885f58..e6863f6 100644
--- a/contrib/mom/momdoc/tables-of-contents.html
+++ b/contrib/mom/momdoc/tables-of-contents.html
@@ -2,7 +2,7 @@
<!--
This file is part of groff, the GNU roff type-setting system.
-Copyright (C) 2004-2018 Free Software Foundation, Inc.
+Copyright (C) 2004-2020 Free Software Foundation, Inc.
Written by Peter Schaffter (address@hidden).
Permission is granted to copy, distribute and/or modify this document
@@ -51,6 +51,9 @@ FDL in the main directory of the groff source package.
<li><a href="#psselect"><kbd>psselect</kbd></a></li>
</ul></li>
<li><a href="#toc">The TOC macro</a></li>
+ <ul style="margin-left: -.5em; list-style-type: disc;">
+ <li><a href="#toc-heading">TOC_HEADING</a>
+ </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>
@@ -192,7 +195,7 @@ AUTO_RELOCATE_TOC usage is described in the manual,
<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>.
+<a href="using.html#pdfmom" style="font-weight: bold">pdfmom</a>
with groff’s native PDF driver (ie without the
<strong>-Tps</strong> flag). Files that need to be processed with
the <strong>-Tps</strong> flag require you to reposition the table
@@ -333,6 +336,39 @@ or
</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>
@@ -1073,6 +1109,13 @@ 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">
diff --git a/contrib/mom/momdoc/toc.html b/contrib/mom/momdoc/toc.html
index 8a03d79..9fe4413 100644
--- a/contrib/mom/momdoc/toc.html
+++ b/contrib/mom/momdoc/toc.html
@@ -2,7 +2,7 @@
<!--
This file is part of groff, the GNU roff type-setting system.
-Copyright (C) 2004-2018 Free Software Foundation, Inc.
+Copyright (C) 2004-2020 Free Software Foundation, Inc.
Written by Peter Schaffter (address@hidden).
Permission is granted to copy, distribute and/or modify this document
@@ -287,7 +287,8 @@ FDL in the main directory of the groff source package.
<li><a href="docprocessing.html#misc">5.3.2.10 MISC</a></li>
<li><a href="docprocessing.html#covertitle">5.3.2.11
COVERTITLE</a></li>
<li><a href="docprocessing.html#covertitle">5.3.2.12
DOC_COVERTITLE</a></li>
- <li><a href="docprocessing.html#pdftitle">5.3.2.12
PDF_TITLE</a></li>
+ <li><a href="docprocessing.html#pdftitle">5.3.2.13
PDF_TITLE</a></li>
+ <li><a href="docprocessing.html#toc-heading">5.3.2.14
TOC_HEADING</a></li>
</ul></li>
<li><a href="docprocessing.html#docstyle-macros">5.3.3 The docstyle
macros</a> – base templates; what kind of document you’re creating,
how you want it to look overall
<ul>
diff --git a/contrib/mom/momdoc/typesetting.html
b/contrib/mom/momdoc/typesetting.html
index 12e53ec..82c828f 100644
--- a/contrib/mom/momdoc/typesetting.html
+++ b/contrib/mom/momdoc/typesetting.html
@@ -2,7 +2,7 @@
<!--
This file is part of groff, the GNU roff type-setting system.
-Copyright (C) 2004-2018 Free Software Foundation, Inc.
+Copyright (C) 2004-2020 Free Software Foundation, Inc.
Written by Peter Schaffter (address@hidden).
Permission is granted to copy, distribute and/or modify this document
diff --git a/contrib/mom/momdoc/using.html b/contrib/mom/momdoc/using.html
index a7917c9..ea90294 100644
--- a/contrib/mom/momdoc/using.html
+++ b/contrib/mom/momdoc/using.html
@@ -2,7 +2,7 @@
<!--
This file is part of groff, the GNU roff type-setting system.
-Copyright (C) 2004-2018 Free Software Foundation, Inc.
+Copyright (C) 2004-2020 Free Software Foundation, Inc.
Written by Peter Schaffter (address@hidden).
Permission is granted to copy, distribute and/or modify this document
diff --git a/contrib/mom/momdoc/version-2.html
b/contrib/mom/momdoc/version-2.html
index d3908e2..49cb02a 100644
--- a/contrib/mom/momdoc/version-2.html
+++ b/contrib/mom/momdoc/version-2.html
@@ -2,7 +2,7 @@
<!--
This file is part of groff, the GNU roff type-setting system.
-Copyright (C) 2004-2018 Free Software Foundation, Inc.
+Copyright (C) 2004-2020 Free Software Foundation, Inc.
Written by Peter Schaffter (address@hidden).
Permission is granted to copy, distribute and/or modify this document
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- [groff] 06/06: Mom 2.4-4 doc updates,
Peter Schaffter <=