Re: <refgroup>

[Michael Smith <smith@xml-doc.org>]

Hi Nuno,

You wrote:

> Hello,
> 
> I don't really know if this can be already done with latest docbook, because
> I'm not a docbook expert, but I would like you to help me :)
> 
> I would like to use nested refentrys or something like that. The PHP 
> documentation is thinking in creating a customised docbook sheet to include 
> a special <refgroup>.

Actually, it looks like they have already added <refgroup> -

  http://www.manucorp.com/archives/phpdoc/200409/msg00084.php
  http://www.manucorp.com/archives/phpdoc/200409/msg00082.php

> Is there any way to make this in a "legal" docbook way?

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 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

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.

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.

  --Mike

> <book>
> ......
> 
> <part id="funcref">
>  <title>&FunctionReference;</title>
> 
>  <refgroup id="refs.basic">
>   <title>Basic PHP Extensions</title>
> 
>   <refgroup id="refs.basic.vartype">
>    <title>Variable and Type Related Extensions</title>
>    &reference.array.reference;
>     ...
>   </refgroup>
> 
>   <refgroup id="refs.basic.php">
>    <title>Affecting PHP's Behaviour</title>
>    &reference.overload.reference;
>    &reference.errorfunc.reference;
>   ....
>   </refgroup>
> 
> .........
>  </refgroup>
> 
>  <refgroup id="refs.database">
>   <title>Database Extensions</title>
> 
>   <refgroup id="refs.database.abstract">
>    <title>Abstraction Layers</title>
>    &reference.dba.reference;
>    &reference.dbx.reference;
>    &reference.uodbc.reference;
>   </refgroup>
> 
>   <refgroup id="refs.database.vendors">
>    <title>Vendor Specific Database Extensions</title>
>     ....
>    &reference.sesam.reference;
>    &reference.sqlite.reference;
>    &reference.sybase.reference;
>   </refgroup>
>  </refgroup>
> .......
> </part>
> </book>
> 
> 
> Thanks,
> Nuno Lopes

PGP signature