On Sun, 28 Jun 2009 03:31:15 -0700 Akshat Kumar <aku...@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
