The Language Spec is comprised of:

Fix list for fourth/fifth drafts (mid February, 2007)

Fix list for third draft (end of January, 2007)

Note - I am still waiting on final wording for @chunk, so it has not yet been updated.

New for the third draft:

  1. Updates to the indexing, image, and object topics sent to the list by Paul Grosso
  2. Updates to the navref element description
  3. Replace "Glossary topic" with "Glossentry topic" everywhere it is used
  4. Updated the contains/contained-by listing to list each document type
  5. Added an alphabetical list of elements before the index
  6. Corrected a large number of index entries
  7. Alphabatized the bookmap elements, and placed the bookmap metadata elements in a new section
  8. Added a section at the beginning with an alphabetical list of all elements, so that we do not need to manually add bookmarks after generating the PDF.
  9. Re-ordered several sections of the book, based on review input
  10. Several editorial comments based on Jeff Ogden's review, plus these content changes:
    1. Added information to the book's intro indicating new items for DITA 1.1. It does not mention @chunk, though this should be added once it is added to the architectural spec.
    2. Clarify that when shortdesc's inside abstract are concatenated, they are space separated
    3. Clarified that @href on lq may point to a DITA topic
    4. Added a note on the type attribute for audience, author, copyright, note, lq, and param that the definition differs from @type on many other elements. This note was already present for the object element.

    5. Clarified the reason for the metadata container, within the <metadata> topic.

    6. Clarified inheritance order in the <relcolspec> element.

    7. In the display-atts topic, moved @pgwide exception into the expanse row
    8. In the description of @translate, added a pointer to the architectural spec for a list of common defaults
    9. Indicated that platform/product/audience/otherprops/props/base take a space delimited set of values (with a note about the more complicated generalized case for props/base).
    10. Combined the topicref-atts and topicref-atts-no-toc topics.

These comments address specific comments by Jeff that were not completed exactly as requested:

  1. Attributes that inherit should say so. I've added the following message to @scope, @format, the filter attributes, and rev (I was unsure how to get the wording into the type attribute, which should inherit based on the architectural spec, but which already says the type should be determined by inspecting the target): "If no value is specified, but the attribute is specified on an ancestor within a map or within the related-links section, the value will inherit from the closest ancestor."
  2. Similar to above, added this note to @toc, print, chunk, linking, search: "If the value is not specified locally, but it specified on an ancestor, it will inherit the value of on the ancestor."
  3. Suggestion to move the indexing elements into the indexing domain: the elements are left in with other topic elements, because they are not part of the indexing domain. All of the other domains are grouped on their own, so the indexing are as well. I've added links from the indexing domain back to the indexing elements, and a link from index-base to the indexing domain section.
  4. Suggestion in abstract to replace "when the initial paragraph of a topic is unsuitable" with "when a short description alone is unsuitable". I think that initial paragraph is the correct intent here. If the initial paragraph is correct, that paragraph should be in the short description. I've added that clarification.

  5. Move related links into the linking section. The <related-links> element is one of the few major components of a topic, so it is left in the major topic elements section. I've added a cross reference from the related links section to the actual related-links element.

  6. I cannot find a record that map/@title was officially deprecated, but I added a note to the description indicating that <title> is preferred.

  7. Noticed that glossarylist/@href and other listings mention <toc>: these all reuse the same definition. I added a clarification: "All of the book listings operate in a similar manner; for example, <toc...."

  8. The section for %topicref-atts; and %topicref-atts-no-toc; are identical, except that in the no-toc version the toc attribute defaults to "no". I would rather not have elements using the "no-toc" version point to the original, so I have not combined them, though I updated the wording in the intro sections.

  9. The description of @type on note is still in the appendix setion on the type attribute, because it is too long to fit in the normal attribute table (it may run off of the page). I've added this to the section: "The descriptions for the type attribute on linking elements and on note are too long to fit in the usual attribute table, so they are included in this section; for other elements, such as audience, copyright, or object, the description can be found with the element."

These comments address specific comments by Jeff that were not addressed:

  1. Attributes with no default should indicate when there is a processing default. I agree that this should be done, but do not have time to track them all down right now.
  2. Should add ditaval to the spec. I agree, but do not have time to write up the elements.
  3. Question in the image element about longdescref: "Without format, scope, and type attributes, how do you know what the references represents?" Unsure how to clarify this, without having the TC add such attributes, or add longdescref as a nested xref-like element.

  4. Should the "select-atts" attributes on <step> be condensed as on other elements: they are all listed because step does not use the normal select-atts parameter; it re-defines the importance attribute with limited values.

  5. I haven't placed anything about the deprecated grouping syntax for @otherprops with that attribute, as it was not there in the 1.0 spec - it seems odd to add it only after it is deprecated.
  6. It is true that some @importance values cause elements to be re-ordered, but I think this is processor-dependent, so I have not added anything about it.

Fix List for second draft (taken from meeting minutes)

List of TC-authorized changes/rewrites for the DITA 1.1 Language Specification draft. For each item, reference the email or minutes in which the action was directed. As each item is assigned, add the name of the responsible author and indicate when it is Completed.

  1. Indexing changes -- http://wiki.oasis-open.org/dita/Indexing_issue_summary

    • (1.1 alpha draft includes new elements -- Verify that agreed-upon behaviors are documented)
    • Disposition: Done
  2. References to ditabases without explicit topicid
  3. Update description of 'chunk' attribute?
  4. Conref overriding attributes of target

    • Minutes--http://www.oasis-open.org/apps/org/workgroup/dita/download.php/20734/DitaTCMeeting061017.txt

    • Disposition: Done
    • All of the enumerated attributes (except object/@declare) have a new value of -dita-use-conref-target, which needs to be defined somewhere. It should be listed in the language ref - maybe with a pointer to the arch spec for details?
      • Disposition: Done (same as previous item)
    • @print has new values of printonly and -dita-use-conref-target. The commonLRdefs needs to be updated for it.
      • Disposition: Done
  5. Update foreign element to include processing info for generalization/specialization use case
  6. Clarify order of inheritance of attribute values in a DITA relationship table
  7. Change DITA version attribute from text to data and to define version-specific IDs in the catalog
  8. Conref recursion behavior (may not be a Lang Ref issue)
  9. Remove xmlns attribute
  10. resolving conflicts between attributes and metadata in DITA (Lang Spec issue?)
  11. Multiple shortdesc in an abstract in a topic (Lang Spec issue?)

Review comments from Robert D Anderson

Robert's comments have been moved here: Robert D Anderson's Comments

Comments from Jeff Ogden at PTC

Note from Robert: this document is getting very long with my comments. I've just been pointed to Jeff's comments from the 1.0 reference. Rather than growing this doc beyond readability, I'll create a new document for this: JeffOgdensComments

Additional comments by anyone

If you have a couple of comments, please add them here (you may create your own small section if you wish). If you have a large number of comments, please create a new page like the ones above, and indicate that the comments are still open.

Additional fixups by Don

  1. Updated ditaref.bkinfo to reflect OASIS cover structure. Gershon will be working from this to extend the metadata needed to generate the official cover.
  2. changed paths in ditaref-book.ditamap to reflect actual re-built page locations
  3. note that several attribute descriptions in commonLRdefs are just stubs, require more complete description.

  • 1 open

Fix list for 1.1 Language Spec draft (last edited 2007-02-13 15:52:48 by )