Re: [9fans] Suggestion: Programming Tutorial for /sys/doc

["Anthony Sorace" <anothy@gmail.com>]

On 11/1/07, Pietro Gagliardi <pietro10@mac.com> wrote:

> /sys/doc doesn't talk much about the system...

Erm, what? That's pretty much all it talks about. From your list of
topics, 9.ms gives a nice view of "basics", acid.ms gives a nice tour
of debugging (acidpaper.ms is a good read, too, but isn't really
"introductory"), comp.ms give a good view of how the compilers are
typically used in Plan 9 (as opposed to compiler.ms, which talks about
the compilers themselves),  and net/net.ms covers networking in Plan 9
very well (I thought i saw a paper on libthread in there, but I seem
to be wrong).

I'm certainly not saying that there isn't valid work to do for an
introductory document, but there's much information already out there
on the topics you're covering. Maybe I'm misunderstanding your
intentions and you want to cover neglected aspects of them or some
such.

> I have to look at lookman first.

Well, yes. Or read the index yourself, I suppose (how *would* one do
that with the online version?).

> The man pages have several flaws: there are too many;

Again, I'm afraid I don't really understand this complaint. They are
numerous, yes, because they're describing lots of different things.
They don't make for the best introduction *on their own* for that
reason, but they make an excellent reference - which is more or less
their intent.

> some important stuff is hard to find;

Sometimes, yes. lookman does a very good job, but is not perfect. Can
you give examples of the types of difficulty you've been having?

> "man page jumping" is a problem.

Why? It's certainly easy enough to do - the acme integration via
plumber is very nice. It's a "problem" in that it doesn't make for a
nice, flowing introduction, but again, that's not their intent.

My point about the man pages as regards an introductory document is
mostly that it'd be bad to needlessly duplicate effort. I'd expect an
introductory document to make extensive reference to the manual for
the topics it covers.