[groff] 09/12: [man pages]: Use italics in headings where needed.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 7cddcd7092c0b04ba3578bdc28d2b0e6c2040780
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Thu May 6 14:43:25 2021 +1000

    [man pages]: Use italics in headings where needed.
    
    Now (after commit 3a919166) that it's safe to use italics in section and
    subsection headings, use them for words we would italicize in running
    text.
    
    I continue to dislike and discourage font escapes in man pages.  There
    is an alternative; .SH and .SS use an input trap if given no arguments.
    So rather than
    
        .SH "Calling \f[I]mom\f[]"
    
    we could say
    
        .SH
        Calling \c
        .I mom
    
    instead.  Somehow I don't think this would be more popular.  (I also
    value the greppability of headings.)
    
    I also shortened or recast some headings and put them in sentence case
    instead of title case where necessary.
---
 contrib/glilypond/glilypond.1.man             |  6 +++---
 contrib/groff_filenames/groff_filenames.5.man | 12 ++++++------
 contrib/hdtbl/groff_hdtbl.7.man               |  2 +-
 contrib/mm/groff_mm.7.man                     |  4 ++--
 contrib/mom/groff_mom.7.man                   |  2 +-
 man/groff.7.man                               |  4 ++--
 man/groff_font.5.man                          |  2 +-
 man/roff.7.man                                | 24 ++++++++++++------------
 src/preproc/grn/grn.1.man                     |  4 ++--
 src/preproc/preconv/preconv.1.man             |  2 +-
 src/preproc/tbl/tbl.1.man                     |  6 +++---
 src/roff/groff/groff.1.man                    |  6 +++---
 tmac/groff_ms.7.man                           |  2 +-
 tmac/groff_www.7.man                          |  2 +-
 14 files changed, 39 insertions(+), 39 deletions(-)

diff --git a/contrib/glilypond/glilypond.1.man 
b/contrib/glilypond/glilypond.1.man
index c519838..775f631 100644
--- a/contrib/glilypond/glilypond.1.man
+++ b/contrib/glilypond/glilypond.1.man
@@ -446,7 +446,7 @@ or even as an abbreviation like
 .
 .
 .\" ====================================================================
-.SH "The LilyPond Parts in roff Input"
+.SH "LilyPond regions in \f[I]roff\f[] input"
 .\" ====================================================================
 .
 .\" ====================================================================
@@ -506,7 +506,7 @@ files.
 .
 .
 .\" ====================================================================
-.SS "Inclusion of ly-Files"
+.SS "Inclusion of \f[I].ly\f[] files"
 .\" ====================================================================
 .
 An additional command line for file inclusion of
@@ -802,7 +802,7 @@ commands
 .
 .
 .\" ====================================================================
-.SH "The Generated New roff Structure"
+.SH "Generated \f[I]groff\f[] output"
 .\" ====================================================================
 .
 The new
diff --git a/contrib/groff_filenames/groff_filenames.5.man 
b/contrib/groff_filenames/groff_filenames.5.man
index 1e2808d..61b78d8 100644
--- a/contrib/groff_filenames/groff_filenames.5.man
+++ b/contrib/groff_filenames/groff_filenames.5.man
@@ -55,7 +55,7 @@ is about these filename extensions.
 .
 .
 .\" ====================================================================
-.SH "Compression of roff Files"
+.SH "Compression of \f[I]roff\f[] files"
 .\" ====================================================================
 .
 Each
@@ -315,7 +315,7 @@ Man page format in BSD.
 .
 .
 .\" ====================================================================
-.SH "Traditional troff Extensions"
+.SH "Traditional \f[I]troff\f[] extensions"
 .\" ====================================================================
 .
 .\" ====================================================================
@@ -373,7 +373,7 @@ languages and their extensions are still very active in
 .
 .
 .\" ====================================================================
-.SS "Source code for macro packages (tmac files)"
+.SS "Source code for macro packages (\f[I]tmac\f[] files)"
 .\" ====================================================================
 .
 In traditional
@@ -446,7 +446,7 @@ for files using the
 .
 .
 .\" ====================================================================
-.SS "Classical roff files"
+.SS "\f[I]roff\f[] files"
 .\" ====================================================================
 .
 .TP
@@ -459,7 +459,7 @@ language of any kind
 .
 .
 .\" ====================================================================
-.SH "New groff Extensions"
+.SH "New \f[I]groff\f[] extensions"
 .\" ====================================================================
 .
 .I "GNU roff"
@@ -488,7 +488,7 @@ general ending for files using the
 .
 .
 .\" ====================================================================
-.SS "Source code for macro packages (tmac files)"
+.SS "Source code for macro packages (\f[I]tmac\f[] files)"
 .\" ====================================================================
 .
 As the classical form
diff --git a/contrib/hdtbl/groff_hdtbl.7.man b/contrib/hdtbl/groff_hdtbl.7.man
index be11c3a..0c9718a 100644
--- a/contrib/hdtbl/groff_hdtbl.7.man
+++ b/contrib/hdtbl/groff_hdtbl.7.man
@@ -1158,7 +1158,7 @@ argument above.
 .
 .
 .\" ====================================================================
-.SH "hdtbl Customization"
+.SH "\f[I]hdtbl\f[] customization"
 .\" ====================================================================
 .
 .PP
diff --git a/contrib/mm/groff_mm.7.man b/contrib/mm/groff_mm.7.man
index 0d536bd..21995a5 100644
--- a/contrib/mm/groff_mm.7.man
+++ b/contrib/mm/groff_mm.7.man
@@ -3165,7 +3165,7 @@ T}
 .
 .
 .\" ====================================================================
-.SS "Strings used in m@TMAC_M_PREFIX@m"
+.SS "Strings used in \f[I]m@TMAC_M_PREFIX@m\f[]"
 .\" ====================================================================
 .
 .TP
@@ -3406,7 +3406,7 @@ Default is\~1.
 .
 .
 .\" ====================================================================
-.SS "Number variables used in m@TMAC_M_PREFIX@m"
+.SS "Number variables used in \f[I]m@TMAC_M_PREFIX@m\f[]"
 .\" ====================================================================
 .
 .TP
diff --git a/contrib/mom/groff_mom.7.man b/contrib/mom/groff_mom.7.man
index 63551cf..cbae8e2 100644
--- a/contrib/mom/groff_mom.7.man
+++ b/contrib/mom/groff_mom.7.man
@@ -83,7 +83,7 @@ groff_mom \- modern macros for document composition with GNU 
roff
 .
 .
 .\" ====================================================================
-.SH "Calling mom"
+.SH "Calling \f[I]mom\f[]"
 .\" ====================================================================
 .
 .B mom
diff --git a/man/groff.7.man b/man/groff.7.man
index 96be62e..a2a2c44 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -382,7 +382,7 @@ to a single one in all macro definitions.
 .
 .
 .\" ====================================================================
-.SH "groff Elements"
+.SH "\f[I]groff\f[] elements"
 .\" ====================================================================
 .
 The roff language elements add formatting information to a text file.
@@ -5157,7 +5157,7 @@ So this request is not really useful.
 .
 .
 .\" ====================================================================
-.SS "Underlining with .UL from ms"
+.SS "Underlining with .UL from \f[I]ms\f[]"
 .\" ====================================================================
 .
 In the \[oq]ms\[cq] macro package in tmac/s.tmac
diff --git a/man/groff_font.5.man b/man/groff_font.5.man
index 1c43e24..8e38378 100644
--- a/man/groff_font.5.man
+++ b/man/groff_font.5.man
@@ -65,7 +65,7 @@ there is no associated binary format.
 .
 .
 .\" ====================================================================
-.SS "DESC file format"
+.SS "\f[I]DESC\f[] file format"
 .\" ====================================================================
 .
 The
diff --git a/man/roff.7.man b/man/roff.7.man
index 514eef5..8bfcc47 100644
--- a/man/roff.7.man
+++ b/man/roff.7.man
@@ -118,7 +118,7 @@ but its roots go back to the earlier operating systems CTSS 
and Multics.
 .
 .
 .\" ====================================================================
-.SS "The predecessor RUNOFF"
+.SS "The predecessor\[em]\f[I]RUNOFF\f[]"
 .\" ====================================================================
 .
 .IR roff 's
@@ -246,7 +246,7 @@ to turn on fill mode got the name it retains to this day.
 .
 .
 .\" ====================================================================
-.SS "Unix and roff"
+.SS "Unix and \f[I]roff\f[]"
 .\" ====================================================================
 .
 By 1971,
@@ -294,7 +294,7 @@ Proportionally-spaced type was unknown.
 .
 .
 .\" ====================================================================
-.SS "New roff and Typesetter roff"
+.SS "New \f[I]roff\f[] and Typesetter \f[I]roff\f[]"
 .\" ====================================================================
 .
 The first years of Unix were spent in rapid evolution.
@@ -584,7 +584,7 @@ follow Kernighan's device-independent design.
 .
 .
 .\" ====================================================================
-.SS "groff\[em]a free roff from GNU"
+.SS "\f[I]groff\f[]\[em]a free \f[I]roff\f[] from GNU"
 .\" ====================================================================
 .
 The most important free
@@ -641,10 +641,10 @@ the
 standard today.
 .
 .
-.\" XXX GBR leaves off here.
 .\" ====================================================================
-.SS "Free Heirloom roff"
+.SS "Heirloom Doctools \f[I]troff\f[]"
 .\" ====================================================================
+.\" XXX GBR leaves off here.
 .
 An alternative is
 .UR https://\:github.com/\:n\-t\-roff/\:heirloom\-doctools
@@ -670,7 +670,7 @@ Moreover, one finds there the
 .
 .
 .\" ====================================================================
-.SH "Using roff"
+.SH "Using \f[I]roff\f[]"
 .\" ====================================================================
 .
 Many people use
@@ -716,7 +716,7 @@ arguments should be used to process it.
 .
 .
 .\" ====================================================================
-.SS "The roff pipeline"
+.SS "The \f[I]roff\f[] pipeline"
 .\" ====================================================================
 .
 Each
@@ -995,7 +995,7 @@ uses 72 000.
 .
 .
 .\" ====================================================================
-.SH "roff programming"
+.SH "\f[I]roff\f[] programming"
 .\" ====================================================================
 .
 Documents using
@@ -1077,7 +1077,7 @@ extensions.
 .
 .
 .\" ====================================================================
-.SS "The roff formatting language"
+.SS "The \f[I]roff\f[] formatting language"
 .\" ====================================================================
 .
 The canonical reference for the AT&T
@@ -1285,7 +1285,7 @@ for more on file name extensions.
 .
 .
 .\" ====================================================================
-.SH "Editing roff"
+.SH "Editing \f[I]roff\f[]"
 .\" ====================================================================
 .
 All
@@ -1623,7 +1623,7 @@ and mailing lists
 .
 .
 .\" ====================================================================
-.SS "Historical roff documentation"
+.SS "Historical \f[I]roff\f[] documentation"
 .\" ====================================================================
 .
 Many AT&T
diff --git a/src/preproc/grn/grn.1.man b/src/preproc/grn/grn.1.man
index be4285a..aa227c3 100644
--- a/src/preproc/grn/grn.1.man
+++ b/src/preproc/grn/grn.1.man
@@ -144,7 +144,7 @@ and thus may not work with other
 .
 .
 .\" ====================================================================
-.SS "grn commands"
+.SS "\f[I]grn\f[] commands"
 .\" ====================================================================
 .
 Each input line between
@@ -400,7 +400,7 @@ line.
 .
 .
 .\" ====================================================================
-.SS "Notes about groff"
+.SS "Usage with \f[I]groff\f[]"
 .\" ====================================================================
 .
 Since
diff --git a/src/preproc/preconv/preconv.1.man 
b/src/preproc/preconv/preconv.1.man
index 2f7b66b..e8f1ca6 100644
--- a/src/preproc/preconv/preconv.1.man
+++ b/src/preproc/preconv/preconv.1.man
@@ -378,7 +378,7 @@ are disregarded for the purpose of comparison with the 
above tags.
 .
 .
 .\" ====================================================================
-.SS "iconv support"
+.SS "\f[I]iconv\f[] support"
 .\" ====================================================================
 .
 While
diff --git a/src/preproc/tbl/tbl.1.man b/src/preproc/tbl/tbl.1.man
index 75042a6..3747122 100644
--- a/src/preproc/tbl/tbl.1.man
+++ b/src/preproc/tbl/tbl.1.man
@@ -986,7 +986,7 @@ macro.
 .
 .
 .\" ====================================================================
-.SS "Interaction with \%@g@eqn"
+.SS "Interaction with \f[I]\%@g@eqn\f[]"
 .\" ====================================================================
 .
 .IR \%@g@tbl (@MAN1EXT@)
@@ -997,7 +997,7 @@ automatically takes care of the correct order of 
preprocessors).
 .
 .
 .\" ====================================================================
-.SS "GNU tbl enhancements"
+.SS "GNU \f[I]tbl\f[] enhancements"
 .\" ====================================================================
 .
 There is no limit on the number of columns in a table,
@@ -1033,7 +1033,7 @@ you should avoid using any names beginning with
 .
 .
 .\" ====================================================================
-.SS "GNU tbl within macros"
+.SS "Using GNU \f[I]tbl\f[] within macros"
 .\" ====================================================================
 .
 Since
diff --git a/src/roff/groff/groff.1.man b/src/roff/groff/groff.1.man
index 6379ab0..db83037 100644
--- a/src/roff/groff/groff.1.man
+++ b/src/roff/groff/groff.1.man
@@ -139,7 +139,7 @@ options can be fed into
 .
 .
 .\" ====================================================================
-.SS "Native groff options"
+.SS "\f[I]groff\f[]-specific options"
 .\" ====================================================================
 .
 The following options either do not exist for
@@ -1808,7 +1808,7 @@ file) directory.
 .
 .
 .\" ====================================================================
-.SS "groff macro directory"
+.SS "\f[I]groff\f[] macro directory"
 .\" ====================================================================
 .
 This contains all information related to macro packages.
@@ -1854,7 +1854,7 @@ Macro file for macro package
 .
 .
 .\" ====================================================================
-.SS "groff font directory"
+.SS "\f[I]groff\f[] font directory"
 .\" ====================================================================
 .
 This contains all information related to output devices.
diff --git a/tmac/groff_ms.7.man b/tmac/groff_ms.7.man
index ee82403..8fe90e0 100644
--- a/tmac/groff_ms.7.man
+++ b/tmac/groff_ms.7.man
@@ -1545,7 +1545,7 @@ and
 .
 .
 .\" ====================================================================
-.SH "Differences from AT&T ms"
+.SH "Differences from AT&T \f[I]ms\f[]"
 .\" ====================================================================
 .
 The
diff --git a/tmac/groff_www.7.man b/tmac/groff_www.7.man
index 8c572d9..29b7e4e 100644
--- a/tmac/groff_www.7.man
+++ b/tmac/groff_www.7.man
@@ -698,7 +698,7 @@ for details of how to switch this off or alter the 
position).
 .
 .
 .\" ====================================================================
-.SH "Limitations of grohtml"
+.SH "Limitations of \f[I]grohtml\f[]"
 .\" ====================================================================
 .
 .LP