1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
|
Well, I spent some time with investigating what structures can we use to
achive the groupings we already discussed. The most important priority
was that no change should be required to any other file but manual.xml.in,
or a very small number of changes should be required.
So we needed a structural element that we can use to group up <reference>
parts and these structural elements should fit into a <part> (which is the
main division in our manual).
Here is the content model of <part>:
part ::=
(beginpage?,partinfo?,
(title,subtitle?,titleabbrev?),
partintro?,
(appendix|chapter|toc|lot|index|glossary|bibliography|article|
preface|refentry|reference)+)
Now we put <reference> tags straight into the <part>, so this is OK. But
there is no structural element here we can use to group up references, as
<chapter> (which would be the only sensible grouping element here) cannot
include <reference>...
What can contain a <reference>? The possible parents of reference are
<book> and <part>. That's all.
So as the current DocBook TDG shows, we have no way to group references
in DocBook 4.1.2.
That lead me to think about extending or at least modifying Docbook for
us to be able to group references. For this reason, I have introduced a
"new DTD" in phpdoc/dtds named phpbook.dtd. This needs to have a non-docbook
DTD, as it's not DocBook (see the TDG for more info). What I needed was
to add <section> to the content model of <part>, and add <reference> as
a possible child of <section>. This is all done in phpbook.dtd.
The manual.xml.in file now in phpdoc/RFC uses this DTD to be able to
group reference sections.
It works quite well, it generates all the HTML pages. The only problem
left is that for some reason the <reference> titles are not printed in
<section>s. This is a DSSSL style sheet issue, so it should be adjusted...
There may be other issued using XSLT sheets (not tested).
The question is if you agree on using this phpbook DTD "instead of" DocBook,
as AFAIK this is the only DTD enables us to correctly group references.
There were some discussions on the phpdoc list about creating a somewhat
customized DocBook DTD (because of see also lists), and it ended up in
the conclusion that it is not needed, as we can use <note role="seealso">
instead (which maybe was not the best solution, but at least it works with
the current DocBook DTD).
Now as it seems, we have no other way to group <reference>s, than to
introduce a simple customization of DocBook. And if we go on this
way, maybe some other simplifications can be introduced in the future,
like <iniopt>extension_dir</iniopt> linking to the options documentation,
etc.
The php-gtk-doc module also uses a modified version of DocBook, and the
guys there have no problem with it, so I don't think so we will face
problems.
See: http://gtk.php.net/manual/en/about.php
and http://cvs.php.net/co.php/php-gtk-doc/dbxml/phpgtkdoc.dtd
Goba@php.net
A different approach:
What we really use are <refentry> blocks for functions, <reference>
is just a container for that (plus it introduces a different numbering
style in the table of contents).
<refentry> may not only occur wrapped up in <reference> but also in
e.g. <chapter> and <section>. So a structure like this is completely
legal with the current DTD:
...
<part><title>Function Reference</title>
<chapter><title>Standard Functions</title>
...
</chapter>
<chapter><title>Database Functions</title>
<section><title>DB xyz Functions</title>
<para>introduction</para>
<refentry id="function.xyz-1">
...
</refentry>
<refentry id="function.xyz-2">
...
</refentry>
...
</section>
</chapter>
...
</part>
...
One problem here is that any material put before the <refentry>s
in a <section> has to be pure content like <para>. Additional
sub-<section>s are only allowed following the <refentry>s
within a <section>, not ahead of it
The DTD model for <section> is
<!ELEMENT section (sectioninfo?,
(%sect.title.content;),
(%nav.class;)*,
(((%divcomponent.mix;)+,
((%refentry.class;)*|section*))
| (%refentry.class;)+|section+),
(%nav.class;)*)>
changing it to something like
<!ELEMENT section (sectioninfo?,
(%sect.title.content;),
(%nav.class;)*,
(((%divcomponent.mix;)+,
((%refentry.class;) | section)*)
| ((%refentry.class;), section)+),
(%nav.class;)*)>
*should* help and the stylesheets *should not* care ...
... but i have to confess that i didn't test that stuff yet ... :/
hartmut@php.net
|
