[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]
Subject: DOCBOOK: FYI: DocBook RFEs for OASIS TC Meeting
In preparation for the OASIS DocBook TC meetings to be held next week in conjunction with XML'99, I've prepared the following list of open/pending RFEs (requests for enhancement). The complete RFE database is available online at http://docbook.org/rfe/Title: DocBook RFEs
There are 17 RFEs in this list.
Issue 70: | Add generic linking ability to all elements. | ||||
---|---|---|---|---|---|
Requested by: | Murray Maloney | Submitted: | Feb 1997 | Resolved: | |
Type: | enhancement | Priority: | medium | Status: | pending |
Rationale
Leave open pending XLink. We don't want to add anything else that might require cleanup in the future.
Description
Only link elements can actually be links, and it is not possible to use link elements everywhere you might want to construct a link. Add a generic linking ability to all elements, in most cases there will be no processing expectations: a relationship among the linked parts will simply be asserted. (Generic uniform linking protocol = GULP?). Certainly for technical inlines, this ability would be useful, and is even weakly allowed already in the form of MoreInfo. Nov 98: we want to wait for XLink before doing anything this drastic.
Issue 93: | Add markup for forms | ||||
---|---|---|---|---|---|
Requested by: | nwalsh | Submitted: | 07 Mar 1999 06:31 | Resolved: | 4.0 |
Type: | enhancement | Priority: | low | Status: | open |
Rationale
Description
Several people have expressed an interest in marking up forms in DocBook (for later web presentation). It could be handy, but perhaps we need to wait until someone sends in a complete proposal. Action: Review IETM form spec
Issue 95: | Extend FuncSynopsis for modern programming languages | ||||
---|---|---|---|---|---|
Requested by: | nwalsh | Submitted: | 08 Mar 1999 07:06 | Resolved: | 5.0 |
Type: | enhancement | Priority: | medium | Status: | pending |
Rationale
This is work that will be done, but there is some background that needs to be read, and we need a complete proposal.
Description
The current FuncSynopsis element is insufficiently robust to handle markup for modern programming languages such as Java, IDL, Python, etc. This RFE concerns new structures needed within FuncSynopsis to represent these languages. See also RFE 23, Store parameter descriptions within FuncSynopsis, and RFE 96, Extend inlines for modern programming languages. These languages have features that there is no appropriate markup to describe. These include object oriented features (methods, members, interfaces, inheritance, encapsulation, etc.), exceptions, and perhaps others. (Users with documentation needs that are not currently met are encouraged to submit their own list.) Some of these features need new inlines as well. Action items: - Review the DOM IDL model for consideration - Examine the DOM extensions to the XML spec DTD
Issue 96: | Extend inlines for modern programming languages | ||||
---|---|---|---|---|---|
Requested by: | nwalsh | Submitted: | 08 Mar 1999 07:14 | Resolved: | 4.0 |
Type: | enhancement | Priority: | medium | Status: | pending |
Rationale
This is work that will be done, but we need a complete proposal.
Description
The current collection of inline elements (including StructName, StructField, Class, Type), is insufficient to markup modern programming languages such as Java, IDL, Python, etc. This RFE concerns new inlines needed describe these languages. (See also RFE 95, Extend FuncSynopsis for modern programming languages). These languages have features that there is no appropriate markup to describe. These include object oriented features (methods, members, interfaces, inheritance, encapsulation, etc.), exceptions, and perhaps others. (Users with documentation needs that are not currently met are encouraged to submit their own list.)
Issue 98: | Reorganize parameter entities | ||||
---|---|---|---|---|---|
Requested by: | nwalsh | Submitted: | 18 Mar 1999 13:14 | Resolved: | |
Type: | enhancement | Priority: | medium | Status: | open |
Rationale
Description
We've started to determine the content model of new elements by looking for some existing parameter entity that "looks about right" and cloning it. This suggests that we don't have a good, modular parameterization. We might get significant benefit from reconsidering the whole scheme. A significant goal of the effort would be to build a better model that made it clear where extensions should be plugged in. As DocBook is more widely adopted, this is going to become crucial.
Issue 99: | Rework MsgSet | ||||
---|---|---|---|---|---|
Requested by: | nwalsh | Submitted: | 18 Mar 1999 13:26 | Resolved: | |
Type: | enhancement | Priority: | medium | Status: | open |
Rationale
Description
Should we reconsider MsgSet? In its present form, it's very difficult to use for the simple cases. Could we make enough of the elements optional to fix this deficiency?
Issue 100: | Keep 'cooked' and 'raw' bibliographic metadata separated | ||||
---|---|---|---|---|---|
Requested by: | nwalsh | Submitted: | 18 Mar 1999 18:17 | Resolved: | 5.0 |
Type: | bug | Priority: | medium | Status: | open |
Rationale
Description
It is currently possible to mix "raw" and "cooked" bibliographic metadata. The content models should be adjusted so that this is no longer possible. 2 April 1999: To: docbook-eb@oasis-open.org Subject: Bibliographic Elements issues Cc: tallen@bolt.sonic.net Status: RO >From some time back: | Terry and I had a brief discussion about this recently. We need to | hash it out. | | 1. Cooked and raw entries should be kept apart to maintain reasonable | processing expectations. I think therefore that BiblioSet should | _not_ be in %bibliocomponent.mix;. (Having it there allows BiblioSet | in BiblioMSet.) (%bibliocomponent.mix; is part of the content model of BiblioEntry, and also of BiblioSet and BiblioMSet.) I agree. We should remove BiblioSet from %bibliocomponent.mix, and add it directly to the content model of BiblioEntry; compare the treatment of BiblioMSet in BiblioMixed. If there's no objection I'll write up an RFE. | 2. Should BibliMisc really contain %para.char.mix? %para.char.mix; is broader than is needed, but I think this is a symptom of our need to remodularize, so I'd leave it alone for now. | 3. Do we want *Info elements to contain contain complete bibliographic | entries for the works they're in? In that case should we put them | in their biblio* wrappers? (er, yes, I think, says norm.) (This is a separate topic.) At one time we'd thought that we wanted to be able to put all the info for a bibliographic entry in an *Info element, and it occurred to me that then we should use bibliographic elements to do so. Alternately, we can just allow *Info to contain information that can be *transformed* into a bibliographic entry. I can live with either - considering that use of the bibliographic elements isn't common, we might want to think on this some before reaching any conclusion. regards, Terry
Issue 102: | There are name case inconsistencies in the DocBook DTD | ||||
---|---|---|---|---|---|
Requested by: | nwalsh | Submitted: | 29 Mar 1999 18:24 | Resolved: | 3.2 |
Type: | enhancement | Priority: | low | Status: | open |
Rationale
Description
If you attempt to parse DocBook with NAMECASE GENERAL NO, it fails because of namecase inconsistencies. To the extent possible, it would be nice to fix this.
Issue 103: | Extend Revision to allow longer descriptions | ||||
---|---|---|---|---|---|
Requested by: | nwalsh | Submitted: | 15 Jun 1999 20:23 | Resolved: | 3.2 |
Type: | enhancement | Priority: | medium | Status: | open |
Rationale
Description
If you want to describe a number of changes in a revision, there's no good way to do it. Perhaps <!E Revision (RevNumber, Date, AuthorInitials*, (RevRemark|RevDescription)> Where RevDescription allows block-level things?
Issue 104: | add specification class attribute value for Article | ||||
---|---|---|---|---|---|
Requested by: | terry | Submitted: | 02 Jul 1999 19:41 | Resolved: | |
Type: | enhancement | Priority: | low | Status: | open |
Rationale
Description
Article can be used for specifications, such as the OASIS Regrep technical spec. There is no value appropriate for this for the Class attribute on Article, and we've said we'll extend the list of values as needed. Terry asked for suggestions on the list, Norm responded with "specification", and it seems appropriate. "specification" should presumably cover a range of documents; there is some uncertainty as to the limits of that range. From Norm's reply to Terry of 17 June 99: ===== | However, to characterize it as a specification requires use of the | Class attribute, the allowable values of which are | | Class (JournalArticle | |ProductSheet | |WhitePaper | |TechReport | |FAQ) #IMPLIED | | I'm not quite happy using TechReport. But I'm not quite sure | what to suggest (we agreed to extend the list as needed, but | what should the string be?). The IETF does drafts and RFCs, | the W3C does notes and recommendations, OASIS does tecnical | resolutions and technical memoranda. | | What word captures all of these? "Specification"? I like 'specification'. But I'd call W3C notes and OASIS technical memoranda "whitepapers". =====
Issue 105: | Add notation for PNG graphics | ||||
---|---|---|---|---|---|
Requested by: | Frederik Fouvry (fouvry@essex.ac.uk) | Submitted: | 06 Jul 1999 15:51 | Resolved: | 3.2 |
Type: | enhancement | Priority: | medium | Status: | open |
Rationale
Description
Frederik requests the addition of PNG graphics in order to support converting the KDE documentation to DocBook. Additional comments by dcm@redhat.com, 27 Sep 1999: The Unisys Corporation currently owns a patent on the compression often used in the creation of GIFs. This patent allows Unisys to collect royalties from anyone who uses this compression. The majotriy of image manipulation programs currently create GIFs with the LZW compression making it hard to stay away from the use of LZW compression. The PNG format was created with this issu in mind and provides the user with a file format tha rivals the quality of GIFs whil keeping software patents out of the way. Since DocBook is an open software project the inclusion of PNGs to the notations would help all who use DocBook remain "patent free". The GNOME project will be adding support for PNGs in a custom DTD until DocBook adds PNG support.
Issue 106: | *.content PEs in wrong place in dbpool.mod | ||||
---|---|---|---|---|---|
Requested by: | nwalsh | Submitted: | 16 Jul 1999 07:00 | Resolved: | 3.2 |
Type: | bug | Priority: | medium | Status: | open |
Rationale
Description
/ Murray Altheim <altheim@eng.sun.com> was heard to say: | Why is it that in dbpool.mod there are several PEs for content models | (particularly %programlisting.content; and %screen.content;) that are not | actually located with the rest of the ProgramListing and Screen modules? | | The reason I ask is that because both of these include %para.char.mix; I | cannot redeclare them (to eliminate 'CO') because the DTD has yet to | declare %para.char.mix; and for me to do that I'd have to redeclare | almost the entirety of the 'Characer-level mixtures' section of dbpool. | | Then again, the more I do this stuff the more I realize the futility of | thinking any wholescale modifications can be done remote to dbpool. You | just end up diving in and modifying a copy of dbpool itself.
Issue 107: | <qandaentry> disallows multiple phrasings of a question and answer | ||||
---|---|---|---|---|---|
Requested by: | nik@freebsd.org | Submitted: | 19 Jul 1999 08:53 | Resolved: | |
Type: | enhancement | Priority: | medium | Status: | open |
Rationale
Description
The new QAndASet (and related) elements are very useful for marking up FAQs. However, they disallow the situation where you might want to present multiple phrasings of a question (together with one answer) and where you might want to present multiple answers. For example, consider http://www.freebsd.org/tutorials/docproj-primer/translations.html and question 10 in particular. With the new elements, I would have expected the 'natural' way to mark up this question to be; <qandaentry> <question> <para>I'm the only person working on translating to this language, how do I submit my translation?</para> </question> <question> <para>We're a translation team, and want to submit documentation that our members have translated. How do we do that?</para> </question> <answer> <para>...</para> </answer> </qandaentry> But you can't, and you need to roll the two questions in to one Question element. It is possible to recast the text of the question, but that requires altering the text, which may not be desirable. Similarly, you can not do something like this; <qandaentry> <question> <para>I need to frob my disks. How do I do that?</para> </question> <answer os="2.2"> <para>First unmount the filesystem, then run &man.frob.1;.</para> </answer> <answer os="3.0"> <para>You don't need to. Your disks are automatically frobbed for you, during system idle time.</para> </answer> </qandaentry> Again, that example could be recast -- you could have both <para>s inside the <answer>, and have the 'os' attribute apply to the <para>s instead. But that approach 'feels' wrong -- there are really two distinct answers, and they should be treated as such.
Issue 108: | Content model disallows <note> in <answer> | ||||
---|---|---|---|---|---|
Requested by: | nik@freebsd.org | Submitted: | 19 Jul 1999 08:44 | Resolved: | |
Type: | bug | Priority: | medium | Status: | open |
Rationale
Description
The content model (DocBook 3.1) for <answer> disallows admonitions (<note>, <tip>, <important>, and so on). This can be fixed relatively easily by adding "|%admon.class;" to qandaset.mix (or local.qandaset.mix for customisations). Thanks, N
Issue 109: | Add FPI to content of dbgenent.mod | ||||
---|---|---|---|---|---|
Requested by: | terry | Submitted: | 11 Oct 1999 16:45 | Resolved: | |
Type: | enhancement | Priority: | low | Status: | open |
Rationale
Description
dbgenent.mod has an FPI - it occurs in docbook.dtd - but unlike other modules the FPI does not occur within the text of the module itself; it would be convenient and consistent were it to.
Issue 110: | Allow revhistory in QandASet | ||||
---|---|---|---|---|---|
Requested by: | jwilleke@ix.netcom.com | Submitted: | 12 Nov 1999 06:36 | Resolved: | 4.0 |
Type: | enhancement | Priority: | medium | Status: | open |
Rationale
Description
I'm converting a departmental FAQ list from HTML to DocBook SGML. The existing list follows the convention of marking each entry with two dates: created and last modified. This helps a user determine the likelihood that the answer is applicable. A month-old Unix tip will probably be useful. A year-old, application-specific workaround may not be as useful. This is an ideal application for the <revhistory> element. Unfortunately, there isn't a good place to put it. I've taken to creating an empty <para> at the end of each <qandaentry>, but that's a kludge. I'd like to put it directly in <qandaentry>.
Issue 111: | Support for the Euro symbol | ||||
---|---|---|---|---|---|
Requested by: | randolph@efn.org | Submitted: | 14 Nov 1999 09:52 | Resolved: | |
Type: | enhancement | Priority: | medium | Status: | open |
Rationale
Description
Please add the Euro symbol to DocBook
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]
Powered by eList eXpress LLC