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