[groff] 01/01: [mom]: Version 2.6_b, update docs

[Peter Schaffter]

PTPi pushed a commit to branch master
in repository groff.

commit 1fa4894ffcd84e7b2673fdbbb32102b5748563b6
Author: Peter Schaffter <peter@schaffter.ca>
AuthorDate: Mon Jan 22 14:52:45 2024 -0500

    [mom]: Version 2.6_b, update docs
---
 contrib/mom/momdoc/headfootpage.html       | 90 ++++++++++++++++++++++++++++--
 contrib/mom/momdoc/images.html             |  6 +-
 contrib/mom/momdoc/macrolist.html          |  3 +
 contrib/mom/momdoc/tables-of-contents.html | 19 +++++++
 contrib/mom/momdoc/toc.html                |  4 +-
 contrib/mom/momdoc/typesetting.html        |  2 +-
 contrib/mom/momdoc/version-2.html          |  8 +++
 7 files changed, 120 insertions(+), 12 deletions(-)

diff --git a/contrib/mom/momdoc/headfootpage.html 
b/contrib/mom/momdoc/headfootpage.html
index 1c11ab14f..fc83a4b15 100644
--- a/contrib/mom/momdoc/headfootpage.html
+++ b/contrib/mom/momdoc/headfootpage.html
@@ -102,6 +102,7 @@ FDL in the main directory of the groff source package.
 <ul class="toc-docproc" style="margin-top: .5em;">
   <li><a href="#index-pagination">Pagination macros</a></li>
   <li><a href="#index-paginate-control">Pagination control macros and 
defaults</a></li>
+  <li><a href="#pdf-outline-numbering">PDF outline page numbering</a></li>
 </ul>
 <h3 class="toc toc-docproc-header"><a class="header-link" 
href="#blank-pages">Inserting blank pages into a document</a></h3>
 
@@ -1996,11 +1997,11 @@ L "^\E*[$AUTHOR]#\*[PAGE#]^"
 <h2 id="pagination-intro" class="macro-group">Pagination</h2>
 
 <p>
-By default, mom paginates documents.  Page numbers
-appear in the bottom margin of the page, centred between two hyphens.
-As with all elements of mom&#8217;s document processing,
-most aspects of pagination style can be altered to suit your taste
-with control macros.
+By default, mom paginates documents.  Page numbers appear in the
+bottom margin of the page, centred between two hyphens.  As with
+all elements of mom&#8217;s document processing, most aspects of
+pagination style can be altered to suit your taste with control
+macros.
 </p>
 
 
@@ -2014,6 +2015,7 @@ with control macros.
   <li><a href="#draft-with-pagenumber">DRAFT_WITH_PAGENUMBER</a> &ndash; 
attach draft/revision information to page numbers</li>
   <li><a href="#pagenumber-string">PAGENUMBER_STRING</a> &ndash; user-defined 
page number string</li>
   <li><a href="#index-paginate-control">Pagination control macros and 
defaults</a></li>
+  <li><a href="#pdf-outline-pagenumber">PDF outline page numbering</a></li>
 </ul>
 </div>
 
@@ -2269,6 +2271,84 @@ If, for some reason, you want to turn page number 
hyphens back
 on, invoke the macro without an argument.
 </p>
 
+<h2 id="pdf-outline-numbering" class="macro-group">PDF outline page 
numbering</h2>
+
+<p>
+Prior to mom 2.6_b, the document outline panel of PDF viewers
+displayed the physical page numbers of mom documents, not the
+printed page number.  As of 2.6_b, entries in the outline panel show
+the printed page number.  Furthermore, null pages (e.g. cover and
+title pages) are no longer given a page number in the outline.
+</p>
+
+<p>
+Though rare, you may at times want to control the PDF outline page
+numbering, which is accomplished with the
+<a href="#pdf-outline-pn">PDF_OUTLINE_PN</a>
+macro.
+</p>
+
+<div id="pdf-outline-pn-note" class="box-tip">
+<p class="tip-top" style="padding-bottom: .5em">
+<span class="note">Note:</span>
+You must be running a version of groff &gt; 1.23 or have recently
+built groff from sources in order for the outline page numbers
+to reflect the printed page numbers, as described above, and for
+PDF_OUTLINE_PN to work.
+</p>
+</div>
+
+<div class="macro-id-overline">
+<h3 id="pdf-outline-pagenumber" class="macro-id">PDF_OUTLINE_PN</h3>
+</div>
+
+<div class="box-macro-args">
+Macro: <b>PDF_OUTLINE_PN</b> <kbd class="macro-args">SUSPEND | RESUME</kbd>
+<br/>
+Macro: <b>PDF_OUTLINE_PN</b> <kbd class="macro-args">[FORMAT 
&lt;format&gt;]&nbsp;[PREFIX &lt;prefix&gt;]&nbsp;[PAGE 
&lt;pagenumber&gt;]</kbd>
+</div>
+
+<p>
+PDF outline page numbering may be suspended or resumed by calling
+PDF_OUTLINE_PN with the appropriate argument.
+</p>
+
+<p>
+If you wish to change the numbering format, add a prefix to the page
+number, or hard set an outline page number, supply one or more of
+the additional keywords with arguments.
+</p>
+
+<h3 class="docs">FORMAT</h3>
+
+<p>
+<kbd>FORMAT</kbd> may be one of
+</p>
+
+<ul style="list-style-type:none; margin-top: -1em">
+<li><kbd>D</kbd> (digit)</li>
+<li><kbd>R</kbd> (roman numeral, caps)</li>
+<li><kbd>r</kbd> (roman numeral, lower case)</li>
+<li><kbd>A</kbd> (alphabetic, caps)</li>
+<li><kbd>a</kbd> (alphabetic, lower case)</li>
+</ul>
+
+<h3 class="docs">PREFIX</h3>
+
+<p>
+<kbd>PREFIX</kbd> may be anything you like, for example
+&#8220;<kbd>A-</kbd>&#8221; to add a prefix to the outline page
+numbering of an Appendix. <kbd>PREFIX</kbd> must not contain
+spaces.
+</p>
+
+<h3 class="docs">PAGE</h3>
+
+<p>
+<kbd>PAGE</kbd> is the page number you want to appear in the
+outline.
+</p>
+
 <!-- -BLANK_PAGE- -->
 
 <h2 id="blank-pages" class="macro-group">Inserting blank pages into a 
document</h2>
diff --git a/contrib/mom/momdoc/images.html b/contrib/mom/momdoc/images.html
index dc1837fc1..de1bbc206 100644
--- a/contrib/mom/momdoc/images.html
+++ b/contrib/mom/momdoc/images.html
@@ -2957,8 +2957,6 @@ Arguments:
 <br/>
 &nbsp;&nbsp;TITLE_QUAD LEFT | CENTER | RIGHT \
 <br/>
-&nbsp;&nbsp;TOC_HEADER_UNDERSCORE default = none
-<br/>
 &nbsp;&nbsp;TITLE_COLOR &lt;color&gt; \
 <br/>
 &nbsp;&nbsp;PN_FAMILY &lt;family&gt; \
@@ -3226,7 +3224,7 @@ require that the box be started beforehand.  Boxed 
pre-processor
 material must be fully enclosed by BOX&nbsp;/&nbsp;BOX&nbsp;OFF, as
 in this recipe for a one-off boxed pic diagram:
 <span class="pre-in-pp">
-.BOX
+.BOX PIC
 .PS
 &lt;pic commands&gt;
 .PE
@@ -3269,7 +3267,7 @@ The colour may be
       or
       <a href="color.html#xcolor">XCOLOR</a>
   </li>
-  <li>an RGB hexadecimal string beginning with (e.g. #FF0000)</li>
+  <li>an RGB hexadecimal string beginning with <kbd>#</kbd> (e.g. #FF0000)</li>
 </ul>
 
 <p>
diff --git a/contrib/mom/momdoc/macrolist.html 
b/contrib/mom/momdoc/macrolist.html
index 81ebd7cb6..ed2f33021 100644
--- a/contrib/mom/momdoc/macrolist.html
+++ b/contrib/mom/momdoc/macrolist.html
@@ -1436,6 +1436,9 @@ elsewhere in the documentation.
 <tr>
 <td style="vertical-align: top;"><a 
href="headfootpage.html#draft-with-pagenumber">&nbsp;DRAFT_WITH_PAGENUMBER</a></td><td>--
 attach draft/revision to page number</td>
 </tr>
+<tr>
+<td style="vertical-align: top;"><a 
href="headfootpage.html#pdf-outline-numbering">&nbsp;PDF_OUTLINE_PN</a></td><td>--
 change page numbers in the pdf outline</td>
+</tr>
 </table>
 
 <table class="quick-ref">
diff --git a/contrib/mom/momdoc/tables-of-contents.html 
b/contrib/mom/momdoc/tables-of-contents.html
index 2dbd8b13b..016236d4e 100644
--- a/contrib/mom/momdoc/tables-of-contents.html
+++ b/contrib/mom/momdoc/tables-of-contents.html
@@ -386,6 +386,7 @@ themselves (overall family, headers/footers, pagination, 
etc).
 <ol style="margin-top: .5em; padding-bottom: .5em;">
   <li><a href="#toc-general">General table of contents style control</a>
   <ul style="margin-left: -.5em;">
+    <li><a href="#toc-margins">TOC_MARGINS</a> &ndash; left and right margins 
for tables of contents</li>
     <li><a href="#toc-family">TOC_FAMILY</a> &ndash; base family for tables of 
contents</li>
     <li><a href="#toc-pt-size">TOC_PT_SIZE</a> &ndash; base point size for 
tables of contents</li>
     <li><a href="#toc-lead">TOC_LEAD</a> &ndash; leading of tables of 
contents</li>
@@ -429,6 +430,24 @@ themselves (overall family, headers/footers, pagination, 
etc).
 
 <h4 id="toc-general" class="docs" style="margin-top: -1.5em; margin-bottom: 
.5em;">1. General tables of contents style control</h4>
 
+<!-- -TOC_MARGINS- -->
+
+<div id="toc-margins" class="box-macro-args">
+Macro: <b>TOC_MARGINS</b> <kbd class="macro-args">&lt;toc left margin&gt; 
&lt;toc right margin&gt;</kbd>
+</div>
+<p class="requires">
+&bull;&nbsp;Requires a <a href="definitions.html#unitofmeasure">unit of 
measure</a>
+</p>
+
+<p>
+By default, mom applies the left and right margins active at the
+first instance of
+<a href="docprocessing.html#start">START</a>
+to the table of contents.  In cases where this is not desirable,
+TOC_MARGINS allows you to set the table of contents' margins
+explicitly.  Values must be given for both arguments.
+</p>
+
 <!-- -TOC_FAMILY- -->
 
 <div id="toc-family" class="box-macro-args">
diff --git a/contrib/mom/momdoc/toc.html b/contrib/mom/momdoc/toc.html
index 9fd78733d..0aa274602 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.6_a -- Table of Contents</title>
+  <title>Mom, version 2.6_b -- 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.6_a
+    mom, version 2.6_b
   </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 51d199e85..7f015dd18 100644
--- a/contrib/mom/momdoc/typesetting.html
+++ b/contrib/mom/momdoc/typesetting.html
@@ -3048,7 +3048,7 @@ To change any or all of the defaults, you might enter
 or, more readably,
 <br/>
 <span class="pre-in-pp">
-  .SMALLCAPS_STYLE 
+  .SMALLCAPS_STYLE \
   SIZE 80 \
   WEIGHT_ADJ .25 \
   EXTEND 3
diff --git a/contrib/mom/momdoc/version-2.html 
b/contrib/mom/momdoc/version-2.html
index d904d602b..ecd6d3f12 100644
--- a/contrib/mom/momdoc/version-2.html
+++ b/contrib/mom/momdoc/version-2.html
@@ -367,6 +367,14 @@ appropriately when necessary, and a macro to set page or 
slide
 background colour.
 </p>
 
+<h2 id="v2.6-changes" class="docs">6. Version 2.6 changes</h2>
+
+<p>
+Version 2.6 improves Table of Contents handling so that entries may
+span multiple lines.  PDF outline page numbers now map correctly to
+printed page numbers.
+</p>
+
 <h2 id="pdfmom" class="docs">6. pdfmom</h2>
 
 <p>