[groff] 14/15: groff_man_style(7): Revise special character info.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit a93557fec56df4924a48c170758c579e6e08395c
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Mon Oct 16 03:19:50 2023 -0500

    groff_man_style(7): Revise special character info.
    
    * Warn reader at the outset that some characters get special handling.
    * Recast description of `\-` escape sequence.  It's difficult to get out
      from under the troff documentation overhang of calling this a "minus
      sign", but let's be clear that (for man(7)) it produces a hyphen-minus
      specifically.
    
      PROBLEMS:
    
        In man pages (only), groff maps the minus sign special character
        '\-' to the Basic Latin hyphen-minus (U+002D) because man pages
        require this glyph and there is no historically established *roff
        input character, ordinary or special, for obtaining it when a hyphen
        and minus sign are both separately available.  To obtain a true
        minus sign, use the special character escape sequences '\(mi' or
        '\[mi]'.
    * On the bright side, when introducing the "break" concept, we say that
      it only happens after "hyphens" or at hyphenation points (that is,
      between letters, unless a man page author wanders off the lit path
      with `hw` or `cflag` requests).  This generalization rules out breaks
      after `\-`, which in fact do not happen in any *roff (nor mandoc(1)).
    * Drop "or similar" language; we've already hedged our bets with "some".
    
    Prompted by discussion with Russ Allbery; see
    <https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1041731#133> et seq.
---
 tmac/groff_man.7.man.in | 24 ++++++++++++------------
 1 file changed, 12 insertions(+), 12 deletions(-)

diff --git a/tmac/groff_man.7.man.in b/tmac/groff_man.7.man.in
index 2840ef458..e15e93b16 100644
--- a/tmac/groff_man.7.man.in
+++ b/tmac/groff_man.7.man.in
@@ -221,6 +221,9 @@ Man pages should be encoded using Unicode basic Latin code 
points
 exclusively,
 and employ the Unix line-ending convention
 (U+000A only).
+Some basic Latin characters have special meaning to
+.I roff;
+see subsection \(lqPortability\(rq below.
 .\" What about rare English words that require diacritics, and
 .\" proper names that require more than basic Latin?
 .\"
@@ -2864,18 +2867,17 @@ but not Plan\~9 or Solaris
 .
 .TP
 .B \e\-
-Minus sign or basic Latin hyphen-minus.
+Minus sign.
 .
 .B \e\-
-produces the Unix command-line option dash in the output.
+produces the basic Latin hyphen-minus (U+002D) specifying Unix
+command-line options and frequently used in file names.
 .
 .RB \(lq \- \(rq
-is a hyphen in the
-.I roff
-language;
-some output devices replace it with U+2010
-(hyphen)
-or similar.
+is a hyphen in
+.IR roff ;
+some output devices format it as U+2010
+(hyphen).
 .
 .
 .TP
@@ -2971,8 +2973,7 @@ Basic Latin circumflex accent
 Some output devices format
 .RB \(lq \(ha \(rq
 as U+02C6
-(modifier letter circumflex accent)
-or similar.
+(modifier letter circumflex accent).
 .
 .
 .TP
@@ -2997,8 +2998,7 @@ Basic Latin tilde.
 Some output devices format
 .RB \(lq \(ti \(rq
 as U+02DC
-(small tilde)
-or similar.
+(small tilde).
 .
 .
 .P