[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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

From: Jan Stary
Subject: Re: [groff] 03/09: tmac/an-old.tmac: Stop remapping ` and '.
Date: Sun, 1 Nov 2020 09:34:18 +0100

On Nov 01 15:37:39, 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.
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

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
.Nm prog
.Nd do stuff
does stuff
.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'.


reply via email to

[Prev in Thread] Current Thread [Next in Thread]