[groff] 08/09: mmroff(1): Revise.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit f96b4d684e956849029b7b7e9f538a071a77b372
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Fri Feb 17 05:59:44 2023 -0600

    mmroff(1): Revise.
    
    * Make more clear when this groff wrapper is useful.
    * Drop a lot of language from `-x` option description.  I can't make
      sense of it; running "mmroff -x" won't result in a document with stale
      cross references--it won't produce the document.  To get a document
      with stale cross references, update the source, then forget to run
      "mmroff -x", instead running groff (nroff, troff) directly.
    * Recast.
---
 contrib/mm/mmroff.1.man | 38 +++++++++++++++++++++++++-------------
 1 file changed, 25 insertions(+), 13 deletions(-)

diff --git a/contrib/mm/mmroff.1.man b/contrib/mm/mmroff.1.man
index 2c9f3c24b..a905add9d 100644
--- a/contrib/mm/mmroff.1.man
+++ b/contrib/mm/mmroff.1.man
@@ -9,7 +9,7 @@ macro package
 .\" Legal Terms
 .\" ====================================================================
 .\"
-.\" Copyright (C) 1989-2020 Free Software Foundation, Inc.
+.\" Copyright (C) 1989-2023 Free Software Foundation, Inc.
 .\"
 .\" Permission is granted to make and distribute verbatim copies of this
 .\" manual provided the copyright notice and this permission notice are
@@ -70,21 +70,39 @@ macro package
 .\" ====================================================================
 .
 .I mmroff
-is a simple preprocessor for
+is a simple wrapper for
 .IR groff ,
-used for expanding cross references in
+used to expand cross references in
 .IR m@TMAC_M_PREFIX@m ;
 see
 .MR groff_mm @MAN7EXT@ .
 .
+It runs
 .I groff
-is executed twice,
+with the
+.B \-mm
+option twice,
 first with
 .B \-z
 and
 .B \-rRef=1
-to collect all cross references and then to do the real processing
-when the cross-reference file is up to date.
+to collect cross references and update the cross-reference file,
+and then again to produce the document.
+.
+Documents that do not use
+.IR "groff mm" 's
+referencing system
+(the
+.BR INITR ,
+.BR SETR ,
+.BR GETHN ,
+.BR GETPN ,
+.BR GETR ,
+and
+.B GETST
+macros)
+do not require
+.IR mmroff .
 .
 .
 .\" ====================================================================
@@ -102,13 +120,7 @@ both exit afterward.
 .
 .TP
 .B \-x
-Just create the cross-reference file.
-.
-This can be used to refresh the cross-reference file;
-it isn't always needed to have accurate cross references and by using
-this option
-.I groff
-will only be run once.
+Create or update the cross-reference file and exit.
 .
 .
 .\" ====================================================================