From mboxrd@z Thu Jan  1 00:00:00 1970
Message-ID: <9f8d13d5d9d4e5731836b25aed002bf1@mail.nanosouffle.net>
To: 9fans@9fans.net
From: Akshat Kumar <akumar@mail.nanosouffle.net>
Date: Sun, 28 Jun 2009 03:31:15 -0700
MIME-Version: 1.0
Content-Type: text/plain; charset="US-ASCII"
Content-Transfer-Encoding: 7bit
Subject: [9fans] Proposal*: A Cousin for man(1)
Topicbox-Message-UUID: 1050257e-ead5-11e9-9d60-3106f5b1d025

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.


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.