[groff] 09/10: groff_man_style(7): Add string usage advice.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit a7c3446ca1d2e4ce516ec89fa154bdf8cec123e9
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sat Oct 17 01:20:47 2020 +1100

    groff_man_style(7): Add string usage advice.
    
    Steer users away from string usage in man page sources.
---
 tmac/groff_man.7.man.in | 30 ++++++++++++++++++++++++++++++
 1 file changed, 30 insertions(+)

diff --git a/tmac/groff_man.7.man.in b/tmac/groff_man.7.man.in
index d280321..5ef23b8 100644
--- a/tmac/groff_man.7.man.in
+++ b/tmac/groff_man.7.man.in
@@ -1951,6 +1951,36 @@ sign\(rq glyph,
 .BR \e(tm ,
 if available,
 and \(lq(TM)\(rq otherwise.
+_ifstyle()dnl
+.
+.
+.PP
+None of the above is necessary in a contemporary man page.
+.
+.B \e*S
+is superfluous,
+since point size changes are invisible on terminal devices and macros
+that change it restore its original value afterward.
+.
+Better alternatives exist for the rest;
+simply use the
+.BR \(rs(rg , \" Heirloom Doctools, mandoc, neatmkfn, Plan 9, Solaris
+.BR \(rs(lq , \" Heirloom Doctools, mandoc, neatmkfn, Plan 9
+.BR \(rs(rq , \" Heirloom Doctools, mandoc, neatmkfn, Plan 9
+and
+.B \(rs(tm \" Heirloom Doctools, mandoc, neatmkfn, Plan 9
+special character escape sequences directly.
+.
+Unless a man page author is aiming for a pathological level of
+portability,
+such as the composition of pages for consumption on simulators of 1980s
+Unix systems
+(or Solaris
+.IR troff ,
+though even it supports
+.BR \(rsrg ),
+the above strings should be avoided.
+_endif()dnl
 .
 .
 .\" ====================================================================