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 € 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.