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


Help: OASIS Mailing Lists Help | MarkMail Help

docbook message

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

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


* 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

That's it.



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

[2] Example instance of proposed Reflist markup:

        <refpurpose>An example object.</refpurpose>
        <para>This class...</para>
              <refname>FooMethod1 ()</refname>
              <refpurpose>An example method.</refpurpose>
              <refname>FooMethod2 (arg)</refname>
              <refpurpose>An example method.</refpurpose>

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

Powered by eList eXpress LLC