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

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

[sl]

> 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

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

[Sean Hinchee]

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

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

[Kurt H Maier]

On Wed, Mar 14, 2018 at 10:57:55PM -0400, sl@stanleylieber.com wrote:
> 
> I agree with Tufte, at least so far as this applies to man pages.
> Flag options should be presented as a table.


Counterpoint:

Man pages should provide a full and well-articulated explanation of the
software.  Tufte's table advocacy is more appropriate for a 'usage'
function that might describe invocation to a user who passed a help
flag or fucked up the initial attempt.

Tufte's USA Today stuff is fine for sales brochures and nutrition
information labels -- man pages should be the developer speaking to the
user, and that happens in English.

My commitment to this opinion is insufficiently intense to cause me to
take any action beyond whining on the internet.

khm

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

[Kyle Nusbaum]

On 03/14/2018 10:34 PM, Kurt H Maier wrote:
> On Wed, Mar 14, 2018 at 10:57:55PM -0400, sl@stanleylieber.com wrote:
>>
>> I agree with Tufte, at least so far as this applies to man pages.
>> Flag options should be presented as a table.
> 
> 
> Counterpoint:
> 
> Man pages should provide a full and well-articulated explanation of the
> software.  Tufte's table advocacy is more appropriate for a 'usage'
> function that might describe invocation to a user who passed a help
> flag or fucked up the initial attempt.
> 
> Tufte's USA Today stuff is fine for sales brochures and nutrition
> information labels -- man pages should be the developer speaking to the
> user, and that happens in English.
> 
> My commitment to this opinion is insufficiently intense to cause me to
> take any action beyond whining on the internet.
> 
> khm
> 

Furthermore, it appears Tufte is speaking specifically about
quantitative materials.
I'm not confident flags are quantitative.

Having said this, I agree with sl, and either way I will obviously do
nothing about it.

-Kyle

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

[Ethan A. Gardener]

Seeing as this appears to be a thread for declaring opinion 
along with an intent to do nothing, I may as well weigh in. ;)

On Thu, Mar 15, 2018, at 2:57 AM, sl@stanleylieber.com wrote:
> 
> 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.

I formerly held to this opinion, with the exception that I never even tried 
wading through more than 4 or 5 paragraphs at most. I have to admit 
that even 2 paragraphs of verbiage around the options could be really 
annoying at times.

I use the word "verbiage" because it sounds like "foliage", which in this 
context reminds me of attempting to proceed through jungle undergrowth. 

> Parsing the big paragraphs for flag options is
> cognitively disruptive and prone to error

Exactly. 

I implied I'll do nothing at the top, but that may turn out to be false. I really 
got back into programming in the last few weeks, but once I really got going 
I found it somewhat addictive. There's always another fascinating puzzle to 
solve, and I don't want to stop. Then, of course, it takes my energy away 
from everything else. I decided to limit programming to one day a week, 
but I need something lighter to fill the rest of my time. 
I've got a few other things to write at the moment, but when they're done, 
maybe I'll have a go at man pages.


-- 
The lyf so short, the craft so long to lerne. -- Chaucer

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

[Ethan A. Gardener]

On Sun, Mar 18, 2018, at 10:07 AM, Ethan A. Gardener wrote:

Oh by the way, I'm changing my surname for personal reasons.
It used to be Grammatikidis.

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

[sl]

> Furthermore, it appears Tufte is speaking specifically about
> quantitative materials.
> I'm not confident flags are quantitative.

The Tufte stuff is about not accidentally lying with pictures.  A
substantial portion of the book I quoted is devoted to recommending
text tables where graphics are commonly employed.  I think his
perspective can be applied generally to all forms of communication.


> Having said this, I agree with sl

Let's draft a time series.

sl

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

[sl]

>> I agree with Tufte, at least so far as this applies to man pages.
>> Flag options should be presented as a table.
> 
> Counterpoint:
> 
> Man pages should provide a full and well-articulated explanation of the
> software.  Tufte's table advocacy is more appropriate for a 'usage'
> function that might describe invocation to a user who passed a help
> flag or fucked up the initial attempt.
> 
> Tufte's USA Today stuff is fine for sales brochures and nutrition
> information labels -- man pages should be the developer speaking to the
> user, and that happens in English.

I want both English and legibility. I don't think tabulating flag options
violates any of this.  Clarity shouldn't replace depth.

sl

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

[Lyndon Nerenberg]

> I want both English and legibility. I don't think tabulating flag options
> violates any of this.  Clarity shouldn't replace depth.

And describing flags using out-dented paragraphs doesn't stop anyone from 
writing prose within those paragraphs.  What frustrates me to no end with 
the traditional Plan9 manpage layout is that you cannot find where the 
flag description starts, when they are all buried inside inline text.

The typeset manpages have differential font helpers, but when you're 
running man in a terminal window, flags get buried on the background 
noise.

Manpages are supposed to be 'reference' pages.  That means visibly calling 
out the flags and their usage.  Otherwise, they (the man pages) aren't 
doing their job.

--lyndon

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

[hiro]

The man pages being very readable is a lesson on how little the rules
you manage to formulate matter in comparison to subtler rules we can
only attribute to the "art" of writing.

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

[hiro]

> Manpages are supposed to be 'reference' pages.

Wrong.

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

[Stanley Lieber]

On Mar 16, 2018, at 9:23 AM, hiro <23hiro@gmail.com> wrote:

>> Manpages are supposed to be 'reference' pages.
> 
> Wrong.

What are they then, hiro. Lottery tickets?

sl

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

[hiro]

They are meant to be read also for getting an overview of the system.

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

[Stanley Lieber]

On Mar 16, 2018, at 11:45 AM, hiro <23hiro@gmail.com> wrote:
> 
> They are meant to be read also for getting an overview of the system.

Are you saying:

Man pages are not a reference work because they are meant to provide information about the system.

Or something else?

This is going to sound rude: Maybe you could try embedding your message inside long paragraphs. If it’s good enough for enumerating flag options, it might work here.

I don’t agree that a tabulated list of flag options is at odds with providing an overview of the system. The same information is still being provided, whichever format is ultimately used.

sl

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

[hiro]

no

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

[hiro]

> I don’t agree that a tabulated list of flag options is at odds with
> providing an overview of the system. The same information is still being
> provided, whichever format is ultimately used.

I agree it is possible either way.

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

[Lyndon Nerenberg]

> They are meant to be read also for getting an overview of the system.

I think /sys/doc/* fulfills that role.

Which isn't to say you can't learn a lot from reading manpages, but they 
aren't tutorials.

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

[hiro]

neither are tutorials, but i would always recommend reading both to
get a good overview.

also: man pages are updated, /sys/doc stuff often is outdated.

earlier sl was correct to complain. what i really wanted to point out
is the significance of this additional use case, i.e. man pages cover
both a lot of detail (for quick references) and more abstract
overview.

On 3/17/18, Lyndon Nerenberg <lyndon@orthanc.ca> wrote:
>> They are meant to be read also for getting an overview of the system.
>
> I think /sys/doc/* fulfills that role.
>
> Which isn't to say you can't learn a lot from reading manpages, but they
> aren't tutorials.
>

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

[Ethan A. Gardener]

On Fri, Mar 16, 2018, at 1:23 PM, hiro wrote:
> > Manpages are supposed to be 'reference' pages.
> 
> Wrong.

I hereby propose the addition of 'ref tables' to provide references on how to use commands. Looking up a command's 'ref table' is easy, simply type 'ref ' followed by the name of the command. For example:
    ref -s δ ref

Or, just plumb a string such as this:
    ref»δ«


-- 
The lyf so short, the craft so long to lerne. -- Chaucer

Argument lists in Plan 9 man pages

[sl]

 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

sl

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

[Kurt H Maier]

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.

khm