Re: [Groff] ASCII Minus Sign in man Pages.

[Ingo Schwarze]

Hi Ralph,

i think it is fair to say that our priorities differ slightly here;
i value simplicity for writers slightly higher than you seem to,
and you seem to value typeset (e.g., PDF) output slightly higher
than i tend to.  No doubt, both priorities have some merit.

I don't deny that writing good manual pages requires some understanding
of the roff(7) language, no matter which macro set you use, even mdoc(7),
and the required understanding goes beyond understanding that request
and macro lines start with a dot and text lines don't.  The mandoc mdoc(7)
manual says as much near the top, in the fifth paragraph of the
description.

As a consequence of the slightly different priorities described above,
we might (or might not) disagree about whether certain low-level roff
best practices should be recommended for manual pages, too, but i don't
see evidence of substantial disagreement in that respect yet.
I certainly don't object if people write "e.g.\&", though i might
not try to train less prolific authors to pay attention to that.
I claim that \c is not needed (and should not be used) in mdoc(7),
but you didn't deny that.  I claim that man(7) requires more low-level
roff constructs than mdoc(7), and you didn't deny that.  So the fact
that \c is occasionally used in man(7), in particular in pages
written by unusually skilled typesetters like in the groff manuals
themselves, does not seem all that surprising to me, even though i
don't like it.  That fact that docbook autogeneration spews it
surprises me even less.  No matter how you judge \c usage in man(7),
docbook is no doubt notorious to be the man(7) autogenerator that
produces the lowest quality and least portable man(7) output available
anywhere on the market, even though generators producing acceptable
quality do exist, for example pod2man(1) - not all of that is pretty,
either, but it works quite reliably.


Ralph Corderoy wrote on Wed, Apr 26, 2017 at 03:50:26PM +0100:
> Ingo wrote:

>> INSIDE manual pages, - for \(hy or \- for \(mi is a terrible idea
>> already now because the three main implementations (including groff)
>> don't do that in the quite important -Tutf8 device.

> This is because of the bodge to map `-' onto ASCII 45, by Debian
> originally, was it?  Rather than stand firm and map just `\-' and
> tell complainants that the upstream man page needed fixing.

That is an argument to be taken very seriously.  *If* we value high
quality manual page output enough to worry about hyphens in normal
English words to be rendered as U+002D HYPHEN-MINUS in text lines,
then we have a second problem to solve (in -Tutf8) in addition to
not having a good way to request U+002D HYPHEN-MINUS where that is
really the character we want.

That leads to a natural suggestion solving *both* of these problems:

 - Make sure *all* output devices (even UTF-8) render - as a
   typographic hyphen (U+2010 HYPHEN) even in manual pages.
   That solves the second problem brought up in this mail.
   Yes, it will require fixing lots of manual pages, but if
   we decide that way, i think i'm willing to try and convince
   the BSD camp and help fixing OpenBSD manuals, even though
   i anticipate that will require some work.  That has good
   chances to work out because quite a few people are already
   at least half-aware that the input - is not quite the same
   as an output ASCII HYPHEN-MINUS.

 - Make sure *all* output devices (even PDF) render \- as
   U+002D HYPHEN-MINUS.  That is admittedly a deviation from current
   practice, but it thoroughly solves Ralph's original problem for
   the future, and i think it is close to what \- was originally
   intended to mean in historical roff implementations, so i don't
   view it as trampling on roff traditions.  Also, the visual
   appearance of U+002D HYPHEN-MINUS and U+2212 MINUS SIGN is so
   similar in most fonts that this change is unlikely to cause
   much outrage.

 - Educate people to always use \(mi rather than \- if they want a
   typographic minus sign U+2212 MINUS SIGN (say, in mathematical
   formula) as opposed to an ASCII minus sign (say, in sample C code).

 - Nothing changes for \(en and \(em.

After the above code changes in groff, Heirloom, mandoc, and the
related documentation, and until manual pages adapt, people may
see slighly wrong typography in practice - but none of that will
harm understanding.  The same goes for people using legacy roff
implementations other than the three mentioned, or old versions
of groff.  So incompatibility costs are minor and the transition
paths are more or less benign.

Thoughts?

If people like that direction, i'm even willing to draft patches.

This route is slightly more complicated for authors than my first
simplistic proposal, but i cannot deny Ralph's point that my proposal
harms manual page PDF output, and i can understand if people object
to that: the ability to produce uncompromisingly good typeset output
is among the most famous assets of the system of manual pages as a
whole.

This route is also technically cleaner and easier to implement than
my first simplistic proposal.

In any case, I'd love to have clear, easy-to-understand rules about
what - \- \(hy \(mi mean.  Lots of people have repeatedly asked me
about that, and i have never been able to answer in a very convincing
way.  The current macro set dependency and the absence of U+002D
output in typeset output makes this a deplorable mess.

Yours,
  Ingo