[groff] 01/01: Doc updates

[Peter Schaffter]

PTPi pushed a commit to branch master
in repository groff.

commit 84ad6b700ad7beb883169208035d09a16021288c
Author: Peter Schaffter <address@hidden>
Date:   Wed May 3 13:57:06 2017 -0400

    Doc updates
---
 contrib/mom/momdoc/docelement.html    | 14 ++++++++-
 contrib/mom/momdoc/docprocessing.html | 56 ++++++++++++++++++++++++++++++++++-
 contrib/mom/momdoc/macrolist.html     | 11 ++++---
 contrib/mom/momdoc/rectoverso.html    |  6 ++--
 contrib/mom/momdoc/toc.html           |  4 +--
 5 files changed, 80 insertions(+), 11 deletions(-)

diff --git a/contrib/mom/momdoc/docelement.html 
b/contrib/mom/momdoc/docelement.html
index 8ee3054..6c0bcd5 100644
--- a/contrib/mom/momdoc/docelement.html
+++ b/contrib/mom/momdoc/docelement.html
@@ -1326,6 +1326,7 @@ which may be given in any order:
   CAPS | NO_CAPS \
   SMALLCAPS | NO_SMALLCAPS \
   BASELINE_ADJUST &lt;amount to raise heading from the baseline&gt; \
+  NEEDS &lt;lines of text required beneath the heading &gt;
   SPACE_AFTER | NO_SPACE_AFTER \
   NUMBER | NO_NUMBER \
   NO_SHIM | SHIM \
@@ -1381,6 +1382,17 @@ appended to it.
 </p>
 
 <p class="defaults" style="margin-bottom: 1em">
+<kbd>NEEDS</kbd> lets you reserve the number of lines of text
+required beneath a heading, including fractions thereof (eg
+&#8220;1.5&#8221; for one line of text plus half a linespace).
+If a heading falls near the bottom margin and there isn&#8217;t
+sufficient room for both the heading and the reserved space, mom
+will break to a new page for the heading.  A
+<a href="definitions.html#unitofmeasure">unit of measure</a>
+should not be appended to the argument.
+</p>
+
+<p class="defaults" style="margin-bottom: 1em">
 <kbd>SPACE_AFTER</kbd> inserts a blank line equal to the current
 <a href="definitions.html#leading">leading</a> after a HEADING.
 If you'd like a full linespace after a heading level, use
@@ -2765,7 +2777,7 @@ or the
 </div>
 
 <div class="box-macro-args">
-Macro: <b>LIST</b> <kbd class="macro-args">[ BULLET | DASH | DIGIT | ALPHA | 
alpha | ROMAN&lt;n&gt; | roman&lt;n&gt; | USER &lt;string&gt;] [ 
&lt;separator&gt; | &lt;user-defined enumerator&gt; ] [ &lt;prefix&gt; ] [ 
&lt;off&gt; ]</kbd>
+Macro: <b>LIST</b> <kbd class="macro-args">[ BULLET | DASH | DIGIT | ALPHA | 
alpha | ROMAN&lt;n&gt; | roman&lt;n&gt; | USER &lt;user-defined enumerator&gt;  
| PLAIN ] [ &lt;separator&gt; ] [ &lt;prefix&gt; ] [ &lt;anything&gt; ]</kbd>
 </div>
 
 <p>
diff --git a/contrib/mom/momdoc/docprocessing.html 
b/contrib/mom/momdoc/docprocessing.html
index 6452ef4..6250ca1 100644
--- a/contrib/mom/momdoc/docprocessing.html
+++ b/contrib/mom/momdoc/docprocessing.html
@@ -1508,6 +1508,44 @@ or
 <a href="cover.html#cover">COVER</a>
 </p>
 
+<p>
+Style parameters for the copyright line may be
+entered as individual macros or
+<a href="docelement.html#grouping">grouped</a>,
+eg
+<br/>
+<span class="pre-in-pp">
+  .COPYRIGHT_FAMILY H
+  .COPYRIGHT_FONT   R
+  .COPYRIGHT_SIZE   -2
+</span>
+or
+<br/>
+<span class="pre-in-pp">
+  .COPYRIGHT_STYLE \
+  FAMILY H \
+  FONT   R \
+  SIZE   -2
+</span>
+The vertical position of the copyright line may be raised (-) or
+lowered (+) with the macro COPYRIGHT_V_ADJUST.  For example, to
+raise the copyright line by 3
+<a href="definitions.html#picaspoints">points</a>, you&#8217;d do
+<br/>
+<span class="pre-in-pp">
+  .COPYRIGHT_V_ADJUST -3p
+</span>
+Alternatively, the COPYRIGHT_STYLE macro may be used with the
+argument <kbd>V_ADJUST</kbd>:
+<span class="pre-in-pp">
+  .COPYRIGHT_STYLE \
+  FAMILY    H \
+  FONT      R \
+  SIZE     -2 \
+  V_ADJUST -3p
+</span>
+</p>
+
 <!-- -MISC- -->
 
 <div class="macro-id-overline">
@@ -3506,11 +3544,13 @@ conjunction with
 <!-- -ADD_SPACE- -->
 
 <div class="macro-id-overline">
-<h3 id="add-space" class= "macro-id">ADD_SPACE</h3>
+<h3 id="add-space" class= "macro-id">ADD_SPACE/RESTORE_SPACE</h3>
 </div>
 
 <div class="box-macro-args">
 Macro: <b>ADD_SPACE</b> <kbd class="macro-args">&lt;amount of space&gt;</kbd>
+<br/>
+Macro: <b>RESTORE_SPACE</b>
 </div>
 
 <p class="requires">
@@ -3554,6 +3594,20 @@ whatever correction is required by the
 strategy in effect.
 </p>
 
+<h4 class="docs doc-param-macros" style="margin-top: .5em">RESTORE_SPACE</h4>
+
+<p style="margin-top: .5em">
+You may sometimes find that mom refuses to respect
+<a href="typesetting.html#space">SP</a>,
+<a href="typesetting.html#index-aldrld">ALD/RLD</a>,
+<a href="docprocessing.html#shim">SHIM</a>,
+or
+<a href="docprocessing.html#flex">FLEX</a>
+after the first element (line of text, floated material) output
+at the top of a page.  Should this happen, insert the macro
+RESTORE_SPACE before issuing the spacing command.
+</p>
+
 <!-- *** -->
 
 <h2 id="intro-doc-param" class="macro-group">Changing document-wide style 
parameters after START</h2>
diff --git a/contrib/mom/momdoc/macrolist.html 
b/contrib/mom/momdoc/macrolist.html
index 1e57984..f36cf74 100644
--- a/contrib/mom/momdoc/macrolist.html
+++ b/contrib/mom/momdoc/macrolist.html
@@ -84,9 +84,9 @@ elsewhere in the documentation.
   <li><a href="#qr-24">Initiate document processing</a></li>
 </ul>
 </div>
-<ul style="margin-top: 1.75em; margin-left: 0; padding-left: 0; 
list-style-type: none;">
+<ul style="margin-top: 2.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&#8217;s first-page header<br/><span 
style="margin-left: 1.25em;">(the &#8220;docheader&#8221;)</span></a></li>
+  <li><a href="#qr-43">Managing the docheader</a></li>
   <li><a href="#qr-25">Epigraphs</a></li>
   <li><a href="#qr-26">Headings</a></li>
   <li><a href="#qr-30">Paragraphs</a></li>
@@ -1414,16 +1414,19 @@ elsewhere in the documentation.
 <td><a href="docprocessing.html#add-space">ADD_SPACE</a></td><td>-- add space 
to the top of a page</td>
 </tr>
 <tr>
+<td><a href="docprocessing.html#add-space">RESTORE_SPACE</a></td><td>-- 
restore spacing at the top of a page</td>
+</tr>
+<tr>
 <td><a href="headfootpage.html#blank-pages">BLANKPAGE</a></td><td>-- output 
one or more blank pages</td>
 </tr>
 <tr>
 <td><a 
href="docprocessing.html#doc-lead-adjust">DOC_LEAD_ADJUST</a></td><td>-- adjust 
leading to fill pages</td>
 </tr>
 <tr>
-<td><a href="rectoverso.html#collate">COLLATE</a></td><td>-- join documents 
(chapters/sections) together</td>
+<td><a href="rectoverso.html#collate">COLLATE</a></td><td>-- join documents 
(chapters/sections)</td>
 </tr>
 <tr>
-<td><a href="docprocessing.html#shim">SHIM</a></td><td>-- move vertical 
position to next valid baseline</td>
+<td><a href="docprocessing.html#shim">SHIM</a></td><td>-- advance to next 
valid baseline</td>
 </tr>
 </table>
 
diff --git a/contrib/mom/momdoc/rectoverso.html 
b/contrib/mom/momdoc/rectoverso.html
index 49bfeb3..9a8ffba 100644
--- a/contrib/mom/momdoc/rectoverso.html
+++ b/contrib/mom/momdoc/rectoverso.html
@@ -40,7 +40,7 @@ FDL in the main directory of the groff source package.
 
 <h1 class="docs">Recto/verso printing, collating</h1>
 
-<div style="width: 40%; margin: auto;">
+<div style="width: 50%; margin: auto;">
 <ul class="no-enumerator" style="margin-left: -1em;">
   <li><a href="#rectoverso-intro">Introduction to recto/verso printing</a>
   <ul style="margin-left: -.5em; list-style-type: disc;">
@@ -77,9 +77,9 @@ aspects of alternating page layout:
       <a href="headfootpage.html#description-general">General description of 
headers</a>)
   </li>
   <li>switching
-      <a href="headfootpage.html#hdrftr-rectoverso">HEADER_RECTO</a>
+      <a href="headfootpage.html#hdrftr-recto">HEADER_RECTO</a>
       and
-      <a href="headfootpage.html#hdrftr-rectoverso">HEADER_VERSO</a>
+      <a href="headfootpage.html#hdrftr-recto">HEADER_VERSO</a>
       if user-defined, single string recto/verso headers
       or footers are used in place of the default 3-part
       headers or footers
diff --git a/contrib/mom/momdoc/toc.html b/contrib/mom/momdoc/toc.html
index b83e8ff..a480895 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.2 -- Table of Contents</title>
+  <title>Mom, version 2.2-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.2
+    mom, version 2.2-a
   </div>
 
 <h1 class="toc" style="margin-top: 9px;">Table of Contents</h1>