From mboxrd@z Thu Jan  1 00:00:00 1970
Date: Sun, 28 Jun 2009 14:16:50 +0100
From: Ethan Grammatikidis <eekee57@fastmail.fm>
To: 9fans@9fans.net
Message-Id: <20090628141650.955191cf.eekee57@fastmail.fm>
In-Reply-To: <9f8d13d5d9d4e5731836b25aed002bf1@mail.nanosouffle.net>
References: <9f8d13d5d9d4e5731836b25aed002bf1@mail.nanosouffle.net>
Mime-Version: 1.0
Content-Type: text/plain; charset=US-ASCII
Content-Transfer-Encoding: 7bit
Subject: Re: [9fans] Proposal*: A Cousin for man(1)
Topicbox-Message-UUID: 105ffd50-ead5-11e9-9d60-3106f5b1d025

On Sun, 28 Jun 2009 03:31:15 -0700
Akshat Kumar <akumar@mail.nanosouffle.net> wrote:

> Plan 9 manuals are known to be concise, and most definitely the first
> source of information for many of us.  It is only after consulting the
> man pages that we go on to further references, which often happen to
> be more definite or at least in-depth sources of information, such as
> the papers found in /sys/doc.  Of course, this isn't always the case,
> as many Plan 9 experts cite section 5 as "the most authoritative
> 'specification' of the 9P protocol"[1].
>
> But this nature of intro-, or even rudiments-, first usage of man(1)
> can be further developed.  A companion, cousin, or - for the sake of
> this proposal - ese(1) can perhaps guide the user through only the
> most basic information regarding the point of inquiry.  It would show,
> for example, only sample usage cases of the basic Plan 9 tools, with
> appropriately labeled special cases where applicable, but not a word
> more.  Likewise, ese(1) could present, as a companion to the section 5
> manual pages, the outline of some 9P file server code, showing, e.g.
> places where proper datastructures are paramount and common mistakes
> abound.  Thus, man(1) would fall somewhere between ese(1) and the
> docs (/sys/doc), such that every ese(1) inquiry would point to some
> relevant man(1) page (with irrelevancies sprinkled about).
>
> For the many Plan 9 contributors spending away the better parts of
> their youthful days on creating new tools/applications, an ese(1)
> could prove to end the solitude of their work by providing a means
> with simpler standards than man(1) by which to officially convey, in
> the most basic sense, the purposes/usages/applications of their
> contributions.

This ese would be much more valuable on a Gnu/Linux box. As it is, those man pages which are overly long could have summary pages: venti-summary, etc. Shorter pages which seem to require time may just need to be reformatted more in the style of gnu pages, or possibly a slightly better style could be devised.

>
>
> Best,
> ak
>
> [1] http://9p.cat-v.org/documentation
>
> * A proposal because the general hierarchy need be amended: the
> introduction of /sys/ese. Alternatives welcome.
>
>


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