Re: .B, .I disable hyphenation?

[G. Branden Robinson]

Hi, Alex!

I realized only after sending my previous giant message on this subject,
that I may have overlooked the elementary step of ensuring that readers
know of the existence and function of the *roff hyphenation control
escape sequence.

groff_man_style(7)[1] explains it as follows.

       \%     Control hyphenation.  The location of this escape sequence
              within a word marks  a  hyphenation  point,  supplementing
              groff’s  automatic hyphenation patterns.  At the beginning
              of a word, it suppresses any automatic hyphenation  points
              within; any specified with \% are still honored.

This escape sequence is ultra-portable and has provenance all the way
back to Bell Labs in the 1970s.

At 2021-09-12T22:09:37+0200, Alejandro Colomar (man-pages) wrote:
> On 9/12/21 7:27 PM, G. Branden Robinson wrote:
> > At 2021-09-12T14:56:39+0200, Alejandro Colomar (man-pages) wrote:
> > > Usually, when a manual page highlights a term, either in bold or
> > > italics, it usually is a special identifier (macro, function,
> > > command name or argument), for which hyphenation can hurt
> > > readability and even worse, turn it into a different valid
> > > identifier.
> > > 
> > > What about disabling hyphenation for .B and .I?
> > > Are there any inconveniences in doing so that I can't see?
> > 
> > The problem that arises is that the font styling macros are
> > presentational, not semantic, so it's hard to know whether someone
> > is using them for emphasis or to suggest syntactical information.
> > This is why you made a statistical argument ("usually").
> 
> Truly, even though most cases of .B/.I are identifiers (or literals),
> some are emphasized words or phrases.
> 
> I think no identifier should ever be hyphenated, if possible, mainly
> due to the confusion with other possibly valid identifiers.

Agreed.  This is especially true for those who view man pages using the
legacy 8-bit output terminal devices (ascii, latin1, cp1047), none which
have a distinct hyphen glyph, and even for users of UTF-8 terminals
where the distributor has configured a remapping of the *roff hyphen
character - to the HYPHEN-MINUS code point, making it indistinguishable
from the *roff minus sign special character \- (which is also what has
been used for the Unix option dash since Ossanna first wrote troff).

> I'd also argue that for the cases when the writer wants to emphasize a
> word, hyphenating it does the opposite.  The writer wanted it to stand
> out from the rest, but now it's broken into two incomplete pieces far
> apart from each other.

I think that's only sometimes true.  If I'm emphasizing a long passage
or an entire sentence, switching off hyphenation can be superfluous.

For example:

man2/execve.2:.B "Do not take advantage of this nonstandard and nonportable 
misfeature!"
man2/getunwind.2:.I Note: this system call is obsolete.
man2/ptrace.2:.I This operation is deprecated; do not use it!
man2/sysctl.2:.B This system call no longer exists on current kernels!
man2/timerfd_create.2:.I "is successfully rearmed"
man3/mallinfo.3:.B Information is returned for only the main memory allocation 
area.
man3/random.3:.I Numerical Recipes in C: The Art of Scientific Computing
man7/mailaddr.7:.I "This behavior is deprecated."
man7/spufs.7:.I The Cell Broadband Engine Architecture (CBEA) specification

While I was performing the above search, I came across something
unfortunate, but on a different subject.[2]

> I think I really want to disable hyphenation everywhere I want a word
> to stand out from the rest, be it an identifier or just an emphasized
> word or phrase.

That's not my preference, particularly in cases of work titles or cases
where an entire sentence is emphasized, both of which are exemplified
above.

> Ingo's option of disabling hyphenation _everywhere_ in man pages seems
> too drastic to me.  There's still a lot of prose, and it's not so
> important there (although I admit both ways have their benefits; not
> saying it's wrong).  But that adds a point against the only downside I
> can see: disabling hyphenation may (in rare occasions where many long
> identifiers are together) produce an awkward number of spaces due to
> filling; but if no-one has complained against mandoc, I guess that's
> not so terrible or doesn't happen that much.

mandoc's audience may share the proclivities of its maintainer; Ingo's
made no secret that the only two output devices he prioritizes are
terminals and HTML.  (Ingo, please correct me on this if necessary.)
groff, like troff before it, is a typesetting engine, and PDF is one of
the formats in which I proofread our documentation.  With a little bit
of care, man pages can be written to a professional quality of
typesetting.  I'd like to preserve that trait.

Is it too much to ask man page writers to remember to type \% before
language keywords when they're using them with the font style macros?  I
dare say that the groff man(7) implementation is much better documented
than it was five years ago.  What else, in your opinion, needs to happen
to improve its ease of acquisition?

Regards,
Branden

[1] https://man7.org/linux/man-pages/man7/groff_man_style.7.html

[2] There's some eye-watering stuff in bpf-helpers(7), like this:

:.B \fBvoid *bpf_map_lookup_elem(struct bpf_map *\fP\fImap\fP\fB, const void 
*\fP\fIkey\fP\fB)\fP

Unsurprisingly to me, there's a comment at the top of the file:

.\" Man page generated from reStructuredText.

...but it doesn't identify the precise tool used in generation.  Do you
know if it was rst2man, or something else?)

signature.asc
Description: PGP signature