I'd like also: - to include HOWTO into docs;
GH> What? Do you mean that our end users are interested in the HOWTO? Why? Well, at least to make everything available in one place. If there is a section for PHP extension developers why not to have one for manual writers/translators? For those who always online it isn't necessary, but for other people who use downloadable format this can be become interesting.
This is exactly the opposite as your last suggestion (split manual in more parts). Now what is better, having all the stuff at one place, or three manuals (PHP Users Manual, PHP Developers Manual, PHP Documentation Howto). IMHO three documents are better. They only need to have three root XML files, and their files can reside in the same CVS module, as it is now. We already have a root file to generate the install part only. I am stronly against integrating the HOWTO into the manual content.
- merge streams section with ZendAPI;
GH> Someone needs to find time to look into the ZendAPI stuff deeper, and
GH> come up with a suggestion on tags we can use to integrate thte ZendAPI GH> docs into the manual, and then to merge that part with the streams GH> development stuff.
It was the first thought I came to - merge streams section, but there
is another problem. Indexing. There was a bug rep about user notes
clutter search results and what if there is also a developers notes?
Weird. Of course when it is in PHP manual it is rather interesting to
read and I've almost written a dummy plugin just because of
curiousity, but for most users this is too much. After higher
mathematics I didn't believe that there can be things to confuse me,
but m4 + english have done that. =) Therefore..
99% of our users are not interested in development details. This is why the Zend stuff was not incldued in the XCHM before.
- release a separate PHP3 manual;
GH> Now? I wonder how you imagine that. It is a tremendous amount of human
GH> work to tag the different parts of the manual now for PHP 3, as PHP 3, 4 GH> and 5 content is intermixed.
What if we fetch a CVS verson of manual before PHP 4.3.0 version for example
or when a latest PHP3 patches were commited to repository? Or when the
support for PHP3 had stopped. Remove all functions, what were not
present in PHP3 and leave it "as is". Well, maybe reviewing some pages
to mark what features are specific for "upcoming" PHP4. =)
There were PHP 3 specific notes added after the 4.3.0 release, or at least it is quite possible. IMHO it is simly too much work to get a PHP 3 manual now. By the way it is identically impossible to get a PHP 4 or PHP 5 manual now. People do close bugs for PHP 4 related errors in the manual, so the PHP 4 specific stuff is actively modified. This was true for the PHP 3 parts back then.
- think about separate ZendAPI and PHPAPI manual;
GH> What do you mean with PHPAPI here? Well, you are right. It's a mistake. PHP Manual. Merge Streams and PHPAPI sections into ZendAPI and release a separate developers manual. So PHP users can search only PHP manual and developers can use their own.
So then why to integrate the HOWTO, I don't see the consistency.
Goba
