> > 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.
There is intro(2) is not a bad introduction either, althought it certainly doesn't cover much. Just thinking out loud here so I might make no sense, but I suspect the issue is that the style of the plan9 documentation is very different from what people have become used to expect, this days people expects 'tutorials' and other handholding with many examples to 'copy paste' into their code and so on, which is quite different from the Unix/Plan 9 documentation style of clear and concise information and simple examples that help illustrate the general concepts, but that does require the reader to actually *understand* things rather than just follow an arbitrary set of steps. Best wishes uriel > > > 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. >
