[groff] 02/04: Document groff_man(7) adjustment control.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit ce65603aa9eeb408bffbbe2b04f8125b206bbcd8
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sat Aug 22 01:42:09 2020 +1000

    Document groff_man(7) adjustment control.
    
    Ordinarily I'd commit the documentation with the code change as is
    proper, but I broke them up in this case so I could test the change to
    the page in light of the one to an-old.tmac.  With "groff -man -dAD=l"
    now recognized, my diffing procedure enables me to review the man page
    changes without all 60 pages showing me the difference between ".ad b"
    and ".ad l".
    
    * tmac/groff_man.7.man.in (Strings) <\*(AD>: Document it.
    
      (Strings) <\*(HF>: Parallelize language with new \*(AD.
    
      (Options) Expand introductory sentence to discuss -d and -r options.
    
      (Options) <-dAD>: Document default and likely values.  Nobody
      right-justifies or centers man page text; send the curious to
      groff(7) for '.ad' request documentation.
    
      (Options) <-dHF>: Document default and steer people to groff(7) for
      '.ft' request documentation.
---
 ChangeLog               | 22 +++++++++++++++++
 NEWS                    |  4 +++
 tmac/groff_man.7.man.in | 66 +++++++++++++++++++++++++++++++++++++++++++++----
 3 files changed, 87 insertions(+), 5 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index c59cfc8..f822649 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,25 @@
+2020-08-22  G. Branden Robinson <g.branden.robinson@gmail.com>
+
+       * tmac/an-old.tmac (TH): Set adjustment to user preference with
+       each new page rendered, in case a hostile page meddled with
+       '.ad' or '.na'.
+       (after .mso man.local): Set the default adjustment mode only if
+       a -d option or man.local did not.  Also do the same for the HF
+       string; relocate its definition here and make it similarly
+       conditional.  Also update comment on setting of CS and CT
+       registers and style their conditionals consistently with the
+       rest of the package.
+
+       * tmac/groff_man.7.man.in (Strings) <\*(AD>: Document it.
+       (Strings) <\*(HF>: Parallelize language with new \*(AD.
+       (Options) Expand introductory sentence to discuss -d and -r
+       options.
+       (Options) <-dAD>: Document default and likely values.  Nobody
+       right-justifies or centers man page text; send the curious to
+       groff(7) for '.ad' request documentation.
+       (Options) <-dHF>: Document default and steer people to groff(7)
+       for '.ft' request documentation.
+
 2020-08-21  G. Branden Robinson <g.branden.robinson@gmail.com>
 
        * tmac/an-old.tmac (set-an-margin): Rename...
diff --git a/NEWS b/NEWS
index 9d876fe..f36585d 100644
--- a/NEWS
+++ b/NEWS
@@ -89,6 +89,10 @@ o The new option -V emits the constructed groff command that 
nroff would
 Macro Packages
 --------------
 
+o The an (man) macro package supports a new AD string to put the default
+  adjustment mode under user control.  The default is 'b' (adjust lines
+  to both margins) as has been the Unix man practice since 1979.
+
 o The an (man) macro package supports new CS and CT number registers to
   control rendering of man page section headings and titles,
   respectively, in full capitals.  These default off (with no visible
diff --git a/tmac/groff_man.7.man.in b/tmac/groff_man.7.man.in
index 894732f..35973e7 100644
--- a/tmac/groff_man.7.man.in
+++ b/tmac/groff_man.7.man.in
@@ -1935,12 +1935,23 @@ expands to an escape setting the point size to the 
document default.
 .
 .
 .TP
-.B \e*(HF
-expands to the font identifier used to print headings and subheadings.
+.B \e*(AD
+expands to the default adjustment mode;
+see section \(lqOptions\(rq below for the default.
+.
+This string is a GNU extension\" from groff 1.22.5
+to support user customization of man page rendering,
+and should not be used in man page sources.
+.
 .
-The default is \(lqB\(rq.
+.TP
+.B \e*(HF
+expands to the font identifier used to print headings and subheadings;
+see section \(lqOptions\(rq below for the default.
 .
-This string is a GNU extension.\" from groff 1.19
+This string is a GNU extension\" from groff 1.19
+to support user customization of man page rendering,
+and should not be used in man page sources.
 .
 .
 .TP
@@ -2820,12 +2831,42 @@ SunOS\~4.0 (1988) may have been the first to support
 .
 The following
 .I groff
-options set number registers recognized and used by the
+options set registers
+(with the
+.B \-r
+option)
+and strings
+(with the
+.B \-d
+option)
+recognized and used by the
 .I man
 macro package.
 .
 .
 .TP
+.BI \-dAD= adjustment-mode
+Set line adjustment to
+.I adjustment-mode ,
+which is typically
+.RB \[lq] b \[rq]
+for adjustment to both margins
+(the default),
+or
+.RB \[lq] l \[rq]
+for left adjustment
+(ragged right margin).
+.
+Any valid parameter to
+.IR groff 's
+\[lq].ad\[rq] request is accepted.
+.
+See
+.IR groff (@MAN7EXT@)
+for less-common choices.
+.
+.
+.TP
 .B \-rcR=1
 Continuous rendering.
 .
@@ -2897,6 +2938,21 @@ The default is \-0.5i.
 .
 .
 .TP
+.BI \-dHF= heading-font
+See the font used to print headings and subheadings;
+the default is
+.RB \(lq B \(rq
+(bold).
+.
+Any valid parameter to
+.IR groff 's
+\[lq].ft\[rq] request is accepted.
+.
+See
+.IR groff (@MAN7EXT@).
+.
+.
+.TP
 .BI \-rHY= mode
 Set hyphenation mode,
 as documented in section \(lqHyphenation\(rq of