[groff] 01/01: Doc updates to reflect changes in 2.0-c_1.

[Peter Schaffter]

PTPi pushed a commit to branch master
in repository groff.

commit 83b356011af6aebdde77b2bf0568f8e107afb216
Author: Peter Schaffter <address@hidden>
Date:   Mon Oct 20 12:55:20 2014 -0400

    Doc updates to reflect changes in 2.0-c_1.
---
 contrib/mom/momdoc/docelement.html  |   27 +++++++
 contrib/mom/momdoc/images.html      |  128 +++++++++++++++--------------------
 contrib/mom/momdoc/toc.html         |   22 +++---
 contrib/mom/momdoc/typesetting.html |    6 ++-
 4 files changed, 97 insertions(+), 86 deletions(-)

diff --git a/contrib/mom/momdoc/docelement.html 
b/contrib/mom/momdoc/docelement.html
index 4e79421..090352e 100644
--- a/contrib/mom/momdoc/docelement.html
+++ b/contrib/mom/momdoc/docelement.html
@@ -1981,6 +1981,33 @@ quotes on the same page are all spaced identically.
 </p>
 </div>
 
+<h3 id="float-quote" class="docs">Keeping QUOTEs and BLOCKQUOTEs together as a 
block</h3>
+
+<p>
+The text of quotes and blockquotes is output immediately, and may therefore
+start on one page and finish on the next.  If you wish to keep the
+text together as a block, deferred to the following page if the
+block doesn&#8217;t all fit on one page, wrap
+(BLOCK)QUOTE&nbsp;/&nbsp;(BLOCK)QUOTE&nbsp;OFF
+inside a
+<a href="images.html#floats-intro">float</a>.  If you further wish to
+force a page break before the floated quote or blockquote (leaving
+whitespace at the bottom of the page, pass
+<a href="images.html#float">FLOAT</a>
+the <kbd>FORCE</kbd> argument.
+<span class="pre-in-pp">
+  .FLOAT FORCE
+  .QUOTE
+  Fly me to the moon
+  And let me play among the stars
+  Let me see what life is like
+  On Jupiter and Mars
+  .QUOTE END
+  .FLOAT OFF
+</span>
+
+</p>
+
 <!-- -QUOTE- -->
 
 <div class="macro-id-overline">
diff --git a/contrib/mom/momdoc/images.html b/contrib/mom/momdoc/images.html
index 0b3a9cb..fdff0c0 100644
--- a/contrib/mom/momdoc/images.html
+++ b/contrib/mom/momdoc/images.html
@@ -937,7 +937,7 @@ in any order, although it is advisable to put 
<kbd>CAPTION</kbd>,
 <kbd>SHORT_CAPTION</kbd>, and/or <kbd>LABEL</kbd> last.
 </p>
 
-<h5 class="docs" style="margin-top: 1em; text-transform: none">'H'</h5>
+<h5 id="h" class="docs" style="margin-top: 1em; text-transform: none">'H'</h5>
 
 <p>
 With the <b>H</b> argument, a table will span as many pages as
@@ -1078,6 +1078,13 @@ in
 The text of the caption must be surrounded by double-quotes.
 </p>
 
+<p>
+Please note that if your table has a caption, you must invoke
+<kbd>TS</kbd> with the <kbd>H</kbd> flag, which also entails the use
+of
+<a href="#th">TH</a>.
+</p>
+
 <h5 class="docs" style="margin-top: 1em; text-transform: 
none">'SHORT_CAPTION'</h5>
 
 <p>
@@ -1105,12 +1112,26 @@ which, if enabled, overrides the <kbd>LABEL</kbd> 
argument.
 The <b>TH</b> macro (<b>T</b>able <b>H</b>eader), which is required
 when you begin a table with <kbd>.TS H</kbd>, allows you to
 determine what goes in a table&#8217;s running header if it spans
-multiple pages.  If you place it immediately underneath your
-<kbd>tbl</kbd> formatting specifications, the last line of which
-always ends with a period (see <kbd>tbl(1)</kbd>), there will
-be no running header.  If you place it under the first row of
-<kbd>tbl</kbd> data, the first row will form the header; under the
-second row, the first and second rows form the header, and so on.
+multiple pages.  Placing <kbd>.TH</kbd> under the first row of
+<kbd>tbl</kbd> data makes the first row the header.  If placed under
+the second row, the first and second rows form the header, and so
+on.
+</p>
+
+<p>
+As there are sometimes reasons to run <kbd>.TS H</kbd> when
+you don&#8217;t, in fact, want a running header (e.g. when
+your table has a caption), you can suppress it by placing
+<kbd>.TH</kbd> immediately underneath your <kbd>tbl</kbd> formatting
+specifications, the last line of which always ends with a period
+(see <kbd>tbl(1)</kbd>).</p>
+</p>
+
+<p>
+See the
+<kbd><a href="#h">H</a></kbd>
+argument to <kbd>.TS</kbd> for examples demonstrating <kbd>.TH</kbd>
+placement.
 </p>
 
 <div class="macro-id-overline">
@@ -1390,7 +1411,7 @@ required)
 <br/>
 &nbsp;&nbsp;[ LABEL "&lt;label&gt;" ]
 <br/>
-&nbsp;&nbsp;[ LABEL_ADJUST +|-&lt;vertical adjustment&gt; ]
+&nbsp;&nbsp;[ SHIFT_LABEL +|-&lt;vertical adjustment&gt; ]
 <br/>
 &nbsp;&nbsp;[ SHORT_CAPTION "&lt;short caption&gt;" ]
 <br/>
@@ -1495,14 +1516,14 @@ Equations.  Mom provides an auto-labelling facility for 
equations (see
 which, if enabled, overrides the <kbd>LABEL</kbd> argument.
 </p>
 
-<h5 class="docs" style="margin-top: 1em; text-transform: 
none">'LABEL_ADJUST'</h5>
+<h5 class="docs" style="margin-top: 1em; text-transform: 
none">'SHIFT_LABEL'</h5>
 
 <p>
-<kbd>LABEL_ADJUST</kbd> allows you to raise (<kbd>-</kbd>) or lower
+<kbd>SHIFT_LABEL</kbd> allows you to raise (<kbd>-</kbd>) or lower
 (<kbd>+</kbd>) the equation label.  It&#8217;s primary use is to
 center equation labels vertically on the equation rather than flush
 with the last line.  Assuming a three-line equation,
-<kbd>.EQ&nbsp;LABEL_ADJUST&nbsp;-1v</kbd> would raise the label by
+<kbd>.EQ&nbsp;SHIFT_LABEL&nbsp;-1v</kbd> would raise the label by
 one line, thus centering it vertically on the equation.
 </p>
 
@@ -1629,27 +1650,27 @@ pdf images as &#8220;Fig. &lt;n&gt;&#8221;, and for 
equations as
 </p>
 
 <p>
-If you wish to change the prefix string, pass <i>both</i>
-the <kbd>PREFIX</kbd> and <kbd>SUFFIX</kbd> arguments to
-<kbd>.AUTOLABEL_&lt;type&gt;</kbd> and enter the string you wish,
-including any spaces, surrounded by double-quotes.  If no suffix is
-needed, give <kbd>SUFFIX</kbd> an empty string with two adjacent
-double-quotes.
-</p>
-
-<p>
-For example, if you are including musical excerpts
-in your document, MLA style requires that they be labelled
-&#8220;Ex. &lt;n&gt;&#8221;.  Since musical excerpts are likely to
-be scanned images (in pdf format, don&#8217;t forget), you must
-change the prefix string for pdf images:
+Use <kbd>PREFIX&nbsp;&lt;"string"&gt;</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 &#8220;Ex.&nbsp;&lt;n&gt;&#8221;.  Since musical excerpts
+are likely to be scanned images (in pdf format, don&#8217;t forget),
+you have to change the prefix string for pdf images:
+<br/>
+<span class="pre-in-pp">
+  .AUTOLABEL_IMAGES PREFIX "Ex. "
+</span>
+If you need a suffix after the automatic numbering, use
+<kbd>SUFFIX&nbsp;&lt;"string"&gt;</kbd>, like this:
 <br/>
 <span class="pre-in-pp">
-  .AUTOLABEL_IMAGES PREFIX "Ex. " SUFFIX ""
+  .AUTOLABEL_IMAGES PREFIX "(Fig. " SUFFIX ")"
 </span>
+Note that the double-quotes around the single-character SUFFIX
+string are optional.
 </p>
 
-<h4 class="docs" style="margin-top: -1em">Prefixing chapter numbers</h4>
+<h4 class="docs" style="margin-top: -.5em">Prefixing chapter numbers</h4>
 
 <p>
 If you would like mom to prefix chapter numbers to the label,
@@ -1663,8 +1684,8 @@ to invoking 
<kbd>AUTOLABEL_&lt;type&gt;&nbsp;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</kbd> when it is required
-will result in mom aborting with a reminder to do so.
+provide a chapter number after <kbd>PREFIX_CHAPTER</kbd> when it is
+required will result in mom aborting with a reminder to do so.
 </p>
 
 <div class="macro-id-overline">
@@ -1825,51 +1846,10 @@ explicitly named style parameters.
 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.
-</p>
-
-<p>
-The meaning of left, center, and right is fluid, depending on a
-number of factors.  Know, however, that if you pass the optional
-<kbd>ON_LL</kbd> argument to <kbd>QUAD &lt;direction&gt;</kbd>, mom
-will use the entire line length, from left to right margin, as the
-basis for quadding.
-</p>
-
-<p>
-For figures and tables, without the <kbd>ON_LL</kbd> argument,
-<kbd>LEFT</kbd>, <kbd>CENTER</kbd>, and <kbd>RIGHT</kbd> mean flush
-left, center, or right on the figure or table.
-</p>
-
-<p>
-If the figure or table is positioned left and the quad direction is
-<kbd>LEFT</kbd>, text will flow past the figure or table and break
-only when the right margin of the page is reached.  If the quad
-direction is <kbd>CENTER</kbd>, text will be centered on the figure
-or table.  If the quad direction is <kbd>RIGHT</kbd>, text will be
-quadded flush with the right margin of the figure or table.
-</p>
-
-<p>
-If the figure or table is positioned center and the quad direction
-is <kbd>CENTER</kbd>, text will be centered on the full line length.
-If the quad direction is <kbd>LEFT</kbd> or <kbd>RIGHT</kbd>, text
-will be set flush left or right on the figure or table, with the
-width of the figure or table determining the line length (unless
-<kbd>ON_LL</kbd> is given).
-</p>
-
-<p>
-If the figure or table is positioned right and the quad direction
-is <kbd>RIGHT</kbd>, text will be set flush right with the figure or
-table (which is also the right margin of the page) and will extend
-<i>to the right</i> of the figure or table over the full line length.
-If the quad direction is <kbd>LEFT</kbd>, text
-will be set flush left on the figure or table, with the
-width of the figure or table determining the line length (unless
-<kbd>ON_LL</kbd> is given).  If the quad direction is
-<kbd>CENTER</kbd>, text is centered on the figure or table.
+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&nbsp;&lt;direction&gt;</kbd>.
 </p>
 
 <p>
diff --git a/contrib/mom/momdoc/toc.html b/contrib/mom/momdoc/toc.html
index b7f72af..da3b6b0 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-c -- Table of Contents</title>
+  <title>Mom, version 2.1-c_1 -- 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-c
+    mom, version 2.1-c_1
   </div>
 
 <h1 class="toc" style="margin-top: 9px;">Table of Contents</h1>
@@ -368,18 +368,18 @@ FDL in the main directory of the groff source package.
             </ul></li>
             <li><a href="images.html#refer">5.5.6.4 refer support</a></li>
           </ul></li>
-        <li><a href="#captions-and-labels">5.5.7 Captions and labels</a>
+        <li><a href="images.html#captions-and-labels">5.5.7 Captions and 
labels</a>
         <ul>
-          <li><a href="#autolabel">5.5.7.1 AUTOLABEL</a></li>
-          <li><a href="#caption-after-label">5.5.7.2 
CAPTION_AFTER_LABEL</a></li>
-          <li><a href="#captions-labels-sources">5.5.7.3 CAPTIONS / LABELS / 
SOURCES&mdash;set style parameters</a></li>
-          <li><a href="#mla">5.5.7.4 MLA</a></li>
+          <li><a href="images.html#autolabel">5.5.7.1 AUTOLABEL</a></li>
+          <li><a href="images.html#caption-after-label">5.5.7.2 
CAPTION_AFTER_LABEL</a></li>
+          <li><a href="images.html#captions-labels-sources">5.5.7.3 CAPTIONS / 
LABELS / SOURCES&mdash;set style parameters</a></li>
+          <li><a href="images.html#mla">5.5.7.4 MLA</a></li>
         </ul></li>
-        <li><a href="#lists-of">5.5.8 Lists of Figures, Tables, and 
Equations</a>
+        <li><a href="images.html#lists-of">5.5.8 Lists of Figures, Tables, and 
Equations</a>
         <ul>
-          <li><a href="#lists-placement">5.5.8.1 Placement of Lists</a></li>
-          <li><a href="#lists-macros">5.5.8.2 Macros to generate Lists</a></li>
-          <li><a href="#formatting-lists">5.5.8.3 Formatting and style 
parameters for Lists</a>
+          <li><a href="images.html#lists-placement">5.5.8.1 Placement of 
Lists</a></li>
+          <li><a href="images.html#lists-macros">5.5.8.2 Macros to generate 
Lists</a></li>
+          <li><a href="images.html#formatting-lists">5.5.8.3 Formatting and 
style parameters for Lists</a>
           <ul>
             <li><a href="#lists-style">5.5.8.3.1 LISTS_STYLE</a></li>
           </ul></li>
diff --git a/contrib/mom/momdoc/typesetting.html 
b/contrib/mom/momdoc/typesetting.html
index 0bda6ea..3a8722a 100644
--- a/contrib/mom/momdoc/typesetting.html
+++ b/contrib/mom/momdoc/typesetting.html
@@ -305,6 +305,7 @@ PAGEWIDTH.
 when you need it, should be placed at the top of your files.
 </p>
 </div>
+
 <!-- -PAGELENGTH- -->
 
 <div class="macro-id-overline">
@@ -345,7 +346,7 @@ when you need it, should be placed at the top of your files.
 </div>
 
 <div class="box-macro-args">
-Macro: <b>PAPER</b> <kbd class="macro-args">&lt;paper type&gt;</kbd>
+Macro: <b>PAPER</b> <kbd class="macro-args">&lt;paper type&gt; [ LANDSCAPE 
]</kbd>
 </div>
 
 <p>
@@ -374,6 +375,9 @@ than to remember the correct dimensions and enter
   .PAGEWIDTH  595p
   .PAGELENGTH 842p
 </span>
+If you&#8217;d like landscape orientation for your paper type,
+pass PAPER the <kbd>LANDSCAPE</kbd> argument.
+<p>
 Please read the
 <a href="#page-setup-note">Important note on page dimensions and papersize</a>
 for information on ensuring groff respects your PAPER size.