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

[Ingo Schwarze]

Hi Branden,

G. Branden Robinson wrote on Sun, Apr 30, 2017 at 07:36:03PM -0400:

> I'm working up a man(7) style guide that is sure to be completely
> uncontroversial.  <beat>
> 
> Here is the relevant material from it.
> 
> Note that this is related to but independent of Ingo's proposal.
> My preference is not to refer to \- as a minus sign at all,

I actually agree with that.  If you want a real minus sign (in
particular in mathematical formulae as opposed to in programming
language source code), \- is not a good choise.  And \- is
commonly used for many purposes that are not really minus signs:
command line flags, hyphens inside program names, command modifiers,
ASCII file names, and so on.

> but that bears on documentation, not his proposed mapping per se.

Right.  The above seems right even without either of the two parts
of my proposal (to always map "-" to \(hy and to always map "\-"
to U+002D).

> Hyphens, dashes, and minus signs
[...]

What i snipped seems good to me.

> Finally, use \- to represent the much-overloaded
> hyphen-minus at code point decimal 45 in the ASCII,
> ISO 8859, and Unicode character sets.  It is best to
> think of \- as a piece of meta-punctuation that has only
> technical and contextual meaning, usually in textual
> human/computer interface discussions (programming
> languages, Unix-style command-line options, and so on).

With my proposal, that becomes strictly true.  Even if my proposal
should be shot down, even in the current state of affairs, that
advice seems much better to me than the widespread and confusing
and inaccurate statement "\- is a minus sign".

> Two important use cases for \- are (1) to separate the
> name of a man page from its summary in the Name section

That ought to be "NAME section" (all caps).

But i would probably delete this example case for three reasons.
(1) It doesn't matter at all.  Nobody will cut and paste this.
(2) Semantically, it doesn't make sense at all.  This is not
    a syntax element in any programming language.  It is a
    purely typographical question, and the intended function
    of that dash in the title line is \(em.
(3) It isn't fully true.  For example, groff_mdoc(7) does indeed
    use the ideal \(em for this purpose.  Mandoc mdoc(7) uses
    \(en for not very convincing historical reasons (OpenBSD
    developers did not like "--" in -Tascii output).
(4) Historical practice is highly volative.
    Version 3 AT&T UNIX (written in pure roff(7)) used "--"
      (in the input!)
    Version 4 to 6 AT&T UNIX and 1BSD (written using the archaic
      man macro set which is very different from the v7 man(7)
      macros some still use today, and which is sometimes called
      "man6") used the predefined string \*- defined in man/man0/naa
      (for nroff) as ".ds - -" and in man/man0/taa (for troff) as
      ".ds - \(mi"
    Version 7 AT&T UNIX and 2BSD (written in the final man(7))
      started using \-, and that practice stuck until 4.4BSD
      (even in early versions of mdoc(7))
    In groff_mdoc(7), Werner Lemberg changed if from \- to \(em
      on May 2, 2003, released with groff-1.19.1 in May 2004.
    In OpenBSD, Jason McIntyre changed it from \- to \(en
      on July 14, 2009, released with OpenBSD 4.7 in Nov. 2009

> and (2) to indicate the hyphen-minus character as
> terminal input or output in Unix command names or
> command-line options.

Sure.  that final sentence might be considered a mere repetition,
though.  The term "hyphen-minus" is already introduced two sentences
before, and "command-line options" is already listed in the
sentence right before.  Maybe "terminal input and out", "Unix
command names", and "programming language syntax elements" can be
better integrated into the previous sentence.

Yours,
  Ingo

P.S.
Regarding my proposal, in addition to the support from Ralph,
i privately got support from one FreeBSD developer who has been
maintaining part of the FreeBSD manual page formatting tools for
some years.  I'm still waiting for feeback from the OpenBSD and
NetBSD camps, but at least the reaction wasn't immediate and
fierce opposition when i sent this out to a couple of people who
have shown interest in related questions in the past, even though
i know that at least one of them values simplicity even more than
i do and dislikes \- in general (and stuff like \(hy and \(mi even
more) for that reason.