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.

Previous | 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]

DITA processing

[JeffO, 06 October] I've been using the html version to review. Several sections in the 'DITA processing' section (Navigation behaviors, Attribute inheritance) seem very short, to the point that I wonder if something has been omitted.

ID Attribute

ALL COMMENTS DATED BEFORE 2 DEC 09 HAVE BEEN ADDRESSED -- S.PARK

Paul [2009-09-22]: Re:

I don't know what "an DITA types" is supposed to be. Re:

That sentence needs help. The part before the semi-colon doesn't parse as an independent clause, and the part after it should probably be a separate sentence.

Also, the tables on this page make it look like the value space for map and topic ids is different from that for IDs on elements within a topic or map. I don't believe this is true.


[JeffO, 06 October 2009] ids are not required on map elements.

[JeffO, 06 October 2009] I suggest the following:


[jeffO, 06 October 2009] I suggest omitting the 'Exceptions and Special Cases' subsection.


[JeffO, 06 October 2009] Are we missing a section on 'ID References' or 'DITA References'?

[JeffO, 06 October 2009] Are we missing a section on 'Indirect Referencing (Key References)'?

[JeffO, 06 October 2009] OK, I found the sections on 'Linking and addressing' that includes 'URI-based addressing' and 'Keyref (indirect addressing)'. They are not part of the 'Processing" section, which seems odd. I won't review them until I get done with the Processing section, but I think they should be moved into the processing section. I also think the heading should be "Key References" rather than "Keyref".

THIS IS A WEAK SECTION; NOTHING WILL BE DONE ABOUT IT FOR 1.2 [S.PARK] .... .... Paul [2009-06-30]: This "Navigation behaviors" topic has very little content except mentions of tocs, related links, and indexing. Other than the obvious commonly understood ideas of tocs, links, and indexes, what processing is explained here? Is any of this processing "DITA processing"? If so, we need to explain it. If not, then it shouldn't be listed under "DITA processing".


[JeffO, 06 October 2009] We should add cross-references (xref) to the list of Navigation behaviors.

Attribute inheritance

I DONT KNOW ANYTHING ABOUT THIS TOPIC [S.PARK] ...

Paul [2009-06-30]: I assume the "Attribute inheritance" topic remains to be written--there is nothing here currently.

Paul [2009-09-22]: Are we using "inheritance" or "cascading" and have we defined these terms anywhere?

Paul [2009-09-22]: What does "have major impact on authors' ability to generate appropriate output and navigation artifacts" mean?

Content inclusion

[S.PARK: ELIOT IS HANDLING THIS TOPIC]

B. Nevin [20091208: All these comments have been taken care of.]

Paul [2009-09-22]: The first sentence (presumably, the shortdesc, but I'm not sure) is repeated as the first sentence of the next paragraph.


[JeffO, 06 October 2009] "... can be a from one ..." should probably be "... can be from one ...".

[JeffO, 06 October 2009] Consider adding "Any content within the referencing element is either replaced or ignored" to the end of the first paragraph after 'Creating and resolving content references'.

[JeffO, 06 October 2009] Need to scan for the terms 'source' and 'target' and make sure that they are not ambiguous. The terms "referencing element" and "referenced element" may work better and are already used elsewhere in this section.

[JeffO, 06 October 2009] Change "When the key in a conkeyref attribute is not defined, the conref attribute itself must be used instead" to "When the key in a conkeyref attribute is not defined, the conref attribute value, if present, must be used instead".

[JeffO: 06 October 2009] The content after the heading 'Specifying a range of content reference with conrefend' does not match the heading. This content should probably be combined with the previous section and the heading moved up to where conrefend is discussed.

In the section on 'Specifying content reference behavior with conaction' there are too many single and double quotes used together and the text is not as readable as it could/should be.

conrefend attributes

Profiling with select attributes

[S.PARK 2DEC: ALL COMMENTS CONSIDERED] [JeffO, 06 October 2009] What is the preferred name for this feature, "Profiling" or "Conditional Processing"? We should pick one or the other and use it throughout the spec. I think "Conditional Processing" may be the better term. So the heading and first paragraph might become:

[JeffO, 06 October 2009] Are the terms 'applicability' and 'effectively' used correctly in the above? Should 'effectively' be "effectivity'?

[JeffO, 06 October 2009] Strictly speaking audience, platform, produce, rev, and otherprops are not specializations of props.

[JeffO, 06 October 2009] Is the statement "processors are not required to perform conditional processing using metadata elements" true?

[JeffO, 06 October 2009] The statement "DITA defines a single base attribute type, props, that is specifically intended to enable filtering and flagging of individual elements, as opposed to entire topics or map components" goes too far since @props can be used to filter or flag entire topics or map components (although I'm not sure how a 'map component' differs from an 'individual element').


Paul [2009-09-22]: The first sentence (presumably, the shortdesc, but I'm not sure) is repeated as the first sentence of the next paragraph.

Select attributes

[JTH: 1 October 2009. Why have we not extended the audience type attribute as we have the job and experience-level? Shouldn’t we be allowing other values here as well, rather than this peculiar set from 1.0 and 1.1?]

[JeffO, 06 October 2009] I don't understand JTH's comment above. @audience is a CDATA attribute, so the list of acceptable values is really unlimited. What could be extended?

[JeffO, 06 October 2009] The type, job, and experience attributes on the audience element are not enumerated, so I don't understand this statement:

  • The values from the enumerated attributes of the audience metadata element have the same meaning when used in the audience attribute of a content element. For instance, the "user" value has the same meaning whether appearing in the type attribute of the audience element for a topic or in the audience attribute of a content element. The principle applies to the type, job, and experience level attributes of the audience element.

[JeffO, 06 October 2009] Change "In DITA 1.1 ..." to "Starting with DITA 1.1 ..." or perhaps omit the phrase entirely and start "The props attribute can be ...".

Using select attributes

Processing select attributes

Filtering logic

Flagging logic

Chunking

[Hamilton, 02 Oct 2009] Under "Usage of the chunk attribute" (which might be better titled "Using the chunk attribute") ==> Policies for splitting or combining documents ==> by-document: 'The "by-topic" token' should be 'The "by-document" token'

[RDAnderson, 7 December 2009] Updated "Usage of" to "Using the", and corrected the by-topic/by-document error.


[Hamilton, 02 Oct 2009] In the numbered list just before Examples:

[JeffO, 12 October 2009] Reguarding item 1 above: I think the list is correct as written. That in this case the name comes from the name of the map and not from the copy-to attribute. The copy-to attribtue really specifies a new name for a topic. I don't think copy-to would ever apply to a top level map. I guess there might be a case when copy-to would apply to a lower level map, but I'm not sure about that and in any case the map isn't usually copied or named in the same way that a topic is. And if we were too chagne it now, it would be an incompatible change from DITA 1.1, something the TC would need to discuss before going ahead with such a change.

[RDAnderson, 7 December 2009] This is correct, as Jeff described. The map actually cannot specify the copy-to attribute - the only way to specify copy-to for a map is when referencing a sub-map, but as Jeff says, requiring that behavior would be incompatible with DITA 1.1.


[JeffO, 12 October 2009] In the intro. just after the "Examples" heading, a "d" is missing in "chil2.dita" and "grandchil2.dita".

[RDAnderson, 7 December 2009] Fixed


[Hamilton, 02 Oct 2009] In Examples, shouldn't 3 say "containing topic P1, with topic Y1 nested within P1, but without topic Y1a." (i.e., adding ", nested within P1" to be consistent with Example 4)?

[JeffO, 12 October 2009] Re example 3, I agree.

[RDAnderson, 7 December 2009] Updated


[JeffO, 12 October 2009] Does the statement earlier that "" apply here? Should the output file name be based on the name of the map rather than the name of the topic? I'm guessing not because "to-content" wasn't used, but it makes you wonder.

[RDAnderson, 7 December 2009] No, because to-content was not used. The to-content token on the map element is a specific way to say that the entire map contents go into one chunk. The by-topic or by-document tokens on a map just establish policy values used by other topicrefs in the map.


[Hamilton, 02 October 2009] In Examples, what is the meaning of the file suffix .xxxx? It's not explained, and there are cases where copy-to explicitly defines a file name ending in .dita, but the explanation uses .xxxx (for example, examples 6, 7, and 8).

[JeffO, 12 October 2009] The file extensions for output files will usually be dependent on the type of output being produced and might have values such as "htm", "html", "pdf", etc. I guess it isn't out of the question for an output file to use the ".dita" extension, but that would be unusual. In any case the DITA speciication does not specify what file extensions output processors must use (and it shouldn't). The ".xxxx" suffix is used to avoid the implication that the file extension for the output files must match the file extension for the input files. It would be a good idea to say this explicitly rather than having it all implied by the ".xxxx" string.

[RDAnderson, 7 December 2009] Clarified - I added a paragraph just after the "Examples" heading that basically says what Jeff said.


[Hamilton, 02 Oct 2009] In Example 7, is topic C2 in both parentchunk.dita and child2chunk.dita? If so, it's worth an explanatory note, since that seems counter-intuitive.

[JeffO, 12 October 2009] I am not sure that example 7 is right either. Why doesn't the "by-document" on the map tag cause more than two chunks to be produced?

[RDAnderson, 7 December 2009] There was a typo, in that it should have read "The first chunk named parentchunk.xxxx will contain the topics P1, C1, C3, and GC3." As written, the C2 appears in place of C3, meaning that a) C2 is in both chunks, b) C3 does not appear anywhere, and c) somehow GC3 ends up under C2 in the first chunk. So, this was pretty clearly meant to refer to C3.

The by-document setting on the map creates a default policy for the map, which indicate that any reference is treated as a reference to the entire document, so that "ditabase.dita#Y1" would still result in pulling in the entire document. Basically, this token determines what is selected by the topicref for the purposes of chunking. The "to-content" setting causes a single new chunk of content to be created, containing all topics selected by the current topicref and its children (until a new chunk is forced by the C2 branch).

I've updated the reference to use C3 in place of C2 - if that still seems wrong, we should add whatever clarifications are needed during the 3rd draft review.

Printing

Paul [2009-09-22]: What is the difference between print="yes" and print="printonly"? This page does not make that clear--in fact, it makes them sound identical.

Stan Doherty [2009-12-10]: I added a table that spells out the overlap in functional similarities and a paragraph explaining that the difference is focused more on semantics than function.


[JeffO, 06 October 2009] Would this be a better description for @print="yes":

Or this is what the Language Reference says about @print:

Stan Doherty [2009-12-10]: Regarding @print="printonly", I tested that setting and could not verify that setting this attribute value on a child topic overrides the @print setting (especially the default) of the parent map element. Some time between early discussions of this setting before DITA 1.1 and the final DITA 1.1 spec, the notion of overriding the parent setting slipped from view. The DITA 1.2 language spec focuses on the current map element, not its parent.

Consider adding: If a value for @print is not specified locally, but it specified on an ancestor, it will inherit the value of on the ancestor. If the value is not specified on an ancestor, a default of "yes" is assumed.

Stan Doherty [2009-12-10]: I verified that this addition is in the topic.

[JeffO, 06 October 2009] Need to add something about the default value (yes) to the Language Reference too.

Stan Doherty [2009-12-10]: I verified that the latest source for Language Ref (topicref-atts.dita) specifies that the default is yes.

[JeffO, 06 October 2009] Put the value 'resource-only' into quotes.

Stan Doherty [2009-12-10]: I verified that this addition is in the topic.


Open comments from review #1

[WEK, 6 July 2009]:

[Hamilton, 16 July 2009]:

s.park: not change as of 18 sept 2009. we need to find a new owner for this topic.

Collation

Open comments from review #1

[WEK, 6 July 2009]:

Stan Doherty [2009-12-10]: I verified that this addition is in the topic.

[Hamilton, 16 July 2009]: Stan Doherty [2009-12-10]: I verified that this addition is in the topic.

Stan Doherty [2009-12-10]: I verified that this edit is in the topic.

Stan Doherty [2009-12-10]: I added two examples for <index-sort-as> in the topic.

Translation

The xml:lang attribute

[JTH, 18 October 2009] Following changes made.

[JeffO, 06 October 2009] I suggest the following change:

  • Note that the recommended style for the xml:lang attribute is lower case language and uppercase locale, separated by a hyphen, i.e., "en-US" or "sp-SP" or possibly simply "en" or "sp".

Just trying to avoid the implication that you must or should specify both the language and the locale.

[JeffO, 06 October 2009] Suggest rewording as follows:

[JeffO, 06 October 2009] So what is 'the default value' the is to be assumed? The Language Ref says "When no xml:lang value is supplied, the default value of English is assumed". Is this correct? Can processors assume a different default? I suggest this wording:

We need to say this for both maps and topics and in both the Arch Spec and in the Language Ref.

[JeffO, 06 October 2009] I suggest deleting the following two paragraphs:


[JTH, 18 October 2009] Following changes made.

Paul [2009-09-22]:

Under "Use with the conref attribute", the wording is confusing. First, this paragraph is using the word "source" for what we usually call the conref target, and "source" and "target" are usually opposites, so I think this needs to be reworded. Also, "must obtain the value of the xml:lang attribute from the closest containing element" doesn't make it clear if it's talking about the element containing the conref or the element in the conref target that is being referenced by the conref. The example makes it clear it is the latter, but the prose needs help.

I would suggest the following rewrite of the first para in this section:

The dir attribute

Elements and their translation properties

Completed

[JTH, 18 October 2009] I don’t agree with this recommendation. Other members of the Translation SC, which asked for this table, concur. This topic could be part of the language reference rather than the architectural specification but the topic is necessary for proper implementation of the standard by translation vendors.

Paul [2009-09-22]: This entire page/topic does not belong in the DITA spec. It should be deleted and published as an article by the DITA Adoption TC.

[Eberlein, 7 December 2009] This topic has been moved into an non-normative appendix.

ditaProcessing2 (last edited 2009-12-10 13:06:11 by StanDoherty)