All of
 help / color / mirror / Atom feed
* Escaping hyphens ("real" minus signs in groff)
@ 2021-01-20 21:03 Michael Kerrisk (man-pages)
  2021-01-21  6:12 ` G. Branden Robinson
  0 siblings, 1 reply; 9+ messages in thread
From: Michael Kerrisk (man-pages) @ 2021-01-20 21:03 UTC (permalink / raw)
  To: G. Branden Robinson; +Cc: linux-man

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 "="?



Michael Kerrisk
Linux man-pages maintainer;
Linux/UNIX System Programming Training:

^ permalink raw reply	[flat|nested] 9+ messages in thread

end of thread, other threads:[~2021-03-07  0:06 UTC | newest]

Thread overview: 9+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2021-01-20 21:03 Escaping hyphens ("real" minus signs in groff) Michael Kerrisk (man-pages)
2021-01-21  6:12 ` G. Branden Robinson
2021-01-21 11:03   ` Michael Kerrisk (man-pages)
2021-01-21 17:42     ` Deri
2021-01-22  8:08       ` Michael Kerrisk (man-pages)
2021-01-22  3:56     ` G. Branden Robinson
2021-01-22 16:27       ` Deri
2021-01-22 17:02         ` G. Branden Robinson
2021-03-07  0:06       ` Alejandro Colomar

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.