From mboxrd@z Thu Jan 1 00:00:00 1970 Message-ID: <509071940711011844w6d2c8ff3r8046b40be55a30ce@mail.gmail.com> Date: Thu, 1 Nov 2007 21:44:44 -0400 From: "Anthony Sorace" To: "Fans of the OS Plan 9 from Bell Labs" <9fans@cse.psu.edu> Subject: Re: [9fans] Suggestion: Programming Tutorial for /sys/doc In-Reply-To: <2552D0A5-2008-4E64-BDDA-A62812CA2E33@mac.com> MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 7bit Content-Disposition: inline References: <02597431-3833-4DDD-8720-E0B2761DBE88@mac.com> <509071940711011347i27feaf1bmf12b6c2358818fd8@mail.gmail.com> <2552D0A5-2008-4E64-BDDA-A62812CA2E33@mac.com> Topicbox-Message-UUID: e5a9014e-ead2-11e9-9d60-3106f5b1d025 On 11/1/07, Pietro Gagliardi 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.