[groff] 02/14: roff(7): Fix style and content nits.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit f9fc008aa89a1cbbb1ea20fa79c49ab60b0bb059
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Tue Feb 16 14:24:04 2021 +1100

    roff(7): Fix style and content nits.
    
    Content:
    
    * Qualify broad statement about Vim syntax highlighting.
    
    Style:
    * Remove superfluous "very".
    * Break input lines at commas.
    * Hyphenate adjective phrase.
    * Set man page references in italics, not bold.
    * Drop redundant paragraph macro.
    * Set multi-word parentheticals on their own input lines.
    * Break input lines at commas.
    * Say "file name" instead of "filename".
    * Set literal parts of file names in italics and variable parts in roman
      (see groff_man_style(7)).
    * Use "and so on" at the end of a sentence instead of "etc.".
    * Recast discussion of file name extension for plain *roff files that
      don't use a macro package.
    * Use quotation marks instead of italics when expanding an abbreviation.
    * Set environment variable name in italics, not bold.
    * Fix colon-terminated sentence fragments; see commit 3afcaf0e.
    * Set command name in italics, not bold.
    * Prevent hyphenation of page name in man page cross reference.
    * Tighten wording.
---
 man/roff.7.man | 80 ++++++++++++++++++++++++++++++----------------------------
 1 file changed, 42 insertions(+), 38 deletions(-)

diff --git a/man/roff.7.man b/man/roff.7.man
index 60e54bd..514eef5 100644
--- a/man/roff.7.man
+++ b/man/roff.7.man
@@ -1213,8 +1213,11 @@ and its value can be retrieved by the escape sequence
 .SH "File name extensions"
 .\" ====================================================================
 .
-Manual pages (man pages) take the section number as a file name
-extension, e.g., the filename for this document is
+Manual pages
+(man\~pages)
+take the section number as a file name extension,
+e.g.,
+the file name for this document is
 .IR roff.7 ,
 i.e., it is kept in section\~7
 of the man pages.
@@ -1223,47 +1226,43 @@ of the man pages.
 .P
 The classical macro packages take the package name as an extension,
 e.g.,
-.IB file. me
+.RI file .me
 for a document using the
 .I me
 macro package,
-.IB file. mm
+.RI file .mm
 for
 .IR mm ,
-.IB file. ms
+.RI file .ms
 for
 .IR ms ,
-.IB file. pic
+.RI file .pic
 for
 .I pic
 files,
-etc.
+and so on.
 .
 .
 .P
-But there is no general naming scheme for
-.I roff
-documents, though
-.IB file. tr
-for
-.I troff file
-is seen now and then.
-.
-Maybe there should be a standardization for the filename extensions of
+There is no general naming scheme for
 .I roff
-files.
+documents,
+though
+.RI file .t
+for \[lq]troff file\[rq] is seen now and then.
 .
 .
 .P
-File name extensions can be very handy in conjunction with the
-.BR less (1)
+File name extensions can be handy in conjunction with the
+.IR less (1)
 pager.
 .
 It provides the possibility to feed all input into a command-line pipe
 that is specified in the shell environment variable
-.BR LESSOPEN .
+.IR LESSOPEN .
 .
-This process is not well documented, so here an example:
+This process is not well documented,
+so here is an example.
 .
 .RS
 .P
@@ -1275,15 +1274,14 @@ LESSOPEN=\[aq]|lesspipe %s\[aq]
 .
 .P
 where
-.B lesspipe
-is either a system supplied command or a shell script of your own.
+.I lesspipe
+is either a system-supplied command or a shell script of your own.
 .
 .
 .P
-More details for
-.I file name extensions
-can be found at
-.BR groff_filenames (@MAN5EXT@).
+See
+.IR \%groff_filenames (@MAN5EXT@)
+for more on file name extensions.
 .
 .
 .\" ====================================================================
@@ -1439,12 +1437,14 @@ program are confused by this; so this is deprecated.
 .
 .\" TODO: elvis, vile.  Nvi does not support highlighting at all, and
 .\" gedit does but has no rules for roff yet.  Other editors TBD.
-Besides Emacs, some other editors provide
+Besides Emacs,
+some other editors provide
 .I nroff
-style files too, e.g.,
-.BR vim (1),
+style files too,
+e.g.,
+.IR vim (1),
 an extension of the
-.BR vi (1)
+.IR vi (1)
 program.
 .
 Vim's highlighting can be made to recognize
@@ -1454,11 +1454,16 @@ files by setting the
 option in a Vim
 .IR modeline .
 .
-For this feature to work, your copy of
-.B vim
-must be built with support for, and configured to enable, several
-features; consult the editor's online help topics
-\[lq]auto\-setting\[rq], \[lq]filetype\[rq], and \[lq]syntax\[rq].
+For this feature to work,
+your copy of
+.I vim
+must be built with support for,
+and configured to enable,
+several features;
+consult the editor's online help topics
+\[lq]auto\-setting\[rq],
+\[lq]filetype\[rq],
+and \[lq]syntax\[rq].
 .
 Then put the following at the end of your
 .I roff
@@ -1470,7 +1475,6 @@ after any Emacs configuration:
 .\" 'modelines' variable tells it to.  A common default is "5", but
 .\" Emacs settings can be longer than that.
 .
-.P
 .
 .RS
 .IP
@@ -1484,7 +1488,7 @@ after any Emacs configuration:
 Replace \[lq]groff\[rq] in the above with \[lq]nroff\[rq] if you want
 highlighing that does
 .I not
-recognize the GNU extensions to
+recognize many of the GNU extensions to
 .IR roff ,
 such as request,
 register,