From mboxrd@z Thu Jan  1 00:00:00 1970
Received: from 5ess.inri.net ([107.161.31.183]) by ewsd; Thu Mar 15 21:20:29 EDT 2018
Message-ID: <5727ED416549AF09B9CA5BAFD544869E@5ess.inri.net>
Date: Thu, 15 Mar 2018 21:20:29 -0400
From: sl@stanleylieber.com
To: 9front@9front.org
Subject: Re: [9front] Argument lists in Plan 9 man pages
In-Reply-To: 20180315033451.GA89773@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: overflow-preventing service 

>> 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