[groff] 10/15: groff_rfc1345(7): Update.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 2d636e901af0f75977f7ad3bf22bcc8c879acc0d
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Wed Feb 3 02:57:51 2021 +1100

    groff_rfc1345(7): Update.
    
    Borganically assimilate with existing groff man page style practices.
    
    Also supply a bit of additional content.
    
    * Add paragraph noting clash between some RFC 1345 mnemonics and groff
      built-in special character escapes.  Supply example and encourage user
      to research individual cases as needed.
    * Add "Files" section showing users the full path to the macro file.
    * Save and restore compatibility mode since a groff language extension
      (the \[] special character escape form) is used.
    * .TH: Use configured man page section 7 suffix instead of literal "7".
    * .TH: Add man page modification date and groff version.
    * Set section titles in sentence case.
    * Use .PP instead of blank lines for paragraphing.
    * Set file names in italics.
    * In apropos line, drop duplicate mention of groff and add reference to
      Vim digraphs.
    * Set inline examples in quotation marks as well as bold so that they
      will be obviously set off even on output devices that don't render
      bold.
    * Use .EX/.EE for displayed example instead of leading spaces.
    * Use \[rs] instead of \e.
    * Break lines at commas.
    * Use one empty request between sentences and expected breaks.
    * Use two empty requests between paragraphs and expected vertical space.
    * Demote nonstandard section "Usage" to a subsection.
    * Prevent hyphenation of Vim inline command example.
    * Add legal terms in *roff comments.
    * Add editor aid comments.
---
 contrib/rfc1345/groff_rfc1345.7.man | 286 ++++++++++++++++++++++++++++--------
 1 file changed, 225 insertions(+), 61 deletions(-)

diff --git a/contrib/rfc1345/groff_rfc1345.7.man 
b/contrib/rfc1345/groff_rfc1345.7.man
index b349cdb..5c29dd4 100644
--- a/contrib/rfc1345/groff_rfc1345.7.man
+++ b/contrib/rfc1345/groff_rfc1345.7.man
@@ -1,62 +1,226 @@
-.TH groff_rfc1345 7
-.SH NAME
-
-groff_rfc1345 \- Groff glyph names based on RFC 1345
-
-.SH DESCRIPTION
-
-The file rfc1345.tmac defines escape sequences based on the glyph
-mnemonics specified in RFC 1345 and the digraph table of the text
-editor Vim.  Each escape translates to a Unicode code point, and
-will render correctly if the underlying font is a Unicode font
-that covers that code point.
-
-For example, \e[Rx] is the recipe or PRESCRIPTION TAKE symbol,
-and maps to the code point U+211E.  Groff lets you write it as
-\e[u211E], but \e[Rx] is more mnemonic. 
-
-For a list of the glyph names provided, please see the file
-rfc1345.tmac, which contains definitions of the form
-
-    .char \e[Rx] \e[u211E]    \e" PRESCRIPTION TAKE
-
-where .char's first argument is the mnemonic glyph name, its
-second argument is the Groff sequence based on the code point,
+.TH groff_rfc1345 @MAN7EXT@ "@MDATE@" "groff @VERSION@"
+.SH Name
+groff_rfc1345 \- special character names from RFC 1345 and Vim digraphs
+.
+.
+.\" ====================================================================
+.\" Legal Terms
+.\" ====================================================================
+.\"
+.\" Copyright (c) 2021 Dorai Sitaram
+.\"
+.\" Permission is hereby granted, free of charge, to any person
+.\" obtaining a copy of this software and associated documentation files
+.\" (the "Software"), to deal in the Software without restriction,
+.\" including without limitation the rights to use, copy, modify, merge,
+.\" publish, distribute, sublicense, and/or sell copies of the Software,
+.\" and to permit persons to whom the Software is furnished to do so,
+.\" subject to the following conditions:
+.\"
+.\" The above copyright notice and this permission notice (including the
+.\" next paragraph) shall be included in all copies or substantial
+.\" portions of the Software.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+.\" EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+.\" NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
+.\" BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
+.\" ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+.\" CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+.\" SOFTWARE.
+.
+.
+.\" Save and disable compatibility mode (for, e.g., Solaris 10/11).
+.do nr *groff_groff_rfc1345_7_man_C \n[.cp]
+.cp 0
+.
+.
+.\" ====================================================================
+.SH Description
+.\" ====================================================================
+.
+The file
+.I rfc1345.tmac
+defines special character escape sequences for
+.IR groff (@MAN7EXT@)
+based on the glyph mnemonics specified in RFC 1345 and the digraph table
+of the text editor Vim.
+.
+Each escape translates to a Unicode code point,
+and will render correctly if the underlying font is a Unicode font that
+covers the code point.
+.
+.
+.PP
+For example,
+.RB \[lq] \[rs][Rx] \[rq]
+is the \[lq]recipe\[rq] or \[lq]prescription take\[rq] symbol,
+and maps to the code point U+211E.
+.
+.I groff
+lets you write it as
+.RB \[lq] \[rs][u211E] \[rq],
+but
+.RB \[lq] \[rs][Rx] \[rq]
+is more mnemonic.
+.
+.
+.PP
+For a list of the glyph names provided,
+please see the file
+.IR rfc1345.tmac ,
+which contains definitions of the form
+.
+.RS
+.EX
+\&.char \[rs][Rx] \[rs][u211E]    \[rs]" PRESCRIPTION TAKE
+.EE
+.RE
+.
+where
+.BR .char 's
+first argument is the mnemonic glyph name,
+its second argument is the
+.I groff
+special character escape sequence based on the code point,
 and the comment describes the glyph defined.
-
-The RFC 1345 glyph names cover a wide range of Unicode code
-points: including supplemental Latin, Greek, Cyrillic, Hebrew,
-Arabic, Hiragana, Katakana, and Bopomofo letters, punctuation,
-math notation, currency symbols, industrial and entertainment
-icons, and box drawing symbols.
-
-The Vim digraph table is practically a small subset of RFC 1345
-(being limited to two-character mnemonics), but as a newer system
-it does add four new mnemonics not specified in the RFC.  These
-have also been added to rfc1345.tmac.
-
-rfc1345.tmac contains a total of 1696 glyph names.  It is not an
-error to load rfc1345.tmac if your font does not have all the
-glyphs, as long as it contains the glyphs that you actually use
-in your document.
-
-.SH USAGE
-
-Load the rfc1345.tmac file.  This can be done by either adding
-
-    .mso rfc1345.tmac
-
-in your document before first use of any of the defined
-glyph names, or by using the command-line option
-
-    -m rfc1345
-
-.SH SEE ALSO
-
-RFC 1345, by Keld Simonsen, June 1992.  Available at
-https://tools.ietf.org/html/rfc1345.
-
-The Vim digraph table, as listed by the Vim command :help
-digraph-table.
-
-groff_char(7)
+.
+.
+.PP
+The RFC 1345 glyph names cover a wide range of Unicode code points,
+including
+supplemental Latin,
+Greek,
+Cyrillic,
+Hebrew,
+Arabic,
+Hiragana,
+Katakana,
+and Bopomofo letters,
+punctuation,
+math notation,
+currency
+symbols,
+industrial and entertainment icons,
+and box-drawing symbols.
+.
+.
+.PP
+The Vim digraph table is practically a subset of RFC 1345
+(being limited to two-character mnemonics),
+but,
+as a newer system,
+it does add four new mnemonics not specified in
+the RFC
+(the horizontal ellipsis,
+the Euro sign,
+and two mappings for the rouble sign).
+.
+These have also been added to
+.IR rfc1345.tmac .
+.
+.
+.PP
+.I rfc1345.tmac
+contains a total of 1,696 glyph names.
+.
+It is not an
+error to load
+.I rfc1345.tmac
+if your font does not have all the glyphs,
+as long as it contains the glyphs that you actually use in your
+document.
+.
+.
+.PP
+The RFC 1345 mnemonics are not identical in every case to the mappings
+for special character glyph names that are built in to
+.IR groff ;
+for example,
+.RB \[lq] \[rs][<<] \[rq]
+means the \[lq]much less than\[rq] sign (U+226A) when
+.I rfc1345.tmac
+is not loaded and this special character is not otherwise defined by a
+document or macro package.
+.
+.I rfc1345.tmac
+redefines
+.RB \[lq] \[rs][<<] \[rq]
+to the \[lq]left-pointing double angle quotation mark\[rq] (U+00AB).
+.
+See
+.IR groff_char (@MAN7EXT@)
+for the full list of predefined special character escapes.
+.
+.
+.\" ====================================================================
+.SS Usage
+.\" ====================================================================
+.
+Load the
+.I rfc1345.tmac
+file.
+.
+This can be done by either adding
+.
+.RS
+.EX
+\&.mso rfc1345.tmac
+.EE
+.RE
+.
+in your document before the first use of any of the defined glyph names,
+or using the
+.IR groff (@MAN1EXT@)
+or
+.IR \%@g@troff (@MAN1EXT@)
+option
+.
+.RS
+.EX
+\-m rfc1345
+.EE
+.RE
+.
+from the shell.
+.
+.
+.\" ====================================================================
+.SH Files
+.\" ====================================================================
+.
+.TP
+.I \%@MACRODIR@/\:rfc1345\:.tmac
+implements the character mappings.
+.
+.
+.\" ====================================================================
+.SH "See also"
+.\" ====================================================================
+.
+.UR https://tools.ietf.org/html/rfc1345
+RFC 1345
+.UE ,
+by Keld Simonsen,
+June 1992.
+.
+.
+.PP
+The Vim digraph table can be listed using the Vim command
+.RB \[lq] ":help \%digraph\-table" \[rq].
+.
+.
+.PP
+.IR groff_char (@MAN7EXT@)
+.
+.
+.\" Restore compatibility mode (for, e.g., Solaris 10/11).
+.cp \n[*groff_groff_rfc1345_7_man_C]
+.
+.
+.\" Local Variables:
+.\" fill-column: 72
+.\" mode: nroff
+.\" End:
+.\" vim: set filetype=groff textwidth=72: