This Wiki page is designed to collect comments on the third review of the DITA 1.2 specification, 11 December 2009 - 4 January 2010. This review is being conducted by members of the OASIS DITA Technical Committee, OASIS DITA Adoption Committee, and the OASIS Technical Advisory Board.

Contents

Introduction to DITA

Previous | Next | Home page for the third review

Important: Reviewers, be sure to preface comments with your name and the date, for example, [Eberlein, 18 September 2009]

Introduction to DITA

Completed

[Jeff, 2 Jan 2009] There are three paragraphs with some good words in the DITA 1.1 Spec. at the start of Chapter 2 "Introduction to DITA" that I can't find anywhere in the DITA 1.2 spec. It would be a shame to lose them, so it would be good to include them somewhere, possibly here or perhaps in the earlier "Overview of the DITA 1.2 specification". These are the words:

DITA is an architecture for creating topic-oriented, information-typed content that can be reused and single-sourced in a variety of ways. It is also an architecture for creating new topic types and describing new information domains based on existing types and domains.
The process for creating new topic types and domains is called specialization. Specialization allows the creation of very specific, targeted document type definitions while still sharing common output transforms and design rules developed for more general types and domains, in much the same way that classes in an object-oriented system can inherit methods of ancestor classes.
DITA topics are XML conforming. As such, they are readily viewed, edited, and validated with standard

XML tools, although some features such as content referencing and specialization may benefit from customized support.

One possibly might be to split the current paragraph in two and reword it something like this:

The Darwin Information Typing Architecture (DITA) is an XML-based architecture for authoring, producing, and delivering topic-oriented, information-typed content that can be reused and single-sourced in a variety of ways. It is also an architecture for creating new document types and describing new information domains based on existing types and domains. The process for creating new types and domains is called specialization. Specialization allows the creation of very specific, targeted document type definitions while still sharing common output transforms and design rules developed for more general types and domains, in much the same way that classes in an object-oriented system can inherit methods of ancestor classes.

While DITA historically has been driven by the requirements of large-scale technical documentation authoring, management, and delivery, it is a standard that is applicable to many sizes and kinds of publication or information that might be presented to readers, including interactive training and educational materials, standards, reports, business documents, trade books, travel and nature guides, and more. Because DITA topics are XML conforming they are readily viewed, edited, and validated using standard XML tools, although realizing the full potential of DITA will require using DITA-aware tools or customizations.

[Eberlein, 5 March 2010] Changed to read as follows:

"The Darwin Information Typing Architecture (DITA) is an XML-based architecture for authoring, producing, and delivering topic-oriented, information-typed content that can be reused and single-sourced in a variety of ways. While DITA historically has been driven by the requirements of large-scale technical documentation authoring, management, and delivery, it is a standard that is applicable to any kind of publication or information that might be presented to readers, including interactive training and educational materials, standards, reports, business documents, trade books, travel and nature guides, and more.

DITA is designed for creating new document types and describing new information domains based on existing types and domains. The process for creating new types and domains is called specialization. Specialization enables the creation of very specific, targeted document-type definitions that still can share the common output transformations and design rules developed for more general types and domains; this is similar to how classes in an object-oriented system can inherit the methods of ancestor classes.

Because DITA topics are XML conforming, they can be readily viewed, edited, and validated using standard XML tools, although realizing the full potential of DITA requires using DITA-aware tools."

About the specification source

Completed

[Jeff, 2 Jan 2010] Isn't the source for the DITA specification being included in the .zip file for the entire specification? If it is, and I think it should be, we should say that here.

[Eberlein, 1 March 2010] Added draft comment to the DITA file, with a reminder that the topic needs to be updated to confirm with the official overview page for the DITA 1.2 specification and the decisions about packaging that the TC made in February 2010.

Completed

[SDoherty, 4 Jan 2010] COMMENT: It's great to put this note right up front. I recommend that "package" be qualified here a bit. Many people associate "DITA specification" with the DITA 1.1 spec documents (architecture and language ref) apart fom the DTDs/schema/shells etc..

[Eberlein, 9 January 2010] Stan, what note are you referring to? And how do you want package to be qualified? Do you want us to list the basic contents of each package, for eaxmple, DTDs and XSDs, documentation (XHTML, PDF, and DITA source), whatever else?

[Eberlein, 10 January 2009] Sent e-mail to Stan Doherty.

[Eberlein, 1 March 2010] Haven't heard from Stan; am changing the disposition of this comment to "Completed."

Terminology and notation

Deferred to DITA 1.3

[Hamilton, 4 Jan 2010] Should there be a definition for DITA attribute? There are definitions of DITA element and DITA element type, but only a definition of DITA attribute type.

[Eberlein, 10 January 2010] Sent e-mail to ad hoc Terminology group

[Jeff, 10 January 2010] This would be fine with me, but I don't feel strongly about it.

[Eberlein, 11 January 2010] I'm going to mark this as "Deferred to DITA 1.3." We have larger issues that are higher priority to be handled before we release 1.2.

Completed

[Hamilton, 4 Jan 2010] Specialization terminology -> base type: "All base DITA types ..." ==> "All DITA base types ..."

[Eberlein, 10 January 2010] Changed to "All base types ..."

Rejected

[Hamilton, 4 Jan 2010] DITA modules: shouldn't there be a definition of what a "module" is? You can kind of figure it out, but it would be useful to have a specific definition.

[Eberlein, 10 January 2010] Sent e-mail to ad hoc Terminology group

[Jeff, 10 January 2010] My thought is that a definition for "module" isn't needed here. I think what a module is made clear in later sections. I'm not sure that there is much that is really DITA specific about modules. But I don't feel strongly about this and so, if others want to include it, I'd go along.

{Eberlein, 11 January 2010] I also don't think that there is anything DITA-specific about "module," and I want to avoid any definitions that are not absolutely necessary.

Completed

[Hamilton, 4 Jan 2010] Linking and addressing terms -> Key definition: This entry really defines "key-defining element" and not "key definition." Since "key-defining element" is used in the previous entry (key), I think this entry should be renamed "key-defining element." I'm not sure that "key definition" needs to be defined.

[Eberlein, 10 January 2010] I actually think that the entry for key definition is fine, although I agree that it is potentially synonymous with "key-defining element." I think the problem is with the definition for key. A key should not be defined as "An identifier defined by a DITA key-defining element"; it should be defined as "A value of the @keys attribute." Let's solicit more discussion for a broader group about this.

[Eberlein, 10 January 2010] Sent e-mail to ad hoc Terminology group

[Jeff, 10 January 2010] We need the definition for "Key definition". I agree with Kris's comment. But I think we should change the term from "key" to "key name". I'd suggest this as the revised entry:

key name<BR> An identifier defined as a value of the @keys attribute. A key name is bound to the resource addressed by the <topicref> element or the specialization of a <topicref>, resources contained within a <topicmeta> element of the <topicref> element or the specialization of a <topicref> element, or both.

[Eberlein, 1 March 2010] Done

Completed

[Jeff, 2 Jan 2010] Is the sentence "This terminology is not intended to serve as a tutorial or provide a user-friendly introduction to the DITA standard" really needed? It doesn't read well as it stands. I think it could be deleted since we said earlier that the entire spec. wasn't an introduction or a user guide.

[Eberlein, 9 January 2010] Done

Completed

[Jeff, 2 Jan 2010] Under "Notation" could the intro sentence be reworded to read "The following conventions are used throughout the specification:"?

And shorten "When elements are named outside of a list, they may be delimited ..." to "Elements names may be delimited ..." which I think it clearer and more parallel with the description for attributes?

[Eberlein, 9 January 2010] Done

Deferred to DITA 1.3

[Jeff, 2 Jan 2010] Is the following statement really true?

In general, the unqualified use of the term map or topic can be interpreted to mean "a <map> element and any specialization of a <map> element " or "a <topic> element or any specialization of a <topic> element."

I suspect that topic or map can also mean an entire topic or an entire map and not just the topic or map elements. Or do we always qualify the former usage with a phrase such as "DITA topic" or "DITA map"? If we do, we should say so. This might be reworded as:

The unqualified use of the terms map and topic refer to "a <map> element or a specialization of a <map> element" and "a <topic> element or a specialization of a <topic> element." The terms DITA map and DITA topic are used to refer to entire maps, map specializations, topics, and topic specializations. An unqualified element name usually refers to that specific element or to a specialization of the element.

Or should this paragraph be moved into the "Basic DITA terminology" section as entries for "map", "topic", "DITA map", "DITA topic", and element name?

[Eberlein, 10 January 2010] Sent e-mail to ad hoc Terminology group

[Eberlein, 1 March 2010] Since no one has made additional comments about this, changing disposition to "Deferred to DITA 1.3."

Completed

[Jeff, 2 Jan 2010] Need to work "informative" into the heading or reword the last sentence, giving something like this:

[Eberlein, 9 January 2010] I think some key information got lost here. Which heading or sentence are you referring to?

[Eberlein, 10 January 2009] Sent e-mail to Jeff Ogden.

[Jeff, 10 Jan 2010] Yes, something got lost or never entered. Sorry. The heading reads "Normative and informative information", but the two terms that are defined don't include "informative" or at least not in the sub-heading that gives the term. So I think we need to work "non-normative" into the heading, perhaps "Normative and non-normative (informative) information".

[Eberlein, 11 January 2009] Changed header to "Normative and non-normative information"

Completed

[SDoherty, 4 Jan 2010] LINE EDIT: Notation section

FROM: "This specification uses specific conventions for mentions of element and attribute types:"
TO: "This specification uses the following conventions for references to element and attribute types:"

[Eberlein, 9 January 2010] Changed to read as follows: "The following conventions are used throughout the specification:"

Completed

[Jeff, 2 Jan 2010] In the "Conformance terminology" section:

Need periods at the end of the "must" and "should" sections.
Missing a closing parenthesis near the end of the "may" section.

[Eberlein, 9 January 2010] Done

Completed

[SDoherty, 4 Jan 2010] LINE EDIT: Agreement in multiple variant instances in the Conformance terminology <dl> section

FROM: "This word, or the terms "required" or "shall", mean . . . "
TO: "This word, or the terms "required" or "shall", means . . . "

[Eberlein, 9 January 2010] Stan, this wording is copied verbatim from RFC 2119. It's not immediately clear to me whether the subject is singular or plural. I'd like to consult an editor. If you could take the time to further investigate this, I'd appreciate it.

[Eberlein, 10 January 2009] Sent e-mail to Stan Doherty.

[Eberlein, 1 March 2010] Haven't heard from Stan; am changing the disposition of this comment to "Completed."

Duplicate

[SDoherty, 4 Jan 2010] LINE EDIT: must <dl> -- add final period.

Duplicate

[SDoherty, 4 Jan 2010] LINE EDIT: should <dl> -- add final period.

Completed

[SDoherty, 4 Jan 2010] LINE EDIT: should not <dl> -- add comma after "not recommended"

[Eberlein, 9 January 2010] Done

Duplicate

[SDoherty, 4 Jan 2010] LINE EDIT: may <dl> -- add closing parenthesis after "the option provides"

Completed

[Jeff, 2 Jan 2010]

Non-normative (informative) information

Non-normative information includes descriptions that provide background, examples, and other useful information that are not formal requirements or rules that must be followed. The terms non-normative and informative are used interchangeably.

[Eberlein, 9 January 2010] Done

Completed

[Jeff, 2 Jan 2010]

The final paragraph is kind of long already and I'm going to suggest adding something about appendices that would make it even longer, so perhaps it should be split into two paragraphs as follows:

All information in the specification should be considered normative unless it is an example, an appendix, or is labeled as informative or non-normative. Appendices are always non-normative unless it is explicitly stated otherwise.

The DITA specification contains examples to help clarify or illustrate specific aspects of the specification. Because examples are specific rather than general, they may not illustrate all aspects or be the only way to accomplish or implement an aspect of the specification. Therefore all examples are informative rather than normative, unless it is explicitly stated otherwise.

[Eberlein, 9 December 2010] Left in one <p>, which reads as follows; wording changes indicated in bold:

"All information in the specification should be considered normative unless it is an example, an appendix, or is explicitly labeled as informative or non-normative. Appendices are always non-normative, unless explicitly stated otherwise. The DITA specification contains examples to help clarify or illustrate specific aspects of the specification. Because examples are specific rather than general, they might not illustrate all aspects or be the only way to accomplish or implement an aspect of the specification. Therefore all examples are non-normative, unless explicitly stated otherwise."

Completed

[SDoherty, 4 Jan 2010] LINE EDIT: Normative and informative information

FROM: "All information . . . unless it is explicitly stated otherwise."
TO: "All information . . . unless explicitly stated otherwise."

[Eberlein, 9 December 2010] Done

Completed

[Jeff, 2 Jan 2010] In the "Basic DITA terminology" section:

Need a comma before "but" in the last item under "DITA document".

[Eberlein, 9 December 2010] Done

Rejected

[SDoherty, 4 Jan 2010] LINE EDIT: Basic DITA terminology

FROM: "One of the base attribute types that are defined . . . "
TO: "One of the base attribute types defined . . . "

[Eberlein, 9 January 2010] No, this usage of the "syntactic this" is important for translation and making the text easier to read for ESL readers. John Kohl at SAS wrote the paradigmatic article on this topic: "Improving Translatability and Readability with Syntactic Cues." I've uploaded a PDF of the article to the document repository.

Duplicate

[SDoherty, 4 Jan 2010] LINE EDIT: Basic DITA terminology - DITA attribute type

FROM: "One of the base attribute types that are defined . . . "
TO: "One of the base attribute types defined . . . "

Completed

Paul [2009-12-11]: [minor edit] Under Specialization terminology, under generalization, an extra hyphen has crept in that shouldn't be there. Change "ancestor-element type" (which is meaningless at best or even misleading, as we are not talking about structural ancestry of the elements) to "ancestor element type" (which I still think is a poor way to word it, but at this point, let's get this spec out).

[Eberlein, 11 January 2010] Changed to " less-specialized ancestor element"

Rejected

[SDoherty, 4 Jan 2010] LINE EDIT: Specialization terminology - base content model

FROM: "The content model ... or the application of constraints or extensions."
TO: "The content model ... or before the application of constraints or extensions."

[Eberlein, 9 January 2010] I cannot see that the rewrite adds additional information or improves clarity.

Rejected

[SDoherty, 4 Jan 2010] COMMENT: Specialization terminology - specialization parent: Feels as though "ancestor" should be "predecessor" or "parent" in context.

[Eberlein, 9 January 2010] No, in this context "ancestor" is the correct word choice. "Parent" or "predecessor" imply containment rather than specialization hierarchy.

Completed

[Jeff, 2 Jan 2010] Under "restricted content model" there is a phrase "(or more?)" that needs to be resolved. I think "or more" is correct and so this should become "... for the element type by one or more of the following mechanisms:".

[Eberlein, 9 January 2010] Done

Completed

[SDoherty, 4 Jan 2010] LINE EDIT: DITA modules - constraint module

FROM: "A set of declarations that impose . . ."
TO: "A set of declarations that imposes . . ."

[Eberlein, 9 January 2010] Done

Completed

Paul [2009-12-11]: [minor edits] Under selective domain extension, change "replaces a extension element" to "replaces an extension element"

[Eberlein, 9 January 2010] Done

Rejected

Paul [2009-12-11]: Under selective domain extension, change "document-type" to "document type".

[Eberlein, 11 January 2010] Standard writing practices call for avoiding noun strings, usually defined as four or more nouns in a sequence. "DITA document type shell" is a good example. Noun strings are difficult to translate and especially hard for ESL readers to parse. Hyphenation is one way to approach the problem when you cannot simply get rid of the noun string.

Completed

Paul [2009-12-11]: [minor edits] Under specialized attribute type, change "The attribute type be specialized" to "The attribute type must be specialized" and change "and its value must be" to "and its range of allowable values must be".

[Eberlein, 11 December 2001] Done

Completed

Paul [2009-12-11]: [minor edits] Under "key", change "element or the specialization of" to "element or a specialization of" in both bullets.

[Eberlein, 11 December 2001] Done

Completed

Paul [2009-12-21]: To make things consistent with my suggestion for the Conformance section, we should insert:

All Appendices are considered informative unless labeled as normative.

as the second sentence of the last paragraph of the "Normative and informative information" section.

[Eberlein, 9 January 2010] Paul, after working review comments above by Jeff Ogden, this section of the topic now reads as follows:

"All information in the specification should be considered normative unless it is an example, an appendix, or is explicitly labeled as informative or non-normative. Appendices are always non-normative, unless explicitly stated otherwise. The DITA specification contains examples to help clarify or illustrate specific aspects of the specification. Because examples are specific rather than general, they may not illustrate all aspects or be the only way to accomplish or implement an aspect of the specification. Therefore all examples are non-normative, unless explicitly stated otherwise."

Does this work for you?

[Eberlein, 10 January 2009] Sent e-mail to Paul Grosso.

Paul [2010-01-10]: Yes, the new wording you show above works for me.

Completed

[Jeff, 2 Jan 2010] The diagram that comes at the end of this section should probably come at the end of the "DITA modules" subsection. And the heading "Example" might be better as "Relationships among DITA modules" or some such.

[Eberlein, 9 January 2010] I've moved the content of the section titled "Example" to the "DITA modules" section. Because of this change in location, it no longer has a heaer. However, the graphic is preceded by the following text -- "The following figure illustrates the relationship between a DITA document, its DITA document-type shell, and the various vocabulary modules that it uses." Also, the <figure> uses the following caption: "Instances, modules, and declarations".

Completed

[Jeff, 2 Jan 2010] The definition for "Domain" that was part of the DITA 1.1 spec. is missing. Is that deliberate?

Domain

A set of elements or an attribute that supports a specific subject area. Elements or attributes in a domain can be integrated with topic or map types to enhance their semantic support for particular kinds of content. For example, the structural type <topic> declares the <keyword> element; when integrated with a domain for describing user interfaces, new keyword specializations (such as <wintitle>) become available wherever <keyword> was allowed in the original structural type.

[Eberlein, 10 January 2010] Sent e-mail to ad hoc terminology group.

[Eberlein, 1 March 2010] From scanning the rest of the terminology topic, I see that the DITA 1.1 definition for "domain" has morphed into a definition for "domain module." Changed disposition to completed.

Basic concepts

Completed

[MPriestley 17 December 2009] Most of these topics are redundant with ones later in the spec, especially under Processing. In the 1.1 spec, there was no redundancy - the "basic concepts" section simply linked to overviews distributed across the arch. Now that we have these redundant sections, it's a lot harder to see how the sections relate, and we have the same info expressed in different ways in different parts of the spec.

[Hamilton 4 Jan 2010] Michael makes a good point here, though I do think it's nice to have a place to go to get oriented. If you do keep these topics, they should at least point to the related information in other sections.

[Eberlein, 12 January 2010] Michael, you make an excellent point. I wish that this issue had been raised earlier; I don't think that the original writers (mine is the 3rd set of hands that has been on these topics) were aware of the logic behind the architectural strategy in the DITA 1.1 spec. Also, the problem of duplication has been further aggravated by our team authoring approach.

From my point of view, we must avoid unnecessary duplication of material; it is antithetical to the principles of modularity and single sourcing which are underpinnings of DITA. (It also impedes maintenance and significantly raises the likelihood of inconsistency.)

Off of the topic of my head, I see the following options:

Return to the architectural strategy employed in the DITA 1.1 spec, where the "Introduction to DITA" section simply contained cross references to core conceptual topics, accompanied by conrefed short descriptions from the topics
Have the other sections of the spec contain the cross references and conrefed short descriptions to the core conceptual topics, which remain located in the "Introduction to DITA" section

If there's any other possibilities, I'm not seeing them. Which route we take might need to be driven by which will require the least work.

Either strategy is going to require (at least) the following work:

Identifying where topics overlap
Consolidating overlapping material into a single topic or single topic collection

I'm going to create a Wiki page and start identifying the areas of overlap: Content duplication problem

[Eberlein, 6 March 2010] I've reworked this section to use the same IA strategies as the DITA 1.1 documentation did.

Topics and maps

Completed

Paul [2009-12-11]: [minor edit] The penultimate paragraph starts with the following sentence:

DITA topics can be used and published individually, for example, one can represent an entire deliverable as a single DITA document that consists of a root topic and nested topics.

The first comma should be either a semi-colon or a period.

[Eberlein, 11 December 2001] Done; changed the comma to a semi-colon.

Rjected

[SDoherty, 4 Jan 2010] COMMENT: Basic concepts - Topics and maps: The meaning of the phrase "subject scheme maps" in the second para is not familiar to me nor recoverable in context.

[Eberlein, 9 January 2010] Stan, I think the following sentence (emphasis added) clearly indicates meaning:

"The DITA specification provides specialized map types; book maps represent printed publications, subject scheme maps represent taxonomic or ontological classifications, and learning maps represent formal units of instruction and assessment."

Completed

[MPriestley 17 December 2009] Add word "typically" to intro explanation for both topics and maps - you can have topics that are not meant to be understood in isolation, and you can have maps that contain no hyperlinks

[Eberlein, 9 January 2010] Changed the 2nd sentence of the short description to read as follows (emphasis added): "A DITA topic is a titled unit of information that typically can be understood in isolation and used in multiple contexts.

Michael, what sort of DITA map would have no hyperlinks?

[Eberlein, 10 January 2009] Sent e-mail to Michael Priestley.

[Eberlein, 1 March 2010] Haven't heard from Michael; changing disposition to "Completed."

Completed

[MPriestley 17 December 2009] "Typically, a given DITA map represents a single deliverable, for example, a specific Web site, a printed publication, or the online help for a product." - or a component of these (and change typically to often - taxo maps don't represent a single deliverable, for example)

[Eberlein, 9 January 2010] Changed to read as follows:

"DITA maps often represent a single deliverable, for example, a specific Web site, a printed publication, or the online help for a product. DITA maps also can be subcomponents for a single deliverable, for example, a DITA map might contain the content for a chapter in a printed publication or the troubleshooting information for an online help system."

Completed

[MPriestley 17 December 2009] "You also can use a relationship table to associate task topics with supporting concept and reference topics. " This limits reltables to just one case. Need to make clear it's an example - eg "to associate topics with each other based on row membership, for example associating task topics..."

[Eberlein, 9 January 2010] Changed to read as follows: "You also can use a relationship table to associate topics with each other based on membership in the same row; for example, you can associate task topics with supporting concept and reference topics."

Completed

[Jeff, 3 Jan 2010] In its title and at the start of this section we talk about topics followed by maps. Then later in the section we give details about maps followed by the details about topics. The section would read better if we used the same order throughout the section.

[Eberlein, 9 January 2010] Moved the <p> about topics to follow the <shortdesc>.

Completed

[Jeff, 3 Jan 2010] In the 4th paragraph the statement "In addition to organizing topics into sequences and hierarchies" is the first mention of sequences, which seems awkward given the wording "In additon".

[Eberlein, 9 January 2010] Changed the first sentence to read "DITA maps organize topics into sequences and hierarchies."

Completed

[Jeff, 3 Jan 2010] Also in the 4th paragraph we talk about keys and link relationships together. It makes them sound as if they were the same thing or at least related. It would be better to talk about them separately. When it comes to link relationships, it might be better to call this "linking relationships" and make it clear that the sequence and hierarchy as well as relationship tables can be used to establish linking relationships.

[Eberlein, 5 March 2010] Added Jeff's comment to the DITA topic as a draft comment. Any content in that topic that is not already handled in the Processing section will be dealt with there.

Information typing

Completed [Hamilton, 4 Jan 2010] The second paragraph seems out of place here. I'd suggest dropping it.

[Eberlein, 11 January 2010] Done

Completed

[SDoherty, 4 Jan 2010] LINE EDIT: Basic concepts - Information typing - para 2

FROM: "DITA currently defines . . . that reflect common practices . . ."
TO: "DITA currently defines . . . that reflects common practices . . ."

[Eberlein, 9 January 2010]

Completed

[Hamilton, 4 Jan 2010] Third paragraph, third sentence: "... types as can be defined as..." ==> "...types can be defined as..."

[Eberlein, 9 January 2010] Done

Completed

[Hamilton, 4 Jan 2010] Fourth paragraph, first sentence: "...requirement that a particular user of DITA use..." ==> "...requirement to use..."

[Eberlein, 9 January 2010] Changed to read "You need not use any of the currently-defined information types"

Linking and addressing

Completed

[Hamilton, 4 Jan 2010] Types of DITA links, Navigation links, first sentence: "... links establish navigation relationships and primarily are intended to enable..." ==> "...links enable..."

[Eberlein, 9 January 2010] Done

Completed [Hamilton, 4 Jan 2010] Types of DITA links, Navigation links: The second sentence is about use-by-reference links, not navigation links. I'd remove it and the following sentence. The last sentence in that paragraph would probably work better in the paragraph that immediately follows the heading "Types of DITA links."

[Eberlein, 9 January 2010] Removed the two sentences and added them as in <p> in the "Use-by-reference links" section.

Completed

[Hamilton, 4 Jan 2010] Types of DITA links, Use-by-reference links: This paragraph does not describe what a use-by-reference link is. Maybe re-purpose the 2nd and 3rd sentences under Navigation links.

[Eberlein, 9 January 2010] Done

Completed

[MPriestley 17 December 2009] image and object seem to belong in use-by-reference cat, and topicref is arguable

[Eberlein, 5 March 2010] Added Michael's comment to a draft comment in the DITA topic. Any content in the topic that is not already addressed in the "Processing" section will be handled there.

Completed

[MPriestley 17 December 2009] "Some links, in particular <topicref> elements, can serve as both navigation links and use-by-reference links depending on how they are used and configured." Should be "depending on the processor" - for example, they may be resolved into content during output to PDF, but resolved to links during output to HTML

[Eberlein, 5 March 2010] Changed to read as follows:

"Some links, in particular <topicref> elements, can serve as both navigation links and use-by-reference links depending on how they are processed; for example, they might be resolved into content when transformed to PDF, but they might be resolved to links when transformed to HTML."

Completed

[MPriestley 17 December 2009] Under "Navigation links", reltable item: "Used within DITA maps to relate sets of topics to each other. Each row in the relationship table defines a single hyperlink among two or more sets of topics or non-DITA resources." should be "defines hyperlinks among".. ("a single hyperlink" is just wrong, or at least very unlikely)

[Eberlein, 9 January 2010] Done

Completed

[MPriestley 17 December 2009] Under "Navigation links", link item: should mention non-DITA resources as potential targets

[Eberlein, 9 January 2010] Done

Completed

[MPriestley 17 December 2009] Under "Navigation links", xref item: may also be resolved to inline, for example when specialized to coderef

[Eberlein, 5 March 2010] Added Michael's comment to a draft comment in the DITA topic. Any content in the topic that is not already addressed in the "Processing" section will be handled there.

Completed

[MPriestley 17 December 2009] Generally this whole section is problematic, just because most things can be resolved into either content or a link (conref excepted).

[Eberlein, 5 March 2010] Added Michael's comment to a draft comment in the DITA topic. Any content in the topic that is not already addressed in the "Processing" section will be handled there.

Completed

[Jeff, 3 Jan 1010] Is "hyperlink" the right term to use here? I think of a "hyperlink" as something that appears or which might appear in rendered output, but not as the thing that is authored in the DITA source. What is authored are relationships. How those relationships are rendered will depend on the type of output, the processor that is used, and how the processing has been customized, probably through the use of a stylesheet.

[Eberlein, 5 March 2010] Added Jeff's comment to a draft comment in the DITA topic. Any content in the topic that is not already addressed in the "Processing" section will be handled there. Changing disposition of the comment to "In progress," as (1) I want to check how frequently hyperlinks are used in this manner in the draft spec, and (2) I want to consider whether such usage is appropriate.

[Eberlein, 9 March 2010] I'll send an e-mail to the list so that we can discuss this issue. Changing disposition to "Completed."

Content reuse

Completed

[Hamilton, 4 Jan 2010] The previous section refers to use-by-reference, which I took to mean the conref mechanism. If that's the case, why is the term not used in this topic at all? If it's not the case, then it would help to have a clearer definition of what use-by-reference means.

[Eberlein, 5 March 2010] Added Dick's comment to a draft comment in the DITA file. Any content in the DITA file which is not already handled in the "Processing" section will be handled there.

Completed

[Hamilton, 4 Jan 2010] Third paragraph, fourth sentence: "...often includes legal warning..." "...often includes legal warnings..."

[Eberlein, 9 January 2010] Done

Completed

[Jeff, 3 Jan 2010] There seems to be a lot of overlap between this section and the previous section on linking and addressing. Do we need both?

[Hamilton, 4 Jan 2010] Overall, I agree with Jeff's thoughts, though I wouldn't object to the section staying

[Eberlein, 5 March 2010] Per the decision of the SWAT team that met on 2 March, all such content will be handled in the "Processing section." Changing the disposition of the comment to "Completed."

Completed

[SDoherty, 4 Jan 2010] FRIENDLY SUGGESTION: Basic concepts - Content reuse - para 1

FROM: "The primary . . . "
TO: "Any number of DITA maps can reference any number of DITA topics. This is the primary reuse mechanism in DITA."

[Eberlein, 9 January 2010] Done

Interchange and interoperation

Completed

Paul [2009-12-11]: [major confusion on my part] The third bullet point of this topic reads:

Any two DITA users can use each other's DITA topics and maps with neither advance knowledge of each other's processing environment nor the need to have previously agreed on a common set of XML document types.

Either I'm confused or I think this statement is wrong. If you create some specialized elements and send me your DITA topics and maps but don't send me your DITA document types, I'm not going to be able to edit or process your documents because they refer to doctypes I don't have and elements for which I don't have declarations. You are going to have to send me your doctypes too--just like in any other XML case--so I don't get at all the part about no "need to have previously agreed on a common set of XML document types".

[Eberlein, 11 December 2009] I agree. I meant to query Eliot about this ... Eliot, was the point that you intended to make the following:

Two DITA users do not need to have advance knowledge of each other's processing environments nor do they need to have previously-agreed upon common specializations. As long as they exchange the doctypes for any specializations, generalization can occur.

[Eberlein, 10 January 2009] Sent e-mail to Eliot Kimber.

[Eberlein, 1 March 2010] Never heard back from Elliot. Changing text to read as I suggested above.

Completed

[MPriestley 17 December 2009] This is a good section to have, but seems a bit strong - what does "mandatory" mean? A specialization can leave off elements and attributes... And a specialization may create processing requirements that are necessary for display/understanding of the content (eg syntaxdiagram, but especially anything specialized from foreign or data)

[Eberlein, 1 March 2010] Removed references to "mandatory and invariant." Hopefully that addresses the problem.

Completed

[Jeff, 3 Jan 2010] Can this be reworded, "... no specialization can so depart from the base elements so that it cannot be generalized by parsers and processors back to a base element."? Make it a positive rather than a negative statement. Avoid using the word "so" so often. Perhaps:

Because all DITA specializations are created from this common set of base elements and attributes, all specializations can be generalized by parsers and processors back to a base elements or attributes.

[Eberlein, 9 January 2010] Changed to read as follows (changes from your suggestion indicated with strikethrough and bolding):

"Because all DITA specializations are created from this common set of base elements and attributes, all specializations can be generalized by parsers and processors back to a the base elements or and attributes.

Conditional processing

Completed

[Hamilton 4 Jan 2010] First paragraph, second sentence: In addition to Jeff's comments below, semantic should be semantics.

[Eberlein, 9 January 2010] Changed to read "These elements and attributes provide the general semantics for managing conditional processing"

Completed

[Hamilton 4 Jan 2010] Second paragraph, first sentence: If the list of starter attributes is short, I'd include it here, maybe just parenthetically after the word "attributes."

[Eberlein, 1 March 2010] Leaving wording as is. Changing disposition to "Completed."

Completed

[MPriestley 17 December 2009] I'd like to make ditaval a bit stronger than "may" - maybe should?

[Jeff, 3 Jan 2010]

We should make this as strong or as weak as it was in DITA 1.1.

I see this wording in the 3rd review draft: "The DITAVAL file is one mechanism for specifying how processors should handle the conditional processing attributes." [emphasis added]. I do not see the word may anywhere. So, is this good enough?

I've always thought that the DITA spec. should say what the desired result is, but not say exactly how that result has to be achieved. So to my way of thinking "conditional processing" including a requirement to provide specific filtering and flagging behaviors could be a should or even a must requirement, but saying that DITAVAL is the way that this must or should be implemented is going too far.

However, I have a conflict here in that I didn't think that DITAVAL should be included in the DITA spec. at all. But that fight was fought and lost for DITA 1.1 and so I'm not sure that going back and refighting it now is appropriate and I'm willing to stick with the requirements imposed in DITA 1.1.

I just went back and looked at the DITA 1.1 Arch. Spec. The string "ditaval" only appears in the arch. spec. once in the section on file extensions. There is this comment in the DITA 1.1 Conditional Processing section: "At processing time, you specify the values you want to exclude and the values you want to flag using a conditional processing profile (described in the DITA Language Specification)." And some DITAVAL markup does appear in some examples in the arch spec.

DITAVAL is described in the DITA 1.1 Language Reference as "formalized for DITA 1.1". The description uses the term "can", but I don't see any real guidance in terms should or must. And while the DITAVAL elements are described in the DITA 1.1 Language Reference the DTD itself was not included with the other DITA 1.1 DTDs. It continued to be available as part of the DITA OT.

[Eberlein, 10 January 2010] The "may" statement is in the last sentence of the topic; I'll quote it and the preceding sentence below:

. "The DITAVAL file is one mechanism for specifying how processors should handle the conditional processing attributes. Processors may provide other mechanisms for conditional processing.

I think the normative terms "should" and "may" are used correctly here, and I've tagged them in <term> elements in the DITA source. I think the larger questions are 1) Whether we state in the specification that processors either should or must provide filtering and flagging behavior, and 2) If we want to make this statement, where should it go?

See also the discussion at DITA processing > Conditional processing

[Jeff, 10 January 2010] But Michael wasn't suggesting that we change "may" to "should" in that sentence was he? That would make it: "Processors should provide other mechanisms for conditional processing." and I'm thinking that that isn't something that Michael would suggest.

I'm happy with the current wording. There wasn't a review comment asking to make DTIAVAL a "must" rather than a "should" was there?

Filtering and flagging can't be a must requirement for all processors because some processors don't need to implement conditional processing (editors for example). This starts to take us down the path of creating feature groups and saying that certain feature groups are or are not required for the various categories of processors. That is something we should do, but not something we are going to get done for DITA 1.2. But having said this, I would be comfortable with Conditional Processing being either a must or a should as long as the use of DITAVAL is no more than a should.

[Eberlein, 1 March 2010] Leaving wording as is. Changing disposition to "Completed."

Completed

[Jeff, 3 Jan 2010] Reword "These elements and attribute provides ..." as "These elements and attributes provide ..."

[Eberlein, 9 January 2010] Done

Separation of content and presentation

Completed

[MPriestley 17 December 2009] First paragraph shouldn't start with "In addition"...

[Eberlein, 9 January 2010] Removed "In addition." Also please see my response to the comment that immediately follows.

Completed

[SDoherty, 4 Jan 2010] FRIENDLY SUGGESTION: Basic concepts - Separation of content and presentation - para 1: Break this up into 2- 3 separate sentences ... it's kinda run-on in its present form.

[Eberlein, 9 January 2010] I agree; it's an awful run-on mess. I suspect that I ran out of energy or time and so didn't edit this topic; it doesn't even have a short description! I have rewritten the topic to read as follows:

"Because DITA is designed to enable the publication of content to any number of different formats, it must maintain as complete a separation between content and presentation as possible. This means that DITA processors, rather than the DITA standard, are responsible for defining the details of the presentations that those processors produce.
The DITA specification does not define or require any particular presentation form, format, or style, beyond certain default presentation expectations that are necessary to foster reasonable consistency across different implementations of common presentation targets, such as HTML and PDF.
DITA provides some means, such as the @outputclass attribute</ph>, which authors can indicate specific presentation intents, but in general the DITA standard expects presentation details to be a matter of separately-specified style that is applied to semantically-tagged content. This separation of content and presentation is essential to ensuring that DITA content is inherently reusable in a wide variety of contexts and for a wide variety of presentation and delivery environments."

Completed

[SDoherty, 4 Jan 2010] LINE EDIT: Basic concepts - Separation of content and presentation - para 1

FROM: "Because DITA . . . different format, . . . "
TO: "Because DITA . . . different formats, . . . "

[Eberlein, 9 January 2010] Done

Duplicate

[Jeff, 3 Jan 2010] Reword "... any number of different format" as "... any number of different formats".

Producing different deliverables from a single source

Completed

[Hamilton 4 Jan 2010] Second paragraph, last sentence: enables ==> enable

[Eberlein, 9 January 2010] Done

DITA document types and modules

Completed

[Jeff, 3 Jan 2010]

In a draft comment Kris asks a question or really reasks a question that was originally asked by Stan: "What specific new content gets introduced here? Even the pitch for local shells is redundant. If it were deleted, what new content would we miss here?"

I think this section could be omitted. If we do that, we'd need to check to be sure that any essential points made here are made in the more detailed section on specializations that comes later.

If the decision is made to keep this section, I think it could be made shorter. We need to ask what information is essential to an understand of the DITA specification and what information is really just explaining concepts that are part of XML? We should keep the former and delete the later.

This statement makes me uneasy: "XSDs need not declare all element types in a document, if the schema allows the content of specific elements to include unknown element types." While I think it is true in general, I'm not sure it is true or useful in the context of a DITA document type. Don't we need a declaration for every element, other than those that might appear within <foreign>, if only to get the default class attribute values?

If we choose to keep this section, I would suggest this shorter version:

DITA document types and modules
DITA is unlike most other XML standards. While the DITA standard includes a starter set of DITA document types, these document types are not definitive or exhaustive. Instead the DITA standard defines design patterns that can be used to construct new use-case-specific DITA document types.

DITA document types are implemented using DITA document type shells which may be DTD or XSD based. The document type shells simply include vocabulary and constraint modules, which provide all of the actual declarations that make up the DITA document type. Thus DITA document types are assembled using standard DITA-defined and non-standard, but DITA-conforming, declaration modules.

Because there is no single definitive set of DITA document types, DITA should be viewed as a standardized application framework that provides the building blocks and extension rules by which DITA-based applications can be constructed that ensure interchange and interoperability of all DITA conforming documents.

[Hamilton 4 Jan 2010] I think the added value here is what Jeff has captured in his suggested re-write. I would suggest taking his shorter version and using that. You might also consider combining this with "Information typing" which is related and hints at the same point.

[Eberlein, 9 January 2010] Replaced body of topic with the content provided by Jeff