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