From mboxrd@z Thu Jan  1 00:00:00 1970
Received: from 5ess.inri.net ([107.161.31.183]) by ewsd; Wed Mar 14 22:57:55 EDT 2018
Message-ID: <8ADDB08FEC580BCDA1A069F2B6469597@5ess.inri.net>
Date: Wed, 14 Mar 2018 22:57:55 -0400
From: sl@stanleylieber.com
To: 9front@9front.org
Subject: Re: [9front] Argument lists in Plan 9 man pages
In-Reply-To: 20180315021926.GA81600@wopr
MIME-Version: 1.0
Content-Type: text/plain; charset="US-ASCII"
Content-Transfer-Encoding: 7bit
List-ID: <9front.9front.org>
List-Help: <http://lists.9front.org>
X-Glyph: ➈
X-Bullshit: patented high-performance API 

> 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