[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]
Subject: DOCBOOK: RFE 514435: Nested reference markup
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>
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]
Powered by eList eXpress LLC