Re: RE: [PHP-DEV] "waldschrotts guide to nifty references" - manualpagedraft, version 0.9b

Addressed to: "Phpdoc" <phpdoc@lists.php.net> php-dev@lists.php.net Sorry for extending this thread, but after reading it, I find I have some pretty strong feelings on the subject. I definitly DO NOT want 1003 places to look for something, but I also don't want to have to wait for pages of introductory information to download before I can find the order of parameters for a function. I think three 'books' would be an ideal number for PHP. o Users Guide You look here for information on what you can do with arrays in PHP, how to use sessions, or upload files, etc. Topics are grouped by activity with no concern for what functions are used to get the job done. I think the PHP Users Guide should assume the user knows something about HTML, CGI, SQL and a programming language or two. First time programmers can hit the third party tutorials for step by step instructions. I consider the three O'Reilly Perl books mentioned earlier to be Users Guides. (Learning, Programming and Advanced Programming) I usually read the Users Guide once or twice and put it away once I know enough functions to get the job done, which is why I don't want to see this info every time I am looking for reference data. o Reference This book gives concise definitions of functions, and parameters. It is grouped by function, or purely alphabetically. Most of the time I know what function I want to use, but need to refresh my memory on the parameters or the return values. This is the book I grab most often. When I write in Perl I use The Perl 5 Programmer's Reference. (Wyke, Duncan - Ventana Communications Group - ISBN 1-56604-750-1) Over half the book is an alphabetical list of functions, with most pages having two functions, a handful of functions spanning two pages, only one page with parts of three functions on it. There is a bleed to the edge of the page that marks all the functions that start with the same first letter, and I have written the letters on the edge of the book. That makes for a very fast way to find details on something. Most of the rest of the book does the same for Perl modules. The current PHP manual is a very good reference manual. It might be improved re-arranging parts of it, but overall it is great. I think it would lose value if the concise function definitions are watered down with too much info on usage. o Extensions, Internals and Philosophy This is the place for all the jucy tidbits that you don't have to know to write PHP programs. Waldschrotts Guide would fit here, along with how to write extensions, and other advanced topics that you don't have to know to paint a web page. This might be a good place for the developers to record why they made the choices they did, and how it affects how scripts are run. Anything that generates 10 or more messages on php-dev about how to do it might deserve a summary in this manual. That wouldn't take a developer to write, but would record the reasons and results of major development decisions. If you just can't handle the idea of three separate 'books', this could be mixed in with the Guide, but it is different enough I think it should stand on its own. Since the PHP manual is most often used via the web rather than paper there is good reason to hyperlink extensively. It does not cost that much to make every reference of a function in the Users Guide a link to the function in the Reference Manual. (sounds like a program to me...) The reference manual could include a link to the user guide chapter that tells how to use a function and both of those 'books' could have footnotes that mention advanced discussion in the Internals Manual. You might even consider allowing URL's to tutorials written by others as an acceptable annotation to the manuals. As long as it did not get abused, what better place for links to tutorials than the bottom of the users guide page. I think the format of three separate books is ideal. It doesn't take that long to figure out what is where, and once you do you can zero in on just the information you need rapidly. One last thing, the biggest, simple improvment to the manual you could make for me would be to have a link in the table of contents to "Alphabetized list of Functions". This link takes you to a page of links, A - Z and 'All'. Each letter page lists all function names that start with that letter. The All page lists them all on one page. The function names are links to the function, followed by the short description from the ref.* pages. This way if I know the name of a function I can find it without having to guess what category it belongs in. I do it now by typing in the URL, but it would be nice if I did not have to take my hand off the mouse. :) It would be even better if it listed ALL php functions, even if they have not yet been documented . Rick Widmer Internet Marketing Specialists www.developersdesk.com