Re: RFC: Re-organizing function reference part

From: Date: Sun, 26 Aug 2001 17:31:23 +0000
Subject: Re: RFC: Re-organizing function reference part
References: 1  Groups: php.doc 
Request: Send a blank email to phpdoc+get-969337285@lists.php.net to get a copy of this message
> This topic has popped up a few times before on the list, and I think I've > seen even bug report(s?) claiming that the current function reference > part makes it hard to find information, because it has grown so big. But I > don't remember that we would haver ever deciced either to do it or not do > it... I have discussed this with Hartmut a bit and your solution seems working. > The main problem is that in DocBook, we can't splice an additional level > between a <part> and <reference>. What I could come up with by reading > DocBook reference is the following: > > <part> -- Function reference > <chapter> -- General category of functions, > ie. like "Database functions" > <section> -- replaces reference, not allowed here, > ie. like "MySQL functions" > <abstract> -- replaces partintro, not allowed here > <refentry> -- the original refentry text It would be nice, if someone could make a first draft about the names of new chapters and which sections could be within sections. > Can be done without any hurry before the change: > - Modify the *.dsl files so that TOC is created the right way. Some small > fixing with HTML version, a bit more with printable versions. I will > volunteer, unless Hartmut explicitly requests to have the honour... I could only guess, but I think, Hartmut is at The Linuxbierwanderung (Linux Beer Hike) and this hike ends on 09/01/2001. > - New subtitles must be agreed on and added to each language-defs.ent. > - I guess that some scripts relating to the online HTML-manual should > be fixed. Not sure though. > - Probably more... > > Can be done only after the re-organization, and with great hurry, because > the change will temporarily break a lot of things: > - Change the tags, and within <abstract>, add <para> tags around <note>s > and <warning>s and change <simpara>s to <para>s, because the DTD > requires this. > - Probably more... > > So, if this will ever happen, the change should be planned carefully and > slowly, make sure that we've got everything ready, and all the translators > should be aware of what's going on and can make a few hours available to > fix broken things within a day or two after the change. Which should > happen on a day commonly agreed upon, preferable at least a week before. > > Comments? I am for a change. -Egon

« previous php.doc (#969337285) next »