[9fans] Proposal*: A Cousin for man(1)

[9fans] Proposal*: A Cousin for man(1)

[Akshat Kumar]

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.

Re: [9fans] Proposal*: A Cousin for man(1)

[yy]

When I started reading Plan9 documentation some years ago I noticed a
lack of examples (a simple 9P file server being the most notorious
one), until nemo's book appeared and I started to really play with the
system. Then, I realized how naive^Wstupid I had been: Plan9 is *full*
of examples. The source is there, grep is there (and src too!), what
else do you need? I don't think any written-on-purpose example can
explain file servers better than ramfs.c and its friends.
That said, more and better documentation is always welcomed, of course.

Regards,


--
- yiyus || JGL .

Re: [9fans] Proposal*: A Cousin for man(1)

[Ethan Grammatikidis]

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

Re: [9fans] Proposal*: A Cousin for man(1)

[Lyle Bickley]

On Sunday 28 June 2009, yy wrote:
> When I started reading Plan9 documentation some years ago I noticed a
> lack of examples (a simple 9P file server being the most notorious
> one), until nemo's book appeared and I started to really play with the
> system. Then, I realized how naive^Wstupid I had been: Plan9 is *full*
> of examples. The source is there, grep is there (and src too!), what
> else do you need? I don't think any written-on-purpose example can
> explain file servers better than ramfs.c and its friends.
> That said, more and better documentation is always welcomed, of course.

I'm a newbie on Plan9 - and have been reading manuals and following this
list for about a month. I don't think I know about "nemo's book" - where
can I find it? (Is it downloadable or published or both?)

Cheers,
Lyle
--
Lyle Bickley
Bickley Consulting West Inc.
http://bickleywest.com
"Black holes are where God is dividing by zero"

Re: [9fans] Proposal*: A Cousin for man(1)

[hiro]

http://www.google.com/search?q=site%3A9fans.net+%22nemo%27s+book%22

On Sun, Jun 28, 2009 at 4:31 PM, Lyle Bickley<lbickley@bickleywest.com> wrote:
> On Sunday 28 June 2009, yy wrote:
>> When I started reading Plan9 documentation some years ago I noticed a
>> lack of examples (a simple 9P file server being the most notorious
>> one), until nemo's book appeared and I started to really play with the
>> system. Then, I realized how naive^Wstupid I had been: Plan9 is *full*
>> of examples. The source is there, grep is there (and src too!), what
>> else do you need? I don't think any written-on-purpose example can
>> explain file servers better than ramfs.c and its friends.
>> That said, more and better documentation is always welcomed, of course.
>
> I'm a newbie on Plan9 - and have been reading manuals and following this
> list for about a month. I don't think I know about "nemo's book" - where
> can I find it? (Is it downloadable or published or both?)
>
> Cheers,
> Lyle
> --
> Lyle Bickley
> Bickley Consulting West Inc.
> http://bickleywest.com
> "Black holes are where God is dividing by zero"
>
>

Re: [9fans] Proposal*: A Cousin for man(1)

[Lyle Bickley]

On Sunday 28 June 2009, hiro wrote:

> On Sun, Jun 28, 2009 at 4:31 PM, Lyle Bickley<lbickley@bickleywest.com> wrote:
> > On Sunday 28 June 2009, yy wrote:
> >> When I started reading Plan9 documentation some years ago I noticed a
> >> lack of examples (a simple 9P file server being the most notorious
> >> one), until nemo's book appeared and I started to really play with the
> >> system. Then, I realized how naive^Wstupid I had been: Plan9 is *full*
> >> of examples. The source is there, grep is there (and src too!), what
> >> else do you need? I don't think any written-on-purpose example can
> >> explain file servers better than ramfs.c and its friends.
> >> That said, more and better documentation is always welcomed, of course.
> >
> > I'm a newbie on Plan9 - and have been reading manuals and following this
> > list for about a month. I don't think I know about "nemo's book" - where
> > can I find it? (Is it downloadable or published or both?)

> http://www.google.com/search?q=site%3A9fans.net+%22nemo%27s+book%22

Thanks for the reply. I had already downloaded that document - I just didn't know it was
called "nero's book" ;-)

Cheers,
Lyle
--
Lyle Bickley
Bickley Consulting West Inc.
http://bickleywest.com
"Black holes are where God is dividing by zero"