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
