Escaping hyphens ("real" minus signs in groff) - Michael Kerrisk (man-pages)

From: "Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com>
To: "G. Branden Robinson" <g.branden.robinson@gmail.com>
Cc: linux-man <linux-man@vger.kernel.org>
Subject: Escaping hyphens ("real" minus signs in groff)
Date: Wed, 20 Jan 2021 22:03:12 +0100	[thread overview]
Message-ID: <CAKgNAkihGY5W178QYHcRvs0f0E4HMQdWir9KOJsEzVF=1wi-sQ@mail.gmail.com> (raw)

Hi Branden,

I wonder if I might ask for your input...

For some time now, man-pages(7) has the text (mostly put there by me):

   Generating optimal glyphs
       Where a real minus character is required (e.g., for  numbers  such
       as  -1,  for  man  page cross references such as utf-8(7), or when
       writing options that have a leading dash, such as in  ls -l),  use
       the following form in the man page source:

           \-

       This guideline applies also to code examples.

(You even helped with this text a little, adding the piece about
manual page cross-references.)

I'm having some doubts about this text. The doubts were triggered
after I noticed that many code snippets (inside .EX/.EE blocks) don't
follow this recommendation. I was about to apply a large patch that
fixed that when I began to wonder: is it even necessary?

Some thoughts/questions:

* I believe that when rendering to a terminal, the use of "\-" is
equivalent to just "-"; they both render as a real minus sign (ASCISS
055). Right?

* When rendering to PDF, then "\-" and "-" certainly produce different
results: the former produces a long dash, while the other produces a
rather short dash.

Certainly, when writing say "-1" in running text (i.e., not in a
.EX/.EE code example), one should use "\-1", since without the "\",
the dash in front of the "1" is rather anaemically small when rendered
in PDF.

The same is true when writing options strings such as "ls -l". We
should use "ls \-l" to avoid an anaemic hyphen in PDF.

When writing man-pages xrefs (e.g., utf-8), the use of "\-" produces a
dash that is almost too long for my taste, but is preferable to the
result from using "-", where the rendered dash is too small.

Inside code blocks (.EX/.EE) is there any reason to use "\-" rather
than just "-"? Long ago I think I convinced myself that "\-" should be
used, but now I am not at all sure that it's necessary. Maybe I forgot
something, and you might remind me why "\-" is needed (and I will make
sure to add the reason to man-pages(7)).

Are there any other things I've missed with respect to "\-" vs "="?

Thanks,

Michael

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/