From mboxrd@z Thu Jan  1 00:00:00 1970
Received: from orthanc.ca ([208.79.93.154]) by ewsd; Thu Mar 15 21:32:35 EDT 2018
Received: from localhost (l6 [IPv6:0:0:0:0:0:0:0:1])
	by orthanc.ca (8.15.2/8.15.2) with ESMTPS id w2G1WX0p061356
	(version=TLSv1.2 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=NO)
	for <9front@9front.org>; Thu, 15 Mar 2018 18:32:33 -0700 (PDT)
	(envelope-from lyndon@orthanc.ca)
Date: Thu, 15 Mar 2018 18:32:33 -0700 (PDT)
From: Lyndon Nerenberg <lyndon@orthanc.ca>
To: 9front@9front.org
Subject: Re: [9front] Argument lists in Plan 9 man pages
In-Reply-To: <5727ED416549AF09B9CA5BAFD544869E@5ess.inri.net>
Message-ID: <alpine.BSF.2.21.1803151827200.47626@orthanc.ca>
References: <5727ED416549AF09B9CA5BAFD544869E@5ess.inri.net>
User-Agent: Alpine 2.21 (BSF 202 2017-01-01)
Organization: The Frobozz Magic Homing Pigeon Company
MIME-Version: 1.0
Content-Type: text/plain; charset=US-ASCII; format=flowed
X-Spam-Status: No, score=-2.9 required=5.0 tests=ALL_TRUSTED,BAYES_00,
	NO_RECEIVED autolearn=ham autolearn_force=no version=3.4.1
X-Spam-Checker-Version: SpamAssassin 3.4.1 (2015-04-28) on orthanc.ca
List-ID: <9front.9front.org>
List-Help: <http://lists.9front.org>
X-Glyph: ➈
X-Bullshit: API SSL over SOAP framework-aware callback reduce/map element solution 

> 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