Comment Form

Note from Don Day:
This format is experimental for the Wiki. Two methods are represented here: by a linked table, and by inline record keeping. I think I prefer the linked table.

Link to a comment using its descriptive ID. For the dispostion, use the same values as for DITA's draft-comment disposition attribute: issue, open, accepted, rejected, deferred, duplicate, reopened, unassigned, completed

Comment	Disposition
Comment-2006-1	new
Comment-2006-2	new
Comment-2006-3	new
Comment-2006-4	new

ID: Comment-2006-1
Disposition: new
Date: 30 Jan 2006
Name: David Cramer
Regarding Specification: DITA

The "title" of a document is stored in the title attribute of the document's <map/>. Unfortunately, this means that you cannot easily include markup within the title (for example a processing instruction providing a hint as to where a line break would look good). I notice that the bookmap demo allows for a <booktitle> element in <bkbasicinfo>. I would suggest moving the title to an element in topicmeta and making it required.

In fact, I wonder if the DITA committed might reconsider the decision to put translatable text in attributes more generally. Doing so means you can't add translate="no" attributes to that text. Consider the following title, which could not be put in an attribute:

Editing the <filepath translate="no">httpd.conf</filepath> file

Response: {place details about the response here}

ID: Comment-2006-2
Disposition: new
Date: 7 Feb 2006
Name: Deborah Pickett (deborah_pickett@moldflow.com)
Organization: Moldflow
Regarding Specification: Inline/block element clarification

The list of inline/block elements at http://www.oasis-open.org/committees/download.php/16527/elements.html is very helpful, thanks.

But I fail to understand how <itemgroup> can be considered inline when it can contain block elements like <p>. My understanding of inline presentation is that it can only include other inline-presented things.

Should I be thinking of <itemgroup> as "inline, unless it contains block children"?

While we're at it, I think that a worthwhile addition to this handy reference table would be a statement of whether an element can contain only block elements (e.g., <fig>), only inline (e.g., <b>), or mixed content (e.g., <li>). (Yes, this is already in the DTD, but it'd be handy in just one place.)

ID: Comment-2006-3
Disposition: new
Date: 13 Feb 2006
Name: Scott Hudson (scott.hudson@flatironssolutions.com)
Title: Senior Consultant
Organization: Flatirons Solutions
Regarding Specification:

We are recommending the bookmap specialization to several of our clients. We have identified a few missing components that we would like to have added to DITA 1.1.

It has been previously recommended (see http://www.oasis-open.org/committees/download.php/15795/IssueNumber38-Bookmap.htm) that shortdesc be used as the logical place for transitional text. However, shortdesc does not allow for other block elements like paragraphs and lists to be nested under it; nor does it allow any cross-referencing to be contained within. This restriction is not flexible enough to handle the variety of transitional or introductory text that we have seen in some of our client’s documentation.

We have found a need for multiple kinds of transitional text: (1) The introduction to the chapter or section itself (e.g. "This chapter covers..." (2) a blurb that could be used BEFORE the chapter or section actually starts (e.g. "The next chapter covers...") (3) an optional blurb that can be used immediately AFTER the chapter or section (e.g. "In the previous chapter we learned...").

Using these three types of transitional text wisely would allow a completely modular writing approach that nonetheless provides smooth transitions between the topics when they are stitched together within a BookMap.

The current shortdesc model in bookmap only allows text and keywords.

We would like to see these needs addressed as early as DITA 1.1 if possible.

Thanks and best regards,

--Scott

ID: Comment-2006-4
Disposition: new
Date: 14 Jul 2006
Name: Doug Burgess (Doug.Burgess@businessobjects.com)
Title: Content Management Lead, TechED
Organization: Business Objects
Regarding Specification: DITA 1.1 Draft Specification

Hi Folks,

Thanks for posting the draft. I'm appreciating some of the clarifications that have made it in there.

I have one comment regarding the specialization of attributes, (besides 'hurray!'), pertaining specifically to atts that use enumeration lists. I would find it helpful to be able to add local vocabulary values to such lists.

Constructs such as @someatt...'value1 | value2 | other', paired with @othertype, are error prone. The desired result is thwarted when an author makes a mistake typing the CDATA othertype attribute into the tiny little att box in XMetaL, Frame, etc.

Why not allow extension of enumeration lists, and generalize to the othertype attribute? That would allow authors to choose local values from the same picklist as the rest of the enumeration list, rather than having to type them in.

Thanks for listening...I'm looking forward to the 1.1 release.

Best Regards, Doug