This Wiki page is designed to collect comments on the second review of the DITA 1.2 specification, 21 September - 3 October 2009. This review is being conducted by members of the OASIS DITA Technical Committee.

TPrevious | Next | Home page for the second review

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

[Eberlein, 8 December 2009] All sections except "DITA module and shell implementation reference" have been completed.

Introduction to DITA (Completed, 8 December 2009)

No work required

[Doherty, 6 October 2009] 1. Prelims: I hope that we're planning to add some prelims to this spec to set the context BEFORE this introduction:

Sign me up to help writing them if they are unassigned.

[Eberlein, 8 December 2009] Stan, these points hopefully are addressed in the overview topic that is the first topic in the spec. The "What's new in DITA 1.2" might have been relocated to a non-normative appendix; that is what both Elliot and Jeff Ogden have been advocating. Do comment about where the "What's new" info is located, if you do not like its placement in the next draft.


Completed

[Doherty, 6 October 2009]

2. Flow ... this is a linear piece of writing. All the tricks of our trade that support coherent, flowing technical writing should come into play here:

3. Information typing ... we have more than the <p> element in DITA 1.2, right? Break up the long parades of <p> elements to add:

[Eberlein, 2 December 2009] Hi, Stan. I can only hope that the introductory topics in the 3rd draft will have benefited from a vigorous edit to improve clarity and the quality of the prose.


Deferred to DITA 1.3

[Doherty, 6 October 2009]

4. Conceptual diagrams ... between all of us, I'll bet that we have collectively developed several hundred conceptual diagrams about DITA. Let's identify the big-ticket concepts and work up some supporting diagrams. Bonus ... will definitely enhance readability. Sign me up ... I'd love to help.

[Eberlein, 2 December 2009] I wish that this could happen in the DITA 1.2 time frame, but I think it is very unlikely. Can we get you to spearhead this for the DITA 1.3 release?


Rejected

[Doherty, 6 October 2009]

5. Chapter title: Our shared experience of DITA involves lots of stuff that is outside the scope of this spec:

If our focus here is NOT to introduce all of these DITA-related topics, perhaps the title of this chapter should be "Introduction to the OASIS DITA Language Standard". That may help in disambiguating some of our audience issues.

[Eberlein, 2 December 2009] I think what you describe is much more the mission of the OASIS DITA Adoption Committee. I don't think that the next draft will seem as fragmented and fraught with "audience issues." Do this bring this point up again, however, if you don't think that the next draft is substantially improved.


[JeffO, 05 October 2009] Should the introduction be part of the base section or is this really an introduction to the entire specification and so should be in a section of its own separate from other "base" sections?

[Eberlein, 8 December 2009] I'd argue that this is an introduction to the whole spec, and so should be where it is, separate from the other sections.


Completed

[JeffO, 05 October 2009] A suggestion for the first paragraph:

[Eberlein, 1 December 2009] I have removed all of the content from this topic and parceled it out into the other topics in this section. The <shortdesc> now reads as follows: "The Darwin Information Typing Architecture (DITA) is an XML-based architecture for authoring, producing, and delivering information. 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."


Completed

[Eberlein, 4 October 2009] Rewrite the first sentence to read as follows:

[Eberlein, 13 October 2009] Done


Completed

[Eberlein, 4 October 2009] Global comment: Replace instances of "The DITA architecture" with simply DITA. (DITA architecture is redundant.)


Completed

[Eberlein, 4 October 2009] This topic needs a substantial edit. I am willing to volunteer to do it.


Completed

Paul [2009-09-22]: Near the end of the 7th (or so) para, it says "...the DITA architecture...is...applicable to...magazines...."

I guess I don't really care what sort of marketing-eze words we put here, but anyone who really knows about publishing magazines (assuming they also know anything aboutDITA) is probably going to feel we are really crazy to suggest DITA be used for magazine publishing.

[Eberlein, 1 December 2009] Removed reference to magazines


Completed

Paul [2009-09-22]: In the middle of the 9th para, it says:

I don't see how that is true. (In fact, "generic" means to indicate "specific" intents is a contradiction in terms.) I suggest we delete that part of the sentence.

[Eberlein, 1 December 2009] Changed the sentence to read as follows: "DITA provides some means by which authors can indicate specific presentation intents, but in general the DITA architecture expects presentation details to be a matter of separately-specified style applied to semantically-tagged content."

Elliot, what did you have in mind by "means means by which authors can indicate specific presentation intents"?

[Kimber, 1 December 2009] I meant the @outputclass attribute. The @outputclass facility is generic, in that it is available on all elements. You use it to specify specific intent (that is, intent for specific element instances).

But your rewrite seems fine. The main point is to not imply that DITA provides *no* facilities for author specification of formatting intent.


Completed

[Hackos: Sept 26, 2009]

In addition, while The DITA architecture is intended to represent human-readable information, the specification does not define or require any particular presentation form, format, or style for DITA-based content, beyond the specification of default presentation expectations for some element types for which it is both …

Remove the capital T on The; remove the comma after DITA-based content beyond

{Eberlein, 13 October 2009] Done


Completed

JTH: 092609 This Introduction is challenging to read. Recommend moving the last two paragraphs nearer the opening. They are more introductory in style.

[Eberlein, 1 December 2009] Done. I will be reworking this topic extensively, so this revision may not last long ...


Completed

[Doherty, 6 October 2009]

ditaintro.dita: Introduction to DITA ============================================================== Para-1: "The specialization feature ... " - This MUST be a misplaced paragraph. Move to the specialization section or delete.

[Eberlein, 1 December 2009] Moved all specialization content to a new "Specialization" topic, child of "Basic concepts"


Rejected [Doherty, 6 October 2009]

Para-0: I would be expecting the first para to establish context and focus (selection) ... the classic rhetorical funnel. - "DITA (Darwin Information Typing Architecture) is an industry standard

[Eberlein, 8 December 2009] Stan, this is a gorgeous piece of prose. But I don't think that it fits well with direction that we are taking the spec, especially with peoples concerns about including non-normative material. Perhaps the DITA Adoption Committee would be a worthy recipient of this write-up?


No work required

[Doherty, 6 October 2009]

Para-2 thru Para-10: Good content in need of some shaping ... perhaps sections on History, Architecture, and key concepts. The sequence seems a bit random as is.

[Eberlein, 1 December 2009] I think this comment becomes extraneous given the complete reworking of the "Introduction to DITA" topic.

About The Specification Source (Completed, 2 December 2009)

Completed

[Eberlein, 21 September 2009] Use sentence-style capitalization for topic titles

[Eberlein, 13 October 2009] Done


Completed

[Eberlein, 2 October 2009] Rewrite this topic as follows:

[Eberlein, 13 October 2009] Done


Completed

[Hamilton, 02 October 2009] Somewhere, either here or at the top, there should be a link to where the source of the specification can be found.

[Eberlein, 1 December 2009] Added a draft comment to this effect.


Duplicate

[JeffO, 02 October 2009] The source for the DITA specification is going to be included in one or more packages, isn't it. If so, say so in this section.


Duplicate

[JeffO, 02 October 2009] Where are the details of the various packages given?

[Eberlein, 2 December 2009] Where do you think that this should be explained? My initial reaction is that this information needs to be in the "Overview of the DITA 1.2 specification" topic ...

[Eberlein, 2 December 2009] Marked as duplicate, since this review comment is also logged on the "Overview of the DITA 1.2 specification" page.


Completed

[JeffO, 02 October 2009] Do readers beyond the DITA TC need to know about Subversion? I suspect not and so think we should not mention that.

[Eberlein, 13 October 2009] Changed to read "The source files for the DITA specification are managed in a version control repository that is maintained by OASIS."


[Doherty, 6 October 2009]

Rejected

Para-1: Wow ... I thought that it was verboten to reference open source or commercial tools. Technically, the DITA source used to produce this specification could be built using any number of tools outside the DITA-OT. I love the DITA-OT, but we should drop the reference in this context.

[Eberlein, 13 October 2009] The DITA OT *is* what we are using to build output. Accordingly, I think it is reasonable to mention it. We also distribute the DITA source files and I think that people ought to be able to reproduce the output formats predictably -- or at least understand *why* output formats of the DITA source look different if they use a different processor.


Completed

[Doherty, 6 October 2009]

Para-2: We should state that the spec source files are available upon request from OASIS. I have learned so much from the spec source files; let's make them available.

[Eberlein, 13 October 2009] Changed to read as follows:

Definitions and background concepts (Completed 13 October 2009)

Completed

[Eberlein, 4 October 2009] Change the title to be "Definitions." (As you'll see in a comment below, I suggest that "Basic concepts" not be nested under "Definitions"; it should be at the same level.

[Eberlein, 13 October 2009] Done

Terminology (Completed, 4 December 2009)

Deferred until DITA 1.3

[Doherty, 6 October 2009]

hese definitions are simultaneously fabulous and confusing. If we are serious about being in the XML language specification business, we need to complement these terminological definitions with programmatic diagrams. A series of focused little diagrams capturing the containment/hierarchy of our XML objects would go a long way in helping readers understand inter-relationships. I see five or six of them in there ... basics (types, elements, attributes), base and specialization types, modules, domains, and shells.

[Eberlein, 2 December 2009] Stan, I agree that a "series of focused little diagrams" would help immensely. However, I just don't think that an improvement that we can make in the DITA 1.2 time frame. Would you be willing to take on this work effort for the DITA 1.3 release?


Completed

[Doherty, 6 October 2009]

Local shell: Sorry ... this is still scary stuff to me. I suspect that these local shells and concrete document types are outside the scope of the OASIS-sponsored modules and shells. Would it suffice to say that local shells are available as optional extensions to standard DITA? - I totally disagree with the tone and substance of the following

[Eberlein, 2 December 2009] As a result of decisions made by the group of TC members who had several calls about terminology -- see http://www.oasis-open.org/apps/org/workgroup/dita/email/archives/200911/msg00135.html -- we are removing any discussion of local shells.


Completed

[Doherty, 6 October 2009]

Information architect: Say what? If we're not going to define the variety of roles or functions performed by people in a DITA group, we shouldn't call this one role out. A prelim topic on audience would be a better context for getting into roles and functional responsibilities.

[JeffO, 02 October 2009] Is "Information Architect" a term we need to define as part of the DITA specification? I'd rather not include it.


Deferred until DITA 1.3

[Doherty, 6 October 2009]

Missing terms: FWIW, I thought that some terms used in this terminology section ought to be candidates for definition: - document - processor - DTD - schema - module - topic - map - required - normative - conforming

Sign me up ... be glad to help here.

[Eberlein, 2 December 2009] As a result of the terminology calls that occurred in November, we are removing rather than adding terms to the "Terminology" topic. Yes, many of the terms that you mentioned are used in the definitions, but I think that it would be impossible (and probably not useful) to completely implement a closed circle of terminology definitions. I was not able to participate in the terminology calls, since I was travelling or presenting, but my understanding of the consensus that emerged is that the terms defined in the topic should be restricted to DITA-specific items.


Completed

Paul [2009-09-22]: Under Generalization it says:

So what do we call a generalization that does not preserve enough original information to recreate the specialized form?

I do not think we need to require that the specialized form can be recreated just to call it a generalization. That may be a goal of certain generalizing processes, but it should not be a requirement just to call it a generalization.

[Eberlein, 2 December 2009] Generalization now is defined as "The process by which a specialized element is transformed into a less-specialized ancestor-element type or a specialized attribute is transformed into a less-specialized ancestor attribute. The original specialization-hierarchy information may be preserved in the generalized instance, thus allowing the original specialized type to be recreated from the generalized instance."

Paul, does this adequately handle your concerns?


Completed

[Hackos: Sept 26 2009]

[Eberlein, 1 December 2009] According to Gershon, the terms have been arranged as decided by the ad hoc terminology group in November. See http://lists.oasis-open.org/archives/dita/200912/msg00043.html


Completed

DITA Document “However, every DITA document has implicit concrete document type implied by the value of the @domains attribute on the document's root element.”

JTH: 092609 “… document has an implicit …” add “an”


Completed

Document type module “A document type component used to compose concrete document types according to DITA-defined implementation requirements. There are two types of document type module: vocabulary modules, and constraint modules. Document type modules are combined through integration and specialization to construct concrete document types.”

JTH: 092609 “…two type of document type modules …” add “s”


Completed

Selective domain extension “An extension that replaces a extension element with element types defined in a domain module, making the base type unavailable in the concrete document type that configures the extension.”

JTH: 092609 “…replaces an extension element “ change “a” to “an”


Completed

JeffO, 02 October 2009] Additional terms or keywords are defined by reference to RFC 2119 in the 'Conformance' section, but that section comes at the very end of the specification, while the terms are used throughout the spec. I think we should include these definitions explicitly (not by reference) in the main terminology section, possibly grouped into a conformance sub-section. Specifically the terms: must, must not, required, shall, shall not, should, should not, recommended, may, and optional. In addition I think we need to define the term "normative" and the term "example" and state explicitly that all examples are non-normative unless explicitly stated otherwise.

[Eberlein, 2 December 2009] I have incorporated the definitions specified at http://www.ietf.org/rfc/rfc2119.txt. Can you draft the other material that you are suggesting incorporating? (normative, example, and a statement that all examples are non-normative unless explicitly stated otherwise.

[Eberlein, 4 December 2009] Added above material (condensed) in a draft comment in the topic.

[Eberlein, 9 December 2009] Added content to the topic


Deferred until DITA 1.3

[JeffO, 02 October 2009] Add the following terms: DITA models, DITA declarations, DITA instances, ditabase

[Eberlein, 1 December 2009] Per decisions of the ad hoc terminology group, we are avoiding adding new definitions to the spec for this release.


Completed

[JeffO, 02 October 2009] For DITA document use angle brackets consistently (either always out them around <map> and <topic> or never put them around <map> and <topic>.


Completed

[JeffO, 02 October 2009] A suggestion for "Specialization":


Completed

[JeffO, 02 October 2009] Should a third definition for "Specialization" be added:

[Eberlein, 2 December 2009] Done


Completed

[JeffO, 02 October 2009] A suggestion for "Generalization":


Completed?

[JeffO, 02 October 2009] The <dita> element does not support the domains attribute.

[Eberlein, 2 December 2009] Jeff, I hope that the rework on thie topic has eliminated the above problem. I cannot find any mention of the <dita> element in conjunction with the @domains attribute. Please let me know if I am missing something.


Completed

[JeffO, 02 October 2009] "Concrete document type" is a new term for me. Do we need it? Is it a widely accepted term? How is a "Concrete document type" different from a "DITA document type"? I am hoping that we can omit this term, but if we keep it, the definition is much too detailed. The details should be moved out into some other section. Here is a shorter version:

[Eberlein, 2 December 2009] Replaced with the following: "A unique set of structural modules, domain modules, and constraint modules that taken together provide the XML element and attribute declarations that define the structure of DITA documents. DITA document types normally are implemented using DITA document-type shells."


Completed

[JeffO, 02 October 2009] A suggestion to move some information frin "Base type" ti "Specialized element type":

[Eberlein, 18 October 2009] Done


[JeffO, 02 October 2009] "Document type shell" do we need to say something about the <dita> element? Possibly:


Completed

[JeffO, 02 October 2009] The definition for "Local shell" is too long. It goes into material should should be included in other sections of the specification. Here is a shorter version:

[Eberlein, 2 December 2009] Replaced with a <dlentry> for "DITA document-type shell." The definition contains "A set of DTD or XSD declarations that implement a DITA document type by using the rules and design patterns that are included in the DITA specification. A DITA document-type shell includes and configures one or more structural modules, zero or more domain modules, and zero or more constraint modules. With the exception of the optional declarations for the <dita> element and its attributes, DITA document-type shells do not declare any element or attribute types directly."


Completed

[JeffO, 02 October 2009] I don't agree with the third note for 'Local shell' and in any case don't think that a list of definitions is the right place for such editorial comments even if there is widespread agreement.

[Eberlein, 2 December 2009] Removed, per decisions made by the ad hoc terminology group.


Completed

JeffO, 02 October 2009] In the 'Instances, Modules, and Declarations' diagram it looks as of strictMyTopicConstraint.mod references the two mod files when it shouldn't. Where to the .ent files come into this? Do we need a diagram that shows how things work in the XSD world?

[Eberlein, 2 December 2009] Jeff, how would you suggest that this graphic be modified? If we cannot modify it before the next review, we can either (1) Add a draft comment specifying what changes will be made to the graphic, or (2) remove the graphic. Which do you prefer?

[Eberlein, 4 December 2009] Added above content to a draft comment in the topic.

[Eberlein, 9 December 2009] Uploaded revised graphic and graphic source file to SVN. Thanks to Jeff for modifying the graphic.

Notation (0 comments)

Basic concepts (Completed, 13 October 2009

Completed

Paul [2009-09-22]: Under Basic concepts it says:

What is "specificity of XML markup"?

[Eberlein, 13 October 2009] I have no idea what was meant here. I have changed this to read as follows -- and I can guaranteer that I will rewrite the <shortdesc> yet again before the 3rd review:


Completed

[Eberlein, 4 October 2009] This section (and its children) needs a substantial edit. I am willing to volunteer to do it.

[Eberlein, 13 October 2009] I am taking responsibility for working these comments and preparing this topic collection for the 3rd review.


Completed

JTH: 092609. Item number 7. Correct the spelling of mandatory

[Eberlein, 13 October 2009]


Completed

[Eberlein, 4 October 2009] Move this topic collection "up" in the hierarchy; it should be at the same nesting level as "Definitions"

[Eberlein, 13 October 2009] Done

Topics and maps (Completed, 2 December 2009)

Completed

[Doherty, 6 October 2009]

The focus for maps here is still kinda locked into DITA 1.1 functionality. All the action for maps in DITA 1.2 involves metadata for <keydef>s ... that should get a paragrph here

[Eberlein, 2 December 2009] Changed the <shortdesc> so that it contains the following content: "Topics and maps are the basic building blocks of the Darwin Information Typing Architecture (DITA). A DITA topic is a titled unit of information that can be understood in isolation and used in multiple contexts. A DITA map is a set of hyperlinks that organize topics and other resources into structured collections of information; it also provides the context in which keys are defined and resolved."

Modified the paragraph about linking to also mention keys. as well.


No work required

Paul [2009-09-22]: Last part of penultimate paragraph reads:

This makes it sound like there is a default for how to chunk, and there isn't (or shouldn't be). I suggest rewording to:

[Eberlein, 13 October 2009] Given the rewrite I've implemented -- see my comment below from 4 October 2009 -- this issue no longer exists.


Completed

[Eberlein, 4 October 2009] Suggest rewriting this as follows:

[Eberlein, 13 October 2009] Done


No work required

[JeffO, 02 October 2009] I like the proposed rewrite above.

Information typing (Completed, 1 December 2009)

Rejected

[Doherty, 6 October 2009]

Love the topic ... classic DITA ... not germane to a language spec ... should be preserved ... but moved to an appendix.

[Eberlein, 1 December 2009] I'm going to leave the topic here; I think it is quite germane to the architectural spec.

Content Reuse (Completed, 29 October 2009)

Completed

[Eberlein, 2 October 2009] Use sentence-style capitalization for topic titles.

[Eberlein, 13 October 2009] Done


Completed

[Doherty, 6 October 2009]

This one needs to be trimmed and focused: - "The DITA language standard contains three categories of elements that

[Eberlein, 29 October 2009] Done. It can use some additional polishing, but the key clean-up work is finished.

Interchange and Interoperation (Completed, 29 October 2009)

Completed

[Eberlein, 2 October 2009] Use sentence-style capitalization for topic titles.

[Eberlein, 13 October 2009] Done


Completed

[Eberlein, 2 October 2009] Change "DITA architecture" to "DITA." (DITA architecture is redundant.)

[Eberlein, 13 October 2009] Done


Completed

[Doherty, 6 October 2009]

Good stuff ... recommend a reordering of points within the paragraph to emphasize the underlying logic of DITA: - All conforming DITA elements and attributes derive . . .

- All DITA content can be understood/taxonomized relative to those

- Because all DITA specializations subclass from the same set of

- Blind interchange and routine interoperation derive from this

[Eberlein, 29 October 2009] Changed to read as follows:

"All conforming DITA elements and attributes are derived from an invariant and mandatory set of base element and attribute types. Because all DITA specializations are created from the same base elements, no specialization can so depart from the base elements so that it cannot be generalized by parsers and processors back to a base element. Blind interchange and routine interoperation derive from this inheritance architecture.

All conforming DITA content can be understood in terms of the base types. This ensures that the following conditions can be met:

Conditional processing (filtering and flagging) (Completed, 1 December 2009)

Completed

[JeffO, 02 October 2009] I don't think that the statement "Elements indicate which conditions they apply to using one or more of the "props" attributes (attributes specialized from the base @props attribute)" is strictly speaking true for the conditional processing attributes that were part of DITA 1.0 before @props and @base were added in DITA 1.1.

[Eberlein, 1 December 2009] Rewrote this topic as follows:


Completed

[Doherty, 6 October 2009]

Good stuff ... needs a focusing sentence to kick it off ... - "The DITA language standard supports another set of elements

[Eberlein, 1 December 2009] Added the following sentence: "The DITA standard contains a set of elements and attributes that supports conditional processing. These elements and attribute provides the general semantic for managing conditional processing, but they impose neither requirements nor restrictions on how particular processors format or organize the output."

Producing different deliverables from a single source (Completed, 1 December 2009)

Completed

[Eberlein, 4 October 2009] Recast the <ul> as a <dl>, with <dlentry> elements for DITA maps, Specialization, Conditional processing, Content referencing, and the @outputclass attribute.

[Eberlein, 13 October 2009] Done


No work required

[Eberlein, 4 October 2009] I think this topic is attempting to cover two main points: 1) DITA is designed for single-sourcing, and 2) Rendition details are handled by different processing implementations. While these points are of course interrelated, they might be better handled separately.


Completed

[JeffO, 02 October 2009] Need to add "Key References" to the bullet list. May also want to add @print to the list.

[Eberlein, 13 October 2009] Added a <dlentry> for "Key referencing, but have not yet added content to the <dd> element.

[Eberlein, 1 December 2009] Added "The keyref mechanism makes it possible to change variables for volatile content, redirect links, and reap the benefits of indirect addressing."


No work required

[Doherty, 6 October 2009]

Love it ... not a bad general model for a lot of other topics: - Good contextual transition - Good focusing sentence - Effective lead-in to the list - Great logic within the list

Concrete Document Types and Modules (Completed, 2 December 2009)

Completed

[Doherty, 6 October 2009]

Sorry ... I can't grok this section. 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?

One exception ... the following sentence is a gem, perhaps the best candidate for an opening sentence for the entire spec: -"DITA can thus be viewed as a standardized application framework

[Eberlein, 1 December 2009] Topic has been extensively reworked. Added a draft comment asking whether the topic adds value or introduces any new content.


Completed

[JeffO, 05 October 2009] I found this section very difficult to read. It uses several new terms that I am not sure are helpful and which I don't think are in common use within the DITA community. I think this section need to be extensively edited.

[Eberlein, 1 December 2009] The topic had been extensively reworked.


Completed

[JeffO, 05 Otober 2009] Can we use the term "DITA Document Type" in place of "Concrete Document Type? Can "document type shell" serve for both DTD and XSD based implementations?

[Eberlein, 1 December 2009] Changed all instances of "concrete document type" to "DITA document type." Removed references to "Shell DTD”, “Head schema”, “Shell XSD”, or “Local shell”.


Completed

[Eberlein, 2 October 2009] Use sentence-style capitalization for topic titles.

[Eberlein, 13 October 2009] Done


Completed

Paul [2009-09-22]: Third para reads:

They are not XSD schemas, they are XML Schema definitions (XSDs). So the above should read:

and then throughout the rest of this page, "XSD schema" should just be "XSD".

[Eberlein, 13 October 2009] Done


Completed

Open comment from review #1

Paul: In "About the DITA 1.2 specification" it says:

In "Concrete Document Types and Modules" it says:

There seems to be a contradiction here. Exactly what is normative?

My understanding is that the document type shells included as part of the specification are normative, but not definitive or not exhaustive.

Dana: I think maybe the word we're looking for is "canonical" - as in "the canonical form of a matrix," or "the canonical works of Shakespeare" - not "normative." The vocabulary is normative, as are the rules of the architecture. But our reference implementation of the architecture is more "canonical."

Or maybe "authoritative" would do...

[Eberlein, 1 December 2009] Changed to read "While the DITA standard provides a starter set of shell DTDs and schemas, these shells are not definitive and exhaustive. What is canonical is the implementation design patterns to which all conforming DTDs, schemas, and modules must conform."


Completed

[Eberlein, 4 October 2009] Global comment: Change "manditory" to "mandatory"

[Eberlein, 13 October 2009] Done


No work required

[Eberlein, 4 October 2009] Regarding the following two sentences:

I think this is misleading. I think I understand what you want to communicate -- that DITA is a very flexible architecture that only requires the base topic and map -- but I think this needs rewording.


Completed

[Eberlein, 4 October 2009] Regarding the last paragraph: I'd suggest changing "Standard DITA practice" to "A best practice".

[JeffO, 05 October 2009] I'd suggest deleting the last paragraph entirely since there is not general agreement that this is a standard or even a best practice. There are many who believe that there are many cases where one can use the DITA doctype shells out of the box and there is no need to create local shells. I believe that. I also believe that there are many cases where you do want to create local doctype shells.

[Eberlein, 1 December 2009] Done.

Module compatibility and the domains attribute (Completed 1 December 2007)

Completed

[Eberlein, 4 October 2009] Regarding your draft comment asking where this topic should be located, I think it has more to do with processing that anything else.

[Eberlein, 1 December 2009] Removed from "Introduction to DITA"; added to the processing DITA map.


Completed

[JeffO, 05 October 2009] "... the set of vocabulary modules it depends on" --> "... the set of vocabulary and constraint modules it depends on".

[Eberlein, 13 October 2009] Changed to read "...the set of vocabulary and constraint modules on which it depends."


Completed

[Hackos: Sept 26, 2009]

“To enable the determination if elements copied into a DITA document from a different DITA document will not be valid in the target document.”

JTH: 092609. Revised wording. “To determine if elements … from a different DITA document are valid in the target document.”

[Eberlein, 13 October 2009] Changed to read as follows:


Completed

JTH: 092609. I don’t think the final paragraph of this section is at all clear. It’s difficult to understand the point being made.

[JeffO, 05 October 2009] I agree with JTH's comment above. In addition, do processors have the option of disallowing or generalizing or, if generalization is possible, is it required"?

[Eberlein, 13 October 2009] Elliot, what were you trying to say here? [Sent a screen capture of this exchange to Elliot]

[WEK, 13 October 2009] This paragraph is as it was in the initial draft. What it's trying to say is that in the case of an unsafe copy, that is one where the copy source is less constrained than the copy target (the document being copied into), the processor may attempt to determine that the content being copied either does not use any elements or attributes not allowed in the copy target or, if it does, can attempt to generalize the copy source until it satisfies the copy target's constraints. That is, copying processors are allowed to actually do the copy if the data being copied is valid after the copy or can recover by applying generalization. Probably better to say that declaratively rather than proceedurally. Here's my shot:

When a copy is unsafe, processors may compare the copy source to the copy target to determine if the copy source satisfies the constraints of the copy target. If the copy source meets the copy target constraints, the copy may be allowed. Processors should issue a warning that the copy was allowed but the constraints are not compatible. If the copy source does not meet the constraints of the copy target, processors may apply generalization until the generalized result either satisfies the copy target constraints or no further generalization can be performed. If the copy can be performed following generalization, the processor should issue a warning that the constraints are not compatible and generalization had to be performed in order to complete the copy operation.

[Eberlein, 1 December 2009] Replaced paragraph with new content provided by Elliot Kimber.

DITA module and shell implementation reference

Completed

DITA module and shell implementation reference – these sentences are both used in the referenced topics. Fix there.

“…others are only used by topics or by maps; and some are only used in specific specializations.

[Eberlein, 13 October 2009] Corrected in both topics.


[Doherty, 6 October 2009]

Needs an introductory paragraph answering the question "What are DITA DTDs, schema, modules in the big picture of things ... why is significant to me?"

XML Schema organization

[Doherty, 6 October 2009]

Feels a bit referen-cy for an introduction.

Nit ... in all the DTD and schema tables, if a left-most cell contains more than one noun and subject, shouldn't the first word (verb) in the middle cell agree with a plural subject? - X,Y define . . .

- X,Y defines ... The first table head label perhaps should be Common module file(s)??


Paul [2009-06-30]: In "XML Schema organization" it says:

We should avoid the word "valid" as that has specific XML meaning. Besides, it has no real DITA meaning. I suspect what's meant here is "compliant with the DITA architecture" or some such.


Paul [2009-06-30]: In "XML Schema organization", under XML Schema catalog identifiers, the entire listing is wrong. It gives URLs instead of the URNs.

See the catalog-dita-xsd.txt file in the latest DITA 1.2 set of XSDs.

Are we distributing the URL based XML schemas as part of DITA 1.2?

If so, should we say something like:


In progress

[Hackos: Sept 26, 2009]

“A significant feature of the DITA implementation is that it places more importance on the modules than on the actual head schema. All element and attribute type declarations are made in modules, which are then integrated into a document type using a head schema. Implementers //spelling correction// are free to create new head schemas that reorganize the modules, introduce new modules, redefine modules, or remove modules as appropriate. For example, the standard topic XML Schema from OASIS includes all of the standard topic domains; in addition, while the default topic XML Schema allows topics to nest, it is not possible to include concepts. //what exactly does this mean; ditto the next sentence?//A new XML Schema can change one or both of these features and still be valid; the XML Schema may add or remove domains, and it may allow topic (s) //add an “s” to topic here// to nest concepts, //remove comma here// or allow authoring of different types at the same level, as in the ditabase document type.”

[Eberlein, 13 October 2009] Corrected spelling and punctuation errors that JoAnn Hackos identified.


Should "... specific specializations" be changed to "... specific document type shells or specific specializations"?


[JeffO, 06 October 2009] In the section titled "XML Schemas versus Modules" should we mention constraint modules:


[JeffO, 06 October 2009] What files should be listed in this section? Just base? Base + bookmap? Base + bookmap + Technical Content?


[JeffO, 06 October 2009] Should the following files be listed: delayResolutionDomain.xsd, hazardstatementDomain.xsd, bookmapGrp.xsd, abbreviateDomain.xsd, glossgroupGrp.xsd, glossgroupMod.xsd, glossentry....xsd, strictTaskbodyConstraintMod.xsd, taskregDomain.xsd


[JeffO, 06 October 2009] Where are the document type shells (Head schemas) listed? We need to list them somewhere, if only to provide a place to explain the difference between task and general task and the various glossary and glossentry files.


[JeffO, 06 October 2009] Should there be a statement about changing URIs similar to the one for DTDs about changing PUBLIC ids:


JTH: 092609 check punctuation in table; it’s inconsistent.

DTD organization

[JeffO, 06 October 2009] If DTDs take precedence over XSDs, perhaps the section on DTDs should come before the section on XSDs?


[JeffO, 06 October 2009] In the first paragraph should "... specific specializations" be changed to "... specific document type shells or specific specializations"?


[JeffO, 06 October 2009] Use "standard OASIS topic document type shell" in place of "standard topic OASIS DTD", "default topic DTD", and "topic DTD". Use "new document type shell" in place of "new DTD", "DTD", and "existing DTD". Use "OASIS version" or "default version from OASIS" in place of "default version".


[JeffO, 06 October 2009] What files should be listed in this section? Just base? Base + bookmap? Base + bookmap + Technical Content?


[JeffO, 06 October 2009] Should the following files be listed: delayResolutionDomain.{mod|ent}, hazardstatementDomain.{mod|ent}, bookmap.ent, abbreviateDomain.{ent|mod}, glossgroup.{ent|mod}, glossentry....{ent|mo}, strictTaskbodyConstraint.mod, taskregDomain.{ent|mod}, xxxx.ent, ....


[JeffO, 06 October 2009] Where are the document type shells listed? We need to list them somewhere, if only to provide a place to explain the difference between task and general task and the various glossary and glossentry files.


[Hackos: Sept 26, 2009] JTH: 092609 check punctuation in table; it’s inconsistent.


Paul [2009-06-30]: In "DTD organization" it says:

We should avoid the word "valid" as that has specific XML meaning. Besides, it has no real DITA meaning. I suspect what's meant here is "compliant with the DITA architecture" or some such.


Paul [2009-06-30]: In "DTD organization", the list of public identifiers:

includes the following that aren't in the DITA 1.2 catalog:

PUBLIC "-//OASIS//DTD DITA 1.1 Concept//EN" "concept.dtd"
PUBLIC "-//OASIS//DTD DITA 1.0 Concept//EN" "concept.dtd"
PUBLIC "-//OASIS//DTD DITA 1.1 Composite//EN" "ditabase.dtd"
PUBLIC "-//OASIS//DTD DITA 1.0 Composite//EN" "ditabase.dtd"
PUBLIC "-//OASIS//DTD DITA 1.1 Glossary//EN" "glossary.dtd"
PUBLIC "-//OASIS//DTD DITA 1.1 Reference//EN" "reference.dtd"
PUBLIC "-//OASIS//DTD DITA 1.0 Reference//EN" "reference.dtd"
PUBLIC "-//OASIS//DTD DITA 1.1 Task//EN" "task.dtd"
PUBLIC "-//OASIS//DTD DITA 1.0 Task//EN" "task.dtd"
PUBLIC "-//OASIS//DTD DITA 1.1 Topic//EN" "topic.dtd"
PUBLIC "-//OASIS//DTD DITA 1.0 Topic//EN" "topic.dtd"
PUBLIC "-//OASIS//DTD DITA 1.1 Map//EN" "map.dtd"
PUBLIC "-//OASIS//DTD DITA 1.0 Map//EN" "map.dtd"
PUBLIC "-//OASIS//DTD DITA 1.1 BookMap//EN" "bookmap.dtd"

and is missing the following that are in the DITA 1.2 catalog:

PUBLIC "-//OASIS//DTD DITA 1.x Concept//EN" "concept.dtd"
PUBLIC "-//OASIS//DTD DITA 1.x Composite//EN" "ditabase.dtd"
PUBLIC "-//OASIS//DTD DITA 1.x Glossary//EN" "glossary.dtd"
PUBLIC "-//OASIS//DTD DITA 1.x Reference//EN" "reference.dtd"
PUBLIC "-//OASIS//DTD DITA 1.x Task//EN" "task.dtd"
PUBLIC "-//OASIS//DTD DITA 1.x Topic//EN" "topic.dtd"
PUBLIC "-//OASIS//DTD DITA 1.x Map//EN" "map.dtd"
PUBLIC "-//OASIS//DTD DITA 1.2 Map//EN" "map.dtd"
PUBLIC "-//OASIS//DTD DITA 1.x BookMap//EN" "bookmap.dtd"
PUBLIC "-//OASIS//DTD DITA General Task//EN" "generalTask.dtd"
PUBLIC "-//OASIS//DTD DITA 1.x General Task//EN" "generalTask.dtd"
PUBLIC "-//OASIS//DTD DITA 1.2 General Task//EN" "generalTask.dtd"

Also missing--but perhaps intentionally so--are all those for:

subjectScheme.dtd
classifyMap.dtd
all the learning ones
machineryTask.dtd


[JeffO, 06 Octobner 2009] Where do we describe the conventions for creating PUBLIC ids? Where do we describe the conventions for DITA version numbers that appear in PUBLIC ids or URIs (none, 1.x, 1.2, ...)?

IntroductionToDITA2 (last edited 2009-12-09 17:44:22 by keberlein)