Re: [9front] Argument lists in Plan 9 man pages

[Sean Hinchee <henesy.dev@gmail.com>]

I can definitely say i find the upasfs(4) style of handling arguments
much more pleasant than the style in which the arguments are
intermixed with paragraphs of prose.

I would agree with sl on this one and would offer my time to help
re-format pages if it would be desired.

Cheers,
Sean

On Wed, Mar 14, 2018 at 9:57 PM,  <sl@stanleylieber.com> wrote:
>> On Wed, Mar 14, 2018 at 09:53:38PM -0400, sl@stanleylieber.com
> wrote: >> From Tufte, Edward R (2001) [1983], The Visual Display of
> Quantitative >> Information (2nd ed.), Cheshire, CT: Graphics Press,
> ISBN >> 0-9613921-4-2: >> >>
> http://img.stanleylieber.com:80/src/19787/img/small.1521069102.png > >
> Tufte is full of it.
>
> I agree with Tufte, at least so far as this applies to man pages.
> Flag options should be presented as a table.
>
> Compare:
>
>         http://man.9front.org/1/rio
>
> with:
>
>         http://man.9front.org/4/upasfs
>
> Both styles are distributed across the total collection of man pages.
> The pages that try to describe flag options by clumping them together
> into communal paragraphs require all kinds of awkward constructions
> that are only slightly more legible (because flag options are printed
> in an alternate font) in the fully-formatted PostScript output.  Even
> then, all the extra words needed to shore up embedding them into
> literary prose obscure the information the page is trying to
> communicate.
>
> The argument against my point of view is that the man pages are
> supposed to be kept short enough, and programs should have few enough
> flag options, that it never becomes a problem wading through tens of
> paragraphs to locate the flag option you're looking for.  This
> argument doesn't wash.  Parsing the big paragraphs for flag options is
> cognitively disruptive and prone to error when the reader has no need
> to re-digest the entirety of an already chewed over man page.
>
> This is not a call to action.  I will not revise a single man page.  I
> will continue to author new man pages that display flag options as a
> table.
>
> Thank you for your time.
>
> sl