[groff] 04/14: groff_mdoc(7): Document `Ba`, `Na` strings better.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 8a4cda5528d28a96c283e54654b041f45b9826c2
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Wed Feb 21 13:14:26 2024 -0600

    groff_mdoc(7): Document `Ba`, `Na` strings better.
    
    mandoc(1)'s commit history calls the forced selection of the roman face
    for the `Ba` string "stupid" and characterizes it as a groff bug[1], but
    it appears to be a deliberate design choice in the mdoc implementation
    from 4.4BSD-Lite2.[2]  (If it weren't, you'd just type "|".)  Document
    this, and do similarly for `Na`, which forces italics.
    
    [1] 
https://cvsweb.bsd.lv/mandoc/predefs.in?rev=1.4&content-type=text/x-cvsweb-markup
    [2] 
https://github.com/sergev/4.4BSD-Lite2/blob/master/usr/src/share/tmac/doc-nroff#L119
---
 tmac/groff_mdoc.7.man | 12 ++++++++++--
 tmac/mdoc/doc-ditroff |  2 +-
 tmac/mdoc/doc-nroff   |  2 +-
 3 files changed, 12 insertions(+), 4 deletions(-)

diff --git a/tmac/groff_mdoc.7.man b/tmac/groff_mdoc.7.man
index adce8438a..4ccc9ecb0 100644
--- a/tmac/groff_mdoc.7.man
+++ b/tmac/groff_mdoc.7.man
@@ -4866,8 +4866,8 @@ String    7-bit   8-bit   UCS     Prefer  Meaning
 \[rs]*(Pm      +\-     \[+-]   \*[Pm]  \[rs](+\-       plus or minus
 \[rs]*(If      infinity        infinity        \*[If]  \[rs](if        infinity
 \[rs]*(Am      \*[Am]  \*[Am]  \*[Am]  &       ampersand
-\[rs]*(Na      \*[Na]  \*[Na]  \*[Na]  NaN     not a number
-\[rs]*(Ba      \*[Ba]  \*[Ba]  \*[Ba]  |       bar
+\[rs]*(Na      \*[Na]  \*[Na]  \*[Na]  \f[I]NaN\f[]    not a number (slanted)
+\[rs]*(Ba      \*[Ba]  \*[Ba]  \*[Ba]  |       bar (upright)
 .TE
 .
 .
@@ -4900,6 +4900,14 @@ output drivers \" technically, their macro files or font 
descriptions
 take on the responsibility of glyph substitution,
 as they possess relevant knowledge of their available repertoires.
 .
+The
+.Ql Ba
+and
+.Ql Na
+strings imply a mandatory typeface:
+upright (roman) in the former,
+and slanted (italics) with the latter.
+.
 .
 .Sh Diagnostics
 .
diff --git a/tmac/mdoc/doc-ditroff b/tmac/mdoc/doc-ditroff
index 30297fc53..c940c43d9 100644
--- a/tmac/mdoc/doc-ditroff
+++ b/tmac/mdoc/doc-ditroff
@@ -131,7 +131,7 @@
 .ds doc-left-singlequote \[oq]
 .ds doc-right-singlequote \[cq]
 .
-.\" the following strings are 'official'
+.\" The following strings are part of mdoc(7)'s documented interface.
 .ds <= \[<=]
 .ds >= \[>=]
 .ds Lq \[lq]
diff --git a/tmac/mdoc/doc-nroff b/tmac/mdoc/doc-nroff
index 2e0872225..b9ab48a83 100644
--- a/tmac/mdoc/doc-nroff
+++ b/tmac/mdoc/doc-nroff
@@ -120,7 +120,7 @@
 .ds doc-left-singlequote \[oq]
 .ds doc-right-singlequote \[cq]
 .
-.\" the following strings are 'official'
+.\" The following strings are part of mdoc(7)'s documented interface.
 .ds <= \[<=]
 .ds >= \[>=]
 .ds aa \[aa]