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

[Ralph Corderoy]

Hi,

Ingo wrote:
> Besides, writing manual pages absolutely needs to be simple.  Manual
> pages must be written by programmers who may not know typography and
> who are not prepared to, and shouldn't be required to, acquire
> specialized knowledge just to write the required manuals together with
> their code.

I disagree here, and thus with much of the resulting threads between
Ingo and Brendan.

Writing a man page is writing troff using the -man macros.  Always was,
always will be.  It's not some non-troff mark-up language that happens
to use troff as a back-end.  One must be prepared to understand it's not
just plain text and commands on lines starting with `.':

  • That the plain text is significant too, e.g.\& putting that `\&'
    after the full stop so the inter-word gap doesn't become
    end-of-sentence if word-wrap should split the line.

  • .IR being is just a shorthand for `\f' and `\^' that can be done
    manually when needed, e.g. `.TH'.

  • And, yes, what `\c' does, and to use it when required;  the common
    case can easily be copied from other man pages.

Fortunately, programmers are the kind of folk that will appreciate the
finesse that can be expressed if they understand the cause, and that
includes attractive PDF output.  I think good PDF representation is a
handy test of whether the man page has flaws, and isn't second-class to
UTF-8 on a TTY.

Note, I'm not talking about writing an mdoc page.  Like others, I find
the macro names too many, too confusing, the result too noisy with its
nested macros, and have never persevered.  That may be my fault and I
should try again.  :-)

> INSIDE manual pages, - for \(hy or \- for \(mi is a terrible idea
> already now because the three main implementations (including groff)
> don't do that in the quite important -Tutf8 device.

This is because of the bodge to map `-' onto ASCII 45, by Debian
originally, was it?  Rather than stand firm and map just `\-' and tell
complainants that the upstream man page needed fixing.

> INSIDE manual pages (both -man and -mdoc), let's change - and \- to
> always map to U+002D HYPHEN-MINUS for all devices and let's tell
> people to simply use - for HYPHEN-MINUS and stop worrying.

But PDFs then look awful.

A new `\(hm' isn't a go-er for the same reason depending on .itc in .TH,
or a new .TH variant, aren't worthwhile;  man pages have to format on
old systems that haven't these fangled additions.  And we've managed OK
without.

an-ext.tmac I've never used, just read it.  Is it mentioned in a man
page?  I even checked `info groff | cat' and didn't spot it.  :-)  I'm
not keen on embedding it at the start of every man page in a project,
even if they're built from a source just to achieve that.  What's the
alternative?  `.so ../man1/foo-an-ext.tmac' and release it to sit
alongside the foo project's other man{1,8} pages.  It obviously mustn't
appear as a page itself in indexes, etc.

Cheers, Ralph.