[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, 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
- Re: [groff] 03/09: tmac/an-old.tmac: Stop remapping ` and '., G. Branden Robinson, 2020/11/01
- Re: [groff] 03/09: tmac/an-old.tmac: Stop remapping ` and '.,
Jan Stary <=
- Re: [groff] 03/09: tmac/an-old.tmac: Stop remapping ` and '., Werner LEMBERG, 2020/11/01
- Re: [groff] 03/09: tmac/an-old.tmac: Stop remapping ` and '., John Gardner, 2020/11/01
- Re: [groff] 03/09: tmac/an-old.tmac: Stop remapping ` and '., Werner LEMBERG, 2020/11/01
- Re: [groff] 03/09: tmac/an-old.tmac: Stop remapping ` and '., John Gardner, 2020/11/01
- Re: [groff] 03/09: tmac/an-old.tmac: Stop remapping ` and '., Werner LEMBERG, 2020/11/02
- Re: [groff] 03/09: tmac/an-old.tmac: Stop remapping ` and '., John Gardner, 2020/11/02
- Re: [groff] 03/09: tmac/an-old.tmac: Stop remapping ` and '., Ingo Schwarze, 2020/11/02
- Re: [groff] 03/09: tmac/an-old.tmac: Stop remapping ` and '., John Gardner, 2020/11/02
- Re: [groff] 03/09: tmac/an-old.tmac: Stop remapping ` and '., Ingo Schwarze, 2020/11/03
- Re: [groff] 03/09: tmac/an-old.tmac: Stop remapping ` and '., John Gardner, 2020/11/04