Re: [groff] hyphen, minus sign and hyphen-minus

[Ingo Schwarze]

Hi Pali,

Pali Rohar wrote on Fri, May 25, 2018 at 04:59:50PM +0200:
> On Friday 25 May 2018 15:18:18 Ingo Schwarze wrote:

>> For manual pages, the long-established workaround is to use \-.

> Can be this information documented somewhere? I was really not able to
> find it in any groff documentation. Probably it should be in
> groff_char(7).

You are right, The documentation is universally defective in this
respect.  Technically, it would have to be in groff_mdoc(7) and
in groff_man(7) for groff(1) and in mdoc(7) for mandoc(1) because
it is a property of those macro sets.  Then again, from a user
perspective, groff_char(7) and mandoc_char(7) is the more logical
place, and the manual page macro sets are important enough that
the layering violation is acceptable, so it should probably go
there.

Currently, groff_char(7) does not discuss the issue at all and what
mandoc_char(7) says below "Dashes and Hyphens" is in part even wrong
(namely, the part about \(mi, which requests the wrong font).  I'm
planning to fix that when fixing the OpenBSD manuals.  Even though
OpenBSD manual page quality is generally not that bad, those pages
are full of markup errors with respect to hyphen-minus, and i did
not yet come round to tackling that task for real.

> You wrote that it should be easy to write manual page, but then it is
> really bad if after reading groff_char(7) documentation I was not able
> to find out what how to print command line arguments...

True, this is a long-standing source of confusion even though we
refrain from defining yet another escape sequence for it.

> As opposite to above "long-established workaround" in manpages I think
> that it makes sense for other documents to define a new input character
> for hyphen-minus. There is no need to edit existing documents and usage
> of this new character is optional (nobody is forced to use it). It just
> helps to standardize a way how to print it.

Sure, feel free to do that in your own non-manual-page document.

> Happens for: man -Tps and man -Tdvi

Regarding -Tps, i don't know what you mean.  As far as i understand,
at least the default font for -Tps does not even contain a
hyphen-minus output glyph.

Regarding -Tdvi, i frankly don't know.  I never used it and right
now, i do not remember hearing anybody ever talking about maintaining
it, but i may easily have missed something about -Tdvi.

>> So i'd call that a bug in the manual page to HTML processing of
>> groff (groff HTML output is notoriously buggy in general).
>> Don't worry too much about groff HTML output, it is of little
>> relevance.

> HTML output for manpages is relevant.

Of course it is, i fully agree with that.

> What is then preferred tool to generates HTML output from manpage
> if groff is notoriously buggy?

mandoc(1).  Not so much because of bugs, but because it better
translates mdoc(7) markup.  The official online manual pages of
Debian, Arch, and OpenBSD use it, for example.

> So usage of mathematical minus sign (\-) is recommended as 0x2D
> character for describing command line options in manpage?

Unfortunately, yes, that is the consensus regarding best practice,
for want of a better alternative.

Yours,
  Ingo