on the need for better quotation in man(7) (was: names of ISO 8859 encodings)

[G. Branden Robinson]

[looping in groff@gnu]

Hi Alex,

At 2024-12-14T18:27:14+0100, Alejandro Colomar wrote:
> [I wrote:]
> > Alex, do you think this issue is enough of a trip hazard to warrant
> > presentation in man-pages(7)?
> 
> What's the issue?  I think it's simple:
> 
> When referring to a standard, use the pedantically correct name for
> it.  When showing a command line, use text that is pedantically
> correct to the command interpreter.

I agree.

> Am I missing anything?

Only that people may sometimes not be clear on which is which.  That is
why it is important to typographically distinguish the cases.
Traditionally this has been difficult in man pages, I think because (1)
the man(7) package has no macros for quotation; (2) idioms for displayed
examples and other I/O were not in Seventh Edition and slow to evolve.

I think some of the blame for (2) can be laid at the feet of the "it's
reference, not a tutorial" camp.  Even references sometimes need
exhibits.

With Chet Ramey's kind indulgence, I've been trialling a simple
quotation macro `Q` in the bash man pages (bash(1), readline(3),
history(3)) this year.[1]  I have an alternative design for quotation
macros in mind as a future groff man(7) development.[2]

Regards,
Branden

[1] https://lists.gnu.org/archive/html/bug-bash/2024-01/msg00027.html

    Chet soon added a `QN` variant to prevent hyphenation, because it's
    a little tricky to achieve that in a quotation context otherwise.

[2] https://lists.gnu.org/archive/html/groff/2023-09/msg00052.html
    https://lists.gnu.org/archive/html/groff/2023-09/msg00058.html

    This is likely due for a cleaned up re-proposal under the new names
    `QS`/`QE` as suggested by Doug McIlroy.  Also, an optional argument
    to disable hyphenation, brought to my attention by Chet this year,
    might be worth having, though mandoc(1) has the problem of
    formatting all arguments to unrecognized macros as text, which is
    not a very *roffy thing to do.  It will do the same with `.YS 0`,
    until and unless mandoc(1) comes to support this extension scheduled
    for groff 1.24.

    Having gained some practical experience with several other man(7)
    corpora, I probably would not float `Q` as a groff man(7) extension;
    I think `QS` and `QE` would suffice.  I am mindful of the benefit of
    keeping the man(7) language as small as possible (but no smaller).

signature.asc
Description: PGP signature