The DocBook TC is currently considering an open DocBook "request for enhancement", RFE 514435[1] -- 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[2]).

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

Questions:

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

That's it.

--Mike

Notes

-----

[1] https://sourceforge.net/tracker/index.php?func=detail&aid=514435&group_id=21935&atid=384107

[2] 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>