RFC: Re-organizing function reference part

From: Date: Sun, 26 Aug 2001 16:15:03 +0000
Subject: RFC: Re-organizing function reference part
Groups: php.doc 
Request: Send a blank email to phpdoc+get-969337284@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... 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 I did some testing, and this seems to work quite well, although there are of course some problems to solve first. Things that must be modified, *if* we come to an agreement that we reorganize the function reference: 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... - 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? -- Jouni

« previous php.doc (#969337284) next »