Re: [groff] 03/09: tmac/an-old.tmac: Stop remapping ` and '.

[G. Branden Robinson]

At 2020-10-31T15:58:00+0100, Jan Stary wrote:
> Hi Branden,
> 
> as an author of manpages for command-line utilities, I want to type
> e.g. `this' into a manpage source like `this' because that's exactly
> what you type on the cmdline and that's what I want the user to read
> in the manpage.

Okay.  Do you ever view your man pages with -Tps or -Tpdf?

> To be sure: are you proposing that manpage authors type something else
> than `that',

It depends on what, exactly, they want.  In ASCII, they didn't have much
choice.  In Latin-1, some of them thought, incorrectly, they they had
some choice, but didn't, because an acute accent ´ is not a quotation
mark of any sort.

And now, with UTF-8, they have choices but pretend they don't.

Man page authors are a turbulent bunch.

> or that formatters display something else? Having to type anything
> else (in the name of good typography) is making me jump through hoops.

Well, there's always plain text for the full WYSIWYG experience.

> I'm all for good typography. In a book,

Are man pages conceivable book content?

> But in a manpage, I want to just type e.g. ` and the formatter
> to display ` and the reader to see ` because that's what
> you type when you run the command.

Again I encourage you to try viewing your pages with -Tps or -Tpdf.

> > > > 6. Revert the change an un-fix the misuses of ` and ' in code
> > > >    specimens that I've been repairing for the past few years.
>
> What "misuse"?

Commit cc7971dfc0865893e5bc95584e5e0b80ae00d664.

> Having `this' in a manpage is perfectly good typography,

It's the idiom for producing single-quoted text in all roff documents
since the early 1970s, that much is true.

> because that's exatly what you type when you use the command.

Your experiences may differ from mine, but I never have to pair ` with '
at the Unix command line.  The only places I see this pairing come up
are not at shell prompts or in scripts, or when writing in C or any of
its descendants, but in groff, TeX, and m4.

> I don't see any benefit in having to type or display something else.

ASCII gives you 94 visible glyphs[1].  How do you propose to obtain any
that it doesn't cover?

> What do you argue _is_ the benefit? A more beautiful manpage that
> says something else than what it wants to say?

The benefit is a man page that renders as documented by groff whether
the output device is a UTF-8 terminal emulator, PostScript, PDF, or
HTML.

> > > manual pages are written by software developers,
> > > not by typesetters, who are used to typing programming languages
> > > and who are used to the fact, from the past, that these five
> > > characters do not need escaping.
> 
> Exactly.

I have a few more questions.

Do your man pages ever use the sequence '\-'?  If so, why?

How do you represent backslashes in your man pages--for example, if you
needed to document 'printf "foo\n"' to your readers?

Are `these' symmetrical glyphs for you?

Regards,
Branden

[1] And the semantics of several of its code points were _deliberately
    amibiguous_, a devil's bargain for which we are still paying.
    https://www.aivosto.com/articles/charsets-7bit.html

signature.asc
Description: PGP signature