From: sl@stanleylieber.com
To: 9front@9front.org
Subject: Re: [9front] Argument lists in Plan 9 man pages
Date: Wed, 14 Mar 2018 22:57:55 -0400 [thread overview]
Message-ID: <8ADDB08FEC580BCDA1A069F2B6469597@5ess.inri.net> (raw)
In-Reply-To: 20180315021926.GA81600@wopr
> 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
next reply other threads:[~2018-03-15 2:57 UTC|newest]
Thread overview: 20+ messages / expand[flat|nested] mbox.gz Atom feed top
2018-03-15 2:57 sl [this message]
2018-03-15 3:33 ` Sean Hinchee
2018-03-15 3:34 ` Kurt H Maier
2018-03-15 4:54 ` Kyle Nusbaum
2018-03-18 10:07 ` Ethan A. Gardener
2018-03-18 10:17 ` Ethan A. Gardener
-- strict thread matches above, loose matches on Subject: below --
2018-03-16 1:25 sl
2018-03-16 1:20 sl
2018-03-16 1:32 ` Lyndon Nerenberg
2018-03-16 13:22 ` hiro
2018-03-16 13:23 ` hiro
2018-03-16 15:08 ` Stanley Lieber
2018-03-16 15:45 ` hiro
2018-03-16 18:00 ` Stanley Lieber
2018-03-16 22:04 ` hiro
2018-03-16 22:06 ` hiro
2018-03-17 21:12 ` Lyndon Nerenberg
2018-03-18 2:33 ` hiro
2018-03-18 10:15 ` Ethan A. Gardener
2018-03-15 1:53 sl
2018-03-15 2:19 ` [9front] " Kurt H Maier
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=8ADDB08FEC580BCDA1A069F2B6469597@5ess.inri.net \
--to=sl@stanleylieber.com \
--cc=9front@9front.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).