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

[Jan Stary]

On Nov 01 15:37:39, g.branden.robinson@gmail.com wrote:
> 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?

Very, very rarely.

> > To be sure: are you proposing that manpage authors type something else
> > than `that',
> 
> It depends on what, exactly, they want.

I want exactly `this' and func('that').

Don't weasel out of the question:
what would you have me write instead
in the manpage source?

> 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.

We are talking about manpages. Are you insinuating
people should just switch to plaintext instead
if they want `this' or 'that' in their manuals?

> > I'm all for good typography. In a book,
> 
> Are man pages conceivable book content?

Yes, conceivable. Much much more often though,
manpages are just displayed in a text terminal, as you well know.

> > 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.

I just did. Now what?

> > > > > 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.

https://www.mail-archive.com/groff-commit@gnu.org/msg03105.html
That doesn't explain much, does it?

Are you seriously proposing people write e.g. "You can\[aq]t use"
and e.g. \[aq]|lesspipe %s\[aq] instead of '|lesspipe %s' ?

> > 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.

So why are you proposing to change that?

> > 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.

OK; that's not relevant to the argument though, is it.
How do you suggest people write func('this') in a manpage?

> > 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?

In a manpage? I never found the need to have Æ or ¾ in a manpage.

> > 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.

And the benefit of _not_ doing that is a manpage that reads exactly as
I intended it to read, in every terminal of any OS, with any formatter.

Which one is more important to a manpage author?

> > > > 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?

I don't think I do. Many do. Why?

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

.Dd Nov 1, 2020
.Dt PROG 1
.Os
.Sh NAME
.Nm prog
.Nd do stuff
.Sh DESCRIPTION
.Nm
does stuff
.Sh EXAMPLES
.Dl prog "foo\\n"

> Are `these' symmetrical glyphs for you?

I don't know what you mean exactly by symmetrical (as with e.g. { and } ?)
and I don't know what difference it makes to the present argument
if they are or are not 'symmetrical'.

        Jan