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

Andrei Zmievski wrote: > > On Sun, 20 Aug 2000, Zeev Suraski wrote: > > De-facto, the manual has always been treated as a reference manual, and not > > a user's 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. Would you expect to see tutorials in > > UNIX man pages? Neither would I. > > I don't really agree with that. PHP manual is the first place people > come to for PHP language questions. Why not provide code samples and > tutorials as part of the manual instead of making them search through > some other site? especially as the second place is most likely one of the mailing lists (and not always the right one as phpdoc subscribers know) or a question in the annotations ... :( it is true thatfor example the MySQL section should not teach you how to speak SQL, thats a different story, but from my experience with the (still unfinished) imap documentation a pure reference style documentation will produce far more problems than solutions as - the extensions name is misleading as it can handle pop, nntp, mailbox files and, of course, imap - it is not clear what a mailbox name is in the context of theese functions - some of the functions do not make sense with some of the supported protocols when i first read my way through this part of the manual it was in a minimalistic reference form, and it was useless even if already had a rough picture of what was going on (protocols, encodings, MIME and such), not to speak of the missing functions, the functions documented but not yet available in PHP4 as they had been added in PHP3 after the code split and the errors on some of the prototypes and descriptions to make it even worse there is no tutorial and only a well-hidden reference text in the UW-imap c-client package itself (called internal.txt) so i started to add more flesh to the function descriptions and tried to write an example for each of them, even describing some protocol background stuff from time to time this is not a beginners tutorial (and shouldn't be) but it has some tutorial aspects and i think that doesn't harm at all (although i might move some of the descriptive stuff from the functions, esp. imap_open() to the intro part in the final version) this is what i talk about when refering to tutorials, other interpretations may differ from it if we say that the manual should not becom a 'PHP for dummies' i totaly agree but it should contain enough background information that someone who has done programming before and has a rough idea what a given extension is good for and how to get started with it without having to browse a lot of 2nd documentation sources or fall back into try&error -- Hartmut Holzgraefe hartmut@six.de http://www.six.de +49-711-99091-77 fax:-99