[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[groff] 01/01: Version 2.2 updates.
|
From: |
Peter Schaffter |
|
Subject: |
[groff] 01/01: Version 2.2 updates. |
|
Date: |
Sun, 26 Feb 2017 22:23:34 -0500 (EST) |
PTPi pushed a commit to branch master
in repository groff.
commit 777ca69fd0bddd9293d436be82f1874981284ff1
Author: Peter Schaffter <address@hidden>
Date: Sun Feb 26 22:23:06 2017 -0500
Version 2.2 updates.
---
contrib/mom/momdoc/appendices.html | 18 +-
contrib/mom/momdoc/color.html | 4 +-
contrib/mom/momdoc/cover.html | 2 +-
contrib/mom/momdoc/definitions.html | 36 ++-
contrib/mom/momdoc/docelement.html | 285 +++++++---------
contrib/mom/momdoc/docprocessing.html | 476 ++++++++++++++++++---------
contrib/mom/momdoc/goodies.html | 51 ++-
contrib/mom/momdoc/graphical.html | 2 +-
contrib/mom/momdoc/headfootpage.html | 33 +-
contrib/mom/momdoc/images.html | 500 ++++++++++++++++++++++-------
contrib/mom/momdoc/inlines.html | 2 +-
contrib/mom/momdoc/intro.html | 8 +-
contrib/mom/momdoc/letters.html | 2 +-
contrib/mom/momdoc/macrolist.html | 145 ++++++---
contrib/mom/momdoc/rectoverso.html | 2 +-
contrib/mom/momdoc/refer.html | 8 +-
contrib/mom/momdoc/reserved.html | 2 +-
contrib/mom/momdoc/stylesheet.css | 4 +-
contrib/mom/momdoc/tables-of-contents.html | 60 +++-
contrib/mom/momdoc/toc.html | 24 +-
contrib/mom/momdoc/typesetting.html | 12 +-
contrib/mom/momdoc/using.html | 14 +-
contrib/mom/momdoc/version-2.html | 20 +-
23 files changed, 1163 insertions(+), 547 deletions(-)
diff --git a/contrib/mom/momdoc/appendices.html
b/contrib/mom/momdoc/appendices.html
index d3cc529..dc8e566 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-2016 Free Software Foundation, Inc.
+Copyright (C) 2004-2017 Free Software Foundation, Inc.
Written by Peter Schaffter (address@hidden).
Permission is granted to copy, distribute and/or modify this document
@@ -832,15 +832,13 @@ helpful to everyone, groff newbies and old hands alike.
<p>
Mom’s macro file, om.tmac, uses long names, aliases, and a
-host of other groff goodies that have become part of the whole
-groff picture under the unflagging guidance of groff’s
-current maintainer, Werner Lemberg. The function of nearly
-every macro, number register and string can be infered simply
-from its name. The file is heavily commented. A consistent, if
-idiosyncratic, indenting style is used as well, significantly
-improving readability. Anyone wanting to futz around with
-mom’s macros should be able to do so with a minimum of head
-scratching.
+host of other groff goodies that have become part of the whole groff
+picture. The function of nearly every macro, number register and
+string can be infered simply from its name. The file is heavily
+commented. A consistent, if idiosyncratic, indenting style is used
+as well, significantly improving readability. Anyone wanting to
+futz around with mom’s macros should be able to do so with a
+minimum of head scratching.
</p>
<div class="box-tip">
diff --git a/contrib/mom/momdoc/color.html b/contrib/mom/momdoc/color.html
index d268118..381517e 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-2016 Free Software Foundation, Inc.
+Copyright (C) 2004-2017 Free Software Foundation, Inc.
Written by Peter Schaffter (address@hidden).
Permission is granted to copy, distribute and/or modify this document
@@ -222,7 +222,7 @@ could enter one of the following:
.NEWCOLOR YELLOW #FFFF00 \"or ##FFFFFFFF0000 or "1 1 0"
.NEWCOLOR YELLOW RGB #FFFF00 \"or ##FFFFFFFF0000 or "1 1 0"
.NEWCOLOR YELLOW CYM #00FF00 \"or ##0000FFFF0000 or "0 1 0"
- .NEWCOLOR YELLOW CYMK #00FF0000 \"or ##0000FFFF00000000 or "1 1 0"
+ .NEWCOLOR YELLOW CYMK #00FF0000 \"or ##0000FFFF00000000 or "0 0 1 0"
</span>
After you've told mom about a colour, you can then get her to set
text in that colour either with the
diff --git a/contrib/mom/momdoc/cover.html b/contrib/mom/momdoc/cover.html
index d2700f4..c58684c 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-2016 Free Software Foundation, Inc.
+Copyright (C) 2004-2017 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 6811a85..806d69b 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-2016 Free Software Foundation, Inc.
+Copyright (C) 2004-2017 Free Software Foundation, Inc.
Written by Peter Schaffter (address@hidden).
Permission is granted to copy, distribute and/or modify this document
@@ -110,6 +110,7 @@ or concept you’re not familiar with.
<a href="#numericargument">Numeric argument</a><br/>
<a href="#outputline">Output line</a><br/>
<a href="#primitives">Primitives</a><br/>
+ <a href="#preprocessor">Pre-processor</a><br/>
<a href="#stringargument">String Argument</a><br/>
<a href="#unitofmeasure">Unit of measure</a><br/>
<a href="#zerowidthcharacter">Zero-width character</a><br/>
@@ -123,10 +124,12 @@ or concept you’re not familiar with.
<tr><th class="definitions">Mom terms</th></tr>
<tr>
<td>
+ <a href="#baseline-grid">Baseline grid</a><br/>
<a href="#blockquote">Blockquote</a><br/>
<a href="#controlmacro">Control macro</a><br/>
<a href="#docheader">Docheader</a><br/>
<a href="#epigraph">Epigraph</a><br/>
+ <a href="#float">Float</a><br/>
<a href="#footer">Footer</a><br/>
<a href="#head">Head</a><br/>
<a href="#header">Header</a><br/>
@@ -698,6 +701,17 @@ or concept you’re not familiar with.
A line of text as it appears in output copy.
</dd>
+ <dt id="preprocessor">Pre-processor</dt>
+ <dd>
+ Pre-processors are used by groff to generate tables (tbl),
+ diagrams (pic), and equations (eqn). These pre-processors are
+ fully supported by mom. In addition, the “refer”
+ pre-processor is used to generate bibliographies and lists of
+ cited works. The PDF_IMAGE macro, which allows insertion of
+ graphics into a document, is not strictly a pre-processor but
+ behaves similarly to tbl, pic, and eqn.
+ </dd>
+
<dt id="primitives">Primitives</dt>
<dd>
The lowercase instructions, introduced with a period, that groff
@@ -828,13 +842,13 @@ or concept you’re not familiar with.
<h3 id="mom-terms" class="docs">Mom terms</h3>
<dl>
- <dt id="blockquote">Blockquote</dt>
+ <dt id="baseline-grid">Baseline grid</dt>
<dd>
- Cited material other than
- <a href="#quote">quotes</a>.
- Typically set at a smaller point size than paragraph text,
- indented from the left and right margins. Blockquotes are
- <a href="#filled">filled</a>.
+ Virtual guide lines spaced according to the
+ <a href="#leading">leading</a>
+ established for running text. Adherence to the grid ensures that
+ text fills the page completely to the bottom margin. Uncorrected
+ deviations from the grid result in bottom margins that fall short.
</dd>
<dt id="controlmacro">Control macro</dt>
@@ -859,6 +873,14 @@ or concept you’re not familiar with.
a chapter, story, or other document.
</dd>
+ <dt id="float">Float</dt>
+ <dd>
+ A float is material intended to be kept together as a block.
+ Floated material that fits on a page in position is output on that
+ page. Floats that do not fit in position are deferred to the top
+ of the next page.
+ </dd>
+
<dt id="footer">Footer/page footer</dt>
<dd>
Document information (frequently author and title) output in
diff --git a/contrib/mom/momdoc/docelement.html
b/contrib/mom/momdoc/docelement.html
index a33a4dd..8ee3054 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-2016 Free Software Foundation, Inc.
+Copyright (C) 2004-2017 Free Software Foundation, Inc.
Written by Peter Schaffter (address@hidden).
Permission is granted to copy, distribute and/or modify this document
@@ -660,23 +660,6 @@ her to do so, use the control macro
<a href="typesetting.html#printstyle">PRINTSTYLE TYPEWRITE</a>.)
</p>
-<div class="box-tip">
-<p class="tip">
-<span class="tip">Tip:</span>
-If you want to add less than a full linespace between
-paragraphs, you may give the amount of space you’d like as an
-argument to
-<kbd>.PARA_SPACE</kbd>.
-</span>
-Introducing a paragraph with <kbd>.PP2</kbd> will add a space equal
-to one-quarter of the prevailing linespace before the start of the
-paragraph. Initial paragraphs, ie those at the start of a document,
-or after a heading or
-<a href="#linebreak-intro">linebreak</a>,
-should still be introduced with
-<kbd>.PP</kbd>.
-</div>
-
<p>
Note that mom does not provide widow or orphan control for
paragraphs (ie even if only one line of a paragraph fits at the
@@ -688,37 +671,16 @@ page—to a new page, which is not what you want.
</p>
<div class="box-tip">
-<p class="tip-top">
+<p class="tip">
<span class="tip">Tip:</span>
-The last thing you want while you’re writing and editing
-drafts of a document (particularly stories and chapters) is a
-text file cluttered up with <kbd>.PP</kbd>’s. The visual
-interruption in the flow of text is a serious obstacle to creativity
-and critiquing.
-</p>
-
-<p>
-I use the tab key on my keyboard to indent paragraphs by four spaces
-when I'm writing, producing a text file that looks pretty much like
-what you see on a printed page. When it comes time to format and
-print the file, I run it through a sed script that (amongst other
-things) converts the intial four spaces into <kbd>.PP</kbd> (plus a
-new line) and pipes the output to groff for processing and printing.
-</p>
-
-<p class="tip-bottom">
-Another solution would be to insert a blank line between paragraphs
-of your text files. The blank lines can then be sedded out at
-print time, as above (<kbd>.PP</kbd> plus a newline), or, more
-conveniently, you could use the <kbd>.blm</kbd>
-<a href="definitions.html#primitives">primitive</a>
-(blank line macro) to tell groff (and mom) that blank lines should
-be interpreted as PP’s.
+If you would prefer not to clutter up your files with
+<kbd>.PP</kbd>s, you can use groff’s “blank line
+macro” to instruct groff to interpret blank lines as
+<kbd>.PP</kbd>’s, like this:
<br/>
<span class="pre-in-pp">
.blm PP
</span>
-tells groff that blank lines are really the macro PP.
</p>
</div>
@@ -908,20 +870,23 @@ and
<p>
If you wish to change the leading of regular text paragraphs only,
-invoke <kbd>.LS</kbd> immediately after <kbd>.PP</kbd> in every
+invoke <kbd>.LS</kbd> immediately after <kbd>.PP</kbd> in any
paragraph whose leading you wish to change.
</p>
<div class="box-tip">
<p class="tip">
<span class="note">Warning:</span>
-It is extremely unwise to change a paragraph’s leading with LS as
-it will, in all cases, screw up mom’s ability to balance
-the bottom margin of pages. Should you absolutely need to change
-paragraph leading with LS, and subsequently want mom to get back on
-the right leading track, use the
+Changing a paragraph’s leading will almost certaininly screw
+up mom’s ability to balance the bottom margin of pages.
+Should you absolutely require a change of paragraph’s leading and
+need to get mom back on track leading-wise afterwards, use the
<a href="docprocessing.html#shim">SHIM</a>
-macro.
+or
+<a href="docprocessing.html#shim">FLEX</a>
+macro, depending on which
+<a href="docprocessing.html#vertical-whitespace-management">vertical
whitespace management</a>
+strategy you are using.
</p>
</div>
@@ -1079,6 +1044,15 @@ paragraphs
</span>
</p>
+<p style="margin-top: -1em" >
+If
+<a href="docprocessing.html#flex-vs-shim">flex-spacing</a>
+is enabled, additional flexible vertical whitespace can be inserted
+between spaced paragraphs with the
+<a href="docprocessing.html#flex">FLEX</a>
+macro.
+</p>
+
<p>
PARA_SPACE is not recommended for use with PRINTSTYLE TYPEWRITE
unless you give PRINTSTYLE the <kbd>SINGLESPACE</kbd> option.
@@ -1262,25 +1236,26 @@ each heading.
<p>
If, however, you disrupt the regular placement of text on
-mom’s baseline grid, HEADING adds as much whitespace to the
-blank line as is necessary to get things back on track. The extra
-whitespace is always less than the current leading and therefore
-usually doesn't draw attention to itself. This, along with a
-similar strategy for whitespace around quotes and blockquotes, is
-what allows mom to balance the bottom margins of pages effectively.
-The manual,
-<a href="http://www.schaffter.ca/mom/pdf/mom-pdf.pdf";><span
class="book-title">Producing PDFs with groff and mom</span></a>,
-demonstrates this well: the inter-paragraph spacing is 1/3 of the
-leading, yet mom is able to produce a document with good page-rhythm
-and evenly balanced bottom margins.
+mom’s
+<a href="definitions.html#baseline-grid">baseline grid</a>,
+HEADING adds extra whitespace to the blank line according to the
+<a href="docprocessing.html#vertical-whitespace-management">vertical
whitespace management</a>
+strategy in effect. This, along with a similar strategy for
+whitespace around quotes, blockquotes, and
+<a href="definitions.html#float">floated</a>
+and
+<a href="definitions.html#preprocessor">pre-processor material</a>
+is what allows mom to balance the bottom
+margins of pages effectively.
</p>
<p>
-It occasionally happens that the extra whitespace becomes noticeable,
-typically when the amount of whitespace approaches the value of the
-current leading. The result looks like two blank lines instead of
-one. When this happens, a simple but effective fix is to reduce the
-space before the heading by backing up one line, either with
+It occasionally happens that the extra whitespace becomes
+noticeable. This typically occurs when the amount of whitespace
+adjustment approaches the value of the current leading. The result
+looks like two blank lines instead of one. When this happens, a
+simple but effective fix is to reduce the space before the heading
+by backing up one line, either with
<br/>
<span class="pre-in-pp">
.SPACE -1v
@@ -1291,30 +1266,21 @@ or
.RLD -1v
</span>
This results in slightly less whitespace than normal, but the
-difference is usually not apparent.
-</p>
-
-<p class="tip-bottom">
-If you’d prefer that mom not add flexible whitespace to
-headings, invoke the macro
+difference is usually not apparent. Alternatively, you may pass the
+<kbd>NO_SHIM</kbd> or <kbd>NO_FLEX</kbd> argument to
+<a href="#heading-style">HEADING_STYLE</a>
+to prevent shimming or flex-spacing of any particlar heading level
+either globally or selectively. If shimming/flex-spacing is
+disabled selectively with
<br/>
<span class="pre-in-pp">
- .NO_SHIM
+ .HEADING_STYLE <n> NO_SHIM | NO_FLEX
</span>
-either in the style sheet section of your document (ie after
-PRINTSTYLE but before START), which will globally disable whitespace
-adjustment not only before headings, but around quotes and
-blockquotes as well, or on a per-instance basis. <kbd>.NO_SHIM</kbd>
-is disabled by issuing
+it can be re-enabled for the heading level with
<br/>
<span class="pre-in-pp">
- .NO_SHIM OFF
+ .HEADING_STYLE <n> SHIM | FLEX
</span>
-Please note that <kbd>.NO_SHIM</kbd> also disables mom’s
-automatic shimming around quotes, blockquotes, after PDF images and
-floats, and
-<a href="docprocessing.html#shim">SHIM</a>
-macro itself.
</p>
</div>
@@ -1361,7 +1327,9 @@ which may be given in any order:
SMALLCAPS | NO_SMALLCAPS \
BASELINE_ADJUST <amount to raise heading from the baseline> \
SPACE_AFTER | NO_SPACE_AFTER \
- NUMBER | NO_NUMBER
+ NUMBER | NO_NUMBER \
+ NO_SHIM | SHIM \
+ NO_FLEX | FLEX
</span>
</p>
@@ -1434,6 +1402,15 @@ number to numbered headings and Table of Contents
entries,
<a href="#prefix-chapter-number">PREFIX_CHAPTER_NUMBER</a>.
</p>
+<p class="defaults" style="margin-bottom: 1em">
+<kbd>SHIM</kbd> is not necessary if shimming is enabled
+globally, which it is by default; it exists to re-enable
+shimming for the heading level if you have previously passed
+HEADING_STYLE <kbd><n></kbd> a <kbd>NO_SHIM</kbd>
+argument. The <kbd>FLEX</kbd> and <kbd>NO_FLEX</kbd> arguments work
+the same way if flex-spacing is enabled.
+</p>
+
<p class="defaults" style="padding-bottom: .5em">
The argument list is long, so you may want to break it into
several lines by using the backslash character (<kbd>\</kbd>).
@@ -2032,63 +2009,30 @@ This behaviour can be changed with the control macro
If your quote (or blockquote) leading differs from the document
leading, mom attempts to observe the same rules for vertical
whitespace outlined above; however, she will also insert a small,
-flexible amount of extra whitespace around the quotes to make sure
-the whitespace is equal, top and bottom. Since she does this
-on a quote by quote basis, rather than by figuring out how much
-extra whitespace is needed to adjust <i>all</i> quotes on a page,
-the spacing around multiple quotes on the same page will differ
-slightly, although each will be balanced between lines of normal
-<a href="definitions.html#running">running text</a>,
-top and bottom. (The inability to scan an entire page and insert
-equalized whitespace at marked places is a limitation of groff,
-which, by and large, processes text on a line-per-line basis.)
-</p>
-
-<h4 id="no-shim" class="docs">Disable shimming of quotes and blockquotes</h4>
-
-<p>
-If you don’t want the behaviour described above (ie you
-don’t want mom shimming quotes and blockquotes), issue the
-macro
-<br/>
-<span class="pre-in-pp">
- .NO_SHIM
-</span>
-in the style sheet section of your document (ie after PRINTSTYLE but
-before START), which will disable shimming globally, or on a
-per-instance basis prior to <kbd>.QUOTE</kbd> or <kbd>.BLOCKQUOTE</kbd>.
-</p>
-
-<p>
-If you set the leading of
-<a href="#quote-autolead">quotes</a>
-or
-<a href="#blockquote-autolead">blockquotes</a>
-to a value other than the one used in paragraphs, mom will apply
-shimming <i>after</i> the quote, whether or not <kbd>.NO_SHIM</kbd>
-is enabled. This is the only way mom can guarantee that the
-difference in leading will not result in uneven bottom margins.
+flexible amount of extra whitespace
+(<a href="docprocessing.html#shim-vs-flex">shim or flex-spacing</a>)
+around the quotes to make sure the whitespace is equal, top and
+bottom. When shimming is enabled, this may result in multiple
+quotes or blockquotes on the same page being spaced slightly
+differently.
</p>
-<p>
-If you’ve disabled shimming of quotes and blockquotes with
-<kbd>.NO_SHIM</kbd> and you want mom to return to her default
-behaviour in this matter, invoke <kbd>.NO_SHIM OFF</kbd> (or
-<kbd>QUIT, END, X</kbd>, etc).
-</p>
-
-<p>
-Please note that <kbd>NO_SHIM</kbd> disables shimming before
-headings, and the
-<a href="docprocessing.html#shim">SHIM</a>
-macro itself.
-</p>
+<h4 id="no-shim" class="docs">Disable shimming/flex-spacing of quotes and
blockquotes</h4>
<p class="tip-bottom">
-If you don’t provide mom with a QUOTE_AUTOLEAD, quotes are
-leaded at the default for normal running text, meaning that multiple
-quotes on the same page are all spaced identically.
+If you don’t want the behaviour
+described above (ie you don’t want mom putting additional shim
+or flex-spacing around quotes and
+blockquotes), put <kbd>.NO_SHIM</kbd> or/and <kbd>.NO_FLEX</kbd>
+in the style sheet section of your document (ie after PRINTSTYLE
+but before START), which will disable shimming or/and flex-spacing
+globally for all tags, or disable shimming/flex-spacing
+on a per-instance basis prior to <kbd>.QUOTE</kbd> or
+<kbd>.BLOCKQUOTE</kbd>, re-enabling it after the terminating
+<kbd>.QUOTE OFF</kbd> or <kbd>.BLOCKQUOTE OFF</kbd> with
+<kbd>.NO_SHIM OFF</kbd> or <kbd>.NO_FLEX OFF</kbd>.
</p>
+
</div>
<h3 id="float-quote" class="docs">Keeping QUOTEs and BLOCKQUOTEs together as a
block</h3>
@@ -2563,11 +2507,17 @@ The correct order for changing the escape character
inside
.ESC_CHAR .
.CODE OFF
</span>
+Be aware that changing the escape character prevents subsequent
+macros, which require that the backslash be the escape character,
+from functioning correctly. Therefore, do not introduce any macros
+into your CODE block without first restoring the escape character to
+its default.
</p>
<p>
Alternatively, you can enter the backslash character as
-<kbd>\e</kbd>, which tells groff to print a literal backslash.
+<kbd>\e</kbd> or <kbd>\\</kbd> (two backslashes), which tells groff
+to print a literal backslash.
</p>
<div class="box-tip">
@@ -2605,13 +2555,15 @@ in conjunction with CODE, like this:
.QUOTE
.CODE
$ echo "Hello, world" | sed -e 's/Hello,/Goodbye, cruel/'
- .CODE OFF
.QUOTE OFF
</span>
QUOTE takes care of breaking both the text and the code, as well as
indenting the code and offsetting it from
<a href="definitions.html#running">running text</a>
-with vertical whitespace.
+with vertical whitespace. Notice that <kbd>.CODE</kbd>, above, has
+no corresponding <kbd>.CODE OFF</kbd>. <kbd>.CODE</kbd> inside a QUOTE
+does not require a terminating <kbd>.CODE OFF</kbd>, which risks
+introducing unwanted vertical whitespace.
</p>
</div>
@@ -2637,8 +2589,9 @@ for short snippets, as in the following example.
<p>
<kbd>\*[CODE]</kbd> does not permit changing the escape character,
-so <kbd>\e</kbd> must be used. Furthermore, if your code starts
-with a period, you must enter it as “<kbd>\&.</kbd>”.
+so <kbd>\e</kbd> or a doubled backslash must be used. Furthermore,
+if your code starts with a period, you must enter it as
+“<kbd>\&.</kbd>”.
<br/>
<span class="pre-in-pp">
Registers are created with the \*[CODE]\&.nr\*[CODE OFF] request.
@@ -2654,7 +2607,8 @@ with the parameters of
<a href="definitions.html#running">running text</a>,
you must terminate the block with “<kbd>\c</kbd>” and
enter the punctuation at the beginning of the next input line. If
-the punctuation mark is a period, you must precede it with
+the punctuation mark is a period or an apostrophe, you must precede
+it with
“<kbd>\&</kbd>”.
<br/>
<span class="pre-in-pp">
@@ -2665,8 +2619,9 @@ the punctuation mark is a period, you must precede it with
\&. As this demonstrates...
</span>
Use of <kbd>\*[CODE]</kbd> inline does not require the
-<kbd>\c</kbd>, however periods after <kbd>\*[CODE OFF]</kbd>
-still need to be introduced with <kbd>\&</kbd>, as in this example:
+<kbd>\c</kbd>, however periods and apostrophes after
+<kbd>\*[CODE OFF]</kbd> still need to be introduced with
+<kbd>\&</kbd>, as in this example:
<br/>
<span class="pre-in-pp">
...append the unit of measure \*[CODE]p\*[CODE OFF]\&. New sentence...
@@ -2815,8 +2770,8 @@ Macro: <b>LIST</b> <kbd class="macro-args">[ BULLET |
DASH | DIGIT | ALPHA | alp
<p>
Invoked by itself (ie with no argument), LIST
-initializes a list (with bullets as the default enumerator).
-Afterwards, each block of input text preceded by
+initializes a list with bullets as the default enumerator.
+Afterward,s each block of input text preceded by
<kbd><a href="#item">.ITEM</a></kbd>,
on a line by itself, is treated as a list item.
</p>
@@ -3343,11 +3298,11 @@ When you turn line-numbering on, mom, by default
<p>
Mom expects that
-<kbd><a href="#quote">QUOTE</a></kbd>s
+<a href="#quote">QUOTE</a>s
and
-<kbd><a href="#blockquote">BLOCKQUOTE</a></kbd>s
-will not be line-numbered, however control macros
-are provided to enable line numbering for either.
+<a href="#blockquote">BLOCKQUOTE</a>s
+will not be line-numbered, however control macros are provided to
+enable line numbering for either.
See
<a href="#number-quote-lines">Line numbering control macros for quotes and
blockquotes</a>.
</p>
@@ -3809,15 +3764,24 @@ assured mom is happy to oblige.
<p>
A small amount of vertical whitespace and a short horizontal rule
-separate footnotes from the document body. The amount of whitespace
-varies slightly from page to page depending on the number of lines
-in the footnotes. Mom tries for a nice balance between too little
+separate footnotes from the document body. When
+<a href="docprocessing.html#flex-vs-shim">shimming</a>
+is enabled, the amount of whitespace
+may vary slightly from page to page depending on the number of lines
+in the footnotes. Mom tries for a nice balance between too little
whitespace and too much, but when push comes to shove, she’ll
usually opt for ample over cramped. The last lines of footnotes are
always flush with the document’s bottom margin.
</p>
<p>
+When
+<a href="docprocessing.html#flex-vs-shim">flex-spacing</a>
+is enabled, the distance between the last line of text and the
+first footnote is always the same.
+</p>
+
+<p>
If mom sees that a portion of a footnote cannot be fit on its page,
she carries that portion over to the next page. If an entire
footnote can’t be fit on its page (ie FOOTNOTE has been
@@ -4710,9 +4674,8 @@ is removed.
</p>
<p>
-By default, mom starts the endnotes page with a bold,
-centred, double-underscored head, “ENDNOTES”.
-Subsequently, for each section in a
+By default, mom starts the endnotes page with a bold, centred head,
+“ENDNOTES”. Subsequently, for each section in a
<a href="rectoverso.html#collate-intro">collated</a>
document (eg chapters in a book), she identifies the section in bold
type, flush left and underscored, followed by one-half linespace.
@@ -5584,9 +5547,9 @@ this way.
</p>
<p>
-Mom’s default is to double-underscore the title with 1/2-point
-rules placed 2 points apart and 2 points below the baseline of the
-title.
+By default, mom double-underscores the title if your
+<a href="docprocessing.html#printstyle">PRINTSTYLE</a>
+is <kbd>TYPEWRITE</kbd>.
</p>
<!-- -ENDNOTES_HEADER_CAPS- -->
diff --git a/contrib/mom/momdoc/docprocessing.html
b/contrib/mom/momdoc/docprocessing.html
index 89b21b4..c6d48b2 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-2016 Free Software Foundation, Inc.
+Copyright (C) 2004-2017 Free Software Foundation, Inc.
Written by Peter Schaffter (address@hidden).
Permission is granted to copy, distribute and/or modify this document
@@ -40,23 +40,14 @@ FDL in the main directory of the groff source package.
<h1 class="docs">Document processing with mom</h1>
-<div style="text-align: center;">
-<ul class="no-enumerator" style="margin-left: -2.5em;">
- <li><a href="#defaults">Document defaults</a></li>
- <li><a href="#leading-note">Important note on leading/spacing and bottom
margins</a></li>
- <li><a href="#shim">The SHIM macro</a></li>
-</ul>
-</div>
-
-<div class="rule-medium"><hr/></div>
-
<h2 id="toc-doc-processing" class="docs" style="text-align: center;">Table of
contents</h2>
<div id="docprocessing-mini-toc" style="font-size: 90%; line-height: 150%;
margin-top: .5em;">
<div class="mini-toc-col-1" style="margin-left: 0;">
-<h3 class="toc toc-docproc-header" style="margin-top: 1em;"><a
class="header-link" href="#docprocessing-intro">Introduction</a></h3>
-<h3 class="toc toc-docproc-header" style="margin-top: .5em;"><a
-class="header-link" href="#setup">Preliminary document setup</a></h3>
+<h3 class="toc toc-docproc-header" style="margin-top: 1em;"><a
class="header-link" href="#docprocessing-intro">Introduction to document
processing</a></h3>
+<h3 class="toc toc-docproc-header" style="margin-top: .5em;"><a
class="header-link" href="#defaults">Document defaults</a></h3>
+<h3 class="toc toc-docproc-header" style="margin-top: .5em;"><a
class="header-link" href="#vertical-whitespace-management">Vertical whitespace
management</a></h3>
+<h3 class="toc toc-docproc-header" style="margin-top: .5em;"><a
class="header-link" href="#setup">Preliminary document setup</a></h3>
<ul class="toc-docproc" style="margin-top: .5em;">
<li><a href="#docprocessing-tut"><b>Tutorial – Setting up a mom
document</b></a></li>
<li><a href="#reference-macros"><b>The reference macros (metadata)</b></a>
@@ -147,8 +138,8 @@ class="header-link" href="#setup">Preliminary document
setup</a></h3>
</ul></li>
</ul></li>
</ul>
+<h3 class="toc toc-docproc-header"><a class="header-link"
href="#terminating">Terminating a document</a></h3>
</div>
-<h3 style="margin-top: -.5em; text-align: center; text-transform: uppercase;
font-size: 95%;"><a class="header-link" href="#terminating">Terminating a
document</a></h3>
</div>
<div class="rule-short" style="margin-top: -1.75em"><br/><hr/></div>
@@ -221,68 +212,143 @@ documentation, so just in case:
<!-- ==================================================================== -->
-<h2 id="leading-note" class="docs">Important note on leading/spacing and
bottom margins</h2>
+<h2 id="vertical-whitespace-management" class="macro-group">Vertical
whitespace management</h2>
+
+<ul style="margin-left: -.5em;">
+ <li><a href="#shim">Macro: SHIM</a></li>
+ <li><a href="#no-shim">Macro: NO_SHIM</a></li>
+ <li><a href="#flex">Macro: FLEX</a></li>
+ <li><a href="#no-flex">Macro: NO_FLEX</a></li>
+</ul>
+
<p>
Mom takes evenly-aligned bottom margins in
<a href="definitions.html#running">running text</a>
-very seriously. Only under a very few (exceptional) circumstances
+very seriously. Only under a very few, exceptional circumstances
will she allow a bottom margin to “hang” (ie to fall
short).
</p>
<p>
-In order to ensure even bottom margins, mom uses the
-“base” document
+Mom offers two modes of operation for ensuring flush bottom margins:
+shimming and flex-spacing. Shimming means that mom nudges the
+next line after a significant break in running text back onto the
+<a href="definitions.html#baseline-grid">baseline grid</a>
+(eg, after the insertion of a graphic). Flex-spacing means that any
+vertical whitespace remaining between the end of running text and
+the bottom margin is distributed equally at logical points on the
+page.
+</p>
+
+<p>
+Mom uses the
<a href="definitions.html#leading">leading</a>
-in effect <i>at the start of running text on each page</i> (ie
-the leading used in paragraphs) to calculate the spacing of every
-document element. Prior to invoking
+of running text (the “document leading”) that’s in effect
+<i>at the start of running text on each page</i>
+to establish the grid and space document elements such as heads or
+blockquotes so that they adhere to it. (Prior to invoking
<a href="#start">START</a>,
-this is set with the
+the document leading is set with the
<a href="typesetting.html#macros-typesetting">typesetting macro</a>
<a href="typesetting.html#leading">LS</a>,
afterwards with the document
<a href="definitions.html#controlmacro">control macro</a>
-<a href="#doc-lead">DOC_LEAD</a>.
+<a href="#doc-lead">DOC_LEAD</a>.)
</p>
<p>
-Because mom relies so heavily on the base document
-leading, any change to the leading or spacing on a page will almost
-certainly have undesirable consequences on that page’s bottom margin
-unless the change is fully compensated for elsewhere on the page.
+What this means is that documents whose paragraphs are not separated
+by whitepace and which do not contain graphics or
+<a href="definitions.html#pre-processor">pre-processor material</a>
+will fill the page completely to the bottom margin.
+However, if your paragraphs are spaced, or if there are any leading
+changes on a page, or if graphics or pre-processor material are
+inserted, it’s very likely the bottom margins will hang
+unless shimming or flex-spacing is enabled.
</p>
+<h3 id="shim-vs-flex" class="docs">Shimming <span style="text-transform:
none">vs.</span> flex-spacing</h3>
+
<p>
-In other words, if you add a few points of space somewhere on a page,
-you must subtract the same number of points somewhere else on that
-same page, and vice versa.
+<b>Shimming</b> is mom's default mode of operation. She applies it
+automatically before headings, around quotes and blockquotes, and
+beneath
+<a href="definitions.html#float">floats</a>
+and
+<a href="definitions.html#preprocessor">pre-processor material</a>.
+In addition, the
+<a href="#shim">SHIM</a>
+macro can be inserted into a document to make sure that the
+text following falls on the baseline grid.
</p>
<p>
-If it’s a question of adding or subtracting full
-line spaces between or within document elements, you
-can do so by using the “<kbd>v</kbd>” <a
-href="definitions.html#unitofmeasure">unit of measure</a> with
-whatever spacing macro you choose —
-<a href="typesetting.html#ald">ALD</a>,
-<a href="typesetting.html#rld">RLD</a>,
-<a href="typesetting.html#space">SPACE</a>
-— and mom won’t object. “<kbd>v</kbd>” means
-“the current leading”, so she isn’t confused by it. And
-since “<kbd>v</kbd>” accepts decimal fractions, you can
add/subtract
-half linespaces and quarter linespaces with “<kbd>v</kbd>” as well,
-<i>provided you compensate for the fractional linespace somewhere
-else on the page</i>.
+This mode of operation works well in documents whose paragraphs are
+not spaced. Deviations from the baseline grid, usually
+caused by floats or pre-processor material, are corrected
+immediately. If the shimming results in slightly unbalanced
+whitespace around them, it can easily be remedied by passing the
+<kbd>ADJUST</kbd> argument to the appropriate macro.
+</p>
+
+<p>
+If you do not want mom shimming automatically,
+<a href="#no-shim">NO_SHIM</a>
+turns shimming off globally and suppresses the SHIM macro. If you
+want to disable shimming only for a particular float or
+pre-processor, the <kbd>NO_SHIM</kbd> argument may be given to the
+appropriate macro.
+</p>
+
+<p>
+<b>Flex-spacing</b> kicks in automatically whenever you turn shimming
+off. In other words, if you want a document flex-spaced,
+<kbd>.NO_SHIM</kbd> is how you achieve it. If, in addition to not
+shimming, you don’t want mom flex-spacing either,
+<a href="#no-flex">NO_FLEX</a>
+lets you disable it, too.
+</p>
+
+<p>
+Flex-spacing differs from shimming in that mom doesn’t
+correct deviations from the baseline grid. Rather, she distributes
+whitespace left at the bottom of the page equally in appropriate
+places. Like shimming, flex-spacing is automatically applied
+before heads, after floats and pre-processor material, and around
+quotes and blockquotes. Like shimming, flex-spacing can be
+disabled for individual floats or pre-processor material with the
+<kbd>NO_FLEX</kbd> flag.
</p>
<p>
-If all this seems like too much work, mom provides a special macro
-to get you out of trouble if you’ve played around with leading
-and/or spacing. The macro is called SHIM (like those little pieces
-of wood carpenters use to get their work even, level and snug), and
-it’s described below.
+In addition, you can use the
+<a href="#flex">FLEX</a>
+macro to insert flex-spacing yourself into the document, which you
+will almost certainly want to do if your paragraphs are spaced.
+This is because paragraphs are not flex-spaced. Typographically,
+the ideal for spaced paragraphs is that the space between them
+remain constant. Paradoxically, the only way to achieve flush
+bottom margins, or to correct excessive flex-spacing before a
+heading, is by adding flex-space between paragraphs. This requires
+human judgment, and mom does not presume to decide for you.
+</p>
+
+<p>
+Shimming and flex-spacing are mutually exclusive. If the one is
+active, the other isn’t unless you have disabled both. This means
+that you cannot use the FLEX macro when shimming is enabled, or the
+SHIM macro when flex-spacing is enabled. Mom will issue a warning
+if you do.
+</p>
+
+<p>
+The choice of whether to use shimming or flex-spacing depends on
+whether or not your paragraphs are spaced. In a document with
+indented, non-spaced paragraphs, shimming and flex-spacing produce
+nearly the same result, with shimming winning by an aesthetic hair.
+In documents with spaced paragraphs, flex-spacing is the only way to
+achieve flush bottom margins.
</p>
<!-- -SHIM- -->
@@ -296,116 +362,198 @@ Macro: <b>SHIM</b>
</div>
<p>
-SHIM doesn’t take any argument. Use it whenever you’ve played
-around with the
-<a href="definitions.html#leading">leading</a>
-or spacing on a page and you need to get mom’s document
-leading back on track.
+When shimming is enabled, which it is by default, the SHIM macro
+allows you to nudge the line following it back onto the baseline
+grid. In documents with non-spaced paragraphs, this prevents
+the bottom margins from hanging.
</p>
+<p style="margin-bottom: -1em">
+Mom herself automatically applies shimming
+</p>
+<ul>
+ <li><i>before</i> headings</li>
+ <li><i>around</i> quotes and blockquotes</li>
+ <li><i>after</i> PDF images, tables, pic diagrams, equations, and floats</li>
+</ul>
+
<p>
-For example, say you want to insert an image into a document with
-<a href="images.html#pspic">PSPIC</a>.
-Images and graphics aren’t usually conveniently sized in
-multiples of the document leading, which means that when you insert
-the picture, you disrupt mom’s ordered placement of baselines
-on the page. This will certainly result in a bottom margin that
-doesn’t match the bottom margins of your document’s
-other pages.
+You may sometimes find the amount of space generated by
+<kbd>SHIM</kbd> looks too big, whether inserted manually into a
+document or as a result of automatic shimming.
+The situation occurs when the amount of shimming applied
+comes close to the leading currently in effect, making it seem as if
+there’s one linespace too much whitespace.
</p>
<p>
-The solution is to insert SHIM after the image, like this:
-<br/>
-<span class="pre-in-pp">
- <text>
- .PSPIC <args>
- .SHIM
- <text>
-</span>
+The solution is simply to add <kbd>.SPACE -1v</kbd> or
+<kbd>.RLD 1v</kbd> to the document immediately after
+<kbd>.SHIM</kbd>. (Both <kbd>.SPACE -1v</kbd> and
+<kbd>.RLD 1v</kbd> back up by one linespace.)
</p>
+<div class="macro-id-overline">
+<h3 id="no-shim" class="macro-id">NO_SHIM</h3>
+</div>
+
+<div class="box-macro-args">
+Macro: <b>NO_SHIM</b> <kbd class="macro-args"><none> | <anything>
+</div>
+
<p>
-SHIM instructs mom to insert as much or a little space after the
-picture as is needed to ensure that the baseline of the next
-<a href="definitions.html#outputline">output line</a>
-falls where mom would have put it had you not disrupted the normal
-flow of output lines with the picture.
+NO_SHIM, without an argument, disables automatic shimming,
+suppresses the SHIM macro, and enables flex-spacing.
</p>
<p>
-And say, on previewing the above example, you find the image
-doesn’t centre nicely between the lines of text, you can
-adjust the image position by using
-<a href="typesetting.html#ald">ALD</a>
-or
-<a href="typesetting.html#rld">RLD</a>
-before PSPIC. To demonstrate,
-<br/>
-<span class="pre-in-pp">
- <text>
- .RLD 3p
- .PSPIC <args>
- .SHIM
- <text>
-</span>
-which raises the image slightly and thereby balances the whitespace around it.
+NO_SHIM with any argument (eg <b>OFF, QUIT, END, X</b>, etc)
+re-enables shimming if it has been disabled and disables
+flex-spacing.
</p>
+<!-- -FLEX- -->
+
+<div class="macro-id-overline">
+<h3 id="flex" class="macro-id">FLEX</h3>
+</div>
+
+<div class="box-macro-args">
+Macro: <b>FLEX</b> <kbd class="macro-args">[ FORCE ]</kbd>
+</div>
+
<p>
-You may sometimes find the amount of space generated by
-<kbd>SHIM</kbd> looks too big, whether inserted manually into a
-document or as a result of automatic shimming (see immediately
-below). The situation occurs when the amount of shimming applied
-comes close to the leading currently in effect, making it seem as if
-there’s one linespace too much whitespace. The solution is
-simply to add <kbd>.SPACE -1v</kbd> or <kbd>.RLD 1v</kbd>
-to the document immediately after <kbd>.SHIM</kbd>. (Both
-<kbd>.SPACE -1v</kbd> and <kbd>.RLD 1v</kbd> back up
-by one linespace.)
+When flex-spacing is enabled, the FLEX macro inserts flexible
+vertical whitespace into a document. The amount of flex-space is
+determined from any extra whitespace at the bottom of a page divided
+by the number of flex points on the same page.
</p>
-<h4 id="automatic-shimming" class="docs">Automatic shimming of headings,
quotes, blockquotes, PDF images, and floats</h4>
<p style="margin-bottom: -1em">
-By default, mom automatically applies shimming
+If flex-spacing is enabled, mom herself automatically applies
+flex-spacing
</p>
-<ul>
+<ul style="margin-bottom: -.5em">
<li><i>before</i> headings</li>
<li><i>around</i> quotes and blockquotes</li>
- <li><i>after</i> PDF images, floats, and tables</li>
+ <li><i>after</i> PDF images, tables, pic diagrams, equations, and floats</li>
</ul>
<p>
-In documents where paragraphs are not spaced, automatic shimming is
-almost always desirable. In documents where paragraphs are spaced
-by an amount less than the document leading, or which have numerous
-graphics, headings, and quotes, you may want to disable shimming,
-either globally or on a tag-by-tag basis.
+Near the bottom of some pages, you may find that
+<a href="definitions.html#float">floated</a>
+or
+<a href="definitions.html#preprocessor">pre-proccesor material</a>,
+including images, or a single line of text afterward, is not flush
+with the bottom margin. This is a result of mom flex-spacing
+<i>after</i> such material but not before. The solution to is
+insert <kbd>.FLEX</kbd> immediately beforehand.
</p>
-<p id="disable-shim">
-<span style="font-weight: bold; font-style: italic; font-size: 95%">To disable
-automatic shimming</span>, invoke the macro, <kbd>.NO_SHIM</kbd>,
-either in the style sheet section of your document (ie after
-<a href="#printstyle">PRINTSTYLE</a>
-and before
-<a href="#start">START</a>),
-or just before
-<a href="docelement.html#heading">HEADING</a>,
-<a href="docelement.html#quote">QUOTE</a>,
-<a href="docelement.html#blockquote">BLOCKQUOTE</a>,
-<a href="images.html#pdf-image">PDF_IMAGE</a>
-<a href="images.html#float">FLOAT</a>.
+<p>
+There are some instances where mom inhibits flex-spacing, notably
+after outputting deferred floats and pre-processor material.
+Introducing FLEX by itself in these instances—say, before a head
+or paragraph—will not have any effect; you must pass FLEX the
+<kbd>FORCE</kbd> argument.
+</p>
+
+<div class="box-tip">
+<p class="tip">
+<span class="important">Important note on flex-spacing policy:</span><br/>
+Mom disables flex-spacing on
+</p>
+<ul style="margin-top: -1em; margin-bottom: -.5em">
+ <li>the last page or column of a document, before the Table of Contents,
+ Endnotes, Bibliography, and/or any “Lists of...”
+ </li>
+ <li>the page preceding a
+ <a href="rectoverso.html#collate">COLLATE</a>
+ </li>
+ <li>the page preceding a
+ <a href="typesetting.html#NEWPAGE">NEWPAGE</a>
+ or
+ <a href="headfootpage.html#blankpage">BLANKPAGE</a>
+ </li>
+ <li>the column preceding a
+ <a href="#col-next">COL_NEXT</a>
+ or
+ <a href="#col-break">COL_BREAK</a>
+ </li>
+</ul>
+
+<p>
+If this is not what you want, insert
+<a href="#no-flex"><kbd>.NO_FLEX OFF</kbd></a>
+before the first flex-space point on the affected page or in the
+affected column.
+</p>
+
+<p>
+Flex-spacing is also disabled for any page or column where
+insufficient room at or near the bottom causes a
+<a href="docelement.html#heading">HEADING</a>
or
-<a href="images.html#ts">TS</a>.
+<a href="images.html#tbl">table</a>
+to be moved to the top of the next page. These situations cannot
+be harmonized with flex-spacing except by adjusting your layout
+to prevent them. You may try re-enabling flex-spacing for the
+page (<kbd>.NO_FLEX OFF</kbd>) and manually inserting
+flex-spaces at appropriate points, but the original whitespace is
+usually large enough that re-distributing it merely changes
+one layout gaffe into another.
</p>
<p>
-Note that <kbd>.NO_SHIM</kbd> also disables the SHIM macro itself.
+Very occasionally you may notice that a document element (spaced
+paragraph, floated material, pre-processor material, or a PDF image)
+near the bottom of page has also caused mom to disable flex-spacing
+for that page. This occurs when the document element following it
+is a
+<a href="docelement.html#pp-space">spaced paragraph</a>.
</p>
-<p>To re-enable automatic shimming and the SHIM macro itself, use
-<kbd>.NO_SHIM OFF</kbd> (or <kbd>QUIT, END, X</kbd>, etc).
+<p>
+It is typographically acceptable for there to be space between
+insertions in running text (eg an image) and the bottom margin when
+the next page begins with a paragraph. If you’d like to
+nudge the insertion a little closer to the bottom margin—not
+all the way; that isn’t possible without pushing it to the
+next page and disrupting subsequent flex-spacing—insert a
+small amount of space beforehand with
+<a href="typesetting.html#sp">SP</a>.
+Do not, in these cases, use the <kbd>ADJUST</kbd>
+argument (for example to
+<a href="images.html#pdf-image">PDF_IMAGE</a>.)
+</p>
+
+<p class="tip-bottom">
+In the case of a spaced paragraph itself near the bottom of the page
+causing a break, re-enabling flex-spacing
+(<kbd>.NO_FLEX OFF</kbd>) at an appropriate place in your input
+file will resolve the issue, provided there is at least one
+flex-point on the page. If not, add one or more.
+</p>
+</div>
+
+<div class="macro-id-overline">
+<h3 id="no-flex" class="macro-id">NO_FLEX</h3>
+</div>
+
+<div class="box-macro-args">
+Macro: <b>NO_FLEX</b> <kbd class="macro-args"><none> |
<anything></kbd>
+</div>
+
+<p>
+NO_FLEX, without an argument, disables automatic flex-spacing
+and suppresses the FLEX macro. If, in addition to NO_FLEX, NO_SHIM
+has also been given, your document will be neither flex-spaced nor
+shimmed.
+</p>
+
+<p>
+NO_FLEX with any argument (eg <b>OFF, QUIT, END, X</b>, etc)
+re-enables flex-spacing if it has been disabled.
</p>
<div class="rule-short"><hr/></div>
@@ -566,8 +714,8 @@ and tag, but who’s ever satisfied with defaults? Use
any of
the
<a href="typesetting.html#macros-typesetting">typesetting macros</a>
here to change mom’s document defaults (paper size, margins,
-family, point size, line space, rag, etc), or use any of the
-document processing
+family, point size, line space, rag, etc), or any of the document
+processing
<a href="definitions.html#controlmacro">control macros</a>.
This is the style-sheet section of a document, and
must come after the
@@ -1566,7 +1714,7 @@ of a
<a href="#reference-macros">reference macro</a>,
<kbd><a href="#chapter">CHAPTER</a></kbd>).
If you give the chapter a title with
-<a href="#chapter-title">CHAPTER TITLE</a>,
+<a href="#chapter-title">CHAPTER_TITLE</a>,
mom prints “Chapter <n>” and the
title underneath. If you omit the
<a href="#chapter">CHAPTER</a>
@@ -2309,14 +2457,10 @@ in the
given to any of the
<a href="docprocessing.html#reference-macros">reference macros</a>,
nor in the string arguments given to
-<a href="docelement.html#head">HEAD</a>,
-<a href="docelement.html#subhead">SUBHEAD</a>
-or
-<a href="docelement.html#parahead">PARAHEAD</a>.
+<a href="docelement.html#heading">HEADING</a>.
Use, rather, the
<a href="definitions.html#controlmacro">control macros</a>
-mom provides to automatically colourize these
-elements.
+mom provides to automatically colourize these elements.
</p>
</div>
@@ -2428,7 +2572,7 @@ for an explanation of how to disable this default
behaviour.
</div>
<div class="box-macro-args">
-Macro: <b>DOCHEADER</b> <kbd class="macro-args"><toggle> [ distance to
advance from top of page ]</kbd>
+Macro: <b>DOCHEADER</b> <kbd class="macro-args"><toggle> [ distance to
advance from top of page ] [ NO_SHIM ]</kbd>
</div>
<p class="requires">
@@ -2480,7 +2624,7 @@ using mom’s typesetting macros. It is recommended
that if you
do create a custom docheader, you make
<a href="docprocessing.html#shim"><kbd>.SHIM</kbd></a>
the last macro before the first item of your document (for
-example, <kbd>.PP</kbd> or <kbd>.HEADING 1</kbd>. PP...)
+example, <kbd>PP</kbd> or <kbd>HEADING 1</kbd>.
</p>
<div class="box-tip">
@@ -2488,15 +2632,14 @@ example, <kbd>.PP</kbd> or <kbd>.HEADING 1</kbd>.
PP...)
<span class="note">Note:</span>
You may have tried <kbd>DOCHEAHER OFF</kbd> with a distance argument
and discovered that mom will not budge the starting position of the document
-from its default location. This is byproduct of
+from her chosen default location. This is byproduct of
<a href="#shim">shimming</a>,
-which is enabled by default. If you encounter the problem and you
-want shimming to remain the default, simply disable it (with
-<a href="#disable-shim">NO_SHIM</a>
-immediately prior to
-<a href="#start">START</a>
-and re-enable it immediately afterwards with
-<a href="#disable-shim">NO_SHIM OFF</a>.
+which mom always applies before the first line of running text after
+the docheader, regardless of which
+<a href="#vertical-whitespace-management">vertical whitespace management</a>
+strategy is in effect. If you encounter the problem, pass
+<kbd>DOCHEADER OFF <distance></kbd>
+the additional final argument, <kbd>NO_SHIM</kbd>.
</p>
</div>
@@ -3027,17 +3170,33 @@ or remove space after the docheader, there is no need
to invoke
<div class="box-tip">
<p class="tip">
<span class="note">Note:</span>
-If you add or subtract space after the docheader, e.g. with
+If you do add or subtract space after the docheader, e.g. with
<a href="typesetting.html#ald">ALD</a>
or
<a href="typesetting.html#SP">SP</a>,
and your
<a href="definitions.html#unitofmeasure">unit of measure</a>
-is something other than “<kbd>v</kbd>”, be sure to follow the
spacing
-command with
-<a href="docprocessing.html#shim"><kbd>.SHIM</kbd></a>
-unless shimming has been disabled with
-<a href="#disable-shim">NO_SHIM</a>.
+is something other than a multiple of “<kbd>v</kbd>”, be
+sure to follow the spacing command with
+<a href="docprocessing.html#shim">SHIM</a>
+before entering <kbd>.COL_MARK</kbd> unless shimming has been
+disabled with
+<a href="#no-shim">NO_SHIM</a>.
+If your document is being flex-spaced, do not use
+<a href="docprocessing.html#flex">FLEX</a>.
+Rather, disable flex-spacing with temporarily with
+<br/>
+<span class="pre-in-pp">
+ .NO_FLEX
+ .NO_SHIM off
+ .SHIM
+ .COL_MARK
+</span>
+and re-enable it afterwards with
+<span class="pre-in-pp">
+ .NO_SHIM
+ .NO_FLEX off
+</span>
</p>
</div>
@@ -3259,8 +3418,8 @@ the tops of pages after the first.)
a document will almost certainly result in a
bottom margin that doesn’t align with the
bottom margin of subsequent pages. You’ll
- need to use the SHIM macro to get mom back on
- track when you’re ready to return to the
+ need to use the SHIM or FLEX macro to get mom back
+ on track when you’re ready to return to the
document’s default leading.
<a id="autolead" style="margin-top: -1em">AUTOLEAD</a> •Invoked
before START, sets the overall document
@@ -3387,7 +3546,12 @@ Since adding space in this way is almost sure to disrupt
mom’s
ability to guarantee perfectly flush bottom margins, I highly
recommend using the
<a href="docprocessing.html#shim">SHIM</a>
-macro immediately after ADD_SPACE.
+or
+<a href="docprocessing.html#flex">FLEX</a>
+macro immediately after ADD_SPACE, which will add the space plus
+whatever correction is required by the
+<a href="docprocessing.html#vertical-whitespace-management">vertical
whitespace management</a>
+strategy in effect.
</p>
<!-- *** -->
diff --git a/contrib/mom/momdoc/goodies.html b/contrib/mom/momdoc/goodies.html
index 055a58f..81154e8 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-2016 Free Software Foundation, Inc.
+Copyright (C) 2004-2017 Free Software Foundation, Inc.
Written by Peter Schaffter (address@hidden).
Permission is granted to copy, distribute and/or modify this document
@@ -619,6 +619,15 @@ character to whatever the argument is. ESC_CHAR with no
argument
restores the escape character to the backslash.
</p>
+<div class="box-tip">
+<p class="tip">
+<span class="important">Important:</span>
+Changing the escape character prevents macros, which require that
+the backslash be the escape character, from functioning correctly.
+Do not introduce any subsequent macros without first restoring the
+escape character to its default.
+</p>
+</div>
<div class="box-tip">
<p class="tip">
@@ -713,6 +722,22 @@ UNDERSCORE. If you need to underscore several lines of
type, use
</p>
</div>
+<div class="box-tip">
+<p class="tip">
+<span class="note">Additional note:</span>
+In
+<a href="definitions.html#filled">nofill modes</a>,
+UNDERSCORE causes a break before and after, meaning the underscored
+word or phrase will appear as a separate line in your output. If
+you wish to embed an underscored word or phrase into non-filled
+text, temporarily change to the corresponding fill mode with
+<a href="typesetting.html#quad">QUAD</a>
+and insert breaks manually with
+<a href="typesetting.html#br">BR</a>
+as appropriate, reverting to the original nofill mode afterwards.
+</p>
+</div>
+
<h3 id="underscore-weight" class="docs">Controlling the weight of
underscores</h3>
<p>
The weight (thickness) of underscores may be controlled with the
@@ -828,6 +853,22 @@ the macro
(q.v).
</p>
+<div class="box-tip">
+<p class="tip">
+<span class="note">Note:</span>
+In
+<a href="definitions.html#filled">nofill modes</a>,
+UNDERSCORE2 causes a break before and after, meaning the double-underscored
+word or phrase will appear as a separate line in your output. If
+you wish to embed a double-underscored word or phrase into non-filled
+text, temporarily change to the corresponding fill mode with
+<a href="typesetting.html#quad">QUAD</a>
+and insert breaks manually with
+<a href="typesetting.html#br">BR</a>
+as appropriate, reverting to the original nofill mode afterwards.
+</p>
+</div>
+
<!-- -UNDERLINE- -->
<div class="macro-id-overline">
<h3 id="underline" class="macro-id">Underline</h3>
@@ -839,10 +880,10 @@ Macro: <b>UNDERLINE</b> <kbd
class="macro-args">toggle</kbd>
<p>
The distinction between underscoring and underlining is that
-underscoring is suitable for occasional effects (a word here, a word
-there), whereas underlining underlines whole passages of type.
-Furthermore, you cannot colorize underlining, and there’s a
-special macro,
+underscoring is suitable for occasional effects (a word here,
+a phrase there), whereas underlining underlines whole passages
+of type. Furthermore, you cannot colorize underlining, and
+there’s a special macro,
<a href="#underline-specs">UNDERLINE_SPECS</a>,
to control the weight and distance from the baseline of the
underline. Lastly, files that use UNDERLINE must be processed with
diff --git a/contrib/mom/momdoc/graphical.html
b/contrib/mom/momdoc/graphical.html
index 494f3d4..8d29ba1 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-2016 Free Software Foundation, Inc.
+Copyright (C) 2004-2017 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 76c9258..2ef2bf4 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-2016 Free Software Foundation, Inc.
+Copyright (C) 2004-2017 Free Software Foundation, Inc.
Written by Peter Schaffter (address@hidden).
Permission is granted to copy, distribute and/or modify this document
@@ -383,7 +383,7 @@ there’s no need to turn headers off first.
</p>
</div>
-<p>
+<p style="margin-top: -.5em">
If you need both headers and footers, there’s a special macro,
<a href="#headers-and-footers">HEADERS_AND_FOOTERS</a>,
that allows you to set it up.
@@ -1318,9 +1318,6 @@ but if you want a different gap, say, 2 centimetres, do
<span class="pre-in-pp">
.HEADER_GAP 2c
</span>
-</p>
-
-<p>
If your document uses
<a href="definitions.html#footer">footers</a>,
replace HEADER_, above, with FOOTER_. The argument to FOOTER_GAP
@@ -1357,6 +1354,32 @@ the number and the first line of running text with
HEADER_GAP.
</p>
</div>
+<div id="gap-note" class="box-tip">
+<p class="tip-top">
+<span class="note">Additional note:</span>
+HEADER_GAP and FOOTER_GAP may only be used once, at the start of a
+document. In
+<a href="rectoverso.html#collate">collated documents</a>,
+this means that HEADER_GAP or FOOTER_GAP cannot be used to change
+the gaps once they have been set. The same applies to the Table of
+Contents, Endnotes, Bibliographies, and Lists of... .
+</p>
+
+<p class="tip-bottom">
+In the event that you need to change the header or footer gap after
+the start of a document, you must do so with
+<a href="typesetting.html#t-margin">T_MARGIN</a>
+or
+<a href="typesetting.html#b-margin">B_MARGIN</a>,
+which raise or lower the top and bottom margins of
+<a href="definitions.html#running">running text</a>
+but do not affect the placement headers and footers.
+(See
+<a href="tables-of-contents.html#toc-page-settings-example">here</a>
+for a demonstration.)
+</p>
+</div>
+
<!-- -HDRFTR_SEPARATOR- -->
<h4 id="hdrftr-separator" class="docs">4. Header/footer separator rule</h4>
diff --git a/contrib/mom/momdoc/images.html b/contrib/mom/momdoc/images.html
index 8beeb68..54c7ee3 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-2016 Free Software Foundation, Inc.
+Copyright (C) 2004-2017 Free Software Foundation, Inc.
Written by Peter Schaffter (address@hidden).
Permission is granted to copy, distribute and/or modify this document
@@ -84,6 +84,7 @@ FDL in the main directory of the groff source package.
<li><a href="#captions-and-labels">Captions and labels</a>
<ul>
<li><a href="#autolabel">AUTOLABEL</a></li>
+ <li><a href="#set-autolabel">SET_AUTOLABEL</a></li>
<li><a href="#caption-after-label">CAPTION_AFTER_LABEL</a></li>
<li><a href="#captions-labels-sources">CAPTIONS / LABELS /
SOURCES</a>—set style parameters for each</li>
<li><a href="#mla">MLA</a></li>
@@ -185,13 +186,13 @@ Macro: <b>PDF_IMAGE</b> <kbd class="macro-args">[ -L | -C
| -R | -I <indent&g
<br/>
<image-file.pdf> <width> <height> [ SCALE <factor> ] \
<br/>
-[ ADJUST +|-<vertical adjustment> ] [ NO_SHIM ] \
+[ ADJUST +|-<vertical adjustment> ] [ NO_SHIM ] [ NO_FLEX ] \
<br/>
[ FRAME ] \
<br/>
[ CAPTION "<caption>" ] [ SHORT_CAPTION "<short caption>" ] \
<br/>
-[ LABEL "<label>" ]</kbd>
+[ LABEL "<label>" ] [ TARGET "<name>" ]</kbd>
</div>
<p class="requires">
• <span style="font-style: normal">
@@ -293,18 +294,31 @@ measure is required.
<p>
<kbd>NO_SHIM</kbd> instructs mom not to apply
-<a href="docprocessing.html#shim">shimming</a>
-after the image, which she does by default. Shimming ensures that
-running text after the image falls properly on the page’s baseline
-grid, but usually results in slightly unequal spacing above and
-below, which must be corrected with the <kbd>ADJUST</kbd> argument.
-Mom’s default shimming is generally a good idea since it ensures
-properly aligned bottom margins for running text, however if you
-have several images on the page, there may be visible differences in
-the spacing beneath images. <kbd>NO_SHIM</kbd> corrects the
-problem, but will result in running text that does not completely
-fill the page unless shimming is applied manually elsewhere on the
-same page.
+<a href="docprocessing.html#shim-vs-flex">shimming</a>
+after an image, which she will do automatically when shimming is
+enabled, which it is by default. Shimming ensures that running text
+after the image falls properly on the page’s
+<a href="definitions.html#baseline-grid">baseline grid</a>,
+but can result in slightly unequal spacing above and below
+(correctible with the <kbd>ADJUST</kbd> argument).
+<kbd>NO_SHIM</kbd> is useful when you have several images on the
+page and there are visible differences in the spacing beneath them
+as a result of shimming. To ensure a flush bottom margin, the last
+image on the page should be shimmed, ie should not be given the
+<kbd>NO_SHIM</kbd> argument.
+</p>
+
+<h5 class="docs" style="margin-top: 1em; text-transform: none">'NO_FLEX'</h5>
+
+<p>
+<kbd>NO_FLEX</kbd> instructs mom not to apply
+<a href="docprocessing.html#shim-vs-flex">flex-spacing</a>
+after an image, which she will do automatically when flex-spacing is
+enabled. <kbd>NO_FLEX</kbd> is useful when you have several images
+on the page and you want to distribute excess vertical
+whitespace on the page amongst other flex-spacing points on the
+page. If there are no others, the final image should be
+flex-spaced, ie not given the <kbd>NO_FLEX</kbd> argument.
</p>
<h5 class="docs" style="margin-top: 1em; text-transform: none">'FRAME'</h5>
@@ -346,6 +360,36 @@ an auto-labelling facility for images (see
which, if enabled, overrides the <kbd>LABEL</kbd> argument.
</p>
+<h5 class="docs" style="margin-top: 1em; text-transform: none">'TARGET'</h5>
+
+<p>
+<kbd>TARGET</kbd> followed by a unique name surrounded by
+double-quotes creates a PDF target for the image so that it may be
+linked to from other places in the file (with PDF_LINK; see
+<a href="version-2.html#mom-pdf">Producing PDFs with groff and mom</a>).
+</p>
+
+<p>
+When
+<a href="#autolabel">autolabelling</a>
+is enabled and the document is processed with
+<a href="using.html#pdfmom" style="font-weight: bold">pdfmom</a>,
+the target name can be used to generate the target’s label
+number in running text if it is entered as a groff string, ie of the
+form <kbd>\*[name]</kbd>. For example, if you create a target named
+“foo” for a pdf image whose autolabel number would be 3,
+entering
+<br/>
+<span class="pre-in-pp">
+ See
+ .PDF_LINK foo "Figure \*[foo]"
+</span>
+anywhere in running text would result in a pdf link that reads
+“Figure 3”. If chapter numbers are being prefixed to
+labels, the same string in, say, chapter 5 would produce the pdf
+link “Figure 5.3”.
+</p>
+
<p>
Remember that mom files with embedded PDF images must be processed
with
@@ -493,14 +537,18 @@ correct optical centering.
</p>
<p>
-Additionally, non-floated EPS images inserted into
-<a href="definitions.html#running">running text</a>
-will almost certainly disrupt the baseline placement of running
-text. In order to get mom back on track after inserting a
-non-floated <kbd>.PSPIC</kbd> image, I strongly recommend using the
+Additionally, non-floated EPS images
+will almost certainly disrupt the baseline placement of
+<a href="definitions.html#running">running text</a>.
+In order to get mom back on track after inserting a non-floated
+<kbd>.PSPIC</kbd> image, insert the
<a href="docprocessing.html#shim">SHIM</a>
-macro so that the bottom margin of running text falls where it
-should.
+or
+<a href="docprocessing.html#flex">FLEX</a>
+macro afterwards, depending on the
+<a href="docprocessing.html#vertical-whitespace-management">vertical
whitespace management</a>
+strategy in effect, so that the bottom margin of running text falls
+where it should.
</p>
<p>
@@ -555,9 +603,10 @@ previous page without interruption.
<p>
In the case of a float that doesn’t fit being followed by
-one that does, the second is output in position and the first is
-deferred. In the case of two or more that don’t fit, they are
-output in order on the next page.
+one that does, both are deferred and output one after the other.
+Note that this represents a change from versions 2.1-b_1 and earlier
+where the second float was output in position and the first was
+deferred.
</p>
<p>
@@ -600,12 +649,13 @@ not
Floats begin on the baseline immediately below the running text
preceding them. No additional whitespace surrounds them, above or
below. Running text below a float is, however,
-<a href="docprocessing.html#shim">shimmed</a>,
-unless shimming has been disabled with <kbd>.NO_SHIM</kbd> or the
-<kbd>NO_SHIM</kbd> argument is given to <kbd>FLOAT</kbd>. Shimming
-generally results in a small amount of extra whitespace after the
-float, which can be equalized with the whitespace beforehand using
-the <kbd>ADJUST</kbd> argument to FLOAT.
+<a href="docprocessing.html#shim">shimmed</a>
+or
+<a href="docprocessing.html#flex">flex-spaced</a>,
+depending on the
+<a href="docprocessing.html#vertical-whitespace-management">vertical
whitespace management</a>
+strategy in effect. This behaviour can be disabled for individual
+floats with <kbd>NO_SHIM</kbd> or <kbd>NO_FLEX</kbd>.
</p>
<p>
@@ -623,7 +673,7 @@ or
</div>
<div class="box-macro-args">
-Macro: <b>FLOAT</b> <kbd class="macro-args">[ ADJUST +|-<amount> ] [
FORCE ] [ SPAN ] [ NO_SHIM] | <anything></kbd>
+Macro: <b>FLOAT</b> <kbd class="macro-args">[ ADJUST +|-<amount> ] [
FORCE ] [ SPAN ] [ NO_SHIM] [ NO_FLEX ] | TARGET "<name>" |
<anything></kbd>
</div>
<div class="box-tip">
@@ -647,10 +697,11 @@ the space allotted to it</i> by the specified amount.
<a href="definitions.html#unitofmeasure">unit of measure</a>
appended. <kbd>ADJUST</kbd> gives you precise control over
the vertical centering of floats, allowing you to compensate for
-unequal spacing that may result of from the automatic shimming of
-floats (or the absence thereof). See
-<a href="docprocessing.html#shim">SHIM</a>
-for a discussion of automatic shimming.
+unequal spacing that may result of from the automatic
+<a href="docprocessing.html#shim">shimming</a>
+or
+<a href="docprocessing.html#flex">flex-spacing</a>
+floats.
</p>
<p>
@@ -675,22 +726,59 @@ a warning should this occur. Unboxed tables, on the
other hand, are
acceptable within floats that are given the <kbd>SPAN</kbd> argument.
</p>
+<h5 class="docs" style="margin-top: 1em; text-transform: none">'NO_SHIM'</h5>
+
<p>
<kbd>NO_SHIM</kbd> instructs mom not to apply
-<a href="docprocessing.html#shim">shimming</a>
-after the float, which she does by default. Shimming ensures that
-running text after the float falls properly on the page’s baseline
-grid, but usually results in slightly unequal spacing above and
-below, which must be corrected with the <kbd>ADJUST</kbd> argument.
-Mom’s default shimming is generally a good idea since it ensures
-properly aligned bottom margins for running text, however if you
-have several floats on the page, there may be visible differences in
-the spacing beneath them. <kbd>NO_SHIM</kbd> corrects the
-problem, but will result in running text that does not completely
-fill the page unless shimming is applied manually elsewhere on the
-same page.
+<a href="docprocessing.html#shim-vs-flex">shimming</a>
+after a float, which she will do automatically when shimming is
+enabled, which it is by default. Shimming ensures that running text
+after the float falls properly on the page’s
+<a href="definitions.html#baseline-grid">baseline grid</a>,
+but can result in slightly unequal spacing above and below
+(correctible with the <kbd>ADJUST</kbd> argument).
+<kbd>NO_SHIM</kbd> is useful when you have several floats on the
+page and there are visible differences in the spacing beneath them
+as a result of shimming. To ensure a flush bottom margin, the last
+float on the page should be shimmed, ie should not be given the
+<kbd>NO_SHIM</kbd> argument.
</p>
+<h5 class="docs" style="margin-top: 1em; text-transform: none">'NO_FLEX'</h5>
+
+<p>
+<kbd>NO_FLEX</kbd> instructs mom not to apply
+<a href="docprocessing.html#shim-vs-flex">flex-spacing</a>
+after a float, which she will do automatically when flex-spacing is
+enabled. <kbd>NO_FLEX</kbd> is useful when you have several floats
+on the page and you want to distribute excess vertical
+whitespace on the page amongst other flex-spacing points on the
+page. If there are no others, the final float should be
+flex-spaced, ie not given the <kbd>NO_FLEX</kbd> argument.
+</p>
+
+<h5 class="docs" style="margin-top: 1em; text-transform: none">'TARGET'</h5>
+
+<p>
+<kbd>TARGET</kbd> followed by a unique name surrounded by
+double-quotes creates a PDF target for the float so that it may be
+linked to from other places in the file (with PDF_LINK; see
+<a href="version-2.html#mom-pdf">Producing PDFs with groff and mom</a>).
+</p>
+
+<p>
+Floats cannot be autolabelled, so unlike pdf images and
+pre-processor material, the target name cannot be used as a string
+to generate the target’s label number in running text. Label
+numbers for floats must be entered explicitly running text, however
+they may be entered symbolically in the argument to
+<a href="#label">LABEL</a>.
+See
+<a href="#reserved-label-strings">Reserved variables for
+labels</a>.
+</p>
+
+
<div class="box-tip">
<p class="tip-top">
<span class="note">Note:</span>
@@ -724,8 +812,7 @@ Labelling and captioning of tables (<b>tbl</b>), equations
are handled by the macros that initiate them, regardless of whether
they’re wrapped inside a float. However, since a float may
contain any valid input, it is sometimes necessary to add a label
-and/or caption to the float itself when it is not being used to
-contain preprocessor input.
+and/or caption to the float itself.
</p>
<div class="box-tip">
@@ -785,18 +872,22 @@ If a float has a caption at the top, the caption is
whitespaced
an additional 1/4 linespace below the caption. If the float has
no corresponding label at the bottom, the float observes the
bottom-spacing rules for all floats, namely that no extra space is
-added except whatever
+added other than
<a href="docprocessing.html#shim">shimming</a>
-is necessary to restore proper baseline alignment.
+or
+<a href="docprocessing.html#shim-vs-flex">flex-spacing</a>,
+depending on the
+<a href="docprocessing.html#vertical-whitespace-management">vertical
whitespace management</a>
+in effect.
</p>
<p>
If a float has a label at the bottom but no caption at the top, the
float begins exactly where started, i.e. with no extra whitespace
between running text and the float. The label (and attached
-caption, if any) are whitespaced 1/4 linespace below the float, with
-an additional 1/4 linespace underneath <i>plus</i> whatever shimming is
-needed to restore proper baseline alignment.
+caption, if any) are whitespaced 1/4 linespace below the float,
+with an additional 1/4 linespace underneath <i>plus</i> shimming or
+flex-spacing.
</p>
<p>
@@ -847,11 +938,12 @@ before ending the float:
<h3 id="reserved-label-strings" class="docs" style="text-transform:
none">Reserved variables for labels</h3>
<p>
-Mom reserves two variables you may use when entering label text
-after the <kbd>LABEL</kbd> argument.
-<kbd>\*[chapter]</kbd> holds the current chapter or major section
-number. <kbd>\*[label]</kbd> increments the label number by one
-and is initially set to zero after each invocation of
+Mom reserves strings you may use when entering label text after
+the <kbd>LABEL</kbd> argument. <kbd>\*[chapter]</kbd> holds the
+current chapter or major section number. <kbd>\*[fig-label]</kbd>,
+<kbd>\*[tbl-label]</kbd>, and <kbd>\*[eqn-label]</kbd>
+increment the label number of the appropriate label type by one,
+and are initially set to zero after each invocation of
<a href="docprocessing.html#start">START</a>
when the
<a href="docprocessing.html#doctype">DOCTYPE</a>
@@ -859,18 +951,20 @@ is <kbd>CHAPTER</kbd>. Thus, in every chapter requiring
numbered
float labels, you can enter
<br/>
<span class="pre-in-pp">
- .LABEL "Fig. \*[chapter].\*[label].
+ .LABEL "Fig. \*[chapter].\*[fig-label]. TO_LIST FIGURES
</span>
-which, assuming the third labelled float of Chapter 2 will produce
-<kbd>Fig. 2.3.</kbd>
+which, assuming the third autolabelled float of Chapter 2, will
+produce <kbd>Fig. 2.3.</kbd>
</p>
<p>
If your <b>DOCTYPE</b> is <kbd>DEFAULT</kbd> or <kbd>NAMED</kbd>,
-you must reset <kbd>\*[label]</kbd> by entering
+you must reset <kbd>\*[<type>-label]</kbd> after each
+<a href="docprocessing.html#collate">COLLATE</a>
+by entering
<br/>
<span class="pre-in-pp">
- .AUTOLABEL <list type>
+ .AUTOLABEL_<list type>
</span>
before <kbd>.START</kbd>.
</p>
@@ -878,7 +972,7 @@ before <kbd>.START</kbd>.
<p>
If
<a href="#autolabel">autolabelling</a>
-is enabled, e.g. <kbd>.AUTOLABEL_IMAGES</kbd> (List
+is enabled, eg <kbd>.AUTOLABEL_IMAGES</kbd> (List
of Figures) or <kbd>.AUTOLABEL_PIC</kbd> (also List of Figures),
the prefix is stripped from the label when it appears in
the List. Thus, if you have invoked <kbd>.AUTOLABEL_PIC</kbd>,
@@ -905,7 +999,7 @@ label”.
If you’d like a caption attached to the label, pass
<kbd>LABEL</kbd> the optional argument <kbd>CAPTION</kbd> followed
by the text of the caption as a single string surrounded by
-double-quotes: <br/>
+double-quotes:
<br/>
<span class="pre-in-pp">
.FLOAT
@@ -1158,14 +1252,22 @@ Unboxed tables inside floats may span multiple pages
provided the
<span class="note">Note:</span>
The vertical spacing around unfloated tables may appear slightly
unequal, especially if there are several tables on the page. This
-is a result of
+is a result of the
<a href="docprocessing.html#shim">shimming</a>
-that mom applies automatically after each table. You may
-disable shimming with <kbd>.NO_SHIM</kbd>, or by giving the
-<kbd>NO_SHIM</kbd> argument to <kbd>.TS</kbd>. In either case, you
-will still likely want to adjust the spacing around with table with
-the <kbd>AJUST</kbd> argument to <kbd>.TS</kbd>. Tables inside
-floats should be adjusted with the <kbd>ADJUST</kbd> argument to
+or
+<a href="docprocessing.html#flex">flex-spacing</a>
+that mom applies automatically after each table, depending on which
+<a href="docprocessing.html#vertical-whitespace-management">vertical
whitespace management</a>
+is in effect. You may
+disable shimming or flex-spacing with
+<a href="docprocessing.html#no-shim">NO_SHIM</a>
+or
+<a href="docprocessing.html#no-flex">NO_FLEX</a>,
+or by passing the <kbd>NO_SHIM</kbd> or <kbd>NO_FLEX</kbd> argument
+to <kbd>.TS</kbd>. In either case, you will still likely want to
+adjust the spacing around with table with the <kbd>AJUST</kbd>
+argument to <kbd>.TS</kbd>. Tables inside floats should be adjusted
+with the <kbd>ADJUST</kbd> argument to
<a href="#float">FLOAT</a>,
not the <kbd>ADJUST</kbd> argument to <kbd>.TS</kbd>.
</p>
@@ -1196,11 +1298,15 @@ required)
<kbd class="macro-args"><br/>
[ NO_SHIM ]
<br/>
+ [ NO_FLEX ]
+<br/>
[ CAPTION "<caption>" ]
<br/>
[ SHORT_CAPTION "<short caption>" ]
<br/>
[ LABEL "<label>" ]
+<br/>
+ [ TARGET "<name>" ]
</kbd>
<br/>
Macro: <a href="#th"><b>TH</b></a> <kbd class="macro-args">(optional, only if
.TS H)</kbd>
@@ -1384,19 +1490,33 @@ measure is required.
<p>
<kbd>NO_SHIM</kbd> instructs mom not to apply
-<a href="docprocessing.html#shim">shimming</a>
-after the image, which she does by default. Shimming ensures that
-running text after the image falls properly on the page’s baseline
-grid, but usually results in slightly unequal spacing above and
-below, which must be corrected with the <kbd>ADJUST</kbd> argument.
-Mom’s default shimming is generally a good idea since it ensures
-properly aligned bottom margins for running text, however if you
-have several images on the page, there may be visible differences in
-the spacing beneath images. <kbd>NO_SHIM</kbd> corrects the
-problem, but will result in running text that does not completely
-fill the page unless shimming is applied manually elsewhere on the
-same page.
+<a href="docprocessing.html#shim-vs-flex">shimming</a>
+after a table, which she will do automatically when shimming is
+enabled, which it is by default. Shimming ensures that running text
+after the table falls properly on the page’s
+<a href="definitions.html#baseline-grid">baseline grid</a>,
+but can result in slightly unequal spacing above and below
+(correctible with the <kbd>ADJUST</kbd> argument).
+<kbd>NO_SHIM</kbd> is useful when you have several tables on the
+page and there are visible differences in the spacing beneath them
+as a result of shimming. To ensure a flush bottom margin, the last
+table on the page should be shimmed, ie should not be given the
+<kbd>NO_SHIM</kbd> argument.
</p>
+
+<h5 class="docs" style="margin-top: 1em; text-transform: none">'NO_FLEX'</h5>
+
+<p>
+<kbd>NO_FLEX</kbd> instructs mom not to apply
+<a href="docprocessing.html#shim-vs-flex">flex-spacing</a>
+after a table, which she will do automatically when flex-spacing is
+enabled. <kbd>NO_FLEX</kbd> is useful when you have several tables
+on the page and you want to distribute excess vertical
+whitespace on the page amongst other flex-spacing points on the
+page. If there are no others, the final table should be
+flex-spaced, ie not given the <kbd>NO_FLEX</kbd> argument.
+</p>
+
<h5 class="docs" style="margin-top: 1em; text-transform: none">'CAPTION'</h5>
<p>
@@ -1435,6 +1555,36 @@ an auto-labelling facility for tables (see
which, if enabled, overrides the <kbd>LABEL</kbd> argument.
</p>
+<h5 class="docs" style="margin-top: 1em; text-transform: none">'TARGET'</h5>
+
+<p>
+<kbd>TARGET</kbd> followed by a unique name surrounded by
+double-quotes creates a PDF target for the table so that it may be
+linked to from other places in the file (with PDF_LINK; see
+<a href="version-2.html#mom-pdf">Producing PDFs with groff and mom</a>).
+</p>
+
+<p>
+When
+<a href="#autolabel">autolabelling</a>
+is enabled and the document is processed with
+<a href="using.html#pdfmom" style="font-weight: bold">pdfmom</a>,
+the target name can be used to generate the target’s label
+number in running text if it is entered as a groff string, ie of
+the form <kbd>\*[name]</kbd>. For example, if you create a target
+called “foo” for a table whose autolabel number would be
+3, entering
+<br/>
+<span class="pre-in-pp">
+ See
+ .PDF_LINK foo "Table \*[foo]"
+</span>
+anywhere in running text would result in a pdf link that reads
+“Table 3”. If chapter numbers are being prefixed to
+labels, the same string in, say, chapter 5 would produce the pdf
+link “Table 5.3”.
+</p>
+
<div class="macro-id-overline">
<h4 id="th" class="docs" style="font-size: 100%; margin-top: .5em">The .TH
macro</h4>
</div>
@@ -1555,12 +1705,16 @@ required)
<kbd class="macro-args"><br/>
[ NO_SHIM ]
<br/>
+ [ NO_FLEX ]
+<br/>
[ CAPTION "<caption>" ]
<br/>
[ SHORT_CAPTION "<short caption>" ]
<br/>
[ LABEL "<label>" ]
</kbd>
+ [ TARGET "<name>" ]
+</kbd>
<br/>
Macro: <b>PE</b> <span style="font-size: 95%">(no arguments; ends
the <b>pic</b> block)</span>
@@ -1606,18 +1760,31 @@ measure is required.
<p>
<kbd>NO_SHIM</kbd> instructs mom not to apply
-<a href="docprocessing.html#shim">shimming</a>
-after the diagram, which she does by default. Shimming ensures that
-running text after the diagram falls properly on the page’s baseline
-grid, but usually results in slightly unequal spacing above and
-below, which must be corrected with the <kbd>ADJUST</kbd> argument.
-Mom’s default shimming is generally a good idea since it ensures
-properly aligned bottom margins for running text, however if you
-have several diagrams on the page, there may be visible differences in
-the spacing beneath them. <kbd>NO_SHIM</kbd> corrects the
-problem, but will result in running text that does not completely
-fill the page unless shimming is applied manually elsewhere on the
-same page.
+<a href="docprocessing.html#shim-vs-flex">shimming</a>
+after a <b>pic</b> diagrame, which she will do automatically when
+shimming is enabled, which it is by default. Shimming ensures that
+running text after the diagrame falls properly on the page’s
+<a href="definitions.html#baseline-grid">baseline grid</a>,
+but can result in slightly unequal spacing above and below
+(correctible with the <kbd>ADJUST</kbd> argument).
+<kbd>NO_SHIM</kbd> is useful when you have several diagrams on the
+page and there are visible differences in the spacing beneath them
+as a result of shimming. To ensure a flush bottom margin, the last
+diagram on the page should be shimmed, ie should not be given the
+<kbd>NO_SHIM</kbd> argument.
+</p>
+
+<h5 class="docs" style="margin-top: 1em; text-transform: none">'NO_FLEX'</h5>
+
+<p>
+<kbd>NO_FLEX</kbd> instructs mom not to apply
+<a href="docprocessing.html#shim-vs-flex">flex-spacing</a>
+after a <b>pic</b> diagram, which she will do automatically when
+flex-spacing is enabled. <kbd>NO_FLEX</kbd> is useful when you
+have several diagrams on the page and you want to distribute excess
+vertical whitespace on the page amongst other flex-spacing points
+on the page. If there are no others, the final diagram should be
+flex-spaced, ie not given the <kbd>NO_FLEX</kbd> argument.
</p>
<h5 class="docs" style="margin-top: 1em; text-transform: none">'CAPTION'</h5>
@@ -1651,6 +1818,36 @@ an auto-labelling facility for diagrams (see
which, if enabled, overrides the <kbd>LABEL</kbd> argument.
</p>
+<h5 class="docs" style="margin-top: 1em; text-transform: none">'TARGET'</h5>
+
+<p>
+<kbd>TARGET</kbd> followed by a unique name surrounded by
+double-quotes creates a PDF target for the diagram so that it may be
+linked to from other places in the file (with PDF_LINK; see
+<a href="version-2.html#mom-pdf">Producing PDFs with groff and mom</a>).
+</p>
+
+<p>
+When
+<a href="#autolabel">autolabelling</a>
+is enabled and the document is processed with
+<a href="using.html#pdfmom" style="font-weight: bold">pdfmom</a>,
+the target name can be used to generate the target’s label
+number in running text if it is entered as a groff string, ie of
+the form <kbd>\*[name]</kbd>. For example, if you create a target
+called “foo” for a diagram whose autolabel number would
+be 3, entering
+<br/>
+<span class="pre-in-pp">
+ See
+ .PDF_LINK foo "Figure \*[foo]"
+</span>
+anywhere in running text would result in a pdf link that reads
+“Figure 3”. If chapter numbers are being prefixed to
+labels, the same string in, say, chapter 5 would produce the pdf
+link “Figure 5.3”.
+</p>
+
<!---PIC_TEXT_STYLE--->
<div class="macro-id-overline">
@@ -1738,6 +1935,10 @@ required)
required)
</span>
<kbd class="macro-args"><br/>
+ [ NO_SHIM ]
+<br/>
+ [ NO_FLEX ]
+<br/>
[ CAPTION "<caption>" ]
<br/>
[ LABEL "<label>" ]
@@ -1746,6 +1947,8 @@ required)
<br/>
[ SHORT_CAPTION "<short caption>" ]
<br/>
+ [ TARGET "<name>" ]
+<br/>
Macro: <a href="#en"><b>EN</b></a> <kbd class="macro-args"> [ CONTINUED | CONT
| ... ]</kbd>
</div>
@@ -1804,18 +2007,31 @@ measure is required.
<p>
<kbd>NO_SHIM</kbd> instructs mom not to apply
-<a href="docprocessing.html#shim">shimming</a>
-after the equation, which she does by default. Shimming ensures that
-running text after the equation falls properly on the page’s baseline
-grid, but usually results in slightly unequal spacing above and
-below, which must be corrected with the <kbd>ADJUST</kbd> argument.
-Mom’s default shimming is generally a good idea since it ensures
-properly aligned bottom margins for running text, however if you
-have several equations on the page, there may be visible differences in
-the spacing beneath them. <kbd>NO_SHIM</kbd> corrects the
-problem, but will result in running text that does not completely
-fill the page unless shimming is applied manually elsewhere on the
-same page.
+<a href="docprocessing.html#shim-vs-flex">shimming</a>
+after an equation, which she will do automatically when shimming is
+enabled, which it is by default. Shimming ensures that running text
+after the equation falls properly on the page’s
+<a href="definitions.html#baseline-grid">baseline grid</a>,
+but can result in slightly unequal spacing above and
+below (correctible with the <kbd>ADJUST</kbd> argument).
+<kbd>NO_SHIM</kbd> is useful when you have several equations on the
+page and there are visible differences in the spacing beneath them
+as a result of shimming. To ensure a flush bottom margin, the last
+equation on the page should be shimmed, ie should not be given the
+<kbd>NO_SHIM</kbd> argument.
+</p>
+
+<h5 class="docs" style="margin-top: 1em; text-transform: none">'NO_FLEX'</h5>
+
+<p>
+<kbd>NO_FLEX</kbd> instructs mom not to apply
+<a href="docprocessing.html#shim-vs-flex">flex-spacing</a>
+after an equation, which she will do automatically when flex-spacing
+is enabled. <kbd>NO_FLEX</kbd> is useful when you have several
+equations on the page and you want to distribute excess vertical
+whitespace on the page amongst other flex-spacing points on
+the page. If there are no others, the final equation should be
+flex-spaced, ie not given the <kbd>NO_FLEX</kbd> argument.
</p>
</p>
@@ -1858,6 +2074,37 @@ with the last line. Assuming a three-line equation,
one line, thus centering it vertically on the equation.
</p>
+<h5 class="docs" style="margin-top: 1em; text-transform: none">'TARGET'</h5>
+
+<p>
+<kbd>TARGET</kbd> followed by a unique name surrounded by
+double-quotes creates a PDF target for the equation so that it may
+be linked to from other places in the file (with PDF_LINK; see
+<a href="version-2.html#mom-pdf">Producing PDFs with groff and mom</a>).
+</p>
+
+<p>
+When
+<a href="#autolabel">autolabelling</a>
+is enabled and the document is processed with
+<a href="using.html#pdfmom" style="font-weight: bold">pdfmom</a>,
+the target name can be used to generate the target’s label
+number in running text if it is entered as a groff string, ie of
+the form <kbd>\*[name]</kbd>. For example, if you create a target
+called “foo” for an equation whose autolabel number
+would be 3, entering
+<br/>
+<span class="pre-in-pp">
+ See
+ .PDF_LINK foo "Equation \*[foo]"
+</span>
+anywhere in running text would result in a pdf link that reads
+“Equation 3”. If chapter numbers are being prefixed to
+labels, the same string in, say, chapter 5 would produce the pdf
+link “Equation 5.3”.
+</p>
+
+
<div class="macro-id-overline" style="margin-top: .5em">
<h4 id="en" class="docs" style="font-size: 100%; margin-top: .5em">The .EN
macro</h4>
</div>
@@ -2063,8 +2310,37 @@ is <i>not</i> reset automatically. To reset it, invoke
<a href="docprocessing.html#collate">COLLATE</a>.
</div>
+<div id="set-autolabel" class="box-macro-args" style="margin-top: .5em">
+Macro: <b>SET_AUTOLABEL</b> <kbd class="macro-args">FIG | TBL | PIC | EQN
<n></kbd>
+</div>
+
+<p>
+You may sometimes need to set or reset the autolabel number for a
+particular type of pre-processor or for PDF images. This is likely
+to occur if you are using
+<a href="#float">FLOAT</a>
+in conjunction with the <kbd>TO_LIST</kbd> argument.
+</p>
+
<p>
-Prefixed chapter numbers
+For example, if your document has Figures (PDF images, pic diagrams)
+and you want your tables to be labelled as Figures as well, you have
+to wrap the tables inside a float and label the float manually as
+“Fig. n”, sending it to the List of Figures with
+<kbd>TO_LIST FIGURES</kbd>.
+</p>
+
+<p>
+Mom does not autolabel floats or assign them automatically
+to a list, so she doesn’t know you’ve interrupted the
+auto-incrementing label numbers. Use SET_AUTOLABEL get her back on
+track. The number you give as an argument after telling her which
+kind of label number to set is the one you want to appear next.
+<br/>
+<span class="pre-in-pp">
+ .SET_AUTOLABEL FIG 6
+</span>
+means the next autolabelled Figure will be “Fig. 6.”
</p>
<div class="macro-id-overline">
@@ -2471,6 +2747,8 @@ Arguments:
<br/>
TITLE_QUAD LEFT | CENTER | RIGHT \
<br/>
+ TOC_HEADER_UNDERSCORE default = none
+<br/>
TITLE_COLOR <color> \
<br/>
PN_FAMILY <family> \
diff --git a/contrib/mom/momdoc/inlines.html b/contrib/mom/momdoc/inlines.html
index 0bc5723..f8d93b1 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-2016 Free Software Foundation, Inc.
+Copyright (C) 2004-2017 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 1632fef..11d20b9 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-2016 Free Software Foundation, Inc.
+Copyright (C) 2004-2017 Free Software Foundation, Inc.
Written by Peter Schaffter (address@hidden).
Permission is granted to copy, distribute and/or modify this document
@@ -70,8 +70,8 @@ PostScript (.ps). She’s aimed at three kinds of users:
not-always-typographically-intuitive
<a href="definitions.html#primitives">primitives</a>;
</li>
- <li>Non-technical writers who need to format their work easily,
- with a minimum of clutter;
+ <li>Writers who need to format their work easily, with a
+ minimum of clutter;
</li>
<li>Newcomers to groff, typesetting, or document processing
who need a well-documented macro set to get them started.
@@ -293,7 +293,7 @@ aren’t enough, I offer examples.
The canonical reference materials for groff are
<strong>cstr54</strong> (a downloadable PostScript copy of which
is available
-<a href="http://www.kohala.com/start/troff/";>here</a>)
+<a href="http://www.kohala.com/start/troff/cstr54.ps";>here</a>)
and the <strong>troff</strong> and <strong>groff_diff</strong>
manpages. The most complete and up-to-date source of information is
the groff info pages, available by typing <kbd>info groff</kbd> at
diff --git a/contrib/mom/momdoc/letters.html b/contrib/mom/momdoc/letters.html
index 572ac46..0531534 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-2016 Free Software Foundation, Inc.
+Copyright (C) 2004-2017 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 f48cf11..721acb6 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-2016 Free Software Foundation, Inc.
+Copyright (C) 2004-2017 Free Software Foundation, Inc.
Written by Peter Schaffter (address@hidden).
Permission is granted to copy, distribute and/or modify this document
@@ -77,14 +77,15 @@ elsewhere in the documentation.
<li><a href="#qr-19">Reference macros (metadata)</a></li>
<li><a href="#qr-20">Document type and initial defaults</a></li>
<li><a href="#qr-23">TYPEWRITE control macros</a></li>
+ <li><a href="#qr-57">Vertical whitespace management</a></li>
<li><a href="#qr-47">Document and section cover (title) pages</a></li>
<li><a href="#qr-22">Set documents in columns</a></li>
<li><a href="#qr-21">Line numbering</a></li>
<li><a href="#qr-24">Initiate document processing</a></li>
- <li><a href="#qr-42">Global print style changes after START</a></li>
</ul>
</div>
<ul style="margin-top: 1.75em; margin-left: 0; padding-left: 0;
list-style-type: none;">
+ <li><a href="#qr-42">Global print style changes after START</a></li>
<li><a href="#qr-43">Managing a document’s first-page header<br/><span
style="margin-left: 1.25em;">(the “docheader”)</span></a></li>
<li><a href="#qr-25">Epigraphs</a></li>
<li><a href="#qr-26">Headings</a></li>
@@ -121,7 +122,8 @@ elsewhere in the documentation.
<table class="quick-ref">
<tr>
-<th id="qr-1" class="quick-ref" colspan="2" >+++ Paper size, margins, line
length</th>
+<th id="qr-1" class="quick-ref" colspan="2" >
+<a href="typesetting.html#page-setup-intro">+++ Paper size, margins, line
length</a></th>
</tr>
<tr>
<td><a href="typesetting.html#paper">PAPER</a></td><td>-- set common paper
sizes (letter, A4, etc)</td>
@@ -153,7 +155,8 @@ elsewhere in the documentation.
</table>
<table class="quick-ref">
-<tr><th id="qr-2" class="quick-ref" colspan="2">+++ Family, font, point
size</th></tr>
+<tr><th id="qr-2" class="quick-ref" colspan="2">
+<a href="typesetting.html#basic-params-intro">+++ Family, font, point
size</a></th></tr>
<tr>
<td><a href="typesetting.html#family">FAMILY</a></td><td>-- set the family of
type</td>
</tr>
@@ -173,7 +176,8 @@ elsewhere in the documentation.
<table class="quick-ref">
<tr>
-<th id="qr-3" class="quick-ref" colspan="2" >+++ Font modifications</th>
+<th id="qr-3" class="quick-ref" colspan="2" >
+<a href="typesetting.html#modifications-intro">+++ Font modifications</a></th>
</tr>
<tr><td style="padding-left: 0;">Pseudo italic</td></tr>
<tr>
@@ -231,7 +235,8 @@ elsewhere in the documentation.
<table class="quick-ref">
<tr>
-<th id="qr-5" class="quick-ref" colspan="2" >+++ Justification, quad
direction, line-by-line setting, breaking lines</th>
+<th id="qr-5" class="quick-ref" colspan="2" >
+<a href="typesetting.html#justification-intro">+++ Justification, quad
direction, line-by-line setting, breaking lines</a></th>
</tr>
<tr>
<td><a href="typesetting.html#justify">JUSTIFY</a></td><td>-- justify text to
both margins</td>
@@ -315,7 +320,8 @@ elsewhere in the documentation.
<table class="quick-ref">
<tr>
-<th id="qr-9" class="quick-ref" colspan="2" >+++ Horizontal and vertical
movements, columnar setting</th>
+<th id="qr-9" class="quick-ref" colspan="2" >
+<a href="typesetting.html#aldrld-intro">+++ Horizontal and vertical movements,
columnar setting</a></th>
</tr>
<tr>
<td><a href="typesetting.html#ald">ALD</a></td><td>-- move downards on the
page</td>
@@ -351,7 +357,8 @@ elsewhere in the documentation.
<table class="quick-ref">
<tr>
-<th id="qr-10" class="quick-ref" colspan="2" >+++ Indents</th>
+<th id="qr-10" class="quick-ref" colspan="2" >
+<a href="typesetting.html#indents-intro">+++ Indents</a></th>
</tr>
<tr>
<td><a href="typesetting.html#il">IL</a></td><td>-- set and turn on a left
indent</td>
@@ -384,7 +391,8 @@ elsewhere in the documentation.
<table class="quick-ref">
<tr>
-<th id="qr-11" class="quick-ref" colspan="2" >+++ Tabs</th>
+<th id="qr-11" class="quick-ref" colspan="2" >
+<a href="typesetting.html#tabs-intro">+++ Tabs</a></th>
</tr>
<tr>
<td><a href="typesetting.html#tab-set">TAB_SET</a></td><td>-- set up a
typesetting tab</td>
@@ -450,7 +458,8 @@ elsewhere in the documentation.
<table class="quick-ref">
<tr>
-<th id="qr-14" class="quick-ref" colspan="2" >+++ Nested lists</th>
+<th id="qr-14" class="quick-ref" colspan="2" >
+<a href="docelement.html#list-intro">+++ Nested lists</a></th>
</tr>
<tr>
<td><a href="docelement.html#list">LIST</a></td><td>-- begin a list</td>
@@ -471,7 +480,8 @@ elsewhere in the documentation.
<table class="quick-ref">
<tr>
-<th id="qr-15" class="quick-ref" colspan="2" >+++ Colour</th>
+<th id="qr-15" class="quick-ref" colspan="2" >
+<a href="color.html#color-intro">+++ Colour</a></th>
</tr>
<tr>
<td><a href="color.html#newcolor">NEWCOLOR</a></td><td>-- initialize (define)
a colour</td>
@@ -571,7 +581,8 @@ elsewhere in the documentation.
<table class="quick-ref">
<tr>
-<th id="qr-18" class="quick-ref" colspan="2" >+++ Graphical objects and
images</th>
+<th id="qr-18" class="quick-ref" colspan="2" >
+<a href="graphical.html#intro-graphical">+++ Graphical objects and
images</a></th>
</tr>
<tr>
<td><a href="graphical.html#drh">DRH</a></td><td>-- draw a horizontal rule</td>
@@ -600,7 +611,8 @@ elsewhere in the documentation.
<table class="quick-ref">
<tr>
-<th id="qr-19" class="quick-ref" colspan="2" >+++ Reference macros</th>
+<th id="qr-19" class="quick-ref" colspan="2" >
+<a href="docprocessing.html#reference-macros">+++ Reference macros</a></th>
</tr>
<tr>
<td><a href="docprocessing.html#title">TITLE</a></td><td>-- document title</td>
@@ -654,7 +666,8 @@ elsewhere in the documentation.
<table class="quick-ref">
<tr>
-<th id="qr-20" class="quick-ref" colspan="2" >+++ General document formatting
directives</th>
+<th id="qr-20" class="quick-ref" colspan="2" >
+<a href="docprocessing.html#docstyle-macros">+++ General document formatting
directives</a></th>
</tr>
<tr>
<td><a href="docprocessing.html#doctype">DOCTYPE</a></td><td>-- general
document type</td>
@@ -669,7 +682,8 @@ elsewhere in the documentation.
<table class="quick-ref">
<tr>
-<th id="qr-21" class="quick-ref" colspan="2" >+++ Line numbering</th>
+<th id="qr-21" class="quick-ref" colspan="2" >
+<a href="docelement.html#number-lines-intro">+++ Line numbering</a></th>
</tr>
<tr>
<td><a href="docelement.html#number-lines">NUMBER_LINES</a></td><td>--
automatic line numbering on/off</td>
@@ -687,7 +701,8 @@ elsewhere in the documentation.
<table class="quick-ref">
<tr>
-<th id="qr-22" class="quick-ref" colspan="2" >+++ Set documents in columns</th>
+<th id="qr-22" class="quick-ref" colspan="2" >
+<a href="docprocessing.html#columns-intro">+++ Set documents in
columns</a></th>
</tr>
<tr>
<td><a href="docprocessing.html#columns">COLUMNS</a></td>
@@ -723,7 +738,8 @@ elsewhere in the documentation.
<table class="quick-ref">
<tr>
-<th id="qr-24" class="quick-ref" colspan="2" >+++ Initiate document
processing</th>
+<th id="qr-24" class="quick-ref" colspan="2" >
+<a href="docprocessing.html#start-macro">+++ Initiate document
processing</a></th>
</tr>
<tr>
<td><a href="docprocessing.html#start">START</a></td><td>-- begin document
processing</td>
@@ -732,7 +748,8 @@ elsewhere in the documentation.
<table class="quick-ref">
<tr>
-<th id="qr-25" class="quick-ref" colspan="2" >+++ Epigraphs</th>
+<th id="qr-25" class="quick-ref" colspan="2" >
+<a href="docelement.html#epigraph-intro">+++ Epigraphs</a></th>
</tr>
<tr>
<td><a href="docelement.html#epigraph">EPIGRAPH</a></td><td>-- set an epigraph
underneath the docheader</td>
@@ -744,7 +761,8 @@ elsewhere in the documentation.
<table class="quick-ref">
<tr>
-<th id="qr-26" class="quick-ref" colspan="2" >+++ HEADINGS</th>
+<th id="qr-26" class="quick-ref" colspan="2" >
+<a href="docelement.html#heading-intro">+++ HEADINGS</a></th>
</tr>
<tr>
<td><a href="docelement.html#heading">HEADING</a></td><td>-- hierarchical
headings</td>
@@ -760,7 +778,8 @@ elsewhere in the documentation.
<table class="quick-ref">
<tr>
-<th id="qr-30" class="quick-ref" colspan="2" >+++ Paragraphs</th>
+<th id="qr-30" class="quick-ref" colspan="2" >
+<a href="docelement.html#pp-intro">+++ Paragraphs</a></th>
</tr>
<tr>
<td><a href="docelement.html#pp">PP</a></td><td>-- set a paragraph</td>
@@ -784,7 +803,8 @@ elsewhere in the documentation.
<table class="quick-ref">
<tr>
-<th id="qr-31" class="quick-ref" colspan="2" >+++ Quotes (line for line
verbatim quotes)</th>
+<th id="qr-31" class="quick-ref" colspan="2" >
+<a href="docelement.html#quote-intro">+++ Quotes (line for line verbatim
quotes)</a></th>
</tr>
<tr>
<td><a href="docelement.html#quote">QUOTE</a></td><td>-- set quoted text line
for line </td>
@@ -799,7 +819,8 @@ elsewhere in the documentation.
<table class="quick-ref">
<tr>
-<th id="qr-32" class="quick-ref" colspan="2" >+++ Blockquotes (cited passages
of text)</th>
+<th id="qr-32" class="quick-ref" colspan="2" >
+<a href="docelement.html#blockquote-intro">+++ Blockquotes (cited passages of
text)</a></th>
</tr>
<tr>
<td><a href="docelement.html#blockquote">BLOCKQUOTE</a></td><td>-- set longer
passages of cited text</td>
@@ -814,7 +835,8 @@ elsewhere in the documentation.
<table class="quick-ref">
<tr>
-<th id="qr-49" class="quick-ref" colspan="2" >+++Floats </th>
+<th id="qr-49" class="quick-ref" colspan="2" >
+<a href="images.html#floats-intro">+++ Floats</a></th>
</tr>
<tr>
<td style="vertical-align: top"><a
href="images.html#float">FLOAT</a></td><td>-- keep blocks of input together,
output on next page
@@ -825,7 +847,8 @@ elsewhere in the documentation.
<table class="quick-ref">
<tr>
-<th id="qr-53" class="quick-ref" colspan="2" >+++Images and graphics </th>
+<th id="qr-53" class="quick-ref" colspan="2" >
+<a href="images.html#images-intro">+++ Images and graphics</a></th>
</tr>
<tr>
<td style="vertical-align: top"><a
href="images.html#pdf">PDF_IMAGE</a></td><td>-- inserting pdf images
@@ -840,7 +863,8 @@ elsewhere in the documentation.
<table class="quick-ref">
<tr>
-<th id="qr-51" class="quick-ref" colspan="2" >+++eqn support </th>
+<th id="qr-51" class="quick-ref" colspan="2" >
+<a href="images.html#eqn">+++ eqn support</a></th>
</tr>
<tr>
<td><a href="images.html#eq-en">EQ</a></td><td>-- begin an eqn block</td>
@@ -852,7 +876,8 @@ elsewhere in the documentation.
<table class="quick-ref">
<tr>
-<th id="qr-52" class="quick-ref" colspan="2" >+++pic support </th>
+<th id="qr-52" class="quick-ref" colspan="2" >
+<a href="images.html#pic">+++ pic support</a></th>
</tr>
<tr>
<td><a href="images.html#ps-pe">PS</a></td><td>-- begin a pic block</td>
@@ -867,7 +892,8 @@ elsewhere in the documentation.
<table class="quick-ref">
<tr>
-<th id="qr-50" class="quick-ref" colspan="2" >+++tbl support</th>
+<th id="qr-50" class="quick-ref" colspan="2" >
+<a href="images.html#tbl">+++ tbl support</a></th>
</tr>
<tr>
<td><a href="images.html#ts-te">TS</a></td><td>-- begin a tbl block</td>
@@ -882,12 +908,16 @@ elsewhere in the documentation.
<table class="quick-ref">
<tr>
-<th id="qr-54" class="quick-ref" colspan="2" >+++ Captions and labels</th>
+<th id="qr-54" class="quick-ref" colspan="2" >
+<a href="images.html#captions-and-labels">+++ Captions and labels</a></th>
</tr>
<tr>
<td><a href="images.html#autolabel">AUTOLABEL</a></td><td>-- auto-label
figures, tables, equations</td>
</tr>
<tr>
+<td><a href="images.html#set-autolabel">SET_AUTOLABEL</a></td><td>-- set or
reset autolabel numbers</td>
+</tr>
+<tr>
<td><a
href="images.html#caption-after-label">CAPTION_AFTER_LABEL</a></td><td>-- place
captions after labels</td>
</tr>
<tr>
@@ -912,7 +942,8 @@ elsewhere in the documentation.
<table class="quick-ref">
<tr>
-<th id="qr-55" class="quick-ref" colspan="2" >+++Lists of Figures, Tables, and
Equations</th>
+<th id="qr-55" class="quick-ref" colspan="2" >
+<a href="images.html#lists-of">+++ Lists of Figures, Tables, and
Equations</a></th>
</tr>
<tr>
<td><a href="images.html#lists-macros">LIST_OF_FIGURES</a></td><td>-- generate
a List of Figures</td>
@@ -930,7 +961,8 @@ elsewhere in the documentation.
<table class="quick-ref">
<tr>
-<th id="qr-33" class="quick-ref" colspan="2" >+++ Code snippets</th>
+<th id="qr-33" class="quick-ref" colspan="2" >
+<a href="docelement.html#code-intro">+++ Code snippets</a></th>
</tr>
<tr>
<td><a href="docelement.html#code">CODE</a></td><td>-- set a code snippet</td>
@@ -948,7 +980,8 @@ elsewhere in the documentation.
<table class="quick-ref">
<tr>
-<th id="qr-34" class="quick-ref" colspan="2" >+++ Author linebreaks (section
breaks)</th>
+<th id="qr-34" class="quick-ref" colspan="2" >
+<a href="docelement.html#linebreak-intro">+++ Author linebreaks (section
breaks)</a></th>
</tr>
<tr>
<td><a href="docelement.html#linebreak">LINEBREAK</a></td><td>-- insert an
author linebreak (section break)</td>
@@ -966,7 +999,8 @@ elsewhere in the documentation.
<table class="quick-ref">
<tr>
-<th id="qr-35" class="quick-ref" colspan="2" >+++ Document termination
string</th>
+<th id="qr-35" class="quick-ref" colspan="2" >
+<a href="docelement.html#finis-intro">+++ Document termination string</a></th>
</tr>
<tr>
<td><a href="docelement.html#finis">FINIS</a></td><td>-- insert a document
termination string</td>
@@ -987,7 +1021,8 @@ elsewhere in the documentation.
<table class="quick-ref">
<tr>
-<th id="qr-36" class="quick-ref" colspan="2" >+++ Footnotes</th>
+<th id="qr-36" class="quick-ref" colspan="2" >
+<a href="docelement.html#footnote-intro">+++ Footnotes</a></th>
</tr>
<tr>
<td><a href="docelement.html#footnote">FOOTNOTE</a></td><td>-- set a
footnote</td>
@@ -1021,7 +1056,8 @@ elsewhere in the documentation.
<table class="quick-ref">
<tr>
-<th id="qr-37" class="quick-ref" colspan="2" >+++ Endnotes</th>
+<th id="qr-37" class="quick-ref" colspan="2" >
+<a href="docelement.html#endnote-intro">+++ Endnotes</a></th>
</tr>
<tr>
<td><a href="docelement.html#endnote">ENDNOTE</a></td><td>-- set an
endnote</td>
@@ -1062,7 +1098,8 @@ elsewhere in the documentation.
<table class="quick-ref">
<tr>
-<th id="qr-38" class="quick-ref" colspan="2" >+++ Margin notes</th>
+<th id="qr-38" class="quick-ref" colspan="2" >
+<a href="docelement.html#margin-notes-intro">+++ Margin notes</a></th>
</tr>
<tr>
<td><a href="docelement.html#mn-init">MN_INIT</a></td><td>-- initialize margin
notes</td>
@@ -1074,7 +1111,8 @@ elsewhere in the documentation.
<table class="quick-ref">
<tr>
-<th id="qr-39" class="quick-ref" colspan="2" >+++ Bibliographic references</th>
+<th id="qr-39" class="quick-ref" colspan="2" >
+<a href="refer.html#intro-ref">+++ Bibliographic references</a></th>
</tr>
<tr>
<td><a href="refer.html#ref">REF</a></td><td>-- begin a reference</td>
@@ -1119,7 +1157,8 @@ elsewhere in the documentation.
<table class="quick-ref">
<tr>
-<th id="qr-40" class="quick-ref" colspan="2" >+++ Tables of contents</th>
+<th id="qr-40" class="quick-ref" colspan="2" >
+<a href="tables-of-contents.html#toc-intro">+++ Tables of contents</a></th>
</tr>
<tr>
<td><a href="tables-of-contents.html#toc">TOC</a></td><td>-- output a table of
contents</td>
@@ -1155,7 +1194,8 @@ elsewhere in the documentation.
<table class="quick-ref">
<tr>
-<th id="qr-41" class="quick-ref" colspan="2" >+++ Letter (correspondence)
macros</th>
+<th id="qr-41" class="quick-ref" colspan="2" >
+<a href="letters.html#letters-intro">+++ Letter (correspondence)
macros</a></th>
</tr>
<tr>
<td><a href="letters.html#date">DATE</a></td><td>-- letter’s date</td>
@@ -1185,7 +1225,8 @@ elsewhere in the documentation.
<table class="quick-ref">
<tr>
-<th id="qr-42" class="quick-ref" colspan="2" >+++ Changing global print style
parameters after START</th>
+<th id="qr-42" class="quick-ref" colspan="2" >
+<a href="docprocessing.html#style-after-start">+++ Changing global print style
parameters after START</a></th>
</tr>
<tr>
<td><a
href="docprocessing.html#doc-left-margin">DOC_LEFT_MARGIN</a></td><td>-- left
margin of everything on the page</td>
@@ -1224,7 +1265,8 @@ elsewhere in the documentation.
<table class="quick-ref">
<tr>
-<th id="qr-44" class="quick-ref" colspan="2" >+++ Managing page headers and
footers</th>
+<th id="qr-44" class="quick-ref" colspan="2" >
+<a href="headfootpage.html#headfoot-management">+++ Managing page headers and
footers</a></th>
</tr>
<tr>
<td><a href="headfootpage.html#headers">HEADERS</a></td><td>-- page headers
on/off</td>
@@ -1264,7 +1306,8 @@ elsewhere in the documentation.
<table class="quick-ref">
<tr>
-<th id="qr-45" class="quick-ref" colspan="2" >+++ Recto/verso page headers and
footers</th>
+<th id="qr-45" class="quick-ref" colspan="2" >
+<a href="rectoverso.html#rectoverso-intro">+++ Recto/verso page headers and
footers</a></th>
</tr>
<tr>
<td><a href="rectoverso.html#recto-verso">RECTO_VERSO</a></td><td>--
recto/verso headers and/or footers on/off</td>
@@ -1291,7 +1334,8 @@ elsewhere in the documentation.
<table class="quick-ref">
<tr>
-<th id="qr-46" class="quick-ref" colspan="2" >+++ Pagination</th>
+<th id="qr-46" class="quick-ref" colspan="2" >
+<a href="headfootpage.html#pagination-intro">+++ Pagination</a></th>
</tr>
<tr>
<td><a href="headfootpage.html#paginate">PAGINATE</a></td><td>-- pagination
on/off</td>
@@ -1315,7 +1359,22 @@ elsewhere in the documentation.
<table class="quick-ref">
<tr>
-<th id="qr-47" class="quick-ref" colspan="2" >+++ Document and section cover
(title) pages</th>
+<th id="qr-57" class="quick-ref" colspan="2" >
+<a href="docprocessing.html#vertical-whitespace-management">+++ Vertical
whitespace management</a></th>
+</tr>
+<tr>
+<td><a href="docprocessing.html#shim">SHIM</a></td><td>-- align to the
baseline grid</td>
+</tr>
+<tr>
+<td><a href="docprocessing.html#flex">FLEX</a></td><td>-- insert flexible
whitespace</td>
+</tr>
+</table>
+
+
+<table class="quick-ref">
+<tr>
+<th id="qr-47" class="quick-ref" colspan="2" >
+<a href="cover.html#cover-intro">+++ Document and section cover (title)
pages</a></th>
</tr>
<tr>
<td><a href="cover.html#cover">COVER</a></td><td>-- information to include in
a section cover</td>
diff --git a/contrib/mom/momdoc/rectoverso.html
b/contrib/mom/momdoc/rectoverso.html
index 025684b..49bfeb3 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-2016 Free Software Foundation, Inc.
+Copyright (C) 2004-2017 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 486c82b..ef90caf 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-2016 Free Software Foundation, Inc.
+Copyright (C) 2004-2017 Free Software Foundation, Inc.
Written by Peter Schaffter (address@hidden).
Permission is granted to copy, distribute and/or modify this document
@@ -2070,9 +2070,9 @@ in this way.
</p>
<p>
-Mom’s default is to double-underscore the title with 1/2-point
-rules placed 2 points apart and 2 points below the baseline of the
-title.
+By default, mom double-underscores the title if your
+<a href="docprocessing.html#printstyle">PRINTSTYLE</a>
+is <kbd>TYPEWRITE</kbd>.
</p>
<!-- -BIBLIO_STRING_CAPS- -->
diff --git a/contrib/mom/momdoc/reserved.html b/contrib/mom/momdoc/reserved.html
index 096d960..91df415 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-2016 Free Software Foundation, Inc.
+Copyright (C) 2004-2017 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 6a2a71f..7791bf0 100644
--- a/contrib/mom/momdoc/stylesheet.css
+++ b/contrib/mom/momdoc/stylesheet.css
@@ -1,4 +1,4 @@
-/* Copyright (C) 2004-2016 Free Software Foundation, Inc. */
+/* Copyright (C) 2004-2017 Free Software Foundation, Inc. */
/* This file is part of mom, which is part of groff, a free software */
/* project. */
@@ -545,7 +545,7 @@ kbd
{
font-family: "Lucida Console",monospace ;
font-weight: bold ;
- font-size: 95% ;
+ font-size: 98% ;
}
kbd.macro-args
{
diff --git a/contrib/mom/momdoc/tables-of-contents.html
b/contrib/mom/momdoc/tables-of-contents.html
index a40510a..0f872e1 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-2016 Free Software Foundation, Inc.
+Copyright (C) 2004-2017 Free Software Foundation, Inc.
Written by Peter Schaffter (address@hidden).
Permission is granted to copy, distribute and/or modify this document
@@ -124,7 +124,7 @@ the rest of the document is. Lastly, if
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="#blank-page">BLANKPAGE</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>
@@ -380,6 +380,7 @@ themselves (overall family, headers/footers, pagination,
etc).
<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>
@@ -1098,7 +1099,60 @@ page when you want an odd, or vice versa.
<p>
The same result can be accomplished by outputting a
-<a href="#blank-page">BLANKPAGE</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 (<b>OFF, QUIT, END</b>...) 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
+(ie 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>
diff --git a/contrib/mom/momdoc/toc.html b/contrib/mom/momdoc/toc.html
index c7cc754..b83e8ff 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-2016 Free Software Foundation, Inc.
+Copyright (C) 2004-2017 Free Software Foundation, Inc.
Written by Peter Schaffter (address@hidden).
Permission is granted to copy, distribute and/or modify this document
@@ -20,7 +20,7 @@ FDL in the main directory of the groff source package.
<head>
<meta http-equiv="content-type" content="text/html;charset=utf-8"/>
- <title>Mom, version 2.1-b -- Table of Contents</title>
+ <title>Mom, version 2.2 -- Table of Contents</title>
<link rel="stylesheet" type="text/css" href="stylesheet.css" />
</head>
@@ -31,7 +31,7 @@ FDL in the main directory of the groff source package.
<div class="page">
<div class="version">
- mom, version 2.1-b
+ mom, version 2.2
</div>
<h1 class="toc" style="margin-top: 9px;">Table of Contents</h1>
@@ -95,6 +95,7 @@ FDL in the main directory of the groff source package.
<ul class="toc" style="margin-left: 3em;">
<li><a href="#doc-proc">Introduction to document processing</a></li>
<li><a href="#doc-defaults">Document defaults</a></li>
+ <li><a href="#vert-ws">Vertical whitespace management</a></li>
<li><a href="#prelim">Preliminary document setup</a></li>
<li><a href="#typemacdoc">Behaviour of the typesetting macros during
document processing</a></li>
<li><a href="#tags">The document element tags</a> – headings,
paragraphs, quotes, footnotes, etc.</li>
@@ -264,9 +265,10 @@ FDL in the main directory of the groff source package.
<ul class="toc">
<li><a href="docprocessing.html#docprocessing-intro">5.1 Introduction to
document processing</a></li>
<li><a id="doc-defaults" href="docprocessing.html#defaults">5.2 Document
defaults</a> – papersize, margins, etc.
- <ul>
- <li><a href="docprocessing.html#leading-note">5.2.1 Important note on
leading/spacing and bottom margins</a></li>
- <li><a href="docprocessing.html#shim">5.2.1 The SHIM macro</a> –
flexible spacer to keep document leading back on track</li>
+ <li><a id="vert-ws"
href="docprocessing.html#vertical-whitespace-management">5.3 Vertical
whitespace management</a>
+ <ul>
+ <li><a id="typemacdoc" href="docprocessing.html#shim">5.3.1
SHIM</a></li>
+ <li><a href="docprocessing.html#flex">5.3.2 FLEX</a>
</ul></li>
<li><a id="prelim" href="docprocessing.html#setup" class="highlight">5.3
PRELIMINARY DOCUMENT SETUP</a>
<ul>
@@ -311,20 +313,14 @@ FDL in the main directory of the groff source package.
</ul></li>
<li><a href="docprocessing.html#doc-lead-adjust">5.3.7.2
DOC_LEAD_ADJUST</a> – adjust document
<a href="definitions.html#leading">leading</a>
- to fill pages
- <ul class="fourth-level">
- <li>– <a href="docprocessing.html#shim">5.3.6.7.1 SHIM</a>
– flexible spacer to keep document leading back on track</li>
- </ul></li>
- </ul></li>
+ to fill pages</li>
+ </ul>
<li><a href="docprocessing.html#style-after-start">5.3.8 Changing basic
type and formatting parameters <span style="font-style: italic">after</span>
START</a>
<ul>
<li><a id="typemacdoc" href="docprocessing.html#behaviour">5.3.8.1
Behaviour of the typesetting macros during document processing</a></li>
<li><a href="docprocessing.html#intro-doc-param">5.3.8.2 Post-START
global style-change macros</a>
- <ul class="fourth-level">
- <li>– <a href="docprocessing.html#index-doc-param">Macro
list</a></li>
</ul></li>
</ul></li>
- </ul></li>
<li><a id="tags" class="highlight" href="docelement.html#top">5.4 THE
DOCUMENT ELEMENT TAGS</a>
<ul>
<li><a href="docelement.html#docelement-intro">5.4.1 Introduction to
the document element tags</a>
diff --git a/contrib/mom/momdoc/typesetting.html
b/contrib/mom/momdoc/typesetting.html
index 7fdb1be..7f5c9d4 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-2016 Free Software Foundation, Inc.
+Copyright (C) 2004-2017 Free Software Foundation, Inc.
Written by Peter Schaffter (address@hidden).
Permission is granted to copy, distribute and/or modify this document
@@ -3020,11 +3020,11 @@ fonts rather than relying on mom's pseudo version.
</p>
<p>
-To achieve a reasonable facsimile of designer-cut small fonts, mom
-needs to know the percentage of regular caps at a given point size
-by which to reduce the small caps. To make adjustments for the
-difference in weight and width of the smaller caps, she also needs
-to know by how much to embolden (“fatten”) the
+To achieve a reasonable facsimile of designer-cut smallcaps fonts,
+mom needs to know the percentage of regular caps at a given point
+size by which to reduce the small caps. To make adjustments for
+the difference in weight and width of the smaller caps, she also
+needs to know by how much to embolden (“fatten”) the
smallcaps, and by how much to increase their width.
</p>
diff --git a/contrib/mom/momdoc/using.html b/contrib/mom/momdoc/using.html
index 2973e06..630fc51 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-2016 Free Software Foundation, Inc.
+Copyright (C) 2004-2017 Free Software Foundation, Inc.
Written by Peter Schaffter (address@hidden).
Permission is granted to copy, distribute and/or modify this document
@@ -286,12 +286,12 @@ metadata, notably the document window title set with
PDF_TITLE.
<p>
Most PDF viewers have a “Watch File” option, which
-automaticaly updates a displayed document whenever there's a change.
-This is useful when preparing documents that require judgment calls.
-I recommend creating a keymapping in your text editor that both
-saves the mom file and processes it with <strong>pdfmom</strong>.
-The displayed PDF then automatically reflects whatever changes you
-save to the mom file.
+automaticaly updates a displayed document whenever there’s
+a change. This is useful when preparing documents that require
+judgment calls. I recommend creating a keymapping in your
+text editor that both saves the mom file and processes it with
+<strong>pdfmom</strong>. The displayed PDF then automatically
+reflects whatever changes you save to the mom file.
</p>
<div class="rule-long"><hr/></div>
diff --git a/contrib/mom/momdoc/version-2.html
b/contrib/mom/momdoc/version-2.html
index 8681b7b..7c566bf 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-2016 Free Software Foundation, Inc.
+Copyright (C) 2004-2017 Free Software Foundation, Inc.
Written by Peter Schaffter (address@hidden).
Permission is granted to copy, distribute and/or modify this document
@@ -367,6 +367,24 @@ The following changes have been made:
elements on them does</li>
</ul>
+<h2 id="v2.1-changes" class="docs">3. Version 2.2 changes</h2>
+
+<p>
+Version 2.2 adds these features:
+</p>
+<ul style="margin-top: -.5em; width: 90%">
+ <li>flex-spacing, an alternative to mom’s default shimming
+ policy; flex-spacing balances vertical whitespace on the page by
+ distributing any excess equally at sensible points so that running
+ text always fills the page to the bottom margin (see
+ <a href="docprocessing.html#vertical-whitespace-management">
+ vertical whitespace management</a>
+ </li>
+ <li>improvements to auto-labelling, such that it is now possible
+ to link symbollically to auto-labelled preprocessor material and
+ PDF images</li>
+</ul>
+
<h2 id="pdfmom" class="docs">4. pdfmom</h2>
<p>
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- [groff] 01/01: Version 2.2 updates.,
Peter Schaffter <=