Re: [docbook-tc] DocBook Technical Committee Meeting Minutes: 17 Sep2002

[Bob Stayton <bobs@caldera.com>]

On Tue, Oct 15, 2002 at 10:14:07PM +0900, Michael Smith wrote:
> Norman Walsh <ndw@nwalsh.com> writes:
> 
> > |    The following RFEs have been moved to the bottom of this agenda in order
> > |    to make sure that all RFEs get fairly discussed.
> > | 
> > |     514435 Allow reference within refentry
> >  
> >       Mike: can you summarize where this issue stands?
> 
> I *think* the status on this is that we might be able to resolve it by
> allowing refpurpose and/or refclass as children of refsect* elements.
> 
> The last action item I had related to this was to ask the submittor if
> the main thing he would gain from using this markup model (instead of
> just using nested sections and methodsynopsis elements) is an ability to
> associate a Refpurpose with each of his class members, and whether he
> could describe any other advantages.
> 
> He wrote back to say,
> 
>   Adding a refpurpose and refclass is the main benefit.  In applications
>   that generate quickref-style reference ToCs, this is significant.
> 
> He provides an example in a dialog he added to the RFE:
> 
>   https://sourceforge.net/tracker/index.php?func=detail&aid=514435&group_id=21935&atid=384107
> 
> So, I think the consensus when we discussed it was, if the goal is to be
> able to associate a Refpurpose with individual class members, there is a
> simpler way to implement that than creating nested refentrys and adding a
> new floating "reflist" element as he suggested.
> 
> I guess that simpler might be to just allow refpurpose and/or refclass
> as children of refsect* elements.

I have an interest in this issue since we have many
man pages that contain more than one 'entry'.  Our
process was to define a primary 'Name - description'
and then add any number of secondary names with descriptions.
The primary and secondary name+description lines are
extracted into the traditional man 'whatis' database
for lookup by apropos on a Unix/Linux system.
The details in the secondary descriptions are very useful
for finding a specific function or command variation.

We had a hard time expressing this in DocBook refentry
because only one refnamediv is permitted.  That was
sufficient for the main entry, but there was no place
to put the secondary names with descriptions.

The refnamediv element seems to be what is needed here, since
it is a container for a refname and refpurpose.
If we added refnamediv to %refcomponent.mix; then users
could include their extra name and purpose text.
Since &synop.class; is already included in that mix,
one could provide a synopsis for each entry too.
-- 

Bob Stayton                                 400 Encinal Street
Publications Architect                      Santa Cruz, CA  95060
Technical Publications                      voice: (831) 427-7796
Caldera International, Inc.                 fax:   (831) 429-1887
                                            email: bobs@caldera.com