Re: [Groff] [PATCH] Expand portable escape section of groff_man(7).

[G. Branden Robinson]

Hi, Ingo!

At 2017-10-28T15:18:18+0200, Ingo Schwarze wrote:
> The new text,
> 
>       Using a boot argument of
>       \&'sound=0' disables the sound driver, according to J.\&
>       Alfred Prufrock.
> 
> is all about non-portable concepts as well - many operating systems
> don't even have boot arguments.  But that's OK: An example need not
> document something portable.  Ideally, it should be a sentence
> 
>  * demonstrates the features (that's the case here)
>  * has no other formatting issues (violated here: If you wanted to
>    escape anything is this case, you would say "J.\ Alfred".
>  * isn't contrived (violated here: In a real manual,
>    you would simply write "argument of 'sound=0' disables...")
>  * has content that could actually occur in a manual (violated
>    here: manuals don't report hearsay)
> 
> But it's still good enough.

Finding the ideal example under several simultaneous constraints is kind
of like playing pangram golf: it's a difficult space to search.

The contrivance is in the ostentatious T. S. Eliot reference, not the
rest of the example, which I lifted from Linux's bootparam(7):

 .PP
 As you can see, it gets pretty messy, and you are better off to compile
 in your own personal values as recommended.
 Using a boot argument of
 \&'sound=0' will disable the sound driver entirely.

As a BSD kind of guy, you might not be surprised to find contrivances in
man pages written for the Linux kernel. ;-)

> The rest of your commit looks good.

Thanks.  I'm happy to see the example replaced if someone can come up
with one that better satisfies all of the criteria you specify.

-- 
Regards,
G.\ Branden "Jackdaws love my big sphinx of quartz!" Robinson

signature.asc
Description: PGP signature