|Subject:||DOCBOOK: RFE 514435: Nested reference markup|
|From:||Michael Smith (smi...@xml-doc.org)|
|Date:||Jul 16, 2002 4:53:27 am|
The DocBook TC is currently considering an open DocBook "request for enhancement", RFE 514435 -- proposing a new Reflist element -- and would appreciate any comments from the DocBook user community regarding the proposed change.
The change basically comes down to:
1. Creating a Reflist with the following content model:
reflist ::= (refentry+)
2. Changing the Refentry content model so that it allows Reflist as a child, which would mean that Refentry would be then be allowed as a descendant of Refentry (see that example instance below).
After discussing this RFE during last month's meeting, the consensus on the TC seemed to be that the main advantage of this proposed markup model is that it would allow a separate Refpurpose to be associated with each sub-section of the Refentry.
The RFE gives the example of documenting an object and class members of that object. The proposed markup model would allow a Refpurpose to be associated with each of those class members.
(The current markup model allows nested sections and Methodsynopsis elements within the Refentry, but doesn't allow a separate Refpurpose for each of those nested sections.)
* The TC would like to know whether anyone else might have use for this kind of nested reference markup.
* The RFE also suggests that Reflist be allowed within other block-level elements, similar to the way in which Glosslist is currently allowed within most block-level element. This would permit Refentries to sort of float around in content -- for example, in the kinds of places where bulleted and numbered lists can show up.
Do others see advantages in allowing reference markup in that context?
 Example instance of proposed Reflist markup:
<refentry> <refnamediv> <refname>FooObject</refname> <refpurpose>An example object.</refpurpose> </refnamediv> <refsect1> <title>Details</title> <para>This class...</para> </refsect1> <refsect1> <title>Members</title> <reflist> <refentry> <refnamediv> <refname>FooMethod1 ()</refname> <refpurpose>An example method.</refpurpose> </refnamediv> ... </refentry> <refentry> <refnamediv> <refname>FooMethod2 (arg)</refname> <refpurpose>An example method.</refpurpose> </refnamediv>