[groff] 04/06: groff_man(7): Add material on hooks and encoding.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit d33a1b9aa60dcb9daaf4e0e24f475e246714a942
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Tue Aug 11 23:11:11 2020 +1000

    groff_man(7): Add material on hooks and encoding.
    
    * tmac/groff_man.7.man: (Description, ./Deprecated features): Stop
      identifying .BT and .DT as "deprecated"; they shouldn't ever be called
      in man pages, but that has never been their intention.
    
      (Description): Identify character encoding and line-ending
      requirements (tutorial/style-guide material).
    
      (Description/Hooks): Add new subsection to house descriptions of .BT
      and .DT.  Add mnemonic expansions for both.
---
 ChangeLog            | 11 ++++++++
 tmac/groff_man.7.man | 72 ++++++++++++++++++++++++++++++----------------------
 2 files changed, 52 insertions(+), 31 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 790eec6..ee8fdbd 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,14 @@
+2020-08-11  G. Branden Robinson <g.branden.robinson@gmail.com>
+
+       * tmac/groff_man.7.man: Add material on hooks and encoding.
+       (Description, ./Deprecated features): Stop identifying .BT and
+       .DT as "deprecated"; they shouldn't ever be called in man pages,
+       but that has never been their intention.
+       (Description): Identify character encoding and line-ending
+       requirements (tutorial/style-guide material).
+       (Description/Hooks): Add new subsection to house descriptions of
+       .BT and .DT.  Add mnemonic expansions for both.
+
 2020-07-31  G. Branden Robinson <g.branden.robinson@gmail.com>
 
        * man/groff.7.man (Control Characters): Incorrect claims were
diff --git a/tmac/groff_man.7.man b/tmac/groff_man.7.man
index 6f19ca0..be4efbf 100644
--- a/tmac/groff_man.7.man
+++ b/tmac/groff_man.7.man
@@ -8,7 +8,7 @@ groff_man \- GNU roff macro package for formatting man pages
 .\" Legal Terms
 .\" ====================================================================
 .\"
-.\" Copyright (C) 1999-2018 Free Software Foundation, Inc.
+.\" Copyright (C) 1999-2018, 2020 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
@@ -130,11 +130,9 @@ _
 .PP
 Macros whose use we discourage
 .RB ( .AT ,
-.BR .BT ,
 .BR .DT ,
 .BR .HP ,
 .BR .PD ,
-.BR .PT ,
 and
 .BR .UC )
 are described in subsection \(lqDeprecated features\(rq below.
@@ -159,8 +157,11 @@ are described in subsection \(lqDeprecated features\(rq 
below.
 .\" ====================================================================
 .\" .SS "Input file format"
 .\" ====================================================================
-.\" UTF-8 (or just ASCII) is a good input encoding.
-.\" Unix line endings
+.PP
+Man pages should be encoded using Unicode basic Latin code points
+exclusively,
+and employ the Unix line-ending convention
+(U+000A only).
 .\" text lines vs. control lines (macro calls)
 .\" The above distinction works well with filling.
 .\" Don't fill your input text yourself; let groff do the work.
@@ -181,6 +182,8 @@ are described in subsection \(lqDeprecated features\(rq 
below.
 .\"   flush left
 .\"   single-spacing
 .\" END STYLE
+.
+.
 .\" ====================================================================
 .SS "Macro reference preliminaries"
 .\" ====================================================================
@@ -2430,6 +2433,39 @@ avoided in man pages.
 .
 .
 .\" ====================================================================
+.SS Hooks
+.\" ====================================================================
+.
+Two macros called internally by the
+.I groff man
+package to format page headers and footers can be redefined by the
+administrator in a site's
+.I man.local
+file
+(see section \(lqFiles\(rq below).
+.
+The default headers and footers are documented in the description of
+.B .TH
+above.
+.
+These macros are GNU extensions and it makes no sense for a man page
+to call them.
+.
+.
+.\" both from groff 1.19
+.TP
+.B .BT
+Set the page footer
+(\(lqbottom trap\(rq).
+.
+.
+.TP
+.B .PT
+Set the page header
+(\(lqpage trap\(rq).
+.
+.
+.\" ====================================================================
 .SS "Deprecated features"
 .\" ====================================================================
 .
@@ -2484,19 +2520,6 @@ such as in \(lqSystem\~V Release\~3\(rq.
 .
 .
 .TP
-.B .BT
-Set the page footer.
-.
-By redefining this macro
-(a GNU extension)\" from groff 1.19
-in a
-.I man.local
-file
-(see section \(lqFiles\(rq below),
-an administrator can customize the footer for a site.
-.
-.
-.TP
 .B .DT
 Set tab stops every 0.5\~inches.
 .
@@ -2579,19 +2602,6 @@ to express are likely to be lost.
 .
 .
 .TP
-.B .PT
-Set the page header.
-.
-By redefining this macro
-(a GNU extension)\" from groff 1.19
-in a
-.I man.local
-file
-(see section \(lqFiles\(rq below),
-an administrator can customize the header for a site.
-.
-.
-.TP
 .BR .UC " ["\c
 .IR version ]
 Alter the footer for use with legacy BSD man pages,