6 messages in org.oasis-open.lists.docbook-tcRe: [docbook-tc] DocBook Technical Co...| From | Sent On | Attachments |
|---|---|---|
| Norman Walsh | Sep 16, 2002 9:24 am | |
| Bob Stayton | Sep 16, 2002 9:36 am | |
| Norman Walsh | Sep 17, 2002 12:14 pm | |
| Paul Grosso | Sep 17, 2002 1:26 pm | |
| Michael Smith | Oct 15, 2002 6:21 am | |
| Bob Stayton | Oct 15, 2002 10:49 am |
| Subject: | Re: [docbook-tc] DocBook Technical Committee Meeting Minutes: 17 Sep2002 | |
|---|---|---|
| From: | Bob Stayton (bo...@caldera.com) | |
| Date: | Oct 15, 2002 10:49:11 am | |
| List: | org.oasis-open.lists.docbook-tc | |
On Tue, Oct 15, 2002 at 10:14:07PM +0900, Michael Smith wrote:
Norman Walsh <nd...@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: bo...@caldera.com