> Egon, please don't put up too many roadblocks here. Give people willing
> to contribute some latitude and see what they come up with. If it turns
> out to be a mess, we will deal with it later. Chances are it will be very
> useful and just needs a little bit of guidance in the right direction as
> opposed to a brick wall.
I see a great improvement for the manual in the part these guys
(Mark and Jan) would like to contribute. They realized, that the
configure options part of our documentation is neither complete
nor detailed. On the Hungarian mailing list we have many questions
regarding configure options, as the manual part for this thing
is not really deatiled. As stated in the preface, this manual
is focused to be a function reference. BUT we also need some
reference for configure options, as they get to be as many as
the functions themselfs :)
As Mark and Jan may or may not know, we discussed previously, that
a split of function XML files would be good in the maintainers
eyes, where people only need to translate small XML files to
have function descriptions translated... As this change will cause
many more diff mails on the phpdoc list, we also discussed breaking
the phpdoc list into language specific lists, such as (phpdoc-de,
phpdoc-hu and so on), where people only get the commit messages
from that specific language and can discuss that languages problems...
We also talked about breaking install.xml into several parts, as
it gets just messy to indicate parts with prepended "Server-"
title parts for servers for example.
This is what Egon talked about he would not like to see, and
he won't validate foreign languages, if this change will go
though.
Now, you decided to propose the break of configure.xml, and would
like to contribute the work :) We'll as I love all the break ideas
previously mentioned, I can understand why and what you would like
to do.
The structure of your new configurations section may strongly
resemble the structure of the categorized function reference, which
we also discussed in the past. As the function reference pages
now ordered alfabetically, people find functions very hard, even
with our new function index. In my eyes duplicating this structure
(which is currently nonexistent, and only written down in some
previous mails in the archives as alternatives) is not a good thing (TM).
IMHO in the new structure we can open a configuration options section
in all the parts, such as Database, Ecommerce and so on. This way,
people can find the information they search for one place. This also
means, that your work will fit perfectly in the future structure of
phpdoc as planned before.
So I am on the side of breaking config.xml into separate pieces, but
generally against creating a new tree structure for configuration
options, but to let it spread in the categorized parts, as the parts
structure will be the same as the config tree structure (at least
I hope).
I also had an idea of putting the "features" part to those tree
structures (eg. presistent database connections to the databases
part, image creation to the image functions part, etc).
This would address Egon's conserns about people hardly find the
things they are looking for, as if you are interested in database
specific things, you only need to look at the databases part in
the manual, where you find feature descriptions, like persistent
connections, configuration options helping you set up a database
extension, and functions you can use. Appendix and language
description parts are not that hard to navigate, and they are
only needed in rare cases, if you are a beginner interested
in language structures or an advanced user interested in a table
of aliases or so...
I also have a dream of conceptual indexes in the parts, where
you can find indexes of functions by usage. Eg. in the text
processing section (including string, ereg, preg functions for
example), we would have an index as such:
String replacing: str_replace(), preg_replace(), preg_replace_all(),
ereg_replace()...
.....
Well this need to be in a sophisticated format... :))
To close my letter, I know that this topic leads us far better
(or I made it to lead) than configure options. As I see your
proposal would be a really nice peace in the new structure,
but this thing cannot be integrated into the current structure
correctly. I cannot give any estimates on when this new
structure will be introduced, as it needs more discussion and
preparation work. But it is a nice vision :)
You may start this new configuration part in a separate
directory, and we can move the thing to the parts when this
structure will be ready and working. I think it is a dead
idea to put this thing in a separate CVS, as we have people
here who would contribute to this thing at least ocassionaly...
The best thing would be to carefully plan this new structure
and discuss it deeply ASAP, and make the changes people like
from the lists above, and the things missed in those lists...
This would help all contributors and readers. Look at
http://www.php.net/manual/en/ The function part was estamped
as unsuable before months. The 4.1.0 release introduced
many extensions, and this thing is getting worse and worse.
I have asked Hartmut if he needs any help in preparing for
this change, but I've got no reply. :(( Currently a "migration
to DocBook 4" project is under the hood, so this may put
this huge project on hold.
Goba
