This is the mail archive of the
docbook@lists.oasis-open.org
mailing list for the DocBook project.
RFE 514435: Nested reference markup
- From: Michael Smith <smith at xml-doc dot org>
- To: docbook at lists dot oasis-open dot org
- Date: Tue, 16 Jul 2002 06:53:20 -0500
- 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>