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