gbranden pushed a commit to branch master
in repository groff.
commit 5485e3b7f1be2956e2067d572c6ce8fd5c036fc1
Author: G. Branden Robinson <[email protected]>
AuthorDate: Fri Aug 4 09:28:55 2023 -0500
[man]: Deprecate `SB` macro.
It is a SunOS 4.0 (1988) extension that in most contexts, does nothing
you can't achieve with `SM` and `B` together (in either order).
Study of the SunOS 4 man page corpus suggests a reason for its
introduction of this macro: use of `SB` immediately after `TP` was
common (610 out of 2,111 occurrences). The problem with `TP` and the
mechanism suggested above is that input traps in troff normally ignore
the `\c` escape sequence, the use of which would be necessary to get the
desired effect. In groff since 1.22.4, the man(7) `TP` macro uses GNU
troff's `itc` request, which _does_ respect `\c`. (mandoc(1) behaves
compatibly with groff man >= 1.22.4.) Solaris 11 switched to groff as
its troff implementation, so there is no reason for newly written or
currently maintained man pages to employ `SB`.
* tmac/an.tmac (SB): Throw deprecation warning.
* tmac/groff_man.7.man.in (Description): Move macro from table to
deprecation list.
(Font style macros): Move description from here...
(Deprecated features): ...to here.
(Portability): Drop mention, since we don't encourage people to
use it at all.
Fixes <https://savannah.gnu.org/bugs/?64515>.
---
ChangeLog | 29 +++++++++++++++
tmac/an.tmac | 19 +++++++++-
tmac/groff_man.7.man.in | 98 +++++++++++++++++++++++++++----------------------
3 files changed, 100 insertions(+), 46 deletions(-)
diff --git a/ChangeLog b/ChangeLog
index 7c7b1b5a2..19cde8307 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,32 @@
+2023-08-04 G. Branden Robinson <[email protected]>
+
+ [man]: Deprecate `SB` macro. It is a SunOS 4.0 (1988) extension
+ that in most contexts, does nothing you can't achieve with `SM`
+ and `B` together (in either order).
+
+ Study of the SunOS 4 man page corpus suggests a reason for its
+ introduction of this macro: use of `SB` immediately after `TP`
+ was common (610 out of 2,111 occurrences). The problem with
+ `TP` and the mechanism suggested above is that input traps in
+ troff normally ignore the `\c` escape sequence, the use of which
+ would be necessary to get the desired effect. In groff since
+ 1.22.4, the man(7) `TP` macro uses GNU troff's `itc` request,
+ which _does_ respect `\c`. (mandoc(1) behaves compatibly with
+ groff man >= 1.22.4.) Solaris 11 switched to groff as its troff
+ implementation, so there is no reason for newly written or
+ currently maintained man pages to employ `SB`.
+
+ * tmac/an.tmac (SB): Throw deprecation warning.
+
+ * tmac/groff_man.7.man.in (Description): Move macro from table
+ to deprecation list.
+ (Font style macros): Move description from here...
+ (Deprecated features): ...to here.
+ (Portability): Drop mention, since we don't encourage people to
+ use it at all.
+
+ Fixes <https://savannah.gnu.org/bugs/?64515>.
+
2023-08-03 G. Branden Robinson <[email protected]>
* src/roff/troff/node.cpp (zoom_font): Validate arguments more.
diff --git a/tmac/an.tmac b/tmac/an.tmac
index c7f7d8782..56d4a0e34 100644
--- a/tmac/an.tmac
+++ b/tmac/an.tmac
@@ -751,9 +751,24 @@ contains unsupported escape sequence
. if \\n[.$] \&\\$*
..
.
-.\" Set arguments (or next input line producing written or drawn output
-.\" if none) in bold style at smaller type size.
+.\" Deprecated: Set arguments (or next input line producing written or
+.\" drawn output if none) in bold style at smaller type size.
+.\"
+.\" This is a SunOS 4.0 extension.
+.\"
+.\" Instead of
+.\" .SB whatever
+.\" say
+.\" .SM
+.\" .B whatever
+.\" or
+.\" .B
+.\" .SM whatever
+.\" to portably get an identical effect.
+.\"
+.\" .SB [text]
.de1 SB
+. nop \\*[an-deprecation-warn]\\
. it 1 an-input-trap
. ps -1
. ft B
diff --git a/tmac/groff_man.7.man.in b/tmac/groff_man.7.man.in
index 69489b57d..fe353a530 100644
--- a/tmac/groff_man.7.man.in
+++ b/tmac/groff_man.7.man.in
@@ -180,7 +180,6 @@ _
\&.RE Relative inset end Document structure macros
\&.RI Roman, italic alternating Font style macros
\&.RS Relative inset start Document structure macros
-\&.SB Small bold Font style macros
\&.SH Section heading Document structure macros
\&.SM Small Font style macros
\&.SS Subsection heading Document structure macros
@@ -201,6 +200,7 @@ We discuss other macros
.BR .HP ,
.BR .OP ,
.BR .PD ,
+.BR .SB ,
and
.BR .UC )
in subsection \(lqDeprecated features\(rq below.
@@ -1568,13 +1568,8 @@ Italic text is usually set underscored instead on
terminal devices.
.
The
.B .SM
-and
-.B .SB
-macros set text in roman or bold,
-respectively,
-at a smaller type size;
-these differ visually from regular-sized roman or bold text only on
-typesetting devices.
+macro sets text at a smaller type size;
+it differs visually from regular-sized text only on typesetting devices.
.
It is often necessary to set text in different styles without
intervening space.
@@ -1727,39 +1722,6 @@ normal size;
it will be hidden from readers using such devices.
.
.
-_endif()dnl
-.TP
-.BR .SB \~[\c
-.IR text ]
-Set
-.I text
-in bold and
-(on typesetting devices)
-one point smaller than the default type size.
-.
-If no argument is given,
-a one-line input trap is planted;
-text on the next line,
-which can be further formatted with a macro,
-is set smaller and in bold.
-.
-This macro is an extension introduced in SunOS\~4.0.
-.
-.
-_ifstyle()dnl
-.IP
-.I Note:
-terminals will render
-.I text
-in bold at the normal size instead.
-.
-Do not rely upon
-.B .SB
-to communicate semantic information distinct from using bold style at
-normal size;
-it will be hidden from readers using such devices.
-.
-.
.P
Observe what is
.I not
@@ -2388,11 +2350,10 @@ The macros we have described as extensions
.BR .TQ ,
.BR .UR / .UE ,
.BR .MT / .ME ,
-.BR .MR ,
and
-.BR .SB )
+.BR .MR )
should be used with caution,
-as they may not be built in to some viewer that is important to your
+as they may not be supported by a formatter that is important to your
audience.
.
See
@@ -3151,6 +3112,55 @@ to express are likely to be lost.
.
.
.TP
+.BR .SB \~[\c
+.IR text ]
+Set
+.I text
+in bold and
+(on typesetting devices)
+one point smaller than the default type size.
+.
+If no argument is given,
+a one-line input trap is planted;
+text on the next line,
+which can be further formatted with a macro,
+is set smaller and in bold.
+.
+Use of this macro,
+an extension originating in SunOS\~4.0
+.IR troff ,\" SunOS
+.\" ..and which Clark included in groff man(7) from 1.01 or earlier...
+is deprecated.
+.
+.B .SM
+without an argument,
+followed immediately by
+.RB \(lq .B
+.IR text \(rq,
+produces the same output more portably.
+.
+The macros' order is interchangable;
+put
+.I text
+with the latter.
+.
+.
+_ifstyle()dnl
+.IP
+.I Note:
+terminals will render
+.I text
+in bold at the normal size instead.
+.
+Do not rely upon
+.B .SB
+to communicate semantic information distinct from using bold style at
+normal size;
+it will be hidden from readers using such devices.
+.
+.
+_endif()dnl
+.TP
.BR .UC " ["\c
.IR version ]
Alter the footer for use with legacy BSD man pages,
_______________________________________________
Groff-commit mailing list
[email protected]
https://lists.gnu.org/mailman/listinfo/groff-commit
