Re: "waldschrotts guide to nifty references" - manualpagedraft, version 0.9b

Zeev Suraski wrote: > De-facto, the manual has always been treated as a reference manual, and not > a user's guide. Perhaps that may have been a part of the original intent, but looking through the annotations, there is a clear and definite need for an online user's guide of some kind, and php.net/manual/ has already *become* that guide. Most sections which did *not* have basic code tutorials now have them added in via the annotations. If there was no basic tutorial in a given area, one has been added by the manual users. What other reason would there be for including user submissions? For correcting the stray typo between returning 1 or 0? The everyday users of the manual have been using it to share complex examples, to give basic tutorials on using the functions, to share information on why to use one function or another. Since there are no online user guides available, the manual has now become the users' guide. > I don't see tutorials being a part of it ever; Many > people have written good tutorials, and we never thought about importing > them into the manual, which is good. Many tutorials would be too large, and too complex. However, I think we need to differentiate between "any form of a tutorial" and "a complex, comprehensive, tutorial for every single function". > Would you expect to see tutorials in > UNIX man pages? Neither would I. I expect the following in man pages, which is *not* currently part of all of the PHP documentation: Usage/Syntax Verbose Usage <-Tutorial info Verbose Explanation of all options <-Tutorial info Examples of many options <-Tutorial info History <-Tutorial info Changelog <-Tutorial info Cross references to similar and inverse functions <-Tutorial info What many of the PHP pages currently have is equivalent to only five to ten lines of a man page. There is also a reason that many beginning Unix developers scoff at man pages and go to online websites, or buy books. Is there a reason to *not* want www.php.net/manual/ as one of the websites that they go to? -Erratacrawlerbop -- Brought to you from iBop the iMac, a MacOS, Win95, Win98, LinuxPPC machine, which is currently in MacOS land. Your bopping may vary.