Historical DocBook RFEs

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 con