gbranden pushed a commit to branch master
in repository groff.
commit 67c5521ae7852725bcd7283750f5bbc00e7cafc8
Author: G. Branden Robinson <[email protected]>
AuthorDate: Sun Aug 9 04:34:06 2026 -0500
groff_man_style(7): Offer advice on fonts.
* tmac/groff_man.7.man.in (Notes) [style]: Tell document authors why
it's better to use the package's font selection macros than "raw"
*roff font selection escape sequences.
Fixes <https://savannah.gnu.org/bugs/?68261>.
---
ChangeLog | 8 +++++++
tmac/groff_man.7.man.in | 57 +++++++++++++++++++++++++++++++++++++++++++++++++
2 files changed, 65 insertions(+)
diff --git a/ChangeLog b/ChangeLog
index 04901e3e5..96497fcee 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,11 @@
+2026-08-09 G. Branden Robinson <[email protected]>
+
+ * tmac/groff_man.7.man.in (Notes) [style]: Tell document authors
+ why it's better to use the package's font selection macros than
+ "raw" *roff font selection escape sequences.
+
+ Fixes <https://savannah.gnu.org/bugs/?68261>.
+
2026-08-06 G. Branden Robinson <[email protected]>
* bootstrap.conf: Add "build-aux/epsf.tex" to
diff --git a/tmac/groff_man.7.man.in b/tmac/groff_man.7.man.in
index 0583d7fc8..b28b33a71 100644
--- a/tmac/groff_man.7.man.in
+++ b/tmac/groff_man.7.man.in
@@ -4425,6 +4425,63 @@ Some tips on composing and troubleshooting your man
pages follow.
.
.
.IP \[bu] 3n
+Why should I favor font macros over font selection escape sequences?
+.
+.
+.LS itemized
+.RS 3n
+.IP + 3n
+The formatter can't distinguish typos like
+.RB \[lq] \^\[rs]f\^i\^ \[rq]
+(where
+.RB \[lq] \^\[rs]f\^I\^ \[rq]
+is meant)
+from demands that may be intentional
+but impossible to fulfill on a given output device,
+like
+.RB \[lq] \^\[rs]f[CR]\^ \[rq];
+.
+.
+.IP +
+because font escape sequences \[lq]punch through the floor\[rq]
+and directly command the formatter,
+the macro package can't help you
+by checking font availability for itself
+and then falling back to something \[lq]reasonable\[rq] in context
+(and which takes output device capabilities into account);
+.
+.
+.IP +
+the identity of the \[lq]previous font\[rq],
+as selected by
+.RB \[lq] \^\[rs]f\^P\^ \[rq],
+is inconsistent among implementations
+if the preceding font selection was unfulfillable;
+.
+.
+.IP +
+input like
+.RB \[lq] \^\[rs]fIthis\[rs]f\^P\^ \[rq]
+can frustrate spell checkers;
+and
+.
+.
+.IP +
+.I "groff man"
+knows to apply italic corrections
+when the document sets upright and slanted glyphs adjacently.
+.LE
+.RE
+.
+.
+.IP
+The first three of these problems mean that you cannot be sure
+that a change of typeface has occurred at all;
+if your document relies on that change to communicate information,
+meaning can be lost.
+.
+.
+.IP \[bu]
What's the difference between a man page topic and identifier?
.
.
_______________________________________________
groff-commit mailing list
[email protected]
https://lists.gnu.org/mailman/listinfo/groff-commit
