Re: [docbook-tc] Re: <refgroup>

[Norman Walsh <ndw@nwalsh.com>]

/ Michael Smith <smith@xml-doc.org> was heard to say:
[...]
| Based on your example (below), I'd say that one way to mark up what's in
| your example using valid DocBook is this:
|
|   <book>
|     <part id="funcref">
|       <title>FunctionReference</title>
|
|       <chapter id="refs.basic">
|         <title>Basic PHP Extensions</title>
|
|         <section id="refs.basic.vartype">
|           <title>Variable and Type Related Extensions</title>
|
|           <section id="reference.array.reference">
|             <title>...</title>
|             <refentry>
|               ...
|             </refentry>
|           </section>
|         </section>
|       </chapter>
|     </part>
|   </book>

That looks reasonable.

| That uses nested Section elements in place of the custom Refgroup element
|
| Based on the change shown in the php.net CVS logs, it looks like the
| php-doc folks had made a previous customization to the DTD to
|
|   - allow Section as a child of Part
|   - allow Reference as a child of Section

Both of those customizations strike me as pretty dramatic. Sections
and Chapters aren't supposed to be peers (but they will be if they're
both allowed in Part). Whether it makes sense to have a Reference in a
Section is less clear. But it's definitely a pretty big change.

| But they have now added Refgroup and replaced the Section/Reference
| instances in the source for the PHP manual with Refgroup/Reference.
|
| It seems like the main rationale behind both the original changes and
| the new one is to be able to use the Reference element at a sectioning
| level that official DocBook doesn't currently allow.
|
| But the same effect can be achieved by not using Reference at all and
| instead using nested Section elements (Part/Chapter/Section/Section/Refentry).
|
| There's no "requirement" in DocBook to use Reference to group multiple
| Refentry elements. The Section element can be used for the same thing.

What Mike said.

| So one suggestion is to use the Part/Chapter/Section/Section/Refentry
| structure. But if you or others working on the PHP docs think that won't
| work for your needs, please submit an RFE at the DocBook project site at
| Sourceforge:
|
|   http://sourceforge.net/tracker/?func=add&group_id=21935&atid=384107
|
| I guess you could just title it "Add Refgroup for grouping Reference
| elements with Parts" or something like that. But you should also provide
| a rationale explaining why the Part/Chapter/Section/Section/Refentry
| structure doesn't meet your needs.

Indeed. What are you trying to accomplish by putting a wrapper around
them?

                                        Be seeing you,
                                          norm

-- 
Norman Walsh <ndw@nwalsh.com>      | A new scientific truth does not
http://www.oasis-open.org/docbook/ | triumph by convincing its
Chair, DocBook Technical Committee | opponents and making them see the
                                   | light, but rather because its
                                   | opponents eventually die, and a
                                   | new generation grows up that is
                                   | familiar with it (Planck 1949)

PGP signature