> Here's an example format that deals with current topics in the manual yet > in a more wordy/newbie friendly way. Can't think of a good description of > control structures offhand, will use 'this and that' for now. This is not > a proposal, careful choice of wording is important, something I did not > fully do. That said: > > --- > Control structures do this and that, here is an example if statement: > [skip] > --- > > I will stop :) Point is, we can talk about topics already covered in the > manual but in a more general/wordy way. Doing this can covertly introduce > concepts such as true/false, return, = == ===, etc. The word "covert" has > good/important meaning here.
One thing to start a section like this, and to write up all the parts. It is not that useful to have this in an under construction stage in the manual, but if you have something like that ready, and it is legal to commit it here, we can talk about this. My intention was first to group our already existing things in a sensible way, and start off with a simple (yet more wordy) intro than we have currently. Yes, it would be nice to have a cool intro. This would be a good long time job for some volunteers :) > Another important topic to be covered is how to read a man page. > Something like "man man". For example: > > mixed str_replace (mixed search, mixed replace, mixed subject) > int fwrite (int fp, string string, int [length]) > void var_dump (mixed expression [, mixed expression [, ...]]) > > Being able to decipher what those means is important, something not > everyone knows how to do. We can't rely on our versions of Common > Sense. So: > > How to use the PHP Manual: > a) What Notes's are used for. > b) Why look at the See Also. > c) How to know when a function came into being. > d) How to decipher a function definition. > e) Difference between construct and function, and why I care. > f) User comments? > g) etc. This should go into the "About the manual" appendix. See the TODO comments on the top of that file. That part was actually started to cover such topics, but this is still just a TODO there... This part may also go to the begining of the manual, as in traditional books. The begining is a more natural place for "how to read" info. > It's also worth mentioning that knowing HTML is good, and pointing to some > basic HTML resources, same with SQL, HTTP, Linux, etc. If we get > aggressive, an appendix of HOWTO's can exist on those subjects. Point > is, PHP is not Everything! Add pointers (external links) to the manual whenever you feel the site has more info, and it is worth mentioning. IMHO links should be where the topics are covered (SQL links to databases, HTTP links to networking, etc). Goba
