> 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
As I wrote before, I did (part of) the work for a book I wrote. So, there is something to start with. I started to compile a list of options which is from PHP 4.1.0. This is what I called the "skeleton". Around this skeleton, we would add infos and links where it is needed. It is for sure, that options like --disable-short-tags do not have a url or that much information. For all the others, an url as well as more information on how to compile or where to get information about compiling the ext should be in the manual. > regarding configure options, as the manual part for this thing > is not really deatiled. As stated in the preface, this manual "not really detailed" is nice ;) > 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 :) Hehe. > 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 I know that and I think Jan knows it too. > eyes, where people only need to translate small XML files to > have function descriptions translated... As this change will cause I won't care. But IMHO it is easier for beginners to translate small files instead of large ones. > 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... IMHO this is not so good. > 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. That's what I said. > 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 discision to break it is of very simple and logical nature. The comfigure options in my book are about 30 pages. If you document them as I'd like to, you'll get probably 50 pages. That would be _50_ book pages on one HTML-page. This is way to much for one page. That's why I thought of spliting the whole thing into, say 10 parts with 5 pages each. It would be easiert to translate, easier to read and probably easier to find for someone who wants to install PHP. > 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. ACK. I myself will find help on IRC very quick. But others will "spam" mailinglists aksing things which should be in the manual. PHP is very good documented, but the manual lacks of a real help on the installation. > 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). This phpdoc/configure/ thing would only be temporaily, until the work is advanced to a point, on which we can add it to the "real" manual. See my "skeleton" thought above. > 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. This would be great! > String replacing: str_replace(), preg_replace(), preg_replace_all(), > ereg_replace()... > Well this need to be in a sophisticated format... :)) Yes, but it would be easier for the people searching for help. Work from the view of a what we Germans call "DAU", someone like a newbie. Don't work from the view of a pro. > 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, piece as well als hopefully peace ;) > 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 :) Thanx. IMHO it could be intigrated in install.configure.php, but that's just what I think. > 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... So, you mean something like phpdoc/en/configure ? > 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. Yes. > 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. Hartmut should be on holiday. Mark
