Historical DocBook RFEs

There are 146 RFEs in this list.

Issue 1: Fix header comments in DTD
Requested by: terry Submitted: 13 Nov 1998 09:17 Resolved: 3.1
Type: enhancement Priority: medium Status: closed

Rationale

The comments are no longer accurate.

Description

The header comments in the DTD which point directly to Terry and Eve 
as the maintainers and describe Davenport need to be fixed.

Issue 2: Add optional title to MsgSet
Requested by: norm Submitted: 13 Nov 1998 15:58 Resolved: 3.1
Type: bug Priority: medium Status: closed

Rationale

It's reasonable

Description

Add optional title to msgset

Issue 3: Generalization of alt element
Requested by: terry Submitted: 6/11/97 Resolved:  
Type: enhancement Priority: medium Status: closed

Rationale

Dup of/superseded by RFE#77

There's no good solution to the current graphic/inlinegraphic/alt situation;
instead a new model will be introduced in 3.1 and the old model phased out
in 5.0

Description

6/11/97 Cambridge:

Alt element is already on Equation; for new Figure, Informalfigure
we want it too.  For inline Graphics we'll rely on alt att on
graphic.

11/13/98 Chicago:

After much discussion, we're going to replace graphic/inlinegraphic
with GraphicObject, VideoObject, and AudioObject.

Issue 4: alt for inlingraphic
Requested by: terry Submitted: 6/11/97 Resolved:  
Type: enhancement Priority: medium Status: closed

Rationale

Dup of #3.

Description

6/11/97 Cambridge

Alt for graphic can be an element within container to allow
markup in Alt, but also need alt att on graphic itself for
the case of multiple graphics in figure/informalfigure and
for inline Graphics.  Harvey:  if you use a CDATA att you
can put markup in it.  So best solution is an alt CDATA att
on graphic itself.  Terry discuss with Eve.

For inline Graphics we'll rely on alt att on graphic

Issue 5: need an alt attribute on graphics
Requested by: eve Submitted: Feb 20 1997 Resolved: 3.1
Type: enhancement Priority: medium Status: closed

Rationale

Dup of/superseded by MediaObject

Description

There is no alt attribute for graphics, but there should be.
It should be possible to specify an alt on graphics.

Nov 98 (day  1):

DECISION: We plan to offer a "proper" solution in V4.0, and deprecate the old Graphic element in an FU
note, for removal in V5.0.

Note that the existing FU for Graphic and InlineGraphic are, according to our new plan, incorrect. We'll back
off of the previously stated V4.0 action for these.

ACTION: Eve to propose immediately a model for additional video, audio, and graphic object elements
that use empty video data, audio data, and graphic data elements respectively. It will include a subproposal
for an appropriate metadata header. She will also resubmit the informal figure proposal.

On day 2 we reviewed Eve's proposal, saw that it allowed recursion,
and reworked it into the subsequent MediaObject proposal.

Issue 6: AreaSet should not have a Coords attribute, but does
Requested by: Norm Walsh Submitted: Jan 26 12:31:23 1997 Resolved: 5.0
Type: bug Priority: medium Status: accepted

Rationale

An obvious bug fix.

Description

The AreaSet element has a Coords attribute.  It should not, since an
AreaSet must contain one or more Areas, and only individual areas can
meaningfully have coordinates that define them.

25 Oct 98.  Terry:  make a FU announcement in 4.0 saying that AreaSet will
lose its Coords attribute in 5.0.

Issue 7: ArtHeader will be dropped from BiblioEntry
Requested by: terry Submitted: 21 Jan 1997 Resolved: 5.0
Type: bug Priority: medium Status: accepted

Rationale

Correction of oversight.

Description

BiblioEntry should contain only bibliocomponent.mix.  BookBiblio
and SeriesInfo are included only for backward compatibility, and
FU comments warn they will or may be dropped entirely in 4.0. 
ArtHeader, too, is included only for backward compatibility, 
but its FU comment says only that it will be renamed in 4.0 (which is
correct), not that it too will be dropped from BiblioEntry's content
model.

The FU comment at line 711 of dbpool.mod should be replaced with

"ArtHeader, which will be renamed ArticleInfo, will be dropped from
the content model of BiblioEntry"

26 Oct 98.  Terry asked on the list just to be sure; Norm remarked
(26 Oct 98):

| The only argument in favor of breaking backward-compatability
| here is that all the legacy that would be effected will break
| anyway in 4.0 when ArtHeader is renamed.
|
| What's the recommended fix for legacy that has ArtHeader in
| BiblioEntry?  Remove the wrapper?   

Terry added (26 Oct 98):

I hope there isn't any, but I believe that ought to work, at least
syntactically.  (Whether you get a sensible result might depend on
why you used ArtHeader in the first place.)

Issue 8: Add FAQ as a class value to Article
Requested by: Peter Flynn Submitted: Feb 1997 Resolved: 3.1
Type: enhancement Priority: medium Status: closed

Rationale

Proper addition to Class on Article, in keeping with original
design intent

Description

Peter Flynn found he wanted FAQ as a Class value on Article when he
created the XML FAQ.

Add "FAQ" to the enumerated value list for the Class attribute of Article.

Accepted at November 98 meeting.

Issue 9: Need a base element for URLs
Requested by: terry Submitted: Feb 20 1997 Resolved:  
Type: bug Priority: medium Status: rejected

Rationale

Too complex to attempt without strong need.

Description

This was just an idea, not something anyone found they needed.

6/11/97
put it in *Info but must decide what the meaning of more
than one is (e.g., if in Sect1Info and a contained Sect2Info)

18 Oct 98.  Terry posts to list:
(oct 98)  Shall we call it URLBase?  I suggest
        that if there is more than one base element (or whatever we call it),
        the one closest in the hierarchy to a given ULink is the one used.
        (Note that this base element should apply only to URLs used for
        linking (which is what we have now), not to URLs that are part of
        the content (if we added a <uri> element).      

Norm responds (19 Oct 98):
Let's see if we agree on the semantic.

Given

<sect1><sect1info><urlbase>http://nwalsh.com/</urlbase></sect1info>
  ...
  <ulink url="foo">foo</ulink>
  ...
  <sect2><sect2info><urlbase>http://www.sonic.net/</urlbase></sect2info>
    ...
    <ulink url="bar">bar</ulink>
    ...
    <ulink url="ftp://ftp.ora.com/pub/davenport/">ftp</ulink>
    ...

The URL for "foo" would be "http://nwalsh.com/foo", the URL for
"bar" would be "http://www.sonic.net/bar" and the URL for ftp
would be "ftp://ftp.ora.com/pub/davenport/"?

Given that nested URLbases are probably tricky, and the fact that you
could say:

<!DOCTYPE ... [
<!ENTITY urlbase "http://nwalsh.com/">
]>
...
<ulink url="&urlbase;foo">foo</ulink>
...

Do we really need o...
[26 Oct 98, info lost here, but] we agreed to do nothing.

Issue 10: Biblioentry cleanup
Requested by: tallen@fsc.fujitsu.com Submitted: Tue Jan 21 09:57:51 PST 1997 Resolved:  
Type: bug Priority: medium Status: closed

Rationale

Duplicate

Description

It's always something.  I see I failed to clean up BiblioEntry.  It
includes Artheader, Bookbiblio, and SeriesInfo.  Bookbiblio is
going to go away, that's warned about.  Seriesinfo is now a
special case of BiblioSet, and should go away, and that's
warned about.  But ArtHeader should be removed from this content
model, however all that is warned about is that it will be renamed.

25 Oct 98.  Terry:  posted to list suggesting a FU comment in 4.0
that ArtHeader will be removed in 5.0 (least work).

Issue 11: clean up the content model of Book
Requested by: terry Submitted: Feb 1997 Resolved: 3.1
Type: enhancement Priority: medium Status: closed

Rationale

The book content model has gotten too intricate to maintain.

Description

We need to clean up the content model of books to simplify it and
make it less prescriptive.  At this time we can then add support for
colophons, etc. We need to do this work at the next meeting.

6/11/97:
Terry will post new content model to list, including colophon
(whatever that resolves to).

19 Oct 98:
Terry posts the following to the Davenport list:

suggested revision (abandoning almost all prescription):

<!ENTITY % colophon.module "INCLUDE">
<![ %colophon.module; [
<!ENTITY % local.colophon.attrib "">
<!ENTITY % colophon.role.attrib "%role.attrib;">
<!ELEMENT Colophon - O ((%sect.title.content;)?, (%legalnotice.mix;)+)>
<!ATTLIST Colophon
        %status.attrib;
        %common.attrib;
        %colophon.role.attrib;
        %local.colophon.attrib;
>
<!--end of colophon.module-->]]>

<!ELEMENT Book - O ((
%div.title.content;)?, BookInfo?, 
        (Dedication | ToC | LoT 
        | Glossary | Bibliography | Preface
        | %chapter.class; | Reference | Part
        | %article.class; 
        | %appendix.class;
        | %index.class;)*,
        Colophon?)
        +(%ubiq.mix;)>

discussion:  Colophon uses the content model of Dedication.
The revised Book model allows nonsensical books, but unless it creates
a problem for style sheets (Norm?), it covers all properly constructed
books in all languages (provided they don't use book components not
listed).

summary of info entered but lost (26 Oct 98):  Norm suggested putting
Colophon in the OR group; Terry resisted, saying that we 
established that Colophon goes at the end.  We agreed to 
rename legalnotice.mix, and use Title in Colophon rather than
sect.title.content.  Terry marked this rfe accepted.

Decided at Nov 98 meeting:  include Colophon in the OR group.
From the minutes:

DECISION: We agreed to a "big potato," as long as we clarify that the default processing expectation (a
slight softening of the current position) is for the input order to be the output order, and we say that if you
make nonsensical book structures, it's your problem. We should add a question to the interchange checklist
about this.

The potato should include Colophon.

The documentation should give a few obvious ideas for how to subset the book model to accomplish
particular tasks.

We don't want to have to maintain or support official customization layers, but Norm will make a contrib
area for customization layers that people (including Norm!) might contribute.

Issue 12: Allow sequence of browsing.
Requested by: trsmith Submitted: Feb 20 1997 Resolved:  
Type: enhancement Priority: medium Status: rejected

Rationale

DECISION: We agreed to reject this because it could be done with an external 
DTD that has link/browse semantics in it. (Nov 98)

Description

There is no mechanism to show browsing sequences, or threads,
within a book.  Tracy Smith requested one.

6/11/97 Cambridge:

also better done externally?  maybe need an element for this
info in metadata.  Tracy should define his requirements.

No further input; rejected at Nov 98 meeting.

Issue 13: Add support for 8bit chars in DocBook
Requested by: eve Submitted: Jan 26 12:46:40 1997 Resolved:  
Type: enhancement Priority: medium Status: rejected

Rationale

DECISION: We agreed to reject this because XML requires handling of such 
characters, and we'll assume full XML support. (Nov 98)

Description

(The following is taken from Murray's notes at November 1996 meeting.)

Can we extend the character set to allow the upper characters in
8-bit?  Proposed by Murray that we extend the DocBook declaration to
allow characters #160-#254.  Lengthy discussion about character sets in
general. Lee points out that allowing any 8-bit characters could
present a future incompatibility problem with shifted character set
encodings.  Should we punt for now and wait until the XML declaration
has been settled and use the character set declaration from that?
Murray withdrew proposal. Jon proposes use of XML's character set
declaration. Murray re-proposes addition of Latin 1 characters.

Feb 20,1997:

It was realized that adding ISO 10646 and other support needs some
investigation of tools support.

Issue 14: A specific ChoiceList element may be useful
Requested by: eve Submitted: Jan 26 12:27:17 1997 Resolved:  
Type: enhancement Priority: medium Status: rejected

Rationale

DECISION: We agreed to reject this because it's the flowcharting aspect that 
would be the most interesting, and this needs to be designed by each DocBook-
using organization as a content-based structure. (Nov 98)

Description

Some DocBook variants have added an element for indicating alternate
choices.  A specific ChoiceList element could be used in two ways:

o To manage consistent output of the following approximate form:

You can:

- Do this
OR
- Do that

o To offer more flowchart-like capability for procedures.

It may not make sense to consider this unless we do a Procedure overhaul to
make it more flowchart-like in general, which DocBook users may not need.
If we want to go this far, IETMs may provide a good model.

Feb 20, 1997
Issue deemed  to complex.  Will need further discussion and
investigation.

6/11/97 Cambridge:

better done by expressing flowchart logic in exterior ilinks?
issue still too complex.

Nov 98 meeting:  decided not to do it.

Issue 15: CiteTitle should be link?
Requested by: eve Submitted: Feb 20 1997 Resolved:  
Type: enhancement Priority: medium Status: rejected

Rationale

DECISION: We agreed to reject this because, until XLink is finished, you can 
always use ULink (or OLink or whatever) inside or surrounding the CiteTitle 
as a workaround, and because the element was originally conceived as a 
textual reference rather than as a true link. It opens
up a big can of worms that we should really try to solve in V5.0. (Nov 98)

Description

Also as a cross-doc link?

25 Oct 98:  Terry posts to list suggesting we reject this rfe,
as citetitle is already defined as not a link, and you can put
a citetitle inside a ulink already.

26 Oct 98:  Eduardo (private mail to Terry) agrees.  So does Norm.
Both also remark that this is an argument for ubiquitous linking,
and agree with Terry that that issue should wait for Xlink.
Peter Flynn would like a link here.

Issue 16: Content model for Colophon
Requested by: eve Submitted: Jan 26 1997 Resolved: 3.1
Type: enhancement Priority: medium Status: closed

Rationale

Colophon should be supported.

Description

Feb 20, 1997
There is interest in adding this element.  It needs more
investigation and discussion.  Murray will provide some background
information for discussion.

19 Oct 98
Terry's proposal for book-model-rationalization includes a Colophon
element.  Murray [Maloney]'s colophon example turned out to have 
its colophon incorrectly placed:  a colophon goes at the absolute
end of a book (unless succeeded by advertisements, which we don't
deal with).

1998/11/14 Chicago

Use legalnotice.mix; named textobject.mix. Use textobject.mix for
legal notices, dedications, and elsewhere.

Issue 17: Add common Condition attribute for generic effectivity
Requested by: eve Submitted: Fri Jan 10 16:31:25 PST 1997 Resolved: 3.2
Type: enhancement Priority: medium Status: closed

Rationale

The current set of effectivity attributes all have explicit semantics,
it is useful to have an attribute that has no explicit semantics. If 
users find that they are using Condition for an explicit semantic, it
should be brought to the attention of the TC so that it can be considered
for inclusion as an explicit named conditionality attribute.

Description

Resolution: add a new Condition attribute as a common attribute.

In several DocBook customizations, I've added a new Condition attribute
that serves for all conditional settings because it's a NAMES attribute.
This is a low-level enhancement request/query.

Feb 20, 1997
This issue needs more discussion following a higher level discussion
on design principles.


6/11/97 Cambridge:

no enthusiasm.  An optimization for particular tools?
Can Eve state the case in greater detail?

19 Oct 98
Terry declares this rfe rejected.

Issue 18: Add Constant element
Requested by: Leslie Wharton DIGITAL UNIX PUBLICATIONS <wharton@zk3.dec.com> Submitted: Feb 11 12:02:46 1997 Resolved: 3.1
Type: enhancement Priority: medium Status: closed

Rationale

Having one element represent a generic category of
"literal" and another element represent a subclass of that
category makes little sense from a semantic standpoint.
Adding "limit" to the list of Class values for SystemItem
does not seem appropriate; the new class value would be a
subdivision of another class value. New elements for former
classes of SystemItem have recently been added to DocBook.

Doing the same for Constant also seems appropriate.

There are some historical (POSIX-related) 
processing issues that this element would help streamline for
documentation of POSIX-conformant systems. 
Constants are typically (but not always) given special 
typographical treatment in formatted output; limits are rendered
the same way as constants, but (typically, but not always) with 
the addition of enclosing braces. It is more efficient 
for style sheets to deal with all constants by using the same 
element and, if appropriate for the style, further differentiate
the typographical treatment of the subtype 
based on the specification of Class.

Description

Add the element Constant to DocBook. 

In addition to common attributes,
Constant would have a Class attribute that could be
set to the value "limit".  I do not propose
any default value for Class and assume that the attribute is
simply omitted by writers when there is no need to subcategorize 
the constant.

This element would replace use of <systemitem class="constant">
to identify a generic constant and <symbol class="limit"> to
identify a constant that is a system limit.

NEED TO FU REMOVAL OF CLASS='CONSTANT' FROM SYSTEMITEM

<!E constant 
<!A constant
    class (limit) #implied
>

Issue 19: Remove Contents attribute from Bookinfo and SetInfo
Requested by: terry Submitted: 22 Jan 1997 Resolved: 5.0
Type: bug Priority: medium Status: accepted

Rationale

The Contents attribute on BookInfo and SetInfo is unused and not useful.

Description

Should it be moved to Book and Set?  discarded?  is anyone using it?

Feb 20,1997
Pending a query to the list on whether anyone is using this
attribute will consider an FU announcement in version 4.04 removal
in version 5.0.

6/11/97:

Terry query list

18 Oct 98:  Terry did so.

Nov 98:  agreed to discard it.

Issue 20: Parameterize element and attribute list declarations more rationally
Requested by: eve Submitted: Jan 26 12:40:49 1997 Resolved: 3.1
Type: enhancement Priority: medium Status: closed

Rationale

Enhances useability.

Description

Customizers of DocBook can avoid a whole lot of hassle if they can
snip out
and replace only a single declaration, rather than pairs of
ELEMENT/ATTLIST
declarations.

The ELEMENT and ATTLIST declarations should each define a single
element (no name groups) and should each have its own marked section
for easy removal/replacement.  The xxx.content.module marked sections
will still be useful for removing large chunks of DocBook.

Some parameter entities that are referenced only once, to aid in
customizing certain content models, can then be removed because it
would be as easy to remove/replace the entire element declaration as to
remove/replace just the content model.

Feb 20, 1997
Needs testing with tools (ie Instant). Terry will ask for testers.

Nov 98:  Terry never did ask for testers, but we decided to do it
anyway.

Issue 21: Figure should allow extended captions in addition to titles
Requested by: eve Submitted: Jan 26 12:46:40 199 Resolved:  
Type: enhancement Priority: medium Status: rejected

Rationale

Captions belong on the objects, not the figures.  We will add Caption to
Vidoe/Graphic/AudioObjects. We can revisit this later if required.

Description

Add new InformalFigure element inside Figure and allow a new Caption
element inside both. (See grphcnln.isu.)

11/13/98 f2f:

After some discussion, we decided that the caption belongs on the graphic
object, not the figure.  WBD.

Issue 22: ELEMENTS keywords in FPIs
Requested by: eve Submitted: Fri Jan 10 16:37:44 PST 1997 Resolved:  
Type: bug Priority: medium Status: rejected

Rationale

DECISION: We agreed to reject this because there's no negative effect to 
continue using the ELEMENTS keyword and it's more descriptive of the intent than DTD.

Description

The ELEMENTS keyword is used in FPIs contrary to the SGML standard.

This is a longstanding known "bug" with DocBook,
but for the moment we're not planning to change it.  Basically, the
modules use the ELEMENTS keyword in their FPIs, even though properly
ELEMENTS public text should contain only element and attlist 
declarations.  Perhaps WG8 will come up with something more intuitive
during the SGML revision.

Feb, 1997:
The ELEMENTS keyword is used contrary to 8879 in the FPIs for DocBook
DTD modules.

Decided that ELEMENTS keword is more intuitive and poses no tools
problems. We will keep it. 

Should ask for comments from Users.

25 Oct 98.  Terry:  we never did, they never complained.  

Nov 98:  rejected

Issue 23: Store parameter descriptions within FuncSynopsis
Requested by: eve Submitted: Feb 4 19:07:28 1997 Resolved:  
Type: enhancement Priority: medium Status: closed

Rationale

Will be considered as part of the broader revamping of FuncSynopsis for
modern programming languages. (See RFE 95)

Description

Many years ago, I designed a function synopsis model that allowed for a
description to be associated with each parameter.  I gave it up because
most people felt it went too far.  However, that was in the age of synopses
done with .B and .I, and I've gotten several requests since that time from
my users for more robust function synopsis markup.

Currently, authors usually follow a function synopsis with a variable list
that details each parameter.  (In man pages, the two can be far apart.)
But each description is more related to its parameter than to the other
descriptions in the list; it would be more logical to store the parameter
and description info together, and then construct the list as necessary for
print presentation.  For online presentation, pop-ups would be one natural
and useful way to display the information.  Note that handling traditional
man pages would be tricky because the "parameters" section is usually
constructed by hand and can appear anywhere in the sequence of sections; a
more structured approach would be necessary.


Feb 1997:

The group was not inclined to add an ability to put an explanatory
text inside ParamDef. Much of the benefit can be gotten from allowing
a link from the parameter to its description.

11/13/98 f2f

Watch future developments, consider the DOM extensions to the XML spec DTD.

from the minutes:

AGENDA ITEM FOR NEXT MEETING: Discuss this and examine the DOM Working
Group's IDL model for consideration. This item is pending.

ACTION: Eve to send out some examples of the DOM IDL model to the list for
consideration.

Issue 24: Add element to link to GlossEntry?
Requested by: terry Submitted: Feb 20 1997 Resolved:  
Type: bug Priority: medium Status: rejected

Rationale

It seems to be a low priority issue, and we're unmotivated to deal with it now.

Description

Need new element? Glossref instead of xref?

There is no semantically specific way to link to a GlossEntry from the text.

Issue 25: Inlineequation incorrectly includes the object-level
Requested by: terry Submitted: 22 Jan 1997 Resolved:  
Type: bug Priority: medium Status: closed

Rationale

Superseded by MediaObject proposal, #77.

Description

A proposed fix is this:
- InlineGraphic is dropped
- Graphic becomes EMPTY, and looses any inline/object rendering
expectations
- A new container, InformalFigure, is added.
- %inlineequation.content is used once and should therefore
be discarded in favor of Graphic as the content model of
InlineEquation; once Graphic is no longer an object the
present conflict will be resolved. 
There is no need to have both Graphic and InlineGraphic,
but InlineGraphic for historical reasons now serves for what we
might otherwise call InformalFigure.  We also should make Graphic
into an EMPTY element, as CDATA elements are problematic.

This would be BI, and so must be announced in v 4.0; the full change
(particularly disallowing Graphic as an unwrapped object) cannot be
made before v 5.0.

Feb 1997:

????

6/11/96 Cambridge:

Terry post model to list.  Informalfigure needs an optional
Caption just like Figure; should c.model of Caption be
paracharmix or component.mix

1st day of Nov 98 meeting:

ACTION: Eve will account for the contexts in which GraphicObject should be allowed (that
is, in addition to all the places where Graphic and InlineGraphic are allowed). Do we really
want to allow (until V5.0) all of Graphic, GraphicObject, Figure, and InformalFigure floating in
content?

ACTION: Eve to include in her proposal an InlineObject element that contains one (no more)
of the specific *Object elements.

Issue 26: %indexdivcomponent.mix usage
Requested by: terry Submitted: 22 Jan 1997 Resolved: 5.0
Type: bug Priority: medium Status: accepted

Rationale

Index and SetIndex should not contain such things as numbered figures;
restrict the content.

Description

Why do we have %indexdivcomponent.mix?  Index/SetIndex use
%component.mix in the same spot (the introductory matter).

From tallen@fsc.fujitsu.com  Tue Jan 14 09:00:53 1997

I don't mind having indexdivcomponent.mix, but if we have it
it ought to be used in Inex/Setindex too.  I didn't untangle
what the difference was between it an component.mix.

From elm@arbortext.com  Tue Jan 14 08:04:03 1997

I did this because someone might want to restrict one context
but not the other.  Given our current level of parameterization,
though, this is probably a case where we could get rid of
indexdivcomponent.mix and just use component.mix.

From elm@arbortext.com  Mon Jan 20 16:04:37 1997

I agree that if we have it at all, it should also be used in the
model of Index/SetIndex where component.mix now occurs.  
indexdivcomponent.mix differs from component.mix in the following
respects:

o Not all the lists
o No admons
o No formals
o No compounds
o No miscellaneous objects other than Anchor and Comment
o Contains link elements directly

I'm pretty sure I copied the old V2.1 content models when I did this;
I have no idea why these differences exist.

I hate to spend time or "backwards incompatibility bucks" on content
model fragments like this one, since I doubt anyone really uses Index,
SetIndex, or IndexDiv in such a way as to depend on the exact character
of thes(truncated)

In 5.0, component.mix will be replaced by indexdivcomponent.mix in Index
and SetIndex

Issue 27: May want to offer index terms that wrap real paragraph content
Requested by: Peter Flynn Submitted: Resolved:  
Type: enhancement Priority: medium Status: rejected

Rationale

DocBook's general approach to metainformation contradicts Peter's
preferences for element content.  Index terms are not the only case of
element content that should be suppressed from direct output.

Description

Peter believes that element content should all contribute directly to
the content of the delivered document, so that if you remove the
markup, the "true content" remains.  Thus, he wants to have an
alternative kind of index term whose processing expectation is to
appear directly in the content.
For example:

Source: An <IndexTermInFlow>apple</> is a fruit.
Output in body of document: An apple is a fruit.

This model necessitates an attribute (or subelement?) that offers the
desired indexing string to use, just in case the phrase in text is 
capitalized or spelled differently from how it should appear in the
index.

Note that DocBook's general approach to metainformation contradicts Peter's
preferences for element content.  Index terms are not the only case of
element content that should be suppressed from direct output.

Feb 1997:

Need more discussion of indexing. Consider having an indexing workshop
at some future meeting.

Issue 28: Allow indexterm within glossary
Requested by: Michael Sabrio Submitted: Feb 21 1997 Resolved:  
Type: bug Priority: medium Status: closed

Rationale

Dup of/will be superseded by RFE#52

Description

Michael wanted to be able to insert indexterms in a glossary, but
they're not allowed there.

6/11/97 Cambridge:

ask Eve first, then ask on list if need be.

Oct 26 1998.  Terry did ask Eve, who wrote (25 Oct 98):

I think this might have had something to do with the fact that glossaries
usually aren't indexed, because they're a kind of index of terms
themselves.  However, I have no principled objection to this.  I do have a
vague memory of objecting originally, but I don't recall why...  Useful, huh? 

Eduardo remarked (26 Oct 98):
Seems to me this is an unnecessary multiplication of entities (in Occam's
sense, not SGML's ;-). Pretty soon we'll have to be able to index index
entries too...

This is not a principled opposition. It's a call to think carefully about
it and the perceived need for it.

Issue 29: Storage when zone being used
Requested by: trsmith Submitted: Feb 20 1997 Resolved:  
Type: bug Priority: medium Status: rejected

Rationale

We don't have a policy for where to put "zoned" index terms, 
and don't want to create a container for them. Users can put them anywhere they like (or decide on their own convention for where to store them).

Description

25 Oct 98.  Terry:  I supplied the rationale "Where store IndexTerm
when using Zone" but no longer remember what Tracy's problem was,
and can't see it now.  You can store IndexTerms in an ITermSet,
either separately, or within an *Info.  

Nov 98:  rejected

Issue 30: non-bibliocomponent.mix elements found in *Info elements
Requested by: terry Submitted: 22 Jan 1997 Resolved: 3.1
Type: enhancement Priority: medium Status: closed

Rationale

ArtHeader is meant to be parallel to the %otherinfo.class
elements, which include Graphic, LegalNotice, ModeSpec,
SubjectSet, KeywordSet, and ITermSet.  Through oversight, 
these elements were not added in v 3.0, when *Info elements
were overhauled.

Description

In the next release, add the specified elements.

The way the summary is worded, it makes me think it's an RFE, not a
bug.
My vote is Priority 2.

Feb 1997:

At version 3.0 all the *Info and equivalent comments were supposed to
have been extended to contain elements such as Graphic,Notice,
SubjectSet, etc. ArtHeader (2 B. meeting ArticleInfo later) was not
extended in this way and it should have been.  These elements should
be added at the next release.

27 Oct 98.  Terry adds this info from a mistakenly attempted dupe
of this rfe:

From: Gordon Matzigkeit <gord@m-tech.ab.ca>
Date: 25 Jun 1998 01:58:48 -0600
Sender: owner-davenport@berkshire.net
Reply-To: davenport@berkshire.net

Hi!

I am confused as to why the Copyright and LegalNotice tags are
separated.  I want to put a LegalNotice on my Article, to accompany
its Copyright, and I am unable to do so.
                                 
26 June 98.  Terry responded:
Copyright is a precise and well understood kind of notice.
LegalNotice can say whatever you want.  So keeping them separate
seems reasonable to me.

We can certainly add LegalNotice to ArtHeader.  (Conceivably we've
already been asked to do so, but I don't recall it.)  Ad interim,
you could make a customization layer for yourself, or abuse one
of the elements in bibliocomponent.mix, such as Abstract or
BiblioMixed.
               
26 Oct 98.  Terry notes that the wanted elements would be those in
otherinfo.class.

<!ELEMENT (%otherinfo.class;) - - ((Graphic | LegalNotice | ModeSpec
        | SubjectSet | KeywordSet | ITermSet | %bibliocomponent.mix;)+)
        -(BeginPage)>

and posts to the list suggesting addition of those elements.

Issue 31: InlineEquation should contain InlineGraphic, not Graphic
Requested by: eve Submitted: Jan 26 12:34:22 1997 Resolved:  
Type: bug Priority: medium Status: closed

Rationale

Handled by MediaObject

Description

Graphic normally has a "displayed/set-off" processing expectation, which
is incorrect in the context of an *inline* equation.

The content model should simply be changed over to use
InlineGraphic.  This is backwards-incompatible.

Issue 32: Do we need inline steps for small procedures
Requested by: trsmith Submitted: Feb 20 1997 Resolved:  
Type: enhancement Priority: medium Status: rejected

Rationale

DECISION: We agreed to reject this because if the procedure is that small and
inconsequential, it's not worth making special markup (instead of some inline 
kind of list) for it.

Description

Need to be able to tag small steps of instructions inline.

6/11/97 Cambridge:

left open for Tracy to argue for; Harvey and Terry agree
if it's important you should break it out.

Nov 98
There's been no further request, and Tracy is not participating;
we rejected it.

Issue 33: We have no example for the Limit att on Symbol
Requested by: terry Submitted: 22 Jan 1997 Resolved:  
Type: enhancement Priority: medium Status: closed

Rationale

dup of constant

Description

At 08:54 AM 1/14/97 -0800, Terry Allen wrote:
Fred did supply some example, which I didn't find when I went
looking for them to use in the doc.  But I'm pretty sure that
"Limit" wasn't used.

Feb 1997:

We were in error in adding a Class attribute value of Limit onto
Symbol; we should "Future use"-announced this in 4.0 removal in
5.0.

See constant.isu.

Issue 34: Add LinkEnd to LoTEntry
Requested by: terry Submitted: 22 Jan 1997 Resolved: 3.1
Type: bug Priority: medium Status: closed

Rationale

We should add a Linkend attribute to the LOTentry, to synchronize the
model with the TOC's.  Augmented DocBook instances with a filled-out
toc and indexes may now become more popular if SGML on the web
increases.

Description

Tocentry has a Linkend att but Lotentry doesn't.  We should
probably postpone meddling with linking until after the XML
discussion concludes, but maybe we want to get rid of it
in one place or add it to the other, and review this kind
of linking-without-formal-linking-elements throughout the DTD.

From elm@arbortext.com  Tue Jan 14 08:15:31 1997

It would be nice if the documentation summarized all the places
that have any kind of explicit or obvious/implicit linking semantic.
E.g., I might count CiteRefEntry as implicitly linking, since it
purposely provides enough information so that a downstream application
can generate a link, and since its purpose is cross-referential.


Feb 1996:

We should add a Linkend attribute to the LOTentry, to synchronize the
model with the TOC's.  Augmented DocBook instances with a filled-out
toc and indexes may now become more popular if SGML on the web
increases.

Issue 35: Add mailto URL in email
Requested by: terry Submitted: Feb 20 1997 Resolved:  
Type: enhancement Priority: medium Status: rejected

Rationale

Abuse of semantics; use <ulink> around <email>

Description

Peter Flynn had requested a change to support construction of
mailto links while marking up the content as email.

6/11/97 Cambridge:

need to cook the requirements further.  Can do already with
email/ulink?  want separate mailto element?  what are 
processing expections?

25 Oct 98  Terry points out:
<!DOCTYPE para PUBLIC "-//Davenport//DTD DocBook V3.0//EN" >
<para>A sentence including an email address, which is
here: <ulink url="mailto:foo@bar.com"><email>foo@bar.com</email></ulink>.
</para>

parses correctly, and asked the list if any change is needed.

26 Oct 98  Norm and Eduardo agree no change needed.

Issue 36: Creating marginal graphics
Requested by: eve Submitted: Feb 20 1997 Resolved:  
Type: enhancement Priority: medium Status: rejected

Rationale

On balance, this appears to be a stylesheet issue and it's unclear
that additional markup can reasonably be provided.

Description

6/11/97 Cambridge:

Issue is that the info can't be generated.

Lee is using Graphic Role="margin" outside the para to do what
Steve Hiebert wanted.  This works, but doens't provide 
containment.  We could make a new attribute for the new
graphic element (4.0/5.0) that provides this processing expectation; 
this generates irony.  Generalize this to the case of marginal hacks,
which need text.  So probably want element for associated marginalia
with wider processing possibilities in other formats.  Maybe
enhance Footnote?  Call this case Sidenote as an attribute
value?  New GI (probably)?  Display where in relation to container 
and location of Sidenote within container?  This also handles
text flow around graphics.

1998/11/14 Chicago

We decided that the issue has aged sufficiently that we need to ask for more 
input. In any case, Lee Fogal only wanted simple graphics in the margin 
(outside of paragraphs), and Steve Hiebert wanted the same thing. We don't 
think we need to solve the "marginal hacks" problem, which was not a request 
expressed by any users, but we're sympathetic to solving the margin graphics 
problem if it can be done simply (a role-like solution as opposed to 
container elements, objects, etc.).

Issue 37: MsgText has far too broad a content model
Requested by: eve Submitted: Jan 26 12:21:03 199 Resolved: 5.0
Type: bug Priority: medium Status: accepted

Rationale

This may not be perfect, but it's forward progress.

Description

Resolution: We will make the content the same as %example.mix;. 

Currently (v 3.0), MsgText contains component.mix, which allows lists, 
synopses, and so on.  This is far too broad.  The content model must be 
significantly reduced.

Feb 1997:

Currently the MsgText element contains component.mix, which is to
broad a content model.  During the discussion of this issue it was
suggested that MsgSet as a whole would be used by many more DocBook
users if it were simplified inadequate.

Terry will ask for examples of subjects used by Novell and Sun.

25 Oct 98:

I recall doing so (or something similar), says Terry, but I don't find the 
mail.  I've suggested to the list that we just get rid of MsgSet
entirely.

26 Oct 98.  Norm thinks it's too late to remove MsgSet entirely;
Eduardo thinks he might be able to get along without it:
It would imply doing some transformations from the current
model to the new one, but if there is a marked improvement
I think it would be worth it. 

a user writes:
[Beckers, Marc]  MsgSet allows us to group messages according
to product component or utility that returns the message.
Not only do I request that MsgSet be kept, I  on the contrary request that 
a Title be included on it (i.e., MsgSet contains a Title
followed by one or more MsgEntry elements).
Thanks

Dr. Marc Beckers
Your friendly Documentation Consultant
Software AG, Germany
Tel.:  +49 (0)6151 92 1322
Fax.:  +49 (0)6151 92 1612
Email: Marc.Beckers@softwareag.com          

to which Terry responds (to the list):
All right, MsgSet remains in play and Dr Beckers's request for a Title
on [info lost 26 Oct 98, but summary follows] is acknowledged.  [Terry
asked Eduardo to detail someone such as Murray A to construct a straw
man for the Chicago meeting in Nov.]

Eve will propose a content model for MsgText

Nov 98 minutes:

It's reasonable to add an optional title to MsgSet. While the model is complicated, it appears to
do a pretty good job.

ACTION: Eduardo, if he desires, to propose a simplification of MsgSet that could be used as a
"lite" alternative.

ACTION: Eve to propose a list of components that are appropriate for the content of MsgText.

Issue 38: Review nav.class availability
Requested by: terry Submitted: 22 Jan 1997 Resolved: 3.2
Type: enhancement Priority: medium Status: closed

Rationale

The contents of nav.class were originally confined to
Book, but can now occur at much lower levels.  The result, for
historical reasons, is somewhat inconsistent.

Description

Reopened by nwalsh 04 Dec 1999

Additional issue to be resolved: making the content model of components
and sections loose is problematic because it would allow Section,
Sect1, and SimpleSect to become siblings in the same container. I think
this is unsatisfactory and assert that we sould not make the content models
loose.

Proposed alternate resolution

- nav.class is allowed at the beginning and end of components and sections
- The content model of components and sections is not significantly changed
- RFE97

  (See Chapter in 4.0beta1)

---

Resolution:
- nav.class will be allowed at the component and section levels
- The content model of components and sections will be made loose,
  as the content model of book was made loose in 3.1.
- The content model of ToC will be simplified drastically (see RFE 97)

We should review
the whole issue and also whether it is useful to have ToCchap,
etc., containers rather than just nested ToCentrys.

nav.class can't appear directly within Chapter, etc., although
it can appear within Sects.  Add it to divcomponent.mix?  and
to the end of the content model?

From elm@arbortext.com  Tue Jan 14 08:15:31 1997

The Book content model has some sequence constraints on it that the
lower levels don't have (e.g., the weird glossary/biblio/lot/toc
ordering).  It may be that this is too restricted.  We could ask.
We've done so much futzing around with this poor content model,
though, that I'm reluctant to open it up again!

From elm@arbortext.com  Mon Jan 20 16:06:46 1997
To: Terry Allen <tallen@fsc.fujitsu.com>
From: "Eve L. Maler" <elm@arbortext.com>
Subject: Re: A Few Docbook Issues unearthed
Cc: dennis.evans@Sun.COM, elm@arbortext.com, tallen@fsc.fujitsu.com

At 09:04 AM 1/14/97 -0800, Terry Allen wrote:
>Eve:
>| >- nav.class can't appear directly within Chapter, etc., although
>| >  it can appear within Sects.  Add it to divcomponent.mix?  and
>| >   to the end of the content model?
>| 
>| The Book content model has some sequence constraints on it that the
>| lower levels don't have (e.g., the weird glossary/biblio/lot/toc
>| ordering).  It may be that this is too restricted.

Issue 39: Notation and character entity declarations should have their own modules
Requested by: norm Submitted: Jan 26 12:46:40 1997 Resolved: 3.1
Type: enhancement Priority: medium Status: closed

Rationale

Further modularization will make maintenance and customization easier 
because the DocBook driver file will have nothing "significant" left in it;
customizers will be able to provide an entirely new driver file and still
pull in the DocBook notations and character entity sets.  Also, it will be
easier for Davenport itself to create new document hierarchies.
This was accepted at the November 1998 meeting.

Description

The new entity "call tree" will look like this:

Driver file
- Notation module
- Character entity module
- Information pool module
. CALS table module
- Document hierarchy module
- Customizable notation/general entity module

Issue 40: New owner identifier for DocBook FPI
Requested by: norm Submitted: 16 Oct 1998 09:14 Resolved: 3.1
Type: bug Priority: medium Status: closed

Rationale

With the demise of Davenport, we need a new owner identifier for
the DocBook FPI.

Description

I'm guessing that it'll be -//OASIS//..., but this RFE is a reminder
that we need to address the issue.

27 oct 98. rfe renamed by Terry for consistency.

Nov 98 minutes:

We need to get the official word from OASIS on the exact wording of the owner identifier
they prefer ("OASIS", "OASIS Group", or whatever). Also, we will ask them to register their
owner identifier. OASIS is starting up a TC for repositories, which may have bearing on the
issue of retrieving official OASIS versions of DTD files.

ACTION: Eduardo to contact OASIS about these matters.

For now, we'll assume that the FPI will start thusly:

-//OASIS//DTD DocBook.......

Issue 41: Should set allow only a single book?
Requested by: jdreystadt Submitted: 16 Oct 1998 13:39 Resolved: 3.1
Type: bug Priority: medium Status: closed

Rationale

Reasonable and consistent with other structures in Docbook

Description

Allowing a single book in Set would make it easy for tools to add a Set wrapper around book.  Then the user could add a second book.  As it stands, it's a little tricky, if you start with a book, to promote the book into a set of books.

Nov 98: agreed

Issue 42: The comment marking the end of the programlistingco.module is wrong
Requested by: norm Submitted: 05 Nov 1998 05:53 Resolved: 3.1
Type: bug Priority: low Status: closed

Rationale

Comments should be correct.

Description

The comment that ends the programlistingco.module reads:

<!--end of informalexample.module-->]]>

it should read 

<!--end of programlistingco.module-->]]>

Issue 43: Need bidirectional linking.
Requested by: Murray Maloney Submitted: Feb 21 1997 Resolved:  
Type: enhancement Priority: medium Status: rejected

Rationale

No demand, prefer to wait for XLink.

Description

Murray Maloney wanted bidirectional linking, but isn't using Docbook.

25 Oct 98.  Terry:  no one else has asked for this, and processing
expectations would have to be clarified.  You can get the effect
by using two one-way links.  We can come back to it if
need be, preferrably after Xlink is done.

Issue 44: ClassName okay for OO classes? Need MethodName too?
Requested by: Norm Walsh Submitted: Jan 26 12:46:40 199 Resolved:  
Type: enhancement Priority: medium Status: closed

Rationale

Reformulated as RFE 96

Description

We need to decide if ClassName is appropriate for object-oriented
classes.  It may also be necessary to add new MethodName markup.
Are there other significant OO constructs that need to be marked up
specially?

Feb 1997:
Object oriented markup needs to be investigated and discussed at a
future meeting.  ClassName already exists; is it appropriate for oo
classes.  Do we need a MethodName element as well?  Do we need
specialized kinds of synopsis?

Nov 98:  decided this should be an agenda item for the next
meeting.

Issue 45: Add pagewide att to figure.
Requested by: eve Submitted: Feb 21 1997 Resolved: 3.1
Type: enhancement Priority: medium Status: closed

Rationale

Given that we have the att on Table, this makes sense.

Description

It is desired to allow on Figure the pagewide attribute from the 
CALS table model:

 pgwide      %yesorno;       #IMPLIED

6/11/97 Cambridge:

clarify that the processing expectation is that you extend
to full width of printable area.

19 Oct 98
Terry notes that a change to the doc is required as well as a 
change to the DTD.

27 Oct 98.  Terry summarizes from email:

Date: Mon, 23 Jun 1997 20:15:46 -0400
From: Paul Grosso <paul@arbortext.com>
To: Multiple recipients of list <davenport@amber.ora.com>
Subject: Re: Docbook:  Pgwide on Figure

At 18:04 1997 06 23 -0400, Terry Allen wrote:
>Issue:  pagewide-on-figure.
>
>We have a request (accepted) to add a pgwide attribute to Figure,
>such as exists on Table and Ifnormaltable.  When we move to a new

Adding pgwide to Figure--given that it is on Table et al.--makes sense.

>model of the use of Graphic and add InformalFigure, pgwide would
>go on that element, too.  We wish to clarify the processing expectations;
>unless we hear otherwise we'll assume that the explanation for
>pgwide on Table:
>
>Pgwide indicates whether the table should be rendered within the current
>text flow (no, the value 0) or within the full text page width (yes, the
>value 1). There is no default.
                              
The above generally agrees with SGML Open Technical Memo 9502 (accepted
by CALS).  Note that per TM9502, pgwide=0 indicates that:

 the maximum available width for the table is the (galley) width (possibly
 respecting current indents in force as specified by the style sheet) of the
 curent column of the [portrait] page.  If a specified value other than zero,
 the table spans the width of the entire page (possibly causing any previous
 mlticolumn text on the page to be balanced and any extra processing
 associated with column balancing and page spanning to be performed).  This
 atribute is ignored [in landscape mode] where all tables are treated as if
 pgwide=1.

>
>(from http://www.ora.com/davenport/dbdoc/ref/refpages/table.htm) is
>what is desired for Figure, too (substituting "figure" for "table").
>Were it not for this precedent from CALS, I'd be inclined to make
>no/0 the default, but there is some value in maintaining alignment
>of semantics.

The latest CALS spec per SO TM9502 indicates:

  Default = IMPLIED (implies value from the style specification if
  available, if not, the default is determined by the presentation system).

I tend to agree that non-pgwide is often a reasonable default, but due
to historical accident, most presentation systems currently default to
"pgwide".

paul

p.s.  For online versions of SO TM9502:
        ftp://ftp.omnimark.com/sgmlopen/9502, though it seems inaccessible now
        http://www.sgmlopen.org/sgml/docs/a502.htm

Date: Tue, 24 Jun 1997 09:16:59 -0400
From: Harvey Bingham <hbingham@ACM.org>
To: Multiple recipients of list <davenport@amber.ora.com>
Subject: Re: Docbook:  Pgwide on Figure

At 18:03 1997/06/23 -0400, Terry Allen wrote:
>Issue:  pagewide-on-figure.
...
>value 1). There is no default.

That is clean and simple, but there may be complications, as that fails
to resolve what precedence a stylesheet would have, how running indents
apply, and the effect of turnpage layout.

With Docbook, is the presumption that any table layout is up to the
rendering system, using whatever attributes may be present as hints?
No expectation that different table rendering systems need do the same?

CALS had no default, but much more style-sheet language on table width.

[CALS Figure allows <!ATTLIST figure orient (port|land) "port" ...>       

SO Exchange table model has "guidance" favoring the current text flow
if reasonable. It recommends that an explicit value be included. See below.
>
>(from http://www.ora.com/davenport/dbdoc/ref/refpages/table.htm) is
>what is desired for Figure, too (substituting "figure" for "table").
>Were it not for this precedent from CALS, I'd be inclined to make
>no/0 the default, but there is some value in maintaining alignment
>of semantics.
>
---------------
>From the CALS Table Model SGML Open Technical Memorandum TM 9502
There is much more style-specific detail:

PGWIDE: If zero, the maximum available width for the <table> is the
(galley) width (possibly respecting current indents in force as specified
by the style sheet) of the current column of the orient="port" page.
If a specified value other than zero, the <table> spans the width of the
entire page (possibly causing any previous multicolumn text on the page
to be balanced and any extra processing associated with column balancing
and page spanning to be performed). This attribute is ignored when
orient="land" where all tables are treated as if pgwide="1".
Declared Value = %yesorno; (NUMBER) 
Default = IMPLIED (implies value from the style specification if available,
if not, the default is determined by the presentation system).

--------------
>From the SGML Open Exchanger Table Model SGML Open Technical Report TR 9503

pgwide

make table span full page width

If zero, the maximum available width for the <table> is the (galley) width
(possibly respecting current indents in force as specified by the style
sheet) of the current column of the orient="port" page. If a specified value
other than zero, the <table> spans the width of the entire page (possibly
causing any previous multicolumn text on the page to be balanced and any
extra processing associated with column balancing and page spanning to be
performed). This attribute is ignored when orient="land" where all tables
are treated as if pgwide="1".

Declared value  %yesorno; (NUMBER)
                                        

Default IMPLIED (implies value from the style specification if available).
In the absence of an explicit value (or one implied from the style
specification), the system should attempt to format the table into a galley
column if reasonable, based on explicit <colspec> colwidth values,
galley column width, and possible table indentation implied by context.
If any relative width specifications exist, they should continue to apply,
but the unit proportion should be first based on the width uncommitted
from the galley column.

In the above paragraph, &ldquoif reasonable&rdquo is intended to preclude
a system generating columns so narrow that the entry content is obscured
by awkward line folding, or clipping. For align=char, the content either
side of the alignment character should also be considered. No explicit
algorithm for determining when a table will fit is provided. Because of
the uncertainty in meaning, interchange of a table should include an
explicit value for pgwide.
-----------

Regards/Harvey Bingham
mailto:hbingham@acm.org
http://www.tiac.net/users/bingham

DECISION: This was agreed on; it was accepted. We should also add it to InformalFigure.

Issue 46: Add a Q & A structure.
Requested by: eve Submitted: Feb 20 1997 Resolved: 3.1
Type: enhancement Priority: medium Status: closed

Rationale

Accomodates an expressed need with a tested solution.

Description

25 Oct 98:  Terry: as I recall, we discussed this in 1997 and realized that
many combinations were possible (for example, a question that has more
than one answer, multiple questions that are all satisfied by the same
answer).  Left open in case someone else wants to argue for it.

Nov 98:

ACTION: Eve to post to the mailing list a description of the Arbortext Q&A 
model. We are dubious that we need the subentry nesting; we'll see what the 
reaction is. We also need to accommodate Q&A subsection with titles, and we 
may want to change the contents of Question to a #PCDATA mixture. Finally, we 
should call this a QandAList.

Day 2: We reviewed it and agreed to it, taking into account that 
Arbortext has used this model successfully for several years now.

Issue 47: Request for recursive division
Requested by: Michael Sabrio Submitted: 6/11/97 Resolved: 3.1
Type: enhancement Priority: medium Status: closed

Rationale

Reasonable request that can be accomodated easily.

Description

It is desired to have a generic and recursive division
structure parallel to the SectN hierarchy

6/11/97 Cambridge:

<!element chapter (title, stuff*, (div|sect1)>
<!element div (stuff*, div*)

This was discussed and approbated.

25 Oct 1998 Terry Allen:

requires modification to bookcomponent.content p.e.
declaration of Div, and addition of DivInfo to otherinfo.class,
all in dbhier.mod.  Proposed changes posted to the list, to
be inserted here when approved and when markup bug is fixed.

25 Oct 98.  Lost it by now; here are the diffs to dbhier.mod
instead:

96d95
<               |DivInfo
213,215c212,214
<         "((%divcomponent.mix;)+,
<         (Sect1*|(%refentry.class;)*|SimpleSect*|Div*))
<         | (Sect1+|(%refentry.class;)+|SimpleSect+|Div+)">
---
>   "((%divcomponent.mix;)+, 
>   (Sect1*|(%refentry.class;)*|SimpleSect*))
>   | (Sect1+|(%refentry.class;)+|SimpleSect+)">
634,660d632
< 
< <!ENTITY % div.module "INCLUDE">
< <![ %div.module; [
< <!ENTITY % local.div.attrib "">
< <!ENTITY % div.role.attrib "%role.attrib;">
< <!ELEMENT Div - - (DivInfo?, (%sect.title.content;), (%nav.class;)*,
<       (((%divcomponent.mix;)+, 
<       ((%refentry.class;)*|Div*))
<       | (%refentry.class;)+|Div+), (%nav.class;)*)
<       +(%ubiq.mix;)>
< <!ATTLIST Div
<       --
<       Renderas: Indicates the format in which the heading should
<       appear
<       --
<       Renderas    (Sect1
<               |Sect2
<               |Sect3
<               |Sect4
<               |Sect5)     #IMPLIED
<       %label.attrib;
<       %status.attrib;
<       %common.attrib;
<       %div.role.attrib;
<       %local.div.attrib;
< >
< <!--end of div.module-->]]>

including Sect1 in renderas, which I missed originally.

11/13/1998 f2f

Michael requested this; he doesn't have strong feelings on whether RenderAs should be
available in the recursive division element. The general feeling is that it doesn't make sense
to have RenderAs on Div. First of all, it doesn't seem to make sense; second, there can
potentially be many more levels of division than levels of section.

This is not an HTML DIV element.

DECISION: Change Terry's proposed model as follows: Change name to Section, and remove
RenderAs attribute. This is for V3.1.

Issue 48: Add related refs to access metainfo
Requested by: trsmith Submitted: Feb 20 1997 Resolved:  
Type: enhancement Priority: medium Status: rejected

Rationale

BLANK

Description

25 Oct 98:  no rationale; Terry declares this rfe rejected.

Issue 49: Add Subtitle to Book, Set, and Articles
Requested by: terry Submitted: Feb 19, 1997 Resolved: 3.1
Type: enhancement Priority: medium Status: closed

Rationale

Provides missing and required functionality.

Description

Sets, Books, and Articles may also have Subtitles, but can't in Docbook.

Solution: Add Subtitle to Sets, Book, Article, Chapter, Sect.

6/11/97 Cambridge:

should be listed as accepted, not open.

Nov 98:  we still agree on this.

Issue 50: Synopses should always be set-off objects
Requested by: eve Submitted: Tue Jan 21 13:23:12 PST 1997 Resolved:  
Type: docbug Priority: medium Status: closed

Rationale

Correction of error.

Description

General usage is to ignore the DTD comment defining these as "inline"
when inside paragraph-like elements.  Synopses are always understood as
set-off.

The DTD, for many years, has explained that the synopsis elements
are included in the para.char.mix entity because when a synopsis
appears in a paragraph-like element, the synopsis should be "inline."
However, we believe that no one understands this to be the case.

The synop.class entity can be referenced in either para.char.mix or
para.mix with identical effect.  However, to make clear that synopses no
longer have a "double life," the reference should be moved to para.mix
and the old DTD comment removed.

To get the effect of inline (wrapped) synopses in paragraphs, authors
should use Literal, Replaceable, Option, Optional, and other related
inline elements as necessary, without a main container element.

This is nominally a change in DocBook semantics and so is backwards
incompatible (though not in the syntactic sense that would require a
major revision to be put into effect).  However, the change in semantics
is not expected to cause problems for any users.

Nov 98:

DECISION: We agree that, wherever it appears, it gets set off. 
We need to clear up this conflict between the comment and the documentation.

Issue 51: Useful to control the point size and/or width of tables
Requested by: Lee Fogal Submitted: Jan 26 12:46:40 1997 Resolved:  
Type: enhancement Priority: medium Status: rejected

Rationale

DECISION: We agreed to reject this because every DocBook table user should 
abuse the model in their own unique way, in private.

Description

There is a need for controlling the presentation of tables for print
output.  The existing pgwide attribute on CALS tables has a specific
meaning: to span multiple columns (if any).  Overloading it to mean "reduce
the point size" or "extend to the gutter reserved for hanging heads" would
make DocBook tables less interoperable.

Should explicitly presentation attributes be added to tables?

Feb 1997:

Digital  controls point size of table text and the positioning using a
single Width attribute.  Others might have different ways of control.
Thus this isn't a good candidate for putting directly into DocBook.
We need to advise people how they can customize the table module.

This probably should be documented.

Nov 98:  we decided against.

Issue 52: Allow IndexTerm at lower levels than in 3.0
Requested by: Michael Sabrio Submitted: 26 Oct 1998 Resolved: 3.1
Type: bug Priority: medium Status: closed

Rationale

Necessary change for management of small chunks of text.

Description

Because DocBook specifies IndexTerm as an inclusion on Sect1
elements and above, we can't create and maintain valid
lower-level elements with IndexTerms.  What are the
chances we could specify IndexTerms so that they could be
included at arbitrary levels of the element hierarchy, at
least down to all the block-level elements.

Norm will publish the list of parameter entity changes attempted
in the XMLification for consideration in 3.1.

Make sure this includes IndexTerm in Glossary (RFE#28 closed as dup)

Nov 98 minutes:

We don't want to use even more inclusions to solve this problem, so then the issue becomes
how to allow IndexTerm in locations where adding it to *.mix and *.char.mix didn't help. We
suspect that Norm has already taken care of the "one-off" cases that really matter; we'll
wrangle about this on the mailing list.

ACTION: Norm will publish a list of the parameter entity changes he did in his DTD. This
will help clarify where this problem is already fixed and where we need additional "one-off"
solutions.

Issue 53: Allow names (%person.ident.mix;) in Address
Requested by: Tony Graham Submitted: 27 Oct 1998 Resolved: 3.1
Type: bug Priority: medium Status: closed

Rationale

Since Address already includes #PCDATA, there seems to be little benefit in adding a new wrapper.  Instead, %person.ident.mix will be allowed directly in Address.  In the future, a new element, PersonName, may be created, at which time it should also be allowed in Address.

Description

27 Oct 98.  In response to Tony Graham, Terry wrote:
At 16 Jul 1998 22:03 -0700, Terry Allen wrote:
 > Right, I see what you want to do, but I think the way to get there
 > is to add a name.and.address element that wraps both name and
 > address.  (To pick nits, "addressee" is apt for a mailing label
 > but not for a list of addresses ... but we will be planning the
 > nitpicking in San Diego in a couple weeks.)

Some problems with wrapping both name and address are:

 - Whitespace and line ends are significant in <Address>, and they are
   not significant in <Author>, <CorpAuthor>, <CorpName>, or
   <PublisherName>.  Handling linespecific and non-linespecific
   elements butted together would be odd, as would making a linespecific
   element to enclose the linespecific <Address> element.

 - <Author> may contain <AuthorBlurb>, which contains various forms of
   paragraph.  I would prefer to avoid the possibility of author
   blurbs in addresses.

I just checked some of the software manuals in my bookshelf, and many
of them contain addresses either in the preface or among the
bibliographic information, and several of those addresses do contain
authors' names, company division names, and company names. 

====

from same thread, 17 July 98, Terry wrote:
I wouldn't see any problem with a linespecific element inside
another ls el.

A name may indeed be part of an address (as on a mailing label),
but it may also be simply followed by an address (here is the
author's name and here is his address) in places where the name
is required, but the address is sometimes present but not always.
So I don't think we have a functional requirement to include
names within addresses (for software manuals, which are not
mailing labels - and we don't cover ads in software manuals ...);
our functional requirements are to find ways of marking up the
cases you and Kendall have found.  There will be some interplay
with whatever solution we find for plain names (without firstname
and surname).
                                           
Add %person.ident.mix to Address. 

Perhaps we need to add a PersonalName

Issue 54: Make sure example of SystemItem includes use of SystemItem
Requested by: Jochen Hein Submitted: 27 Oct 1998 Resolved:  
Type: docbug Priority: medium Status: closed

Rationale

Documentation is more useful if it is accurate.

Description

The example for SystemItem in the documentation does not use the element.

The example for SystemItem in the documentation should be replaced
with a proper one.

Nov 98:  accepted.

Issue 55: Request to change or amplify example for ManVolNum in documentation
Requested by: terry Submitted: 27 Oct 1998 Resolved:  
Type: docbug Priority: medium Status: closed

Rationale

We should fix confusing or incomplete documentation when someone is troubled 
by it.

Description

Documentation and example for ManVolNum could be clearer.

27 Oct 98.  Terry creates this rfe on basis of correspondence
from Nik Clayton:

Message-ID: <19980723100846.20352@iii.co.uk>
Date: Thu, 23 Jul 1998 10:08:46 +0100
To: davenport@berkshire.net
Subject: Re: DAVENPORT: Marking up references to man page sections
References: <199807211931.MAA07443@bolt.sonic.net>      

On Tue, Jul 21, 1998 at 12:31:23PM -0700, Terry Allen wrote:
> | The ManVolNum element isn't
> | appropriate as far as I can tell, because it's for references rather
> | than commands.
>
> I don't see why the documentation would lead you to believe that,

Partly my own lack of familiarity with some of the terms, I suspect.

When I was trying to work out how to do this (before posting to the list)
I went through the DocBook documentation at ora.com, in particular, the
element reference at

    <URL:http://www.ora.com/davenport/dbdoc/ref/element.html>

I saw 'ManVolNum', but (at least to these eyes) the example doesn't look
like a Unix man page reference -- in fact, if I understand it right,
'RefMeta' isn't the right element to use.

Going back through the 'ManVolNum' info and following the link to
'CiteRefEntry' also doesn't lead to anything that looks remotely like        
a Unix manual page reference.

> but in any event that's not the case.  Refentries can be used for commands,

That's very true, and had my brain made the connection between 'RefEntry'
and 'Unix manual page' I would probably have been fine.

Perhaps the following

    <CITEREFENTRY>
    <REFENTRYTITLE>cat
    </REFENTRYTITLE>
    <MANVOLNUM>1
    </MANVOLNUM>

could be added to the 'ManVolNum' examples?

N
--
Work: nik@iii.co.uk

Nov 98:  Norm to do this.

Issue 56: Add att to LiteralLayout to indicate font.
Requested by: norm Submitted: 27 Oct 1998 Resolved: 3.1
Type: bug Priority: medium Status: closed

Rationale

Clarifies processing expectations and allows flexibility.

Description

LiteralLayout isn't monospaced by default, but people want to use it that way.

27 Oct 98.  Terry's summary from email:

Date: Tue,  3 Mar 1998 10:25:55 -0500
Add

<!ATTLIST LiteralLayout
  Class  (Monospaced|Normal)  Normal
>

In my experience, most people expect LiteralLayout to be in Courier.
Since it isn't, one is forced to abuse the Screen tag for non-Screen
things to get verbatim presentation.  Tag abuse is bad ;-)

--norm

Date: Tue, 03 Mar 1998 10:33:24 -0500
Aha...  And ProgramListing would also be tag abuse in these cases?

        Eve

Nov 98:  we agreed to add the attribute.

Issue 57: ULink should be allowed in docinfo.char.mix
Requested by: terry Submitted: 27 Oct 1998 Resolved: 3.1
Type: bug Priority: medium Status: closed

Rationale

It seems reasonable to link from places like Holder in Copyright.

Description

27 oct 98.  Terry summarizes from email:

Subject: DocBook bug: Add ulink to docinfo.char.class?
From: Norman Walsh <norm@berkshire.net>

In particular,

  <copyright><year>1998</year>
    <holder><ulink url="http://www.arbortext.com/">ArborText, Inc.</></holder>
  </copyright>

might be nice...

--norm

Subject: Re: DocBook bug: Add ulink to docinfo.char.class?
In-Reply-To: <98Feb16.083705est.18822@thicket.arbortext.com>

This makes sense.  In fact, ulink (as an <a> equivalent) is probably useful
to allow in all #PCDATA mixtures, if it's not already.

        Eve

Nov 98:  agreed to add it in docinfo.char.class and not worry about
its availability in other places pending completion of XLink.

Issue 58: optmult and reqmult options on Group should be removed
Requested by: Eve Submitted: 27 Oct 1998 Resolved: 4.0
Type: bug Priority: low Status: closed

Rationale

Group's optmult and reqmult options mean the same thing.

Description

From: "Eve L. Maler" <elm@arbortext.com>
Subject: ISSUE: optmult-reqmult-redundant

ISSUE: optmult-reqmult-redundant
SUBMIT DATE: 27 January 1998
SUBMITTER: elm
SUMMARY: optmult and reqmult options on Group should be removed
TYPE: BUG
SEVERITY: 4
PRIORITY: 4
STATUS: OPEN
RATIONALE:
DESCRIPTION:
The optmult and reqmult options on Group are redundant because they mean
"zero or more" and "one or more".  If you have "opt" and "repeat" or "mult"
and "repeat", it amounts to the same thing.

I thought we had decided a long time ago to remove these (I recall Steve
Hiebert noticing it), but I guess it never got into the official issues
list.

Nov 98: We're already scheduled to do this in V4.0.

Issue 59: Clarify documentation for usage of Void
Requested by: terry Submitted: 27 Oct 1998 Resolved:  
Type: docbug Priority: medium Status: closed

Rationale

There may be some confusion.

Description

27 Oct 98.  Terry summarizes from email (but doesn't pretend to understand):

Subject: Re: More on Void...
References: <199704281720.KAA00033@bolt.sonic.net>
From: Norman Walsh <norm@berkshire.net>
Date: 28 Apr 1997 13:47:02 -0400

Terry Allen <tallen@sonic.net> writes:
> If you'll write a bug report that says what the change to the doc
> should be, that would help.

FWIW, I described it thusly:

<para>
The <sgmltag>Void</> element indicates explicitly that a <sgmltag>Function</>
has no arguments.
</para>

<para>
See also: <sgmltag>VarArgs</> and <sgmltag>ParamDef</>.
</para>
    
<refsect2><title>Processing Expectations</title>
<para>
The string ``(void)'' should appear in the output where <sgmltag>Void</>
is used.
</para>
</refsect2>
        
From Dennis.Evans@Eng.Sun.COM Tue Apr 29 08:25:54 1997
To: tallen@sonic.net, norm@berkshire.net
Subject: Re: More on Void...
Cc: elm@arbortext.com, dennis.evans@Eng.Sun.COM

++ <refsect2><title>Processing Expectations</title>
++ <para>
++ The string ``(void)'' should appear in the output where <sgmltag>Void</>
++ is used.
++ </para>
++ </refsect2>

One problem I see with the Processing Expectations is that the
<function> tag often is the element that causes the ()'s to be
generated. If what is said here were to happen the result of

<function>foo</function><void>

would be

foo((void));       

I think the correct description should be

<refsect2><title>Processing Expectations</title>
<para>
The string ``void'' should appear in the output where <sgmltag>Void</>
is used.
</para>
</refsect2>

Nov 98:  ACTION: Norm to soften the documentation to say that using void 
generates "an indication that there are no parameters."

Issue 60: Clarify processing expectations for endterm on Link
Requested by: norm Submitted: 27 Oct 1998 Resolved:  
Type: docbug Priority: medium Status: closed

Rationale

Endterm wins.  In SGML, we could make it CONREF and content wouldn't
be allowed, but we'll be moving to XML and won't be able to use CONREF.

Description

27 oct 98.  Terry summarizes from email:

Subject: Processing expectations of Link...
From: Norman Walsh <norm@berkshire.net>
Date: 29 Apr 1997 09:41:34 -0400
Message-ID: <qad8req73l.fsf@norm.berkshire.net>

I see that Link has an Endterm attribute.  The meaning of Endterm on, e.g.,
Xref, is fairly clear since Xref is empty, but what does this mean:

<chapter><title rfenumber=foo>Chapter Title</title>
<para>
This <link endterm=foo>pointer</link> is point<emphasis>less</>.
</para>

Or is that intended to be verboten.  If I use Endterm, should I say
<link endterm=foo></link>.  In which case, er, shouldn't Endterm be
#conref?

--norm

Issue 61: Allow subtitle as an optional sibling to title
Requested by: terry Submitted: 27 Oct 1998 Resolved: 3.1
Type: bug Priority: medium Status: closed

Rationale

Subtitle isn't allowed for book components, but should be.

Description

27 Oct 98.  Terry summarizes from email:

Date: Tue, 11 Nov 1997 13:34:51 -0800
Message-Id: <2540-Tue11Nov1997163401-0500-norm@berkshire.net>
From: Norman Walsh <norm@berkshire.net>
To: Multiple recipients of list <davenport@amber.ora.com>

I was tinkering with the DSSSL DocBook stylesheet this morning, adding
support for subtitles here and there and I discovered the following:

In order to provide a subtitle for a chapter, you must use <DocInfo>.
Once you put <Subtitle> in <DocInfo>, it seems reasonable to put
<Title> in there as well.  Alas, you can't omit the <Title> as a child
of <Chapter> so you wind up with either:

<chapter>
<docinfo>
  <title>this is my title</title>
  <subtitle>this is my subtitle</subtitle>
</docinfo>
<title>this is my title</title>

or
            
<chapter>
<docinfo>
  <title>this is my title</title>
  <subtitle>this is my subtitle</subtitle>
</docinfo>
<title>this is my title</title>

or

<chapter>
<docinfo>
  <subtitle>this is my subtitle</subtitle>
</docinfo>
<title>this is my title</title>

I'm not suggesting that it's really a problem, but if no one
else has seen it, I thought I'd at least pass it along...I
suppose Title could be optional on Chapter, but then one would
have to deal with untitled chapters, so...

--norm    

From norm@berkshire.net Thu Nov 13 05:17:54 1997
To: Terry Allen <tallen@sonic.net>
Subject: Re: subtitle on chapter
References: <199711122341.PAA22449@bolt.sonic.net>

Terry Allen <tallen@sonic.net> writes:

> That was it.  Thanks.  I'd go for Title, Subtitle?, TitleAbbrev?, because
> the first two are logical content, but TitleAbbrev is only to be used when
> presentation circumstances require it.

No argument.

--norm

Date: Thu, 13 Nov 1997 13:51:03 -0800
Message-Id: <0042700003869441000002*@MHS>
From: Sara.Mitchell@smed.com
To: Multiple recipients of list <davenport@amber.ora.com>
Subject: re subtitle on chapter

Not sure if these examples are really what you had in mind, but I can think of
two instances where subtitle for Chapter or Sect1 would be useful. I've never
seen any need below Sect1, however.

---------------------- Forwarded by Sara Mitchell/SMS on 11/13/97 01:31 PM
---------------------------
Terry Allen wrote:
...
>No, it's a problem.  In fact, I've had it in mind since our discussion
>of the multiple places to put Title in Book, which resulted in
>(thanks to Dennis Evans),
>ISSUE:subtitle
>SUBMIT DATE: Feb 19, 1997
>SUBMITTER: tallen
>SUMMARY: Add SubTitle to Book, Set, and Articles
>TYPE: RFE
>PRIORITY:  3
>SEVERITY:  3
>STATUS:  ACCEPTED
>RATIONALE:  Sets, Books, and Articles may also have SubTitles

>Subtitle was originally absent but later was added as
>part of the metadata but not to the regular content models.  That was
>either an oversight or a judgement that in software doc chapters don't
>have subtitles (I suppose you have an example that shows the
>contrary ...).  I've forgotten which.  In any event, the cure is to
>decide that any book component that may have a Title may have a Subtitle,
>and to add Subtitle to the various *.title.content parameter entities
>as appropriate, I suppose between Title and TitleAbbrev (or, as it will
>be in XML, title and titleabbrev, hooray).

>Before we decide that's right, though, 1) does anyone have examples of
>subsubtitles, or other funny business (in software doc)?  I can
>give you any number of examples from print publishing in general,
>but for Docbook's domain, is Title, Subtitle sufficient for book
>components?  and 2), can lower-level textforms have subtitles, such
>as FormalPara and Sects?  This would be an outright oddity in general
>print publishing, but if anyone knows of an example in software doc,
>please present it!     

We have two cases where I would have choose to use Subtitle rather than
TitleAbbrev, if it is available. The first example is a book with
conceptual discussions of how to leverage setup of our software to meet
different business needs in our market (healthcare). Business practices
vary depending on the area of specialization, such as a Psychiatric hospital
versus a community hospital or a Rehabilitation clinic.

We decided to use Article as the container of each conceptual piece...but
in some cases chapter may have been a better wrapper. Since the content
needs to clearly relate both to the specialty and to the setup areas
within our software (for our internal audience), having two titles was
important.

The other case is in reference information for functions.  We don't use
the FuncSynopsis or RefSection pieces because we're not creating Man Pages
and the structures didn't readily fit in with our existing documentation
organization. We've been using Sect1s instead (with an appropriate Role).

In this case, we need both the system name for the function and a fuller
English name to more clearly indicate the purpose of the function. Having
Subtitle for the English name would be particularly useful.    

Sara Mitchell
SMS
Sara.Mitchell@smed.com

Nov 98:  agreed to do this.

Issue 62: Add Superscript, Subscript, Emphasis to bibliocomponent.mix
Requested by: terry Submitted: 27 Oct 1998 Resolved:  
Type: bug Priority: medium Status: rejected

Rationale

These elements are needed in title.char.mix, not bibliocomponent.mix.  And
they're already allowed there.

Description

Superscript, Subscript, Emphasis are missing from BiblioMixed, but are needed.

28 Oct 98.  Terry renames and amplifies rfe (was originally only
re Superscript).

Superscript is used in some languages for abbreviations that appear
in bibliographic citations.  To allow it in BiblioMixed we need to
add it to bibliocomponent.mix.  I haven't used Subscript yet, but
it would be reasonable to add it at the same time.  And Emphasis 
occurs sometimes, too.  So add them all.

Nov 98:  This RFE revealed as a case of sloppy thinking by Terry.
Never mind.

Issue 63: Clarify processing expectation of Title in or outside *Info.
Requested by: terry Submitted: 27 Oct 1998 Resolved:  
Type: docbug Priority: medium Status: closed

Rationale

Issue needs clarification.

Description

Need to clarify what the processing expectations are for Title inside
vs. outside *Info.

27 Oct 98. Terry summarizes from email:

Date: Fri, 11 Jul 1997 09:21:08 -0700 (PDT)
From: Documentation Group <writers@odie.allegra.com>
To: Terry Allen <tallen@sonic.net>
Subject: Re: Title duplication

Works for us and sounds very reasonable.

Sara Mitchell
SMS

[Michael Sabrio also agreed.]

Date: Tue, 22 Jul 1997 15:33:15 -0400
Sender: davenport@amber.ora.com
From: "Eve L. Maler" <elm@arbortext.com>
To: Multiple recipients of list <davenport@amber.ora.com>
Subject: Re: Title duplication

I like your proposed wording, and I agree that we don't *absolutely need* a
specific question in the checklist about this.  However, interchange
partners should be saying somewhere how they use Title, whether as the
answer to a more-general checklist question or somewhere else.  Otherwise,
results will vary...   

        Eve

At 06:06 PM 7/10/97 -0400, Terry Allen wrote:
>Here's how I'd like to change the documentation to accord with reality:
>
> - eliminate the warning that you should choose either Title within
>       Book or Title within Bookinfo as one single place to put
>       your Book's Title.
> - replace it with something like the following:
>
>       "Docbook's structure allows Titles both directly within
>        Books, Book components, and Sects, and within their
>        associated metadata containers (*Info).  If you put a
>        Title in both places, be sure it is the same in both
>        places; the results of processing documents in which
>        Title differs in these two locations is undefined
>        by this specification."
>
>   in other words, I don't want to add this issue to the interchange
>   checklist, only point it out as a possible pitfall.
>
>Regards,                                        
>  Terry Allen    Electronic Publishing Consultant    tallen[at]sonic.net

Date: Thu, 24 Jul 1997 09:54:45 -0400
To: Terry Allen <tallen@sonic.net>
From: "Eve L. Maler" <elm@arbortext.com>
Subject: Re: Title duplication

I think you'll find that the checklist does a pretty good job of asking
general questions about processing expectations and the like.  It's a good
idea to pose questions where we know there's been some interchange strife,
so if you think we should add a specific Title duplication question, I
could agree with that.  But there's no reason to have a question for each
*Info element...

>>I like your proposed wording, and I agree that we don't *absolutely need* a
>specific question in the checklist about this.  However, interchange
>partners should be saying somewhere how they use Title, whether as the
>answer to a more-general checklist question or somewhere else.  Otherwise,
>results will vary...
>
>Note how many places this now crops up because we specialized *Info.
>It would be a hefty piece of the checklist.  If you put the same thing
>in both places you should never get a wrong result (if you do, the       
>implementation is broken).
>
>More generally, we're going to have to start thinking of interchange
>(though not just yet for Docbook) as including processing info such
>as style sheets.

Nov 98:  already agreed to.

Issue 64: Add RevHistory to GlossEntry
Requested by: terry Submitted: 27 Oct 1998 13:58 Resolved: 3.1
Type: bug Priority: medium Status: closed

Rationale

RevHistory is wanted on GlossEntry much more than on GlossTerm.

Description

27 Oct 98:  Terry summarizes from email:

Date: Mon, 4 Aug 1997 16:13:48 -0400
From: Norman Walsh <norm@berkshire.net>
To: Multiple recipients of list <davenport@amber.ora.com>
Subject: RevHistory in GlossEntry...

I see that RevHistory is allowed in GlossTerm (!?) but not in
GlossDef.  This strikes me as odd.  RevHistory, being a
block-level element, is tricky to deal with in GlossTerm, which
is an inline (even in a GlossEntry).  I expect it's present by
accident.

I propose removing RevHistory from GlossTerm and adding it to
GlossEntry.  It would be a backwards-incompatible change for
V5.0, if accepted.

If asked, I'd recommend putting it first, or just before GlossDef,
but I don't much care.

<!ELEMENT GlossEntry - - (GlossTerm, Acronym?, Abbrev?,
                          RevHistory?
                          (GlossSee | GlossDef+))

                                        Cheers,    
                                          norm

Date: Tue, 05 Aug 1997 10:04:14 -0400
To: tallen@sonic.net
From: "Eve L. Maler" <elm@arbortext.com>
Subject: Re: Re RevHistory in GlossEn
Cc: Multiple recipients of list <davenport@amber.ora.com>

A few comments:

o I agree that RevHistory isn't inherently a block element; it's a metadata
("document information") element.  However, in practice, I've most often
seen it formatted as a block element.  FWIW, in our internal use of
DocBook, ArborText formats RevHistory in BookInfo as a pseudo-table, and
then grabs some of the fields of the final Revision element and puts them
in the running footer, so you can easily see which rev of the document
you've got.

o RevHistory is one of those roving metadata elements that I don't think
should be allowed in random places.  So if I had my druthers, I'd
FU-announce it (and maybe a host of others) for removal from these mixtures
unless someone could demonstrate a need.  Then again, I'm happy to leave      
well enough alone, unless I'm not the only one complaining.

o Norm, it sounds like you want to track changes made to a glossary entry.
This suggests that a glossary entry may be a big enough "chunk" to deserve
its own metadata, for tracking and identification and what-all.  If this is
the case, and this is a more general need, the right solution would be to
examine giving glossary entries their own *Info element and to consider
what elements should be allowed inside it.

        Eve

At 06:32 PM 8/4/97 -0400, Terry Allen wrote:
>Norm writes:
>| I see that RevHistory is allowed in GlossTerm (!?) but not in
>| GlossDef.  This strikes me as odd.  RevHistory, being a
>| block-level element, is tricky to deal with in GlossTerm, which
>| is an inline (even in a GlossEntry).  I expect it's present by
>| accident.
>
>In GlossTerm, by happenstance (though %para.char.mix;).  GlossDef
>contains (through %glossdef.mix;) various things that can contain
>RevHistory, such as paragraphs.  If you want RevHistory on GlossDef
>as a whole, that's something different (and okay, but where all   
>else do you want the same capability, e.g., for ListItem?).
>
>| I propose removing RevHistory from GlossTerm and adding it to
>| GlossEntry.  It would be a backwards-incompatible change for
>| V5.0, if accepted.
>
>Removal would be b-i, but addition wouldn't be.  However,
>
>| If asked, I'd recommend putting it first, or just before GlossDef,
>| but I don't much care.
>|
>| <!ELEMENT GlossEntry - - (GlossTerm, Acronym?, Abbrev?,
>|                        RevHistory?
>|                        (GlossSee | GlossDef+))
>
>The structure here is that GlossEntry (which is really keyed to
>the single GlossTerm - that's what identifies the entry) can
>have more than one GlossDef.  Say there are three GlossDefs;
>all can be revised independently of the others.  So we want to
>retain RevHistory at least in GlossDef's children.
>
>We might also want to add it to GlossEntry, as you suggest (I agree
>it seems unneeded in GlossTerm); that would be something different        
>again from what we have now (but also okay).
>
>I would say that RevHistory isn't a block element, based on
>the parameter entities in which it occurs; the man page
>
>  http://www.ora.com/davenport/dbdoc/ref/refpages/revhi.htm
>
>doesn't indicate how it should be formatted.
>
>Separately, it occurs to me that we may be unclear in the doc
>about what the scope of a RevHistory is (it applies to the immediate
>parent is the only sensible rule I can think of); if so, that unclarity
>will be present in a lot of other places.
>
>One way of solving this problem would be to make
>*Info elements that can be children of the all the elements
>to which you might conceivably want to apply RevHistory (let's
>not).  Or we could make a common attribute that can point off to
>somewhere else (such as the nearest *Info element up the
>hierarchy), where the RevHistory could be stored.
>
>Comments?

Accepted; just before the glossdef. Removing it from glossterm in 5.0 (FU).

Issue 65: Additional inlines for Linux documentation
Requested by: terry Submitted: 27 Oct 1998 14:15 Resolved: 3.2
Type: bug Priority: medium Status: closed

Rationale

These items are the ones that were explicitly requested and that we thought made sense. Additional requests are welcome. One criteria for selection was
whether or not you would want to search on it.

Description

In San Jose 3/7/1999, we decided to:

Add 'devicefile' and 'libraryfile' to Filename
Add 'username' and 'groupname' to SystemItem
Add 'library' to SystemItem

We did not address makefile targets because we a more complete case.
Is marking up dependencies also a requirement? What are the processing
expectations of text marked up.

---

Linuxdoc folks are finding they want some new inlines.

27 Oct 98.  Terry summarizes from email:

Date: Mon, 22 Jun 1998 09:15:36 -0400
Message-ID: <9316-Mon22Jun1998091536-0400-ndw@nwalsh.com>
To: davenport@berkshire.net
Subject: Re: DAVENPORT: Available extensions to DocBook?
From: Norman Walsh <ndw@nwalsh.com>

/ Nik Clayton <nik@nothing-going-on.demon.co.uk> was heard to say:
| I'm midway through a process converting ~ 1MB of documentation marked up
| using LinuxDoc to DocBook. The DocBook DTD seems to be missing elements for
| marking up certain information -- I don't see this as a fault of the DTD,
| and it will be easy to extend.
|
| The information I will be marking up includes

Extensions may be the way to go here.  But if you want to avoid them,
I'd suggest the following (verbose though they are):
|     Unix user names and groups
<systemitem role="username">, <systemitem role="group">?
|     Hostnames and domain names
<systemitem class="systemname>
|     Device names
<filaname role="device"> (And I think DocBook should add
class="device" for this case.)     
|     Makefile variables
There are a number of variable related inlines.  <replaceable> is one
possibility.
|     Makefile targets
|     Library names (e.g., 'crypt', 'c', 'alias' and so on).
Er, nothing springs to mind.  <literal> or <systemitem> with
another role, I guess.
|     FAQ questions and answers
<variablelist>, with a role if desired.

Nov 98:
People need some new inlines. We could add new Class attribute values on 
SystemItem of "username" and "group". We could add a new Class attribute 
value on FileName of "device".  For makefile variables, they could use the 
new VarName and this might suffice. For makefile targets, we don't know.

Issue 66: Add att to CmdSynopsis to indicate Command length?
Requested by: terry Submitted: 27 Oct 1998 14:45 Resolved: 3.1
Type: bug Priority: medium Status: closed

Rationale

Sometimes you need a little help.

Description

Line breaking is difficult with long Commands in CmdSynopsis.

27 Oct 98.  Terry summarizes from email:

From norm@berkshire.net Thu Nov 20 07:30:26 1997
To: Dennis.Evans@eng.sun.com (Dennis Evans)
Cc: tallen@sonic.net, elm@arbortext.com
Subject: Re: DocBook buglet report

> To reiterate, the important issue is not so much the indent, but that
> a synopsis line not be broken up inappropriately.

You can insert a line break with <SBR>.

--norm

[Dennis remarked that SBR was missing from Sunbook.]

From norm@berkshire.net Thu Nov 20 07:31:38 1997
To: Terry Allen <tallen@sonic.net>
Cc: Dennis.Evans@eng.sun.com, elm@arbortext.com
Subject: Re: DocBook buglet report

> [ omitted ]
>
> For this I'm inclined to push back and say you should use a
> processing instruction.  An attribute to indicate that a synopsis is   
> more than a line long can apply to the element in general, but for
> this example don't you need to indicate exactly where the breaks
> should be, and not leave it up to your line-breaking algorithm?

Now, since we have TERMLENGTH on VARIABLELIST and SBR which Terry had
forgotten about, does that help further my argument that we can/should
add an attribute to CMDSYNOPSIS to indicate the command length
(COMMANDLENGTH, for example ;-)

--norm

[Terry replied:]
Yes.

From Dennis.Evans@Eng.Sun.COM Mon Nov 17 18:04:18 1997
To: tallen@sonic.net, nwalsh@arbortext.com, elm@arbortext.com
Subject: Re: DocBook buglet report

I don't know if there was a resolution to Norm's original question
about adding an attribute to aid in making the line break correctly
within a cmdsynopsis, but I am *very* interested in the answer.

After talking to the person here who maintains our print FOSI, it seems       
that we would need some sort of indicator that the line can break at
certain locations. Or to put it another way, specify that parts of the
command synopsis should stay together.

To reiterate, the important issue is not so much the indent, but that
a synopsis line not be broken up inappropriately.

[-k filename ] is easier to read than

 blah blah blah blah blah blah blah blah blah blah blah blah blah [-k
filename]

or

blah blah blah blah blah blah blah blah blah blah blah blah blah [
-k filename ] blah blah blah blah blah blah blah blah blah blah blah

Particularly when it is part of several lines of options. Here is an example of
a long cmdsynopsis. This formats to three lines.

[example omitted, but very long]                         

===

Terry wonders in October if this isn't a job for a PI ...

Nov 98:
DECISION: We agreed to add a cmdlength attribute with the same semantics as 
termlength.  That is, the potential units of measurement should be borrowed 
from CALS tables. (This should be documented better.)

Issue 67: give Article Title, TitleAbbrev outside ArtHeader
Requested by: terry Submitted: 22 Jan 1997 Resolved: 3.1
Type: enhancement Priority: medium Status: closed

Rationale

Consistency and utility.

Description

All the other book component elements must have a Title
outside of their *Info container.  Article is an exception, and
should be made consistent with the others.  For discussion:  Sets, Books,
and Articles, unlike software doc Chapters, may also have Subtitles.
Add Subtitle to those elements outside *Info also?

Add v.title.content to the content model for Article.

Feb 1997:

We want to allow optional div.title.content before the
ArtHeader/ArticleInfo at the next release.  We want to change the 
section metadata to match the Book/Article order.

Nov 98: agreed to align Article with other parts of Docbook in
this respect.

Issue 68: Parameterize the inclusions and exclusions to make customization easier.
Requested by: Glenda Jeffrey Submitted: Resolved: 3.1
Type: bug Priority: medium Status: closed

Rationale

Parameterizing exclusions makes certain kinds of customization layers much, much easier. During integration, extended to all inclusions and exclusions.

Description

Glenda asked how to minus out all of the ubiq.mix contents.  If you do
it, what's left in the element declarations is "+()", which is illegal.  We
should parameterize the DTD a little differently so that ubiq.mix (or an
equivalent with a more appropriate name) contains the entire inclusion
clause, such as "+(%ndxterm.class;...)".

The workaround for now is to modify *all* the element declarations that
have ubiq.mix, to remove that entire clause.

Feb 1997:

It was decided to add a level of parameter entity for ubiquitous
inclusion/exclusions that references ubiq.mix and contains the
plus/-sign and the parentheses.  If you re-define the new level of
parameter entity as null, you can easily subset out the ubiquitous
elements.

<!EN % ubiq.exclusion "-(%ubiq.mix)">
<!EN % ubiq.inclusion "+(%ubiq.mix)">

Nov 98:  agreed.

Issue 69: Permit underscore in SGML names
Requested by: eve Submitted: Fri Jan 10 16:31:59 PST 1997 Resolved: 3.1
Type: bug Priority: medium Status: closed

Rationale

Removal of pointless inconvenience.

Description

Underscore in SGML names: This is a relatively high-level problem that
various DocBook users keep running into.

Feb 1997:

Using the extended SGML declaration would allow underscores in names.
Underscores will be permitted as long as the full iso 10646
declaration is used.

We initially agreed to provide our present SGML declaration and a full
10646 declaration plus at least one other method as an example, with
advisory wording.

Keep the shortref feature but provide a null set of shortref
delimitors.

Nov 98:  agreed to make this possible even before we shift to XML,
if we can.

Issue 70: Add generic linking ability to all elements.
Requested by: Murray Maloney Submitted: Feb 1997 Resolved: 5.0
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 71: Markup is needed for variable names
Requested by: eve Submitted: Jan 26 12:46:40 1997 Resolved: 3.1
Type: enhancement Priority: medium Status: closed

Rationale

This is an obvious hole, given DocBook's scope.  Also, since some 
software comes with predefined variables, this is a natural opportunity 
for doing more than just typographical emphasis (e.g., automatic linking 
and indexing).

Description

DocBook already has Replaceable for "variable value placeholders" that 
have no official name (such as "filename" appearing in the place where
a user should supply the filename of interest).  And it already has
EnVar for environment variables.  What it doesn't have is a way to mark
up the names of programming variables, which in some cases are not
user-defined but are supplied as part of the software (e.g., argv).

Calling such an element Variable is problematic because of the potential
confusion between the variable's name and its value.  We settled on
VarName, and tentatively decided to add it to the technical-terms
class and give it smallcptr.mix content.

We are still considering whether to add a VarValue element in.
People generally use Literal now for such values.  Since the values
are by their nature ephemeral, they would benefit less from specific
markup.

Feb 1997:

A new element, Varname, for the name of a variable, not its value will
be added.  The documentation should clearly state that this isn't the
"Name that varies"; it's the handle you use to set or get values.

Nov 98:  agreed.

Issue 72: Does DocBook need to be compatible with XML?
Requested by: eve Submitted: Jan 26 12:19:36 1997 Resolved:  
Type: enhancement Priority: medium Status: rejected

Rationale

Want to support the future and the past.

Description

SGML-only DocBook will be phased out in favor of something new that is both SGML and XML compliant.

Some changes to DocBook's physical structure would be needed.  E.g.,
XML comments must be self-contained markup declarations; they cannot
appear inside other markup declarations.  Also, multiple-element
declarations would need to be broken out (which is planned to be done
anyway).

More seriously, changes to DocBook's markup specifications would be
needed.
E.g., [R]CDATA elements (Graphic, InlineGraphic, SynopFragmentRef)
would need to become either #PCDATA or EMPTY.  (The latter is being
considered for a future version of the graphic elements.)  Also, the
mixed content models would need to use an optional-repeatable
occurrence indicator.

The SDATA character entity sets would not be usable with XML
applications, but it is reasonable to expect that users could
substitute XML-ready character entity sets that use numeric character
references of some kind.

Finally, the omitted-tag specifications in the DTD would have to be
removed, or at least parameterized for easy removal.

This description is the result of a cursory examination.  Other changes
may also be necessary.

Feb 1997:

See meeting minutes nad DuckBook discussions.

Nov 98:  agreed in principle.  Eduardo proposed, and we agreed, to
carry SGML-only Docbook no farther than 5.0 (we want to get that far
so that presently contemplated backward-incompatible changes will
be available to SGML users), and then go forward with an XML
version (version numbering to restart, perhaps with a name change)
that is also compatible with SGML tools (for example, in parameterizing
the occurrence indicators).

Issue 73: BookBiblio and SeriesInfo will be removed from BiblioEntry
Requested by: terry Submitted: 21 Jan 1997 Resolved: 4.0
Type: bug Priority: medium Status: closed

Rationale

Migration toward improved and more consistent model of bibliographic info.

Description

BiblioEntry should contain only bibliocomponent.mix.  BookBiblio
and SeriesInfo are included only for backward compatibility, and
FU comments warn they will or may be dropped entirely in 4.0.

An FU comment about this change is already present in 3.0.

Nov 98: reviewed and continued to agree.

Issue 74: Remove RevHistory from GlossTerm
Requested by: nwalsh Submitted: 14 Nov 1998 11:37 Resolved: 5.0
Type: bug Priority: medium Status: closed

Rationale

dupe of #75

Description


Issue 75: Remove RevHistory from GlossTerm
Requested by: norm Submitted: 14 Nov 1998 16:47 Resolved: 5.0
Type: bug Priority: medium Status: accepted

Rationale

Tweak for utility.

Description

RevHistory has been added to GlossEntry.  It seems unlikely that you'd need
it on both GlossEntry and GlossTerm (or GlossTerm and GlossDef separately).
A better mechanism for tracking revision history information may need to be developed.

Nov 98:

DECISION: We agreed to add RevHistory just before the GlossDef (or whatever), to indicate
the revision history for the GlossEntry as a whole. This is a weird place to put it, but no more
weird than adding it anyplace else. We agreed to FU-announce in V4.0 the removal of
RevHistory from GlossTerm in V5.0.

Issue 76: Remove Constant class value for SystemItem
Requested by: norm Submitted: 15 Nov 1998 11:19 Resolved: 5.0
Type: bug Priority: medium Status: accepted

Rationale

Part of reworking inlines.

Description

With the addition of the Constant element, a Constant class value on SystemItem is redundant.

Nov 98:  FU-announce in 4.0 the removal of the class value in 5.0.

Issue 77: Add MediaObject
Requested by: norm Submitted: 15 Nov 1998 11:46 Resolved: 3.1
Type: enhancement Priority: medium Status: closed

Rationale

Increase functionality while improving structure.

Description

Broader support for video and audio formats has been a long standing request. Support for text (and other fallback) alternatives is often requested.

Nov 98:

(from "alt-on-graphic"):
DECISION: We plan to offer a "proper" solution in V4.0, and deprecate the old Graphic
element in an FU note, for removal in V5.0.

Note that the existing FU for Graphic and InlineGraphic are, according to our new plan,
incorrect. We'll back off of the previously stated V4.0 action for these.

ACTION: Eve to propose immediately a model for additional video, audio, and graphic
object elements that use empty video data, audio data, and graphic data elements respectively.
It will include a subproposal for an appropriate metadata header. She will also resubmit the
informal figure proposal.

Day 2:  we reworked the proposal and came up with a new one that we think
will work better (avoiding recursion of alts).  We considered several 
cases Eduardo had actually encountered.

(historical:  cf. nos 3, 4, and 5)

Issue 78: InlineGraphic and Graphic will be removed
Requested by: norm Submitted: 15 Nov 1998 11:48 Resolved: 5.0
Type: bug Priority: medium Status: accepted

Rationale

Part of #77

Description

Nov 98:

InlineGraphic and Graphic will be superseded by MediaObject and will 
therefore be phased out.  (see #77)

Issue 79: Release notes should mention change to declaration
Requested by: norm Submitted: 16 Nov 1998 06:10 Resolved: 3.1
Type: docbug Priority: medium Status: closed

Rationale

Some tools don't read the declaration

Description

The release notes for 3.1 should mention our change to the declaration.
Some tools don't read the declaration, so additional work may be needed at some locations.

Issue 80: DocBook should use the exchange table model
Requested by: norm Submitted: 18 Nov 1998 07:09 Resolved: 5.0
Type: enhancement Priority: medium Status: accepted

Rationale

In the interest of tools interoperability, we've long felt that moving to
the exchange table model would be a good idea. The move to XML seems like
a good time to do it.

Description

DocBook should use the exchange table model and, in particular, should 
migrate to the XML version of the exchange model, when it is available.

Issue 81: Sidebar should have a *Info element
Requested by: norm Submitted: 18 Nov 1998 07:33 Resolved: 3.2
Type: bug Priority: medium Status: closed

Rationale

Consistency and response to user requirement.

Description

Sidebars may be authored and stored separately.  It should be possible to add 
bibliographic metadata to Sidebars (and Chris M of O'Reilly has an actual
case of this).  We should add an optional SidebarInfo element to 3.1.

Issue 82: add citetitle to bibliocomponent.mix
Requested by: terry Submitted: 14 Dec 1998 15:41 Resolved: 3.1
Type: bug Priority: medium Status: closed

Rationale

See description.

Description

bibliocomponent.mix incorrectly allows Title, but not CiteTitle.  It's
CiteTitle one wants to use, because it has the correct semantics for
referring to rather than providing a title, and because it has an
attribute for saying what kind of thing the title pertains to, which
is needed for differentiating the rendering of article and book titles
in a bibliography.  So what needs to be done is:

Add CiteTitle to bibliocomponent.mix in 3.1.

"Add CiteTitle to bibliocomponent.mix in 3.1." -TA

[Split into 3]

Issue 83: remove Title from bibliocomponent.mix
Requested by: terry Submitted: 14 Dec 1998 18:48 Resolved: 5.0
Type: bug Priority: medium Status: accepted

Rationale

Description

See RFE 82; this RFE completes the shift from Title to CiteTitle in
bibliocomponent.mix.

In 4.0, warn that Title will be removed from bibliocomponent.mix in 5.0.
In 4.0, warn that the content of CiteTitle will be changed (reduced)
   from para.char.mix (which inappropriately allows synopses) to
   title.char.mix.
In 5.0, make those two changes.

Issue 84: Adjust content of CiteTitle
Requested by: terry Submitted: 14 Dec 1998 18:50 Resolved: 5.0
Type: bug Priority: medium Status: accepted

Rationale

Description

See RFE 82; this RFE adjusts the content of CiteTitle, which was
inspected in the course of arriving at RFE 82.

In 4.0, warn that Title will be removed from bibliocomponent.mix
In 4.0, warn that the content of CiteTitle will be changed (reduced)
   from para.char.mix (which, inappropriately for cited titles, allows 
   synopses) to title.char.mix.
In 5.0, make the changes.

Issue 85: Add 'Journal', 'Series', 'Set' and 'Manuscript' values to Pubwork on CiteTitle
Requested by: terry Submitted: 29 Dec 1998 17:24 Resolved: 3.1
Type: bug Priority: medium Status: closed

Rationale

Description

In a bibliography entry for an article, one should cite not only the title of
the article but also the title of the journal in which it appears, which is
not a "Book", even though DocBook's <Book> element is meant to serve
for <Journal>, too.  There is no value for "Journal", so it should be added.

You may also want to cite the title of a Series (not the same as a Journal,
which is a periodical), a Set, or a manuscript.  So add Series, Set, and 
Manuscript values, too.

Issue 86: Create new inlines for object-oriented programming
Requested by: cg@cdegroot.com Submitted: 03 Feb 1999 14:16 Resolved: 4.0
Type: enhancement Priority: medium Status: closed

Rationale

Reformulated as RFE 96

Description

ndw@nwalsh.com said:
> If you can suggest a set of new inlines that would address your needs
> in this area, please do.  If you can provide at least a refpurpose for
> each element, that would be great. 

Well, a very minimal set for OO software documentation:

<Class> - object's type. IIRC, <Type> is in use already for another purpose.
<Interface> - exposed behaviour of an object. 
<Method> - a function or procedure implementing a piece of the behaviour of a 
Class.
<Property> should be ok with the definition it now has.

I've been thinking on stuff like <Actor> for OO design documentation. Probably 
not...

-- 
Cees de Groot               http://www.xs4all.nl/~cg    <cg@cdegroot.com>
                            http://www.sgmltools.org   <cg@sgmltools.org>

Issue 87: SGMLTag doesn't deal well with XML
Requested by: norm Submitted: 06 Feb 1999 09:01 Resolved: 3.2
Type: bug Priority: medium Status: closed

Rationale

XML markup is, in fact, a special case of SGML markup, so a new element
doesn't seem warranted.

Description

7 Mar 1999:

We will add 'xmlpi' and 'emptytag' as class values to SGMLTag.

There's no way to specify that the markup from SGMLTag should be XML markup.
(e.g., producing <foo/> or <?pi foo?>.)

We could add an XMLTag element, I suppose.  Or we could add an attribute
to SGMLTag.

SGMLTag needs a class that indicates the new style of empty element.

Issue 88: Add PEs to INCLUDE/IGNORE dbcent and dbnotn en masse
Requested by: terry Submitted: 06 Feb 1999 18:09 Resolved: 3.2
Type: enhancement Priority: medium Status: closed

Rationale

This is clearly useful.

Description

It would sometimes be useful in a customization layer to be able to
INCLUDE or IGNORE all of dbcent and dbnotn in one fell swoop.  Add
parameter entities to make this possible.

Issue 89: Remove default values for (some) attributes
Requested by: norm Submitted: 10 Feb 1999 10:31 Resolved: 5.0
Type: bug Priority: medium Status: accepted

Rationale

The Class attribute value will be made #IMPLIED.

Description

The Class attribute on ProductName has a default value. This effectively
prevents anyone from using ProductName without generating a mark (Trademark,
Service mark, etc.).  Perhaps its value should be #IMPLIED instead.

This raises the larger issue, since the EB is tending to make things more
loose these days, if other default values shouldn't be made #IMPLIED.

Issue 90: Relax the content model of sections
Requested by: norm Submitted: 10 Feb 1999 10:34 Resolved: 3.2
Type: enhancement Priority: medium Status: closed

Rationale

Dup of RFE 38

Description

Following the loosening of the Book content model in V3.1, should the
content model of sections also be made looser?

The exterior motivation is to allow sections to function as an outline
in the early authoring stages of a document.  By making all content
optional, except title, you could write things like this:

<chapter><title>Some Chapter</title>
<sect1><title>I'll Fill This in Later</title>
</sect1>
<sect1><title>I'll Fill This in Too</title>
</sect1>
</chapter>

Issue 91: Remove %synop.class; from %para.char.mix;?
Requested by: norm Submitted: 10 Feb 1999 10:38 Resolved: 5.0
Type: bug Priority: medium Status: accepted

Rationale

We will remove Synopsis from para.char.mix; CmdSynopsis and FuncSynopsis
will remain, with the processing expectation that they are inline if used
in an inline context.

Description

The Synopsis element cannot be an inline.  CmdSynopsis and FuncSynopsis
could be, but should they?

/ Eduardo Gutentag <Eduardo.Gutentag@Eng.Sun.COM> was heard to say:
| On the other hand, I don't see a conceptual problem with something like:
| 
| "The command ls accepts a whole bunch of options and an optional
| file argument: /usr/bin/ls  [ -aAbcCdfFgilLmnopqrRstux1 ]  [ file ... ]"
| 
| (the above looks like two lines only by accident)

Norm replies:

But does it need to be a synopsis?

<para>
The command <command>ls</> accepts a whole bunch of options and an
optional file argument:
<command>/usr/bin/ls</command>
<optional><option>aAbcCdfFgilLmnopqrRstux1</option></optional>
<optional>file ...</optional>
</para>

If you've put it inline, do you really need or want to be able to
point to the whole thing?  If it's that important, why did you run it
inline?

The only downside I see is that there's no way to generate the ellipsis
in the final optional in that command.  (Rep is only on Arg and Group
which can only occur in a CmdSynopsis.)

Issue 92: Add CO to Synopsis?
Requested by: nwalsh Submitted: 28 Feb 1999 15:18 Resolved: 3.2
Type: enhancement Priority: medium Status: closed

Rationale

For consistency, CO will be added to Synopsis and LiteralLayout.

Description

The CO element is allowed in ProgramListing and Screen, it seems like
it would be handy in the other verbatim environments, particularly Synopsis.

Issue 93: Add markup for forms
Requested by: nwalsh Submitted: 07 Mar 1999 06:31 Resolved:  
Type: enhancement Priority: low Status: open

Rationale

Left pending for 5.0 in order to consider how namespaces interact with
schema

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 94: ErrorName is confusing and probably wrong
Requested by: dennis Submitted: 07 Mar 1999 11:29 Resolved: 5.0
Type: bug Priority: medium Status: accepted

Rationale

There's no proper place for the text of an error message and the documentation for ErrorName and ErrorCode has not been particularly
good.

Description

ErrorName will be defined to be the name for an ErrorCode (ENOENT)
ErrorCode will be defined to be the alphanumeric code for the error (-2)
ErrorType remains the classification
ErrorText will be added to hold the text of the error message.

Note that we may be doing the same thing in two different ways, considering MsgText in MsgSet.

MsgText should be constrained to MsgSet (it is currently allowed outside)
and outside, it should be ErrorText.

Norm will break this into several RFEs.

- ErrorText will be added in 3.2
- DocBug will be fixed.

Issue 95: Extend FuncSynopsis for modern programming languages
Requested by: nwalsh Submitted: 08 Mar 1999 07:06 Resolved: 4.0
Type: enhancement Priority: medium Status: accepted

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

Action:

Make one more cleanup pass, post to list, post to XML-Dev, incorporate
into DocBook 4.0

Make sure that the *Name elements match the inlines

--

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

Rationale

This is work that will be done, but we need a complete proposal.

Description

Proposal:

MethodName, Exception, Interface, Implements

Remove implements because what you implement is an interface.

Now we have MethodName, Exception, and Interface.

Name conflict, so it should be:

MethodName, ExceptionName, InterfaceName

---

The current collection of inline elements (including StructName,
StructField, ClassName, 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 97: Simplify ToC content model
Requested by: nwalsh Submitted: 08 Mar 1999 07:36 Resolved: 5.0
Type: enhancement Priority: medium Status: accepted

Rationale

Description

See also RFE 38.

- ToC content model will be simplified.
- The semantic of a ToC is that it only contains entries for the
  elements that are it's peers and descendants of its peers.
- The semantic of an empty ToC is that it is a location where
  an automatically generated ToC is to appear.

Perhaps:

<!ELEMENT ToC - O ((%bookcomponent.title.content;)?,
        (%component.mix;)*, (ToCDiv* | ToCEntry*))
        %ndxterm.exclusion;>
<!ATTLIST ToC
        %pagenum.attrib;
        %common.attrib;
        %toc.role.attrib;
        %local.toc.attrib;
>

<!ELEMENT ToCDiv - O ((%sect.title.content;)?, ((%tocdivcomponent.mix;)*,
        ToCEntry+))>
<!ATTLIST ToCDiv
        %linkend.attrib; --to element that this entry represents--
        %pagenum.attrib;
        %common.attrib;
        %toc.role.attrib;
        %local.toc.attrib;
>

<!ELEMENT ToCEntry - - ((%para.char.mix;)+,ToCEntry*)>
<!ATTLIST ToCEntry
        %linkend.attrib; --to element that this entry represents--
        %pagenum.attrib;
        %common.attrib;
        %tocentry.role.attrib;
        %local.tocentry.attrib;
>

Issue 98: Reorganize parameter entities
Requested by: nwalsh Submitted: 18 Mar 1999 13:14 Resolved:  
Type: enhancement Priority: medium Status: pending

Rationale

Description

Perhaps this is moot if we move to an XML Schema...

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: 4.0
Type: enhancement Priority: medium Status: closed

Rationale

Reasonble for simple cases, possible migration path over the long haul.

Description

06 Dec

<!ELEMENT SimpleMsgEntry (MsgText, MsgExplan)>

Make MsgSet (MsgEntry+|SimpleMsgEntry+)

Add Level, Audience, and Origin as attributes on SimpleMsgEntry (CDATA)

Class = "MainMessage|SubMessage" defaults to MainMessage
We will leave out RelatedMessage because it really should be a link
and we don't want to add more ID/IDREF linking

We've explored the issue of class, it seems that we need to use a linking
mechanism instead of a containment. 

In the 5.0 time frame, we'll add the notion of sub-messages and related
messages back in with some form of XLink.


---

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

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.

Issue 101: this is just a test
Requested by: nwalsh Submitted: 27 Mar 1999 08:41 Resolved:  
Type: bug Priority: medium Status: rejected

Rationale

Description

this is just a test. ignore this rfe.

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

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

Rationale

This will allow DocBook representations of the sorts of things that go
in version control systems, where version and revision are the same thing
but multiple changes are made in a single revision.

There was no concern among members of the committee about the fact that
this would allow complex things in RevDescription

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: 4.0
Type: enhancement Priority: low Status: closed

Rationale

It makes sense.

Description

06 Dec 1999

Add 'Specification' to the list of values.

---

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

Rationale

It makes sense.

Description

06 Dec 1999

Add PNG notation; SYSTEM "PNG"

---

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: altheim@eng.sun.com Submitted: 16 Jul 1999 07:00 Resolved: 3.2
Type: bug Priority: medium Status: closed

Rationale

Many of them are used in exactly one place, and now that we have parameter
entities around every element and attlist declaration, it's no longer
important to have a PE for these content models.

Description

06 Dec 1999

Delete the *.content parameter entities.


--


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

Rationale

The committee feels that multiple questions have not been sufficiently
motivated. We feel that it would be confusing to have multiple questions.

If you have multiple questions with a similar answer, you can use a
cross reference.

Multiple answers are already allowed.

Description

06 Dec 1999

Rejected.

---

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: 4.0
Type: bug Priority: medium Status: closed

Rationale

It makes sense.

Description

06 Dec 1999

Add them.

--

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: 4.0
Type: enhancement Priority: low Status: closed

Rationale

It makes sense.

Description

06 Dec 1999

Add it to the module.

---

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

Rationale

It's reasonable and useful to keep track of the revision history
on questions and answers.

Description

06 Dec 1999

<!E Question (RevHistory?, Question, Answer*)

--

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: 4.0
Type: enhancement Priority: medium Status: closed

Rationale

The Euro is a special case and will be added. It will be removed when
it appears in an appropriate entity set. We will not get into the business of
adding addtional character entities; moving to XML for Unicode is probably
a preferable solution.

Description

06 Dec 1999

We will add &euro; as SDATA [euro  ] inside dbcent.module

---

Please add the Euro symbol to DocBook

Issue 112: AckNo ought to be a block not an inline!
Requested by: nwalsh Submitted: 03 Dec 1999 14:27 Resolved: 5.0
Type: bug Priority: medium Status: rejected

Rationale

It's supposed to be small.

Description

06 Dec 1999

Rejected; it's supposed to be small.

---

AckNo is used in a block context, but it's an inline. This really
odd. And probably "a bad thing".

Issue 113: Processing expectations of RevHistory wrt chronological order of revisions
Requested by: Eve Maler Submitted: 06 Dec 1999 11:13 Resolved:  
Type: docenhancement Priority: medium Status: open

Rationale

Description

What are the processing expectations of RevHistory with respect to the
chronological order of the revisions in the list.

Issue 114: Support for EBNF (XML Spec productions)
Requested by: Eve Maler Submitted: 06 Dec 1999 11:23 Resolved:  
Type: enhancement Priority: medium Status: open

Rationale

Description

It would be useful to be able to represent productions such as EBNF
(and XML specification productions in general) in DocBook.

Issue 115: Desire unbulleted list with titles
Requested by: Sunthar Submitted: 06 Dec 1999 14:36 Resolved: 4.0
Type: enhancement Priority: medium Status: closed

Rationale

Titles on VariableList but not on OrderedList and ItemizedList seems
odd. And titles on lists are useful.

List of capital cities; where you want a "Capitals" title. Titles on
checklists.

Description

Add optional titles to OrderedList and ItemizedList

Issue 116: Line numbers on program listings
Requested by: Sunthar Submitted: 06 Dec 1999 14:41 Resolved: 4.0
Type: enhancement Priority: medium Status: closed

Rationale

This is display numbering, there is no reference to real program sources.
We don't need to start with numbers other than 1, we don't need to be
able to elide regions, etc.

Description

LineNumbering = Numbered | Unnumbered

Support for line numbers on program listings

Issue 117: Allow callout regions in, for example, programlistings
Requested by: Eve Maler Submitted: 06 Dec 1999 15:12 Resolved:  
Type: enhancement Priority: medium Status: rejected

Rationale

It would not have significantly reduced processing expectations and the
functionality is already available through areaset.

Description

Should we support things like callouts that span regions, perhaps
<coregion>, a content-full <co>

Issue 118: The processing expectations of SimpleSect were lost
Requested by: Eve Maler Submitted: 06 Dec 1999 15:54 Resolved: 4.0
Type: docbug Priority: medium Status: accepted

Rationale

This is useful for canonical repeated things that occur at the end
of a component or section.

At the end of every section you might have subsections
that are always repeated. For example, "Summary" at the
end of every section, or "Notes" at the end of Chapter

Description

The processing expectations of SimpleSect were intended to be:

- They do not appear in the ToC
- They may or may not be numbered

Issue 119: Add support for DOI in meta
Requested by: norm Submitted: 27 Mar 2000 13:02 Resolved: 4.1
Type: enhancement Priority: medium Status: accepted

Rationale

We see that DOI will not be the only object identifier. Rather than
adding additional inlines, we will add a bibliography identifier,
biblioid, with a class attribute so that we can easily extend it in
the future. Like title, we wish to distinguish between it's
definitional use and it's referential use, so we will add citebiblioid
as well.

Description

Currently we support ISBN and ISSN. We've had a request to support DOI
as well. Terry observes that we're going to get more requests in the future
and suggests <biblioidentifier class="isbn|issn|doi|..."> as an alternative
to more discrete elements.

...

We will add biblioid and citebiblioid with a class attribute. The
legal values of this attribute will be: urn, doi, isbn, issn, pubnumber.
The elements isbn, issn, and pubnumber are deprecated. FU that we will
remove them in 6.0.

Issue 120: Add macro element for marking up macros in programming languages
Requested by: dcm@redhat.com Submitted: 19 Oct 1999 Resolved:  
Type: enhancement Priority: medium Status: rejected

Rationale

Macro already exists as a class of systemitem.

Description

An element is needed for macros in the languages of C, C++, pascal, scheme, m4, and  more. Macros are a means for textual substitution and need to be
described in API and programming documentation.

Issue 121: Add markup for signals
Requested by: dcm@redhat.com Submitted: 19 Oct 1999 Resolved:  
Type: enhancement Priority: medium Status: open

Rationale

Need more info. What other sorts of things are like this. Rather than
adding new inlines for signal specifically, we'd like to come up with
an element that was more general and add class values. Perhaps "Event"
and "EventHandler"?

Description

An element needs to be added for Signals. Signals are in several
GUI toolkits within the "signal/slot" mechanism for notification
of events.  An object emits a "signal" when something
interesting happens, and signal handlers connected to the proper
"slot" are thus called.  It would be convenient to be able to
differentiate these names from plain symbols.

Issue 122: Add markup for troubleshooting
Requested by: scotcro@e-docarchitects.com Submitted: 19 Jan 2000 Resolved:  
Type: enhancement Priority: medium Status: open

Rationale

This seems to be too application specific. Suggest Procedure with role
and possibly other inline markup or a local extension.

Description

Provide a element structure to support troubleshooting steps.  This can currently be done with a table or segmented list, but would be beneficial if the content was formally tagged.

This also includes description of an applicability element which could also be used in the <*info> elements of DocBook.

Proposed structure:

<troubleshooting>
     <applicability>
        <partnumber/>
        <modelnumber/>
        <serialnumber>         
           <mask>1924-?????</mask>
           <range>
               <upperrange>99999</upperrange>
               <lowerrange>56789</lowerrange>
           </range>
           <range>
               <upperrange>0</upperrange>
               <lowerrange>39999</lowerrange>
           </range>
        </serialnumber>
        <serialnumber>1924-44321</serialnumber>
        <serialnumber>1972-54123</serialnumber>
     </applicability>
     <symptom>
         The thing don't work.
         <cause>
             Is it plugged in?
         </cause>
         <action>
             Plug it in?
         </action>          
         <cause>
             Is it turned on?
         </cause>
         <action>
             turn it on?
         </action>              
     </symptom>
</troubleshooting>

Issue 123: Add markup to support specifications
Requested by: scotcro@e-docarchitects.com Submitted: 19 Jan 2000 Resolved:  
Type: enhancement Priority: medium Status: open

Rationale

We consider this is out-of-scope for DocBook, but he should consider
RosettaNet which is doing product spec sheets and similar sorts of things.

Description

Add formal element set for product specifications:

<specifications>
    <specgroup>
        <title>Physical</title>
        <spec>
        <title>Weight</title>
        <value>450<value>
        <units>Lbs</units>
        <spec>
            <spec>
        <title>NEMA Rating</title>
        <value>4<value>
        </spec>
            <specgroup>  
                <title>Dimensions</title>
                <spec>
                <title>Height</title>
            <value>23<value>
            <units>Inches</units>
            </spec>
                <spec>
            <title>Width</title>
            <value>14<value>
            <units>Inches</units>
        </spec>
                <spec>
            <title>Length</title>
            <value>2<value>
            <units>Inches</units>
        </spec>
                <spec>
            <title>Depth</title>
            <value>23<value>
            <units>Inches</units>
        </spec>
        </specgroup>
    </specgroup>
    <specgroup>
        <title>Electrical</title>
        <spec>
            <title>Supply Voltage</title>
            <value>120/230<value>
            <units>VAC</units>
        <spec>
    </specgroup>    
</specifications>

Issue 124: Add markup for hostnames and other host identifiers
Requested by: nik@freebsd.org Submitted: 08 Apr 2000 Resolved:  
Type: enhancement Priority: medium Status: open

Rationale

We already have a class on systemitem for systename. We suggest that these
are further useful class values for systemitem but do not warrant a unique
element name. We'll add the following class attributes to systemitem:
domainname, fqdomainname, ipaddress, netmask, etheraddress. We consider
hostname already covered by systemname.

Description

The FreeBSD Documentation Project <URL:http://www.FreeBSD.org/docproj/>
has been using this extension to the DocBook DTD for some time, and would
like feedback on folding the change back in to the main DocBook DTD.

For marking up hostnames, and other host identifiers
----------------------------------------------------

<!-- ...................................................................... -->

<!ELEMENT HostID - - ((%cptr.char.mix;)+)>
<!ATTLIST HostID
                --
                Role: More specific information about this HostID.
                If not specified then the default is 'hostname'.
                --
                Role    (Hostname
                        |Domainname
                        |FQDN
                        |IPAddr
                        |Netmask
                        |MAC)      #IMPLIED
                %common.attrib;
>

<!-- ...................................................................... -->

("FQDN" == "Fully Qualified Domain Name")

Typical usage would be:

    <para>The local machine can always be referred to by the
      name <hostid>localhost</hostid>, which will have the IP address
      <hostid role="ipaddr">127.0.0.1</hostid>.</para>

    <para>The <hostid role="domainname">FreeBSD.org</hostid> domain
      contains a number of different hosts, including
      <hostid role="fqdn">freefall.FreeBSD.org</hostid> and
      <hostid role="fqdn">bento.FreeBSD.org</hostid>.</para>

    <para>When adding an IP alias to an interface (using
      <command>ifconfig</command>) <emphasis>always</emphasis> use a
      netmask of <hostid role="netmask">255.255.255.255</hostid>
      (which can also be expressed as <hostid
        role="netmask">0xffffffff</hostid>.</para>

    <para>The MAC address uniquely identifies every network card in
      in existence.  A typical MAC address looks like <hostid
        role="mac">08:00:20:87:ef:d0</hostid>.</para>

While these could be added as additional "Class" values for SystemItem,
the trend seems to have been to migrate information like this in to
individual elements, rather than as attributes.

Per the SystemItem element, "SystemName" may be a better element name
than "HostID", and "Class" might be a better attribute name than "Role".

Issue 125: Add markup for usernames
Requested by: nik@freebsd.org Submitted: 08 Apr 2000 Resolved:  
Type: enhancement Priority: medium Status: open

Rationale

Username already exists as a class of systemitem.

Description

The FreeBSD Documentation Project <URL:http://www.FreeBSD.org/docproj/>
has been using this extension to the DocBook DTD for some time, and would
like feedback on folding the change back in to the main DocBook DTD.

For marking up user names
-------------------------

<!-- ...................................................................... -->

<!ELEMENT Username - - ((%cptr.char.mix;)+)>
<!ATTLIST Username
                %common.attrib;
>

<!-- ...................................................................... -->

    <para>To carry out most system administration functions you
      will need to be <username>root</username>.</para>

While this could be an additional Class value for SystemItem, the trend
seems to have been to migrate information like this in to individual
elements, rather than as attributes.

Issue 126: Allow SimpleSect in Section
Requested by: nwalsh Submitted: 11 Apr 2000 09:56 Resolved: 4.1
Type: bug Priority: medium Status: open

Rationale

We will add SimpleSect to the end of Section.

Description

SimpleSect is not allowed as a child of Section. I think this is a bug.

Issue 127: Add 'dissertation' to list of article classes
Requested by: nwalsh Submitted: 12 Apr 2000 15:19 Resolved:  
Type: enhancement Priority: medium Status: open

Rationale

We will.

Description

It's another legitimate class of published work.

Issue 128: Better support for typing and linking in funcdef
Requested by: nwalsh Submitted: 20 Apr 2000 07:39 Resolved:  
Type: enhancement Priority: medium Status: open

Rationale

We'll add type to the content model of funcdef and paramdef to allow
authors to specify that types are in fact types. Linking will be handled
by XLink in some future version.

Description

Some authors would like to be able to tag data types in funcdef elements.
They'd also like to be able to create links from parts of a funcsynopsis
to other parts of the document.

Issue 129: Support easier installation
Requested by: nwalsh Submitted: 20 Apr 2000 07:40 Resolved:  
Type: enhancement Priority: medium Status: open

Rationale

We don't want to go there.

Description

It would be nice if DocBook (and the stylesheets, though that's not strictly
a TC issue) supported easier installation on platforms that have a standard
install process.

Issue 130: Add inline markup for protocols, FS types, and partitions
Requested by: godoy@connectiva.com.br Submitted: 19 May 2000 06:29 Resolved: 4.1
Type: enhancement Priority: medium Status: open

Rationale

Protocol is another example of a case where we need to consider the design
more carefully (what other things are like protocols); in the meantime use
literal, phrase, or some other markup with a role attribute.

We'll add 'filesystem' to the class attribute of systemitem.

We'll add 'partition' to the class attribute of filename.

Description

| > godoy@conectiva.com.br escribió:
| > 
| > > I'm having problems marking up some network items which I don't know
| > > what tag I could use:
| > > 
| > > 2. Network protocols (e.g. PPP, TCP/IP)
| > > 3. Filesystem type (e.g. VFAT, EXT2, UFS, NTFS)
| > > 4. Disk partition (e.g. the first partition of a SCSI disk on a linux
| > >                    system should be /dev/sda1)

Issue 131: Simplify citerefentry markup
Requested by: godoy@conectiva.com Submitted: 26 May 2000 08:42 Resolved: 4.1
Type: enhancement Priority: medium Status: rejected

Rationale

Considered and rejected.

Description

Current markup for making a citation to a refentry is a bit cumbersome:

  <citerefentry>
    <refentrytitle>grep</refentrytitle>
    <manvolnum>1</manvolnum>
  </citerefentry>

Perhaps something simpler could be added:

<man section="1">mail</man> or
<citerefentry section="1">mail</citerefentry>

Issue 132: Allow date to occur inline
Requested by: Ziemek Borowski, ziembor@faq-bot.ziembor.waw.pl Submitted: 7 Aug 2000 08:22 Resolved: 4.2
Type: enhancement Priority: medium Status: open

Rationale

Description

Is there any possibility to encode date in text?
<date> in current (4.x) dtds is used only in
bibliocomponent.mix module (so, we cannot use that in PCDATA)

I need:
<abstract><para>
Test was performed at <date notation="european"> 20.01.1999
</date>
</para> etc...

currently I plan to write customisation layer to both DTD and DSSSL
(and mayby other) but I want to minimalize incompatibilities with
,,standard'' docbook.

Issue 133: Add newsgroup element
Requested by: "Eric S. Raymond" <esr@snark.thyrsus.com> Submitted: 24 Aug 2000 9:00 Resolved: 4.2
Type: enhancement Priority: medium Status: open

Rationale

Description

1. Missing <newsgroup> tag.

The problem with the DocBook markup itself is that I cannot find any
way to semantically tag a USENET newsgroup name.  This comes up
especially frequently in connection with LDP HOWTOs, which often 
cite newsgroups.  

We're missing a <newsgroup> element, which would be desirable for
the
same reason as <email>.  Consider

     <newsgroup>comp.os.linux.announce</newsgroup>

In HTML output, this wants to become

     <a
href="news:comp.os.linux.announce">comp.os.linux.announce</a>

But in print we probably want the equivalent of

     <emphasis>comp.os.linux.announce</emphasis>

without news URL.

Issue 134: Additional elements to describe file systems and database objects
Requested by: sbline@apsydev.com Submitted: 07 Aug 2000 11:31 Resolved:  
Type: enhancement Priority: medium Status: accepted

Rationale

The database objects are already supported by the <database> tag and its
class attribute. Are those not sufficient for the task?

We'll add "extension" to the list of class values on Filename.

Description

It would be nice to have some elements dedicated to database objects,
such as: <field>, <link>, <index>, <key>, etc...
Also a <fileextension> element would be nice.

Issue 135: Support for a <po> and </po> tag for creating pot files for easier doc translation
Requested by: kenneth@ripen.dk Submitted: 26 Apr 2000 14:05 Resolved:  
Type: enhancement Priority: medium Status: pending

Rationale

Don't understand the request. Waiting for more info.

Description

I would really much like support for a <po> and </po> tag for creating pot 
files for easier doc translation. This was the contens between <po> and </po>
will be extracted like a string to be put in the gettext pot file. 
This is done with a simple script, that you can always run.

the script generated a pot file which can be merged with the translations
with the msgmerge script just like all other po and pot files.

then an other script is ran to generate the different sgml files

this would really help the translators

Thanks Kenneth

Issue 136: Allow <co> in <userinput>
Requested by: nik@freebsd.org Submitted: 18 Jul 2000 13:03 Resolved:  
Type: enhancement Priority: medium Status: open

Rationale

Description

<co> is allowed inside <screen>, but is disallowed in <userinput>.

Being able to mark parts of a user's command line for future reference
would be a useful facility.

On the FreeBSD project we kludge around this with:

    <!ENTITY % local.cptr.char.mix "|CO">

in our DocBook extension layer, but there are probably better ways
of doing it.

Issue 138: Add PDF to ImageData format notations.
Requested by: robert@cogent.ca Submitted: 08 Aug 2000 09:12 Resolved:  
Type: enhancement Priority: medium Status: open

Rationale

Description

Excuse me if this is repetitious, but I just read on the DocBook mailing
list that we could submit RFEs (thank you very much), and I wanted to 
make sure this request has been received.

Is there any possibility of adding PDF to the format notations for
<imagedata> in version 5.0?  

We find that using PDF images gives us high-quality graphics in PDF
output, even when scaled.  We're currently sneaking them in using the
<graphic> element, by not specifying a format and letting the stylesheet
find it. (See posting of 06/09/00 and 07/11/00 to docbook-apps list.)  

But in looking ahead to version 5.0, the <graphic> element will be
discarded.  If PDF can be added to the <imagedata> format notations our
life will be a lot easier.  

Thanks.

---
Bob

Issue 139: Add SVG as a Notation
Requested by: nwalsh Submitted: 05 Dec 2000 20:15 Resolved:  
Type: bug Priority: medium Status: open

Rationale

Description


Issue 140: Allow multiple MsgExplan inside SimpleMsgEntry
Requested by: Dennis.Evans Submitted: 06 Dec 2000 09:12 Resolved: 4.2
Type: enhancement Priority: medium Status: accepted

Rationale

Allows for explanations (with a role, for example) of different types:
description, cause, solution, example.

Description

Allow multiple MsgExplan's in a SimpleMsgEntry.

Issue 141: Add 'contribution' attribute to OtherCredit
Requested by: nwalsh Submitted: 06 Dec 2000 09:50 Resolved: 4.2
Type: enhancement Priority: medium Status: open

Rationale

Description

Allow OtherCredit to identify the reason for additional credit.

Issue 142: Add inline markup for CPU registers
Requested by: G. Adam Stanislav <adam@whizkidtech.net> Submitted: 07 Dec 2000 15:56 Resolved: 4.2
Type: enhancement Priority: medium Status: open

Rationale

Description

I don't understand how it is possible that DocBook has no tag for CPU
registers (such as EAX, EBX, etc). What tag would you use for them in a
book on assembly language?

Issue 143: Add xml:space attribute to linespecific environments
Requested by: nwalsh Submitted: 10 Dec 2000 10:00 Resolved: 4.2
Type: bug Priority: medium Status: open

Rationale

Description

XML tools, such as editors, need this information in order to know which
DocBook elements contain whitespace that is significant.

Issue 144: Add introductory material to lists
Requested by: Dennis.Evans@Eng.Sun.COM Submitted: 12 Dec 2000 10:19 Resolved: 4.2
Type: enhancement Priority: medium Status: accepted

Rationale

No problems have been reported due to the fact that
Procedure allows this structure.

Description

This continues to be an issue for Sun documentation.

Recap: Authors sometimes need to provide a paragraph or two
of description before the items of a list. These paragraphs are considered
to be part of the list, so it's perhaps not appropriate to put them
before the list. Putting them before the list is problematic because grabbing
the list and moving it elsewhere will not capture the necessary introductory
material. Procedure already allows this structure.

Moved: add %component mix;* (minus the list elements) to 
orderedlist,
itemizedlist, calloutlist, and
variablelist before the first list item.

The motion was adopted without objection.

Issue 145: Allow additional material after the last step in a Procedure
Requested by: Dennis.Evans@eng.Sun.COM Submitted: 12 Dec 2000 10:22 Resolved: 4.2
Type: enhancement Priority: medium Status: pending

Rationale

Description

Sun documentation requirement.

Perhaps add %component.mix; optionally after the last step?

Tabled: waiting for feedback from Sun.

Issue 146: Extend textobject to insert external files
Requested by: nwalsh Submitted: 22 Feb 2001 09:38 Resolved: 4.2
Type: enhancement Priority: medium Status: open

Rationale

Description

At the moment, external files can only be inserted into DocBook documents
using the format=linespecific hack on inlinemediaobject.

Should we extend textobject to allow this? Should we add attributes to
identify the type of content? The encoding?

Or is this what XInclude is for?

Issue 147: Add coref
Requested by: nwalsh Submitted: 22 Feb 2001 09:40 Resolved: 4.2
Type: enhancement Priority: medium Status: open

Rationale

Description

If you use the *co callout model with areaspecs, you can have the same
callout bug appear in several places. This isn't possible with literal
<co> elements.

Suggestion: add <coref>, analagous to footnoteref, to fix this problem.