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

Stanislav Malyshev wrote: > > AL>> I´m really agreeing that the manual should be *most* useful and that > AL>> seperation from reference/guide does not improve *usability* > > Sure it does. When you want to look up what is array_diff and go to > ref. manual you don't want to read 5-page tutorial on how to use arrays > and why you might want to use array_diff. You want to get it's parameters, > short explanation and one-two examples of usage, that's it. That's the > difference between reference manual and user's guide - the former just > gives you a list of options, the latter really teaches you what to do with > these options, in which cases and why. that's why a <reference> may have a <partintro> block before the <refentry>s if i want to look up especially array_diff() i almost certainly know roughly what i am looking for and go over index (in printed matter) or quickref in online manual and if i do not know to much about arrays i start with the introduction page to this section to get the big picture the array chapter is a bad example as it doesn't have a <partintro>, but other parts of the function reference have additional information on their partintro and this tends to be more like a guide than a reference it all should not go down to a beginners guide to programming but it should contain any substantial information and IMHO this shouldn't even stop at the PHP<->C boundary but contain stuff like the C APIs that are currently well hidden in the two apidoc files as later parts so you could read up from "getting started" to "some insights into inner works" how to extend it myself" or stop as soon as you have reached your personal "level of incompetence :)" if you do not understand what its all about in any part or want it served in an easier form it is always ok to have other sources of information but thats no argument for anything being left out PS: i always hated to have unix progammers guide and unix programmers reference in two different books where the guide always links to the reference but the reference part is not always available (in other office, not in my backpack...) -- Harmut Holzgraefe hartmut@six.de