OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

docbook-tc message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

Subject: Re: <refgroup>

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


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

    <part id="funcref">

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

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


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.


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

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]