Groff output breaks Lexgrog

[bensmrs]

I’m packaging an app that uses Cmdliner for Debian, and generating the manpages by piping <command> --help=groff to my manpage files.
It works great, the manpages can properly be read, but the Debian package linter, lintian, uses lexgrog to parse the manpages for some metadata. However, lexgrog doesn’t like escape characters in the NAME section. Cmdliner is generating \N'45' for the regular dash - character, which breaks this tool (and thus quite a few Debian packaging tools). Would it be possible to generate \- instead? (or - within the text and \- for command-line options, but that one may be too tricky)

For now, I’m piping the output to sed "s/\\N'45'/\\-/g", but was hoping for a more “legacy” handling of dashes that works well with groff parsers. What do you think?

[dbuenzli]

I don't mind changing if

1. It works everywhere
2. It doesn't hamper search, i.e. in the groff output dashes are rendered as U+002D and not something else (I remember that being an issue).

That being said in my book I'd rather say that the problem lies with lexgrog here.

[bensmrs]

the groff output dashes are rendered as U+002D and not something else (I remember that being an issue)

- is converted to a typographic dash, but \- is the actual uninterpreted dash, so that should work fine.

That being said in my book I'd rather say that the problem lies with lexgrog here.

Oh I completely agree with that, but unfortunately, inertia makes it so that it felt more convenient asking here :)

Want me to come up with a PR?

[dbuenzli]

Ok but I'm just wondering why I didn't come up with \- in the first place which sounds rather natural in contrast to \N'45' :–)

Could you perhaps just please dig me a reference so that we can be confident it will work everywhere?

[bensmrs]

Ok but I'm just wondering why I didn't come up with \- in the first place which sounds rather natural in contrast to \N'45' :–)

Well given the code I’ve read, I’d say convenience. You’re just “base10-escaping” every special character in a uniform way… until some rando tells you this one particular niche tool doesn’t like it :)

Could you perhaps just please dig me a reference so that we can be confident it will work everywhere?

The groff_char manpage is a very nice reference for that: https://man7.org/linux/man-pages/man7/groff_char.7.html, more specifically:

       The hyphen‐minus is a particularly unfortunate case of
       overloading.  Its awkward name in ISO 8859 and later standards
       reflects the many distinguishable purposes to which it had already
       been put by the 1980s, including a hyphen, a minus sign, and
       (alone or in repetition) dashes of varying widths.  For best
       results in roff systems, use the “-” character in input outside an
       escape sequence only to mean a hyphen, as in the phrase “long‐
       term”.  For a minus sign in running text or a Unix file name or
       command‐line option dash, use \- (or \[-] in groff if you find it
       helps the clarity of the source document).  (Another minus sign,
       for use in mathematical expressions, is available as \(mi.)  AT&T
       troff supported em‐dashes as \(em, as does groff.

And later in the manpage,

       Output   Input          Unicode      Notes
       ─────────────────────────────────────────────────────────────────────
...
       -        \[-]           u002D        minus

[dbuenzli]

Okay thanks!

[bensmrs]

Sorry for the radio silence, I’ll have a look this week.

[dbuenzli]

Rereading this I still think it would be better to fix lexgrog :-)

[bensmrs]

The manpages for man in French (https://manpages.debian.org/testing/manpages-fr/man.7.fr.html) explicitly mention that under “Sections”. So that seems to be bigger than the scope of lexgrog. Funnily enough, I can’t find that sentence in the English manpages :)

[bensmrs]

Oh, there https://manpages.debian.org/testing/man-db/lexgrog.1.en.html#WHATIS_PARSING