[groff] 04/04: [ms]: Support .BX better in nroff mode.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit e260fc23612e9c865a01bc25fbc154fe67608680
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Fri Apr 30 17:44:12 2021 +1000

    [ms]: Support .BX better in nroff mode.
    
    * tmac/s.tmac (BX): Add alternative implementation for terminal (nroff)
      devices.  Store width of boxed text, adding .4m only on troff devices
      (to make room for the vertical box lines).  Break long input line in
      troff implementation.  If not in troff mode, use ISO 6429 color
      escapes to render boxed text in black on white.  Use the \Z escape to
      match breaking semantics of macro in troff mode.
    
    * doc/groff.texi (Highlighting in ms) <BX>:
    * doc/ms.ms (Highlighting) <BX>:
    * tmac/groff_ms.7.man (Usage/Highlighting) <BX>: Document it.
    
    Fixes <https://savannah.gnu.org/bugs/?60477>.
---
 ChangeLog           | 16 +++++++++++++
 doc/groff.texi      |  6 +++--
 doc/ms.ms           | 68 ++++++++++++++++++++++++++++++++++++++++++++++++++---
 tmac/groff_ms.7.man | 18 +++++++++++---
 tmac/s.tmac         | 12 ++++++----
 5 files changed, 108 insertions(+), 12 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index cab64a4..5d4b52b 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,21 @@
 2021-04-30  G. Branden Robinson <g.branden.robinson@gmail.com>
 
+       * tmac/s.tmac (BX): Add alternative implementation for terminal
+       {nroff} devices.  Store width of boxed text, adding .4m only on
+       troff devices (to make room for the vertical box lines).  Break
+       long input line in troff implementation.  If not in troff mode,
+       use ISO 6429 color escapes to render boxed text in black on
+       white.  Use the \Z escape to match breaking semantics of macro
+       in troff mode.
+
+       * doc/groff.texi (Highlighting in ms) <BX>:
+       * doc/ms.ms (Highlighting) <BX>:
+       * tmac/groff_ms.7.man (Usage/Highlighting) <BX>: Document it.
+
+       Fixes <https://savannah.gnu.org/bugs/?60477>.
+
+2021-04-30  G. Branden Robinson <g.branden.robinson@gmail.com>
+
        * doc/doc.am: Make $(PROCESSEDDOCFILES) depend on all the same
        targets as $(PROCESSEDEXAMPLEFILES); this way the me, ms, and
        pic.ms manuals are all regenerated upon changes to their
diff --git a/doc/groff.texi b/doc/groff.texi
index b8d9504..5d208ee 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -3244,8 +3244,10 @@ otherwise.  This is a Version@tie{}10 Research Unix 
extension.
 @endDefmac
 
 @Defmac {BX, [@Var{txt}], ms}
-Prints its argument and draws a box around it.  If you want to box a
-string that contains spaces, use a digit-width space (@code{\0}).
+Prints @var{txt} and draws a box around it.  On terminal devices,
+reverse video is used instead.  If you want the argument to contain
+space, use non-breaking space escapes of appropriate width (@code{\~},
+@code{\^}, @code{\|}, @code{\0}) or @code{\h}.
 @endDefmac
 
 @Defmac {UL, [@Var{txt} [@Var{post}]], ms}
diff --git a/doc/ms.ms b/doc/ms.ms
index 9310243..a828144 100644
--- a/doc/ms.ms
+++ b/doc/ms.ms
@@ -1211,12 +1211,24 @@ This is a Version\~10 Research Unix extension.
 T}
 _
 \&.BX [txt]    T{
-Prints its argument and draws a
+Prints
+.I txt
+and draws a
 .BX box
 around it.
 .
-If you want to box a string that contains spaces,
-use a digit-width space (\\0).
+On terminal devices,
+reverse video is used instead
+(see the implementation note below).
+.
+If you want the argument to contain space,
+use non-breaking space escapes of appropriate width
+.CW \[rs]\[ti] , (
+.CW \[rs]\[ha] ,
+.CW \[rs]| ,
+.CW \[rs]0 ),
+or
+.CW \[rs]h .
 T}
 _
 \&.UL [txt [post]]     T{
@@ -1319,6 +1331,56 @@ and
 .I groff .
 .
 .
+.nr PS -2
+.nr VS -2
+.B1
+.LP
+.hy 0
+.I "Implementation note:"
+In
+.CW nroff
+mode,
+the
+.CW BX
+macro \[lq]boxes\[rq] its argument by bracketing it with
+.I groff
+extension escapes to set the foreground color to black and the
+background to white and then reset them to the defaults;
+the terminal output driver,
+.I grotty (1),
+converts these to ISO\~6429 color escapes,
+which may be ignored or mishandled by some terminals,
+or may be disabled by
+.I grotty 's
+.CW \-c
+option.
+.
+Further,
+if the terminal is set up to use these colors in those roles already,
+.CW .BX
+will cause no visible effect in the output.
+.
+Surmounting these challenges would require adding features to
+.I grotty ,
+for instance to provide a mechanism to request ISO\~6429's
+\[lq]standout\[rq] mode \" That's "smso" and "rmso" in terminfo.
+(often supported on monochrome terminals),
+or to replace the presumed support of the terminal for ISO\~6429 escapes
+with the use of a library that can query the capabilities of the
+terminal and adapt the output sent to the device accordingly.
+.
+(Practically,
+this likely means adding a dependency on
+.CW libtinfo .)
+.
+Contact the
+.I groff
+development mailing list if you'd like to contribute.
+.B2
+.nr PS +2
+.nr VS +2
+.
+.
 .NH 2
 Lists
 .XS
diff --git a/tmac/groff_ms.7.man b/tmac/groff_ms.7.man
index 4337738..e1e8b0a 100644
--- a/tmac/groff_ms.7.man
+++ b/tmac/groff_ms.7.man
@@ -861,10 +861,22 @@ This is a Version\~10 Research Unix extension.
 .TP
 .B .BX\c
 .RI " [" txt ]
-Prints its argument and draws a box around it.
+Prints
+.I txt
+and draws a box around it.
+.
+On terminal devices,
+reverse video is used instead.
+.
+If you want the argument to contain space,
+use non-breaking space escapes of appropriate width
+.RB ( \[rs]\[ti] ,
+.BR \[rs]\[ha] ,
+.BR \[rs]| ,
+.BR \[rs]0 ),
+or
+.BR \[rs]h .
 .
-If you want to box a string that contains spaces,
-use a digit-width space (\[rs]0).
 .
 .TP
 .B .UL\c
diff --git a/tmac/s.tmac b/tmac/s.tmac
index e9c1b3d..2b84212 100644
--- a/tmac/s.tmac
+++ b/tmac/s.tmac
@@ -1529,10 +1529,14 @@ along with this program.  If not, see 
<http://www.gnu.org/licenses/>.
 ..
 .\" box a word
 .de BX
-.nr par*bxw \w'\\$1'+.4m
-\Z'\v'.25m'\D'l 0 -1m'\D'l \\n[par*bxw]u 0'\D'l 0 1m'\D'l -\\n[par*bxw]u 0''\
-\Z'\h'.2m'\\$1'\
-\h'\\n[par*bxw]u'
+.nr par*bxw \w'\\$1'
+.ie t \{\
+.nr par*bxw +.4m
+\Z'\v'.25m'\
+\D'l 0 -1m'\D'l \\n[par*bxw]u 0'\D'l 0 1m'\D'l -\\n[par*bxw]u 0''\
+\Z'\h'.2m'\\$1'\h'\\n[par*bxw]u'
+.\}
+.el \m[black]\M[white]\Z'\\$1'\h'\\n[par*bxw]u'\m[]\M[]
 ..
 .\" The first time UX is used, put a registered mark after it.
 .ds par*ux-rg \(rg