[PHP-DOC] Re: [PHP-DEV] "waldschrotts guide to nifty references" - manualpagedraft, version 0.9b From: Stanislav Malyshev (stas <email protected>)
Date: 08/20/00

HH(>> that's why a <reference> may have a <partintro> block
HH(>> before the <refentry>s

Well, partintro block per-chapter seems OK to me, especially if we can
group them into separate "Tutorial" book.

HH(>> the array chapter is a bad example as it doesn't have
HH(>> a <partintro>, but other parts of the function reference
HH(>> have additional information on their partintro and
HH(>> this tends to be more like a guide than a reference

partintro blocks I saw look like references, not tutorials. Most just
cover what is that extension, where to take external libraries and how to
turn it on. The don't really teach to use this extension (like user's
guide/tutorial do).

HH(>> it all should not go down to a beginners guide to
HH(>> programming but it should contain any substantial
HH(>> information and IMHO this shouldn't even stop at
HH(>> the PHP<->C boundary but contain stuff like the C APIs
HH(>> that are currently well hidden in the two apidoc files
HH(>> as later parts

This is what I call "bloat". Unless you hide them pretty well (some small
link in the side). Note also that most PHP extensions don't have C APIs by
themselves. I'm not against includign these details in XML files (though
putting so many things in one file seems to me a crime against
modularity), I'm against including it as part of the "logical manual".

HH(>> PS: i always hated to have unix progammers guide
HH(>> and unix programmers reference in two different
HH(>> books where the guide always links to the
HH(>> reference but the reference part is not always
HH(>> available (in other office, not in my backpack...)

When you start learning, it is a bit inconvenient, but when you are an
experienced programmer, it helps a lot. 

-- 
Stanislav Malyshev   stas <email protected>          
+972-3-6139665 ext.106