[PHP-DOC] users manual / developers manual

[Gabor Hojtsy]

Hi!

I am opening this up as a new thread, so we can start in a clean situation to discuss only this problem.

What's wrong?

The current manual contains developers information (Zend
engine internals, streams development), which is not for
users.

Some users may get confused with them (especially with streams
now introduced in PHP 4.3.0). Manual searches may return
results in those pages, and users can unintentionally get into
it...

The solution

Have a separate users manual and developers manual.

Technical side

Most of the current manual stays in the users manual. The dev.
part goes into the developers manual. It is discussed that the
dev manual should not be translated, as it would make crap appear
in the CVS of PHP4/5, as some outdated docs may be used to develop
an extension (this is an issue currently too with ZE1 docs).

Also someone who develops and extension needs to know English, as
all the current code, comments in them, etc. are in English, and
someone who works with PHP development, always needs to dig up some
details in the code, as there will always be undocumented parts.

We also would not like to split the efforrts of translation groups,
they should focus on the users documentation only. There is enough
to translate there.

Should the dev manual have it's own CVS repository with it's own
build system? Probably not for the first time. I think it may go
into phpdoc/devmanual/* and if it grows to something reasonable,
then it should go alone.

This also means that the build system needs to be extended to
choose what manual you would like to build (in the configure step).

Here are my thoughts. It is important to make up an RFC of this, as
we discussed, so the results will stay at some place, and there would
be no need to restart this again, and again...

Goba


--
PHP Documentation Mailing List (http://www.php.net/)
To unsubscribe, visit: http://www.php.net/unsub.php