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

DocBook RFEs

There are 17 RFEs in this list.


Issue 70:Add generic linking ability to all elements.
Requested by:Murray MaloneySubmitted:Feb 1997Resolved: 
Type:enhancementPriority:mediumStatus: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:nwalshSubmitted:07 Mar 1999 06:31Resolved:4.0
Type:enhancementPriority:lowStatus: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:nwalshSubmitted:08 Mar 1999 07:06Resolved:5.0
Type:enhancementPriority:mediumStatus: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:nwalshSubmitted:08 Mar 1999 07:14Resolved:4.0
Type:enhancementPriority:mediumStatus: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:nwalshSubmitted:18 Mar 1999 13:14Resolved: 
Type:enhancementPriority:mediumStatus: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:nwalshSubmitted:18 Mar 1999 13:26Resolved: 
Type:enhancementPriority:mediumStatus: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:nwalshSubmitted:18 Mar 1999 18:17Resolved:5.0
Type:bugPriority:mediumStatus: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:nwalshSubmitted:29 Mar 1999 18:24Resolved:3.2
Type:enhancementPriority:lowStatus: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:nwalshSubmitted:15 Jun 1999 20:23Resolved:3.2
Type:enhancementPriority:mediumStatus: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:terrySubmitted:02 Jul 1999 19:41Resolved: 
Type:enhancementPriority:lowStatus: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:51Resolved:3.2
Type:enhancementPriority:mediumStatus: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:nwalshSubmitted:16 Jul 1999 07:00Resolved:3.2
Type:bugPriority:mediumStatus: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.orgSubmitted:19 Jul 1999 08:53Resolved: 
Type:enhancementPriority:mediumStatus: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.orgSubmitted:19 Jul 1999 08:44Resolved: 
Type:bugPriority:mediumStatus: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:terrySubmitted:11 Oct 1999 16:45Resolved: 
Type:enhancementPriority:lowStatus: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.comSubmitted:12 Nov 1999 06:36Resolved:4.0
Type:enhancementPriority:mediumStatus: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.orgSubmitted:14 Nov 1999 09:52Resolved: 
Type:enhancementPriority:mediumStatus: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