[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[groff] 01/01: Updated documentation for 2.1-a
|
From: |
Peter Schaffter |
|
Subject: |
[groff] 01/01: Updated documentation for 2.1-a |
|
Date: |
Tue, 28 Apr 2015 16:44:27 +0000 |
PTPi pushed a commit to branch master
in repository groff.
commit b79a06b499cf95f8a785b93db5ee9242dca77ffa
Author: Peter Schaffter <address@hidden>
Date: Tue Apr 28 12:44:09 2015 -0400
Updated documentation for 2.1-a
---
contrib/mom/momdoc/docelement.html | 33 ++-
contrib/mom/momdoc/docprocessing.html | 28 +-
contrib/mom/momdoc/images.html | 547 +++++++++++++++++++++++++---
contrib/mom/momdoc/inlines.html | 2 +-
contrib/mom/momdoc/macrolist.html | 6 +
contrib/mom/momdoc/rectoverso.html | 22 ++
contrib/mom/momdoc/refer.html | 9 +-
contrib/mom/momdoc/tables-of-contents.html | 102 +++++-
contrib/mom/momdoc/toc.html | 4 +-
contrib/mom/momdoc/typesetting.html | 11 +-
10 files changed, 688 insertions(+), 76 deletions(-)
diff --git a/contrib/mom/momdoc/docelement.html
b/contrib/mom/momdoc/docelement.html
index a267e66..524581d 100644
--- a/contrib/mom/momdoc/docelement.html
+++ b/contrib/mom/momdoc/docelement.html
@@ -1962,11 +1962,21 @@ or
<h2 id="quote-intro" class="macro-group">Quotes (line for line, poetry or
code)</h2>
<ul style="margin-left: -.5em;">
+ <li><a href="#quote-description">Introduction</a>
+ <ul style="margin-left: -1.25em">
+ <li><a href="#quote-spacing">Quote spacing</a>
+ <ul style="margin-left: -1.25em">
+ <li><a href="#quote-spacing-notes">Notes on quote spacing</a></li>
+ </ul></li>
+ <li><a href="#no-shim">Disable shimming of quotes and blockquotes</a></li>
+ <li><a href="#float-quote">Keeping quotes and blockquotes together as a
block</a></li>
+ <li><a href="#label-caption">Labelling/captioning quotes and
blockquotes</a></li>
+ </ul></li>
<li><a href="#quote">Tag: QUOTE</a></li>
<li><a href="#quote-control">Quote control macros and defaults</a></li>
</ul>
-<p>
+<p id="quote-decription">
<a href="definitions.html#quote">Quotes</a>
are always set in
<a href="definitions.html#filled">nofill mode</a>,
@@ -2105,7 +2115,17 @@ the <kbd>FORCE</kbd> argument.
.QUOTE END
.FLOAT OFF
</span>
+</p>
+
+<h3 id="label-caption" class="docs">Labelling/captioning quotes and
blockquotes</h3>
+<p>
+Quotes and blockquotes may be labelled and/or captioned identically to
+<a href="images.html#floats-intro">floats</a>
+with the macros
+<a href="images.html#label">LABEL</a>
+and
+<a href="images.html#caption">CAPTION</a>.
</p>
<!-- -QUOTE- -->
@@ -2284,11 +2304,12 @@ ITALIC_MEANS_ITALIC is enabled (see
<h2 id="blockquote-intro" class="macro-group">Blockquotes (cited material)</h2>
<ul style="margin-left: -.5em;">
+ <li><a href="#blockquote-description">Introduction</a>
<li><a href="#blockquote">Tag: BLOCKQUOTE</a></li>
<li><a href="#blockquote-control">BLOCKQUOTE control macros</a></li>
</ul>
-<p>
+<p id="blockquote-description">
<a href="definitions.html#blockquote">Blockquotes</a>
are used to cite passages from another author’s work. So that
they stand out well from
@@ -2314,6 +2335,14 @@ for a complete explanation of how this is managed, and
how
to control it.)
</p>
+<p>
+Additional information concerning blockquotes, floats, and labelling
+blockquotes can be found in the sections
+<a href="#float-quote">Keeping quotes and blockquotes together as a block</a>,
+and
+<a href="#label-caption">Labelling/captioning quotes and blockquotes</a>.
+</p>
+
<!-- -BLOCKQUOTE- -->
<div class="macro-id-overline">
diff --git a/contrib/mom/momdoc/docprocessing.html
b/contrib/mom/momdoc/docprocessing.html
index 60fe073..e091f4c 100644
--- a/contrib/mom/momdoc/docprocessing.html
+++ b/contrib/mom/momdoc/docprocessing.html
@@ -400,12 +400,9 @@ or
<a href="images.html#ts">TS</a>.
</p>
-<div class="box-tip">
-<p class="tip">
-<span class="note">Note:</span>
-<kbd>.NO_SHIM</kbd> also disables the SHIM macro itself.
+<p>
+Note that <kbd>.NO_SHIM</kbd> also disables the SHIM macro itself.
</p>
-</div>
<p>To re-enable automatic shimming and the SHIM macro itself, use
<kbd>.NO_SHIM OFF</kbd> (or <kbd>QUIT, END, X</kbd>, etc).
@@ -2486,6 +2483,23 @@ the last macro before the first item of your document
(for
example, <kbd>.PP</kbd> or <kbd>.HEADING 1</kbd>. PP...)
</p>
+<div class="box-tip">
+<p class="tip">
+<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
+<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>.
+</p>
+</div>
+
<!-- DOCHEADER CONTROL -->
<h3 id="docheader-control" class="docs">Docheader control: How to change the
look of docheaders</h3>
@@ -2752,7 +2766,7 @@ as the name for the string passed to <kbd>DOCTYPE
NAMED "string"</kbd>.
<a href="definitions.html#picaspoints">points</a>
is assumed.
</dd>
- <dt id="space-before" class="params">_SPACE_BEFORE</dt>
+ <dt id="space-before" class="params">_SPACE</dt>
<dd>
Takes a numeric value with a
<a href="definitions.html#unitofmeasure">unit of measure</a>
@@ -2760,7 +2774,7 @@ as the name for the string passed to <kbd>DOCTYPE
NAMED "string"</kbd>.
to adjust the whitespace before a docheader part, for example
if you want more whitespace between the title and the author.
<span style="display: block; margin-top: .5em">
- Note that <kbd>TITLE</kbd> does not have a <kbd>_SPACE_BEFORE</kbd>
+ Note that <kbd>TITLE</kbd> does not have a <kbd>_SPACE</kbd>
parameter; use
<a href="#change-start">DOCHEADER_ADVANCE</a>
to move the title further down on the page.
diff --git a/contrib/mom/momdoc/images.html b/contrib/mom/momdoc/images.html
index 39cd23a..976e939 100644
--- a/contrib/mom/momdoc/images.html
+++ b/contrib/mom/momdoc/images.html
@@ -58,6 +58,11 @@ FDL in the main directory of the groff source package.
<li><a href="#floats-intro">Floats</a>
<ul>
<li><a href="#float">The FLOAT macro</a></li>
+ <li><a href="#float-label-caption">Labelling and captioning floats</a>
+ <ul style="margin-left: -1.25em">
+ <li><a href="#label">LABEL</a></li>
+ <li><a href="#caption">CAPTION</a></li>
+ </ul></li>
</ul></li>
<li><a href="#preprocessor-support">Preprocessor support</a>
<ul>
@@ -373,7 +378,7 @@ but this is now no longer required, and should, in fact, be
avoided.
</p>
</div>
-<!---PDF_IMAGE_FRAME--->
+<!-- -PDF_IMAGE_FRAME- -->
<div class="macro-id-overline">
<h3 id="pdf-image-frame" class= "macro-id">PDF_IMAGE_FRAME</h3>
@@ -397,6 +402,7 @@ PDF_IMAGE_FRAME establishes the parameters for subsequent
invocations of
when the <kbd>FRAME</kbd> argument is given. Arguments must appear
in order, and any you wish left at the current value should be
entered as two adjacent double-quotes. So, for example,
+<br/>
<span class="pre-in-pp">
.PDF_IMAGE_FRAME "" "" blue
</span>
@@ -460,6 +466,7 @@ and <kbd><height></kbd> arguments unless you are
scaling
the image, in which case you will most likely need the original
dimensions of the EPS image’s bounding box. These can be
found with
+<br/>
<span class="pre-in-pp">
gs -q -dBATCH -dNOPAUSE -sDEVICE=bbox <image file>.pdf 2>&1 \
| grep "%%BoundingBox" | cut -d " " -f4,5
@@ -708,6 +715,330 @@ within the float.
</p>
</div>
+<h2 id="float-label-caption" class="docs">Labelling and captioning floats</h2>
+
+<p>
+Labelling and captioning of tables (<b>tbl</b>), equations
+(<b>eq</b>), diagrams (<b>pic</b>) and pdf images
+(<a href="#pdf-image">PDF_IMAGE</a>)
+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.
+</p>
+
+<div class="box-tip">
+<p class="tip">
+<span class="important">Important:</span>
+Always use the native labelling/captioning facilities for
+preprocessor output and pdf images rather than labelling the
+containing float, if any.
+</p>
+</div>
+
+<p>
+The macros to label and caption floats are
+<a href="#label">LABEL</a>
+and
+<a href="#caption">CAPTION</a>.
+If a label or caption is to appear above the float, the appropriate
+macro is entered immediately after
+<a href="#float">FLOAT</a>.
+If a label or caption is to appear beneath the float, the appropriate
+macro is entered immediately before ending the float with
+<kbd>FLOAT OFF</kbd>.
+</p>
+
+<p>
+If a label and caption are to be joined, the <b>LABEL</b> macro is
+used to enter both by passing the <kbd>CAPTION</kbd> argument to
+<kbd>LABEL</kbd>.
+</p>
+
+<p>
+It is impossible for mom to know the contents of a float, so
+floats cannot be autolabelled. Each label must be entered
+explicitly. Mom does, however, provide a way to enter both
+chapter numbers and incrementing label numbers
+<a href="#reserved-label-strings">symbolically</a>,
+easing the burden of keeping the numbering scheme intact as
+labelled floats are added to or subtracted from a document.
+</p>
+
+<div class="box-tip">
+<p class="tip">
+<span class="note">Tip:</span>
+<a href="docelement.html#blockquote">QUOTE</a>
+and
+<a href="docelement.html#blockquote">BLOCKQUOTE</a>
+may also be labelled and captioned using <b>LABEL</b> and
+<b>CAPTION</b>.
+</p>
+</div>
+
+<h4 class="docs">Spacing</h4>
+
+<p>
+If a float has a caption at the top, the caption is whitespaced
+1/4 linespace from running text and the float itself begins
+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
+<a href="docprocessing.html#shim">shimming</a>
+is necessary to restore proper baseline alignment.
+</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.
+</p>
+
+<p>
+Labelled/captioned quotes and blockquotes inside floats treat the
+labels/captions as part of the quote so the spacing above and
+below the whole float block is what you’d expect from quotes
+normally, while the spacing between the label/caption and the quote
+is 1/4 linespace.
+</p>
+
+<div class="macro-id-overline">
+<h3 id="label" class="macro-id">LABEL</h3>
+</div>
+
+<div class="box-macro-args">
+Macro: <b>LABEL</b></a>
+<kbd class="macro-args">"<label>" [ CAPTION "<caption>" ] [
SHORT_CAPTION ] \
+<br/>
+[ TO_LIST FIGURES | TABLES | EQUATIONS ]</kbd>
+</div>
+
+<p>
+The placement of a float’s label depends on where you put it
+inside the float.
+</p>
+
+<p>
+If you want a label at the top, put <kbd>LABEL</kbd> immediately
+underneath
+<a href="#float">FLOAT</a>
+and follow it with the text of the label surrounded by double-quotes:
+<br/>
+<span class="pre-in-pp">
+ .FLOAT
+ .LABEL "Fig. 1"
+</span>
+If you want a label at the bottom, put <kbd>LABEL</kbd> immediately
+before ending the float:
+<br/>
+<span class="pre-in-pp">
+ .FLOAT
+ <contents of float>
+ .LABEL "Fig. 1"
+ .FLOAT OFF
+</span>
+</p>
+
+<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
+<a href="docprocessing.html#start">START</a>
+when the
+<a href="docprocessing.html#doctype">DOCTYPE</a>
+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].
+</span>
+which, assuming the third labelled 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
+<br/>
+<span class="pre-in-pp">
+ .AUTOLABEL <list type>
+</span>
+before <kbd>.START</kbd>.
+</p>
+
+<p>
+If
+<a href="#autolabel">autolabelling</a>
+is enabled, e.g. <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>,
+<br/>
+<span class="pre-in-pp">
+ .LABEL "Fig. 1.1."
+ CAPTION "Caption for label \
+ TO_LIST FIGURES
+</span>
+or
+<br/>
+<span class="pre-in-pp">
+ .LABEL "Fig. \*[chapter].\*[label]." \
+ CAPTION "Caption for label \
+ TO_LIST FIGURES
+</span>
+will appear in the List of Figures as “1.1. Caption for
+label”.
+</p>
+
+<h3 class="docs">CAPTION</h3>
+
+<p>
+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/>
+<br/>
+<span class="pre-in-pp">
+ .FLOAT
+ <contents of float>
+ .LABEL "Fig. 1" CAPTION "Caption for Fig. 1"
+ .FLOAT OFF
+</span>
+Note that the
+<a href="#caption">CAPTION</a>
+macro by itself permits entering several strings, each output on
+a line by itself, whereas the <kbd>CAPTION</kbd> argument to
+<kbd>LABEL</kbd> accepts only a single string.
+</p>
+
+<h3 class="docs">SHORT_CAPTION</h3>
+
+<p>
+If your caption runs long and you’re including the
+float in a “List of ...”, (see
+<a href="#list-of">TO_LIST</a>, below)
+<kbd>SHORT_CAPTION</kbd> tells
+mom how you’d like the caption to appear in the List.
+</p>
+
+<h3 class="docs">TO_LIST</h3>
+
+<p>
+The optional argument <kbd>TO_LIST</kbd> tells mom to add the
+float’s label and attached caption, if present, to the specified
+<a href="#lists-of">list</a>,
+which may be one of <kbd>FIGURES</kbd>, <kbd>TABLES</kbd>, or
+<kbd>EQUATIONS</kbd>.
+</p>
+
+<p>
+If, for some reason, you want only the caption appended to the List,
+give <kbd>\&</kbd> as the first argument to LABEL, followed by
+<kbd>CAPTION “caption”</kbd>:
+<br/>
+<span class="pre-in-pp">
+ .LABEL \& \
+ CAPTION "caption"
+</p>
+
+<div class="box-tip">
+<p class="tip-top">
+<span class="note">Tip:</span>
+<kbd>TO_LIST</kbd> can be used to handle situations where labelled
+floats need to go to a uniquely named “List of ...”.
+</p>
+
+<p class="tip-bottom">
+Suppose, for example, your document contains figures (e.g.
+<b>pic</b> output or pdf-images) and tables, and you need a
+“List of Examples” for floats labelled “Example
+n.n”. By changing the default title string for
+<a href="#lists-macros">LIST_OF_EQUATIONS</a>
+to “List of Examples”, you may include the float in your
+List of Examples with
+<br/>
+<span class="pre-in-pp">
+ .TO_FIGURES EQUATIONS
+</p>
+</div>
+
+<div class="macro-id-overline">
+<h3 id="caption" class="macro-id">CAPTION</h3>
+</div>
+
+<div class="box-macro-args">
+Macro: <b>CAPTION</b></a>
+<kbd class="macro-args">"<caption>" \
+<br/>
+[ "<additional line>" [ "<additional line>"... ] ] \
+<br/>
+[ TO_LIST FIGURES | TABLES | EQUATIONS ]</kbd>
+</div>
+
+<p>
+The placement of a float’s caption depends on where you put it
+inside the float.
+</p>
+
+<p>
+If you want a caption at the top, put <kbd>CAPTIO</kbd> immediately
+underneath
+<a href="#float">FLOAT</a>
+and follow it with the text of the caption surrounded by double-quotes:
+<br/>
+<span class="pre-in-pp">
+ .FLOAT
+ .CAPTION "Caption at top of float"
+</span>
+<b>CAPTION</b> can take multiple string arguments, allowing for
+captions that run to several lines. There is a caveat: the strings
+are not automatically broken into individual lines. You must
+provide strings that include literal breaks or spaces:
+<br/>
+<span class="pre-in-pp">
+ .FLOAT
+ .CAPTION "Caption" ".BR" "at top" ".BR" "of float"
+</span>
+or, easier to read:
+<br/>
+<span class="pre-in-pp">
+ .FLOAT
+ .CAPTION "Caption" \
+ ".BR" \
+ "at top" \
+ ".BR" \
+ "of float"
+</span>
+If you want a caption at the bottom, put <kbd>CAPTION</kbd> immediately
+before ending the float:
+<br/>
+<span class="pre-in-pp">
+ .FLOAT
+ <contents of float>
+ .CAPTION "Caption at bottom of float"
+ .FLOAT OFF
+</span>
+</p>
+
+<div class="box-tip">
+<p class="tip">
+<span class="note">Note:</span>
+If you want a caption attached to a label, do not use
+<b>CAPTION</b> by itself. Rather, invoke
+<a href="#label"><kbd>.LABEL</kbd></a>
+with the <kbd>CAPTION</kbd> argument.
+</p>
+</div>
+
<div class="rule-medium"><hr/></div>
<h2 id="preprocessor-support" class="docs">Preprocessor support</h2>
@@ -1642,33 +1973,64 @@ Macro: <b>AUTOLABEL_TABLES</b>
<b>AUTOLABEL_<type></b> takes care of labelling <type> by
identifying each with a separate, incrementing numeric scheme, which
is also collected for output in Lists of Figures, Equations, and
-Tables. By default, the label numbers are prefixed, and, in the
-case of equations, suffixed, with strings such that they appear for
-tables as “Table <n>”, for <b>pic</b> diagrams and
-pdf images as “Fig. <n>”, and for equations as
-“(<n>)”.
+Tables.
+</p>
+
+<p>
+Autolabelling may be disabled on-the-fly by giving any argument
+other than <kbd>PREFIX</kbd>, <kbd>SUFFIX</kbd>, or
+<kbd>PREFIX_CHAPTER</kbd> to the appropriate macro. For example,
+</br>
+<span class="pre-in-pp">
+ .AUTOLABEL_IMAGES NO
+</span>
+would disable autolabelling of images.
</p>
+<h4 class="docs" style="margin-top: -.5em">Prefixes and suffixes</h4>
+
<p>
-Use <kbd>PREFIX <"string"></kbd> to change what comes
-before the automatic numbering. For example, if you are including
-musical excerpts in your document, MLA style requires that they be
-labelled “Ex. <n>”. Since musical excerpts
-are likely to be scanned images (in pdf format, don’t forget),
-you have to change the prefix string for pdf images:
+By default, when <b>AUTOLABEL</b> is enabled, the label numbers are
+prefixed, and, in the case of equations, suffixed, with strings such
+that they appear for tables as “Table <n>”, for
+<b>pic</b> diagrams and pdf images as “Fig. <n>”,
+and for equations as “(<n>)”.
+</p>
+
+<p>
+You can use <kbd>PREFIX <"string"></kbd> to change what
+comes before the automatic numbering. For example, if you are
+including musical excerpts in your document, MLA style requires that
+they be labelled “Ex. <n>”. Since musical
+excerpts are likely to be scanned images (in pdf format, don’t
+forget), you have to change the prefix string for pdf images:
<br/>
<span class="pre-in-pp">
- .AUTOLABEL_IMAGES PREFIX "Ex. "
+ .AUTOLABEL_IMAGES \
+ PREFIX "Ex. " \
+ SUFFIX ""
</span>
If you need a suffix after the automatic numbering, use
<kbd>SUFFIX <"string"></kbd>, like this:
<br/>
<span class="pre-in-pp">
- .AUTOLABEL_IMAGES PREFIX "(Fig. " SUFFIX ")"
+ .AUTOLABEL_IMAGES \
+ PREFIX "(Fig. " \
+ SUFFIX ")"
</span>
-Note that the double-quotes around the single-character SUFFIX
-string are optional.
+Note from the above that both arguments, <kbd>PREFIX</kbd> and
+<kbd>SUFFIX</kbd>, are required should you want either. Two
+adjacent double-quotes leaves the string blank.
+</p>
+
+<div class="box-tip">
+<p class="tip">
+<span class="note">Note:</span>
+In automatically formatted
+<a href="#lists-macros">“Lists of ...”</a>,
+label number prefixes are stripped when autolabelling is enabled.
</p>
+</div>
<h4 class="docs" style="margin-top: -.5em">Prefixing chapter numbers</h4>
@@ -1679,13 +2041,30 @@ pass <kbd>AUTOLABEL_<type></kbd> the argument
</p>
<p>
-If you have not given mom a <kbd>CHAPTER <n></kbd> prior
-to invoking <kbd>AUTOLABEL_<type> PREFIX_CHAPTER</kbd>,
-you must give the chapter number after <kbd>PREFIX_CHAPTER</kbd>.
-Once done, all subsequent chapters or collated document sections
-will increment the chapter number by one automatically. Failure to
-provide a chapter number after <kbd>PREFIX_CHAPTER</kbd> when it is
-required will result in mom aborting with a reminder to do so.
+If for some reason you need to specify the chapter number,
+you may do so by passing the number as an argument to
+<kbd>PREFIX_CHAPTER</kbd>. Subsequent chapters or major sections
+will increment by one as expected.
+</p>
+
+<div class="box-tip">
+<p class="tip">
+<span class="note">Note:</span>
+For the purposes of labelling, mom
+treats
+<a href="docprocessing.html#doctype">DOCTYPE DEFAULT</a>
+as if it were <b>DOCTYPE CHAPTER</b>, hence, with
+<kbd>PREFIX_CHAPTER</kbd>, each collated <b>DEFAULT</b>
+doctype's prefixed “chapter” number is incremented
+and the label number itself reset to “1”. If
+you do not give <kbd>PREFIX_CHAPTER</kbd>, the label number
+is <i>not</i> reset automatically. To reset it, invoke
+<kbd>.AUTOLABEL_<type></kbd> after each
+<a href="docprocessing.html#collate">COLLATE</a>.
+</div>
+
+<p>
+Prefixed chapter numbers
</p>
<div class="macro-id-overline">
@@ -1776,9 +2155,9 @@ anything you like (<kbd>X</kbd>, <kbd>NO</kbd>, etc).
</div>
<div class="box-macro-args" style="margin-top: .5em">
-Macro: <b>CAPTIONS</b> <kbd class="macro-args">EQN | IMG | PIC | TBL |
ALL</kbd>
+Macro: <b>CAPTIONS</b> <kbd class="macro-args">EQN | IMG | PIC | TBL |
FLOATING | ALL</kbd>
<br/>
-Macro: <b>LABELS</b> <kbd class="macro-args">EQN | IMG | PIC | TBL | ALL</kbd>
+Macro: <b>LABELS</b> <kbd class="macro-args">EQN | IMG | PIC | TBL | FLOATING
| ALL</kbd>
<br/>
Macro: <b>SOURCES</b> <kbd class="macro-args">TBL</kbd>
<br/>
@@ -1788,14 +2167,16 @@ Macro: <b>SOURCES</b> <kbd class="macro-args">TBL</kbd>
<br/>
FONT <font> \
<br/>
- SIZE "+|-<size>" \
+ SIZE +|-<size> \
<br/>
- AUTOLEAD "<value>" \
+ AUTOLEAD <value> \
<br/>
- COLOR "<color>" \
+ COLOR <color> \
<br/>
QUAD LEFT | CENTER | RIGHT [ ON_LL ] \
<br/>
+ INDENT <indent> \
+<br/>
ADJUST +|-<vertical adjustment>
</kbd>
</div>
@@ -1830,28 +2211,46 @@ for tables) behave identically to the
<p>
The first, required argument after <kbd>CAPTIONS</kbd>,
-<kbd>LABELS</kbd>, and <kbd>SOURCES</kbd> indicates the preprocessor
+<kbd>LABELS</kbd>, or <kbd>SOURCES</kbd> indicates the preprocessor
type for which you are setting the parameters. (For convenience
PDF_IMAGE—argument <kbd>IMG</kbd>—is here treated as a
-preprocessor.) An argument of <kbd>ALL</kbd> sets a unified
-style for every preprocessor. If the <kbd>ALL</kbd> argument is
-given, arguments to subsequent invocations of <kbd>CAPTIONS</kbd>,
-<kbd>LABELS</kbd>, or <kbd>SOURCES</kbd> overwrite only the
-explicitly named style parameters.
+preprocessor.) <kbd>FLOATING</kbd> sets the style for the macros
+<a href="#caption">CAPTION</a>
+and
+<a href="#label">LABEL</a>,
+which are used to label floats, quotes, and blockquotes.
+</p>
+
+<p>
+An argument of <kbd>ALL</kbd> sets a unified style for all
+preprocessors, floats, quotes, and blockquotes. If the
+<kbd>ALL</kbd> argument is given, arguments to subsequent
+invocations of <kbd>CAPTIONS</kbd>, <kbd>LABELS</kbd>, or
+<kbd>SOURCES</kbd> overwrite only the explicitly named style
+parameters.
</p>
<h4 class="docs">QUAD — quadding of labels, captions, and sources</h4>
+<h5 class="docs" style="text-transform: none">• pic, tbl, pdf
images</h5>
+
<p>
By default, figures (<b>pic</b> output and pdf images) and tables
-have their captions and labels set quad left. Sources (for tables)
-are also set quad left. Equations have their labels set quad right,
-and their captions centered. Regardless of the quad direction,
-captions, labels, and sources are quadded over the width of figures
-and tables unless you pass the optional <kbd>ON_LL</kbd> argument to
-<kbd>QUAD <direction></kbd>.
+have their captions and labels set quad left. Sources (for
+tables) are also set quad left. Equations have their labels
+set quad right, and their captions centered.
+</p>
+
+<p>
+Regardless of the quad direction, captions, labels and sources
+are set on the width of the figure, table, or pdf image
+unless you pass the optional <kbd>ON_LL</kbd> argument to
+<kbd>QUAD <direction></kbd>, in which case the prevailing
+document line length is used instead.
</p>
+<h5 class="docs" style="text-transform: none">• eqn</h5>
+
<p>
Equations behave differently. By default, equation labels are
set flush right with the page’s right margin regardless of
@@ -1860,9 +2259,65 @@ equation is positioned left, the label will appear at
the right
margin regardless of the direction you give to <kbd>QUAD</kbd>. If
the equation is indented with the <kbd>-I <indent></kbd>
option, a quad direction of <kbd>LEFT</kbd> is observed, but may
-overprint the last line of the equation. Note that there is no
-<kbd>CENTER</kbd> option for equation labels, and that captions are
-always quadded over the full line length.
+overprint the last line of the equation.
+</p>
+
+<p>
+Note that there is no <kbd>CENTER</kbd> option for equation labels,
+and that captions are always quadded over the prevailing document
+line length.
+</p>
+
+<h5 class="docs" style="text-transform: none">• quotes and
blockquotes</h5>
+
+<p>
+Floating labels attached to <b>QUOTE</b>s are quadded on the
+prevailing document line length, and require the <kbd>INDENT</kbd>
+argument if you want to align them with the left and/or right edges
+the quote.
+</p>
+
+<p>
+Floating labels attached to <b>BLOCKQUOTE</b>s are always quadded on
+the indent and line length of the blockquote.
+</p>
+
+<h5 class="docs" style="text-transform: none">• floats</h5>
+
+<p>
+Floating labels and captions attached to <b>FLOAT</b>s are always
+quadded over the prevailing document line length, and require the
+<kbd>INDENT</kbd> argument if you want to align them with the left
+and/or right edges the the float’s contents.
+</p>
+
+<h4 class="docs">INDENT</h4>
+
+<p>
+The <kbd>INDENT</kbd> argument may only be used if the label
+or caption type is <kbd>FLOATING</kbd>, and only applies to
+<b>FLOAT</b>s and <b>QUOTE</b>s, not <b>BLOCKQUOTE</b>s.
+</p>
+
+<p>
+It is not possible for mom to know the width of a float before
+setting a label or caption attached to a float. She therefore sets
+it on the prevailing document line length. While this isn’t
+much of an issue when the label or caption quad is <b>CENTER</b>,
+you may want to adjust the horizontal positioning when the quad is
+<b>LEFT</b> or <b>RIGHT</b>.
+</p>
+
+<p>
+<kbd>INDENT</kbd>, with a numeric value to which a
+<a href="definitions.html#unitofmeasure">unit of measure</a>
+is appended, allows you to indent a floating label or caption so
+it lines up with the left edge of a <b>FLOAT</b> or <b>QUOTE</b>.
+<kbd>INDENT RIGHT</kbd> (with a value) allows you to shorten the
+line length to the appropriate width. If you need both a left and
+right indent, invoke <kbd>LABELS</kbd> or <kbd>CAPTIONS</kbd> twice,
+one instance containing <kbd>INDENT <indent></kbd> and
+the other <kbd>INDENT RIGHT <indent></kbd>.
</p>
<h4 class="docs">ADJUST</h4>
@@ -1871,9 +2326,9 @@ always quadded over the full line length.
The <kbd>ADJUST</kbd> argument allows you to add(<kbd>+</kbd>) or
subtract (<kbd>-</kbd>) vertical space between labels and captions
and the output to which they are attached. The argument requires a
-<a href="definitions.html#unitofmeasure">unit of measure</a>. For
-example, if you find that table labels are a bit too close to the
-table itself,
+<a href="definitions.html#unitofmeasure">unit of measure</a>.
+For example, if you find that table labels are a bit too close to
+the table itself,
<br/>
<span class="pre-in-pp">
.LABELS TBL ADJUST +3p
diff --git a/contrib/mom/momdoc/inlines.html b/contrib/mom/momdoc/inlines.html
index a377069..ea7ed49 100644
--- a/contrib/mom/momdoc/inlines.html
+++ b/contrib/mom/momdoc/inlines.html
@@ -501,7 +501,7 @@ HEADERS or FOOTERS, or in the strings passed to
you <i>must</i> use the forms <kbd>\E*[BP<n>]</kbd>
and <kbd>\E*[FP<n>]</kbd> (ie with no space), and enter the
inline beginning with <kbd>\E*</kbd> rather than just <kbd>\*</kbd>,
-eg <kbd>\E*[BP.755]</kbd>.
+eg <kbd>\E*[BP.75]</kbd>.
</p>
</div>
diff --git a/contrib/mom/momdoc/macrolist.html
b/contrib/mom/momdoc/macrolist.html
index 198d35a..7e7e6ee 100644
--- a/contrib/mom/momdoc/macrolist.html
+++ b/contrib/mom/momdoc/macrolist.html
@@ -894,6 +894,12 @@ elsewhere in the documentation.
<td><a href="images.html#mla">MLA</a></td><td>-- MLA-style labelling and
captioning</td>
</tr>
<tr>
+<td><a href="images.html#caption">CAPTION</a></td><td>-- add a caption to a
float or (block)quote</td>
+</tr>
+<tr>
+<td><a href="images.html#label">LABEL</a></td><td>-- add a label to a float or
(block)quote</td>
+</tr>
+<tr>
<td><a href="images.html#captions-labels-sources">CAPTIONS</a></td><td>-- set
style for captions</td>
</tr>
<tr>
diff --git a/contrib/mom/momdoc/rectoverso.html
b/contrib/mom/momdoc/rectoverso.html
index 6877952..e786986 100644
--- a/contrib/mom/momdoc/rectoverso.html
+++ b/contrib/mom/momdoc/rectoverso.html
@@ -92,6 +92,7 @@ aspects of alternating page layout:
<h3 id="rectoverso-list" class="macro-list">Recto/verso macros</h3>
<ul class="macro-list">
<li><a href="#recto-verso">RECTO_VERSO</a></li>
+ <li><a href="#force-recto">FORCE_RECTO</a></li>
<li><a href="#switch-hdrftr">SWITCH_HEADERS (also FOOTERS)</a>
– switch starting position of the header parts (left and right)
</li>
@@ -143,6 +144,27 @@ number position with
</p>
</div>
+<!-- -FORCE_RECTO- -->
+
+<div id="force-recto" class="box-macro-args" style="margin-top: 1em;">
+Macro: <b>FORCE_RECTO</b>
+</div>
+
+<p>
+It is a common convention with two-sided printing to ensure that
+cover pages, title pages, and chapters or major sections of a document
+always begin on the recto side of a page. This sometimes
+necessitates inserting a blank page before the start of a new
+chapter or major section.
+</p>
+
+<p>
+If you would like mom to take care of this for you automatically,
+simply invoke <kbd>FORCE_RECTO</kbd> before the first
+<a href="docprocessing.html#start">START</a>
+of the document.
+</p>
+
<!-- -SWITCH_HDRFTR- -->
<div id="switch-hdrftr" class="box-macro-args" style="margin-top: 1em;">
diff --git a/contrib/mom/momdoc/refer.html b/contrib/mom/momdoc/refer.html
index 05ba1a6..9af763e 100644
--- a/contrib/mom/momdoc/refer.html
+++ b/contrib/mom/momdoc/refer.html
@@ -1725,7 +1725,7 @@ If you output bibliographies at the end of each document
in a
document set in columns, column mode will automatically be
reinstated for each document, even with BIBLIOGRAPHY_NO_COLUMNS
turned on. In such circumstances, you must re-enable
-ENDNOTES_NO_COLUMNS for each separate collated document.
+BIBLIOGRAPHY_NO_COLUMNS for each separate collated document.
</p>
<h4 id="biblio-pagination" class="docs" style="margin-bottom: .5em;">2.
Pagination of bibliographies</h4>
@@ -1822,7 +1822,7 @@ after you’ve finished with your bibliography.
<h5 id="biblio-modify-hdrftr" class="docs" style="margin-top: 0;
margin-bottom: .5em; margin-left: .5em;">• Modifying what goes in the
bibliography header/footer</h5>
-<p>
+<p style="margin-top: 0">
If you wish to modify what appears in the header/footer that appears
on bibliography pages, make the changes before you invoke
<a href="#bibliography"><kbd>.BIBLIOGRAPHY</kbd></a>,
@@ -1863,7 +1863,10 @@ prior to invoking <kbd>.BIBLIOGRAPHY</kbd>.
If your
<a href="docprocessing.html#doctype">DOCTYPE</a>
is <kbd>CHAPTER</kbd>, you must also invoke
-<a href="#endnotes-hdrftr-center">BIBLIOGRAPHY_HEADER_CENTER</a>
+<br/>
+<span class="pre-in-pp">
+ <a href="#endnotes-hdrftr-center">BIBLIOGRAPHY_HEADER_CENTER</a>
+</span>
for the BIBLIOGRAPHY_HEADER_CENTER to appear.
</p>
</div>
diff --git a/contrib/mom/momdoc/tables-of-contents.html
b/contrib/mom/momdoc/tables-of-contents.html
index de98f67..feb05b7 100644
--- a/contrib/mom/momdoc/tables-of-contents.html
+++ b/contrib/mom/momdoc/tables-of-contents.html
@@ -276,7 +276,7 @@ output to a new file.
</div>
<div class="box-macro-args">
-Macro: <b>TOC</b>
+Macro: <b>TOC</b> <kbd class="macro-args">[ INCLUDE_TITLE ]</kbd>
</div>
<p>
@@ -284,9 +284,18 @@ If you want a table of contents, just place
<kbd>.TOC</kbd> at the
very end of your document. Mom takes care of the rest.
</p>
+<p>
+The optional argument, <kbd>INCLUDE_TITLE</kbd>, is needed only
+if your document is standalone, i.e. is not collated, for example
+an essay. By default, mom does not include the title (and page
+number) of standalone documents in the Table of Contents since it
+is largely redundant. If you would like her to include the title,
+invoke <kbd>.TOC</kbd> with <kbd>INCLUDE_TITLE</kbd>.
+</p>
+
<div class="box-tip">
<p class="tip">
-<span class="tip">Tip:</span>
+<span class="note">Note:</span>
If the last line of text in a document, before <kbd>.TOC</kbd>,
falls too close to the bottom margin, or if the line is followed
by a macro likely to cause a linebreak (eg <kbd>.LIST OFF</kbd> or
@@ -296,7 +305,7 @@ Table of Contents.
<p class="tip-bottom">
In order to avoid this, insert
-<a href="docprocessing.html#EL"><kbd>.EL</kbd></a>
+<a href="typesetting.html#el"><kbd>.EL</kbd></a>
after the last line of text, before <kbd>.TOC</kbd> and/or any
concluding macros. For example,
<br/>
@@ -354,7 +363,14 @@ themselves (overall family, headers/footers, pagination,
etc).
<li><a href="#toc-pn">Reference page numbers style control</a></li>
<li><a href="#toc-title-style">Title entry style control</a></li>
<li><a href="#toc-entry-style">Heading entry style control</a></li>
- <li><a href="#toc-entry-numbers">Controlling the numbering of
entries</a></li>
+ <li>Numbering table of contents items
+ <ul style="margin-left: -.75em; list-style: disc">
+ <li><a href="#toc-prefix-ch-number">Prefix chapter/section numbers</a>
+ <ul style="margin-left: -.75em;">
+ <li><a href="#toc-pad-ch-numbers">Pad chapter/section numbers</a></li>
+ </ul></li>
+ <li><a href="#toc-entry-numbers">Numbering heading entries</a></li>
+ </ul></li>
</ul></li>
<li><a href="#toc-additional">Additional table of contents control macros</a>
<ul style="margin-left: -.5em;">
@@ -802,6 +818,75 @@ or
</span>
</p>
+<!-- -PREFIX_CHAPTER_NUMBERS- -->
+
+<div id="toc-prefix-ch-number" class="box-macro-args">
+Macro: <b>TOC_PREFIX_CHAPTER_NUMBER</b> <kbd class="macro-args"><none>
<anything></kbd>
+</div>
+<p class="alias" style="margin-bottom: 0;">
+<i>Alias:</i> <b>TOC_PREFIX_SECTION_NUMBER</b>
+</p>
+
+<p>
+By default, mom does not prefix a chapter number to chapters or
+section titles in the table of contents. If you would like her to
+do so, invoke <kbd>TOC_PREFIX_CHAPTER_NUMBER</kbd> without an
+argument before
+<a href="docprocessing.html#start">START</a>.
+</p>
+
+<p>
+You may subsequently disable the prefixing of chapter numbers by
+supplying the macro with any argument (<b>OFF, QUIT, Q, X</b>...)
+prior to the <kbd>START</kbd> that comes after
+<a href="rectoverso.html#collate">COLLATE</a>.
+</p>
+
+<p>
+This macro is useful you want chapters numbered in the table of
+contents but the chapters themselves are identified by title only.
+It can be used with both
+<a href="docprocessing.html#doctype">DOCTYPE CHAPTER</a>
+and
+<a href="docprocessing.html#doctype">DOCTYPE DEFAULT</a>.
+The alias <b>TOC_PREFIX_SECTION_NUMBER</b> may be preferable
+in the latter case.
+</p>
+
+<!-- -PAD_TOC_CHAPTER_NUMBERS- -->
+
+<div id="toc-pad-ch-numbers" class="box-macro-args">
+Macro: <b>PAD_TOC_CHAPTER_NUMBERS</b> <kbd class="macro-args"><number of
chapters></kbd>
+</div>
+<p class="alias" style="margin-bottom: 0;">
+<i>Alias:</i> <b>PAD_TOC_SECTION_NUMBERS</b>
+</p>
+
+
+<p>
+If the number of chapters or major sections
+(<a href="docprocessing.html#doctype">DOCTYPE DEFAULT</a>)
+exceeds 9, you can have mom pad the numbers so the rightmost
+numerals of the chapter numbers align. Simply invoke
+<kbd>PAD_TOC_CHAPTER_NUMBERS</kbd> with the number of chapters in
+the document.
+</p>
+
+<p>
+Without padding:
+<br/>
+<span class="pre-in-pp">
+ 9. Chapter Title.....................100
+ 10. Chapter Title....................123
+</span>
+With padding:
+<br/>
+<span class="pre-in-pp">
+ 9. Chapter Title....................100
+ 10. Chapter Title....................123
+</span>
+</p>
+
<!-- -TOC_ENTRY_NUMBERS- -->
<div id="toc-entry-numbers" class="box-macro-args">
@@ -859,10 +944,13 @@ completely.
<div class="box-tip">
<p class="tip">
<span class="note">Note:</span>
-<kbd>.TOC_ENTRY_NUMBER TRUNCATE</kbd> removes the numbering
-associated with title entries if
+<kbd>.TOC_ENTRY_NUMBERS TRUNCATE</kbd> removes the numbering
+associated with table of contents chapter or section titles
+when
<a href="docelement.html#prefix-chapter-number">PREFIX_CHAPTER_NUMBER</a>
-is enabled.
+is enabled. To enable the numbering of chapter or section titles
+in this circumstance, use
+<a href="#toc-prefix-ch-number"><kbd>TOC_PREFIX_CHAPTER_NUMBER</kbd></a>.
</p>
</div>
diff --git a/contrib/mom/momdoc/toc.html b/contrib/mom/momdoc/toc.html
index 077e12c..0381caf 100644
--- a/contrib/mom/momdoc/toc.html
+++ b/contrib/mom/momdoc/toc.html
@@ -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 -- Table of Contents</title>
+ <title>Mom, version 2.1-a -- 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
+ mom, version 2.1-a
</div>
<h1 class="toc" style="margin-top: 9px;">Table of Contents</h1>
diff --git a/contrib/mom/momdoc/typesetting.html
b/contrib/mom/momdoc/typesetting.html
index 4b3f3d3..d89354a 100644
--- a/contrib/mom/momdoc/typesetting.html
+++ b/contrib/mom/momdoc/typesetting.html
@@ -109,9 +109,9 @@ FDL in the main directory of the groff source package.
<li class="item"><a href="inlines.html#index-inlines">List of inline
escapes</a>
</li>
</ul></li>
- <li class="list-head"><a href="color.html#colored-text-intro">Coloured
text</a>
+ <li class="list-head"><a href="color.html">Coloured text</a>
<ul class="no-enumerator">
- <li class="item"><a href="color.html#colored-text-macros">Macro
list</a></li>
+ <li class="item"><a href="color.html#index-color">Macro list</a></li>
</ul></li>
</ul>
</div>
@@ -1348,7 +1348,7 @@ groff’s
<a href="inlines.html#inline-stringwidth-groff"><kbd>\w</kbd></a>
escape as the argument to LL, like this:
<br/>
-<span class="pre=in-pp">
+<span class="pre-in-pp">
.LL +\w'.'u
</span>
The above example increases the current line length by the width of
@@ -1663,11 +1663,6 @@ with the
<span style="font-style: normal;">
<kbd>\c</kbd> inline escape.
</span>
-See
-<span style="font-style: normal;">
-<a href="#el-notes">NOTES</a>,
-</span>
-below.
</p>
<p style="margin-top: -.5em">
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- [groff] 01/01: Updated documentation for 2.1-a,
Peter Schaffter <=