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

  1. DITA processing
    1. Module compatibility and the @domains attribute
    2. Navigation behaviors
    3. Linking and addressing
    4. DITA addressing
      1. @id attribute
      2. URI-based (direct) addressing
      3. Key-based (indirect) addressing
    5. Content inclusion (conref)
    6. Profiling with select attributes
      1. Select attributes
        1. Using select attributes
        2. Processing select attributes
        3. Filtering logic
        4. Flagging logic
    7. Chunking
    8. Printing
    9. Collation
    10. Translation and localization
      1. The xml:lang attribute
      2. The dir attribute

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]

[WEK 31 Jan 2010] Comments complete for linking and addressing topics. Working with David H. to refine organization of Keyref topic per his comments but all other comments integrated.

DITA processing

/!\ Redundant content item still open

Redundant content

[MPriestley 17 December 2009] Many topics here are redundant with "Basic concepts" - need to eliminate redundancy

Completed

[Eberlein, 9 January 2010] Insertions marked in bold:

[gerjosep 1FEB2010 : Fixed]

Completed

[Eberlein, 9 January 2010] Remove or comment out <draft-comment> elements.

[gerjosep 1FEB2010 : Removed]

Module compatibility and the @domains attribute

Redundant content

[MPriestley 17 December 2009] redundancy here with the content inclusion topic

[Jeff, 5Jan 2010] Delete this topic. Make sure that all of its content is covered in the conref processing topic, the @domains specializations topic, or the @domains description in the Language Reference.

[Eberlein, 9 January 2010] This topic seems out of place; it seems jarring and certainly does not create a logical flow for people reading the processing section sequentially.

No action

[Eberlein, 9 January 2010] What sort of "media-specific navigational aids" are there other than those discussed in this topic?

[Anderson, 10 March 2010] Facet-based browsing would be one that comes to mind. I suspect there are other ways to navigate information outside of a TOC, index, or set of links, but I'm not sure - search based tools probably count.

No action

[Eberlein, 9 January 2010] Regarding "Processors may generate a TOC based on the hierarchy of the <topicref> elements in the DITA map"; should this be a must statement? Under what circumstances would we want processors to ignore the hierarchy of the the <topicref> elements?

[Anderson, 10 March 2010] I don't think that the lack of a TOC means that the hierarchy is necessarily ignored. For facet based searching, for example, the hierarchy may still result in parent/child links and relationships, even if no TOC is ever presented to the end user.

Completed

[Eberlein, 9 January 2010] Remove quotation marks around "navigation tree" and "map reference."

[gerjosep 1FEB2010 : Done.]

Completed

[RDAnderson, December 16 2009] 2nd paragraph in the TOC section: last sentence should end with "referenced topic's title" (add a D to reference), to match "referenced topic's title" in the first sentence.

[gerjosep 1FEB2010 : Done.]

Completed

[Jeff, 5 Jan 2010] Do we want to include a comment stating that nesting topicrefs within topicrefs that reference ditamaps is undefined?

[gerjosep 1FEB2010 : Added the following note after the paragraph that discusses map references: If a <topicref> element that references a map contains child <topicref> elements, the processing behavior of the child <topicref> elements is undefined.]

Completed

[Jeff, 5 Jan 2010] Make it clear that <navtitle> is prefered over @navtitle when both are present and that @locktitle applies to both.

[gerjosep 1FEB2010]Added the following sentence:

Completed

[Jeff, 5 Jan 2010] This isn't the whole truth, is it? "By default, a TOC node is generated for every <topicref> element (or specialization thereof) in the map". What about @processing-role? @print? Conditional processing? No @href and no @title (a topicgroup)?

[gerjosep 1FEB2010 : I have tried to address this comment, though the result is rather wordy and long. I'm not sure if I've captured all the cases, but I could not come up with suitable wording that didn't list all the cases Jeff mentioned.]

Completed

[RDAnderson, December 16 2009] 3rd paragraph in the TOC section: "@toc attribute is inherited by" should read "@toc attribute cascades to" - we've replaced the "inherit" term with "cascade" for 1.2

[gerjosep 1FEB2010 : Done.]

Completed

[RDAnderson, December 16 2009] 3rd paragraph in the TOC section: this says that if @toc=no on a topicref, all of that topicref's children are excluded from the TOC. That is only true when a child topicref does not turn the TOC back on with toc="yes" - if it is turned back on, the branch that is marked toc="yes" should appear in the TOC (minus the intermediate nodes that turned off @toc)

[gerjosep 1FEB2010 : I reworked the paragraph to add this clarification.]

Redundant content

[Eberlein, 9 January 2010] There is overlap with the content in DITA markup > DITA maps > DITA map attributes. Is this overlap problematic?

Completed

[Jeff, 5Jan 2010] In the section on Linking, 3rd paragraph make it clear that links can be autogenerated from the hierarachy and/or a relationship table. As it is written now, it seems to say that this is just done from reltables.

[Eberlein, 9 January 2010] In my reading, the topic seemed to be stating that auto-generated links arise only from the @collection-type attribute.

[Anderson, 10 March 2010] Changed the text to:

Completed

[RDAnderson, December 16 2009] In the Indexing section, the first sentence is not actually a sentence (doesn't seem to have a subject). It probably needs something like "An index may be " at the start of the sentence.

[Anderson, 10 March 2010] Completed

Completed

[MPriestley 17 December 2009] Reltable links are not marked up explicitly - they are implied by membership in a row

[Anderson, 10 March 2010] Completed -- see the revised text two comments above

Completed

[DHelfinstine, 20091228] Spelling 'controled' -> 'controlled'.

[Anderson, 10 March 2010] Completed

Linking and addressing

[WEK 24 Jan 2010] All review comments complete. Issues related to overall organization need to be resolved by the editors.

Completed

[TC, March 9] Need to resolve use of Hyperlink with language elsewhere

[Anderson, March 10 2010] Completed - generally replaced with "reference" as elsewhere.

Completed

[Eberlein, 9 January 2010] This topic is much too long. Consider splitting it into several, smaller topics.

[WEK 24 Jan 2020] Done. Created subtopics out of each of the three titled sections.

Completed

[MPriestley 17 December 2009] This topic should be retitled to "DITA linking" in the map (to match source, and because addressing has clearly been split out)

[WEK 24 Jan 2020] Done.

Completed

[Eberlein, 9 January 2010] Change "Hyperlinks serve to relate information components together for various purposes" ==> "Hyperlinks express relationships between information components"?

Or, consider making the following changes; deletions indicated with strikethough; insertions indicated with bolding:

. "Hyperlinks serve to relate information components together for various purposes. DITA depends heavily on links. The different purposes for which it provides different kinds of links include defining the content and organization of publication structures,- topic-to-topic navigation links, and cross references, and reuse of content by reference."

I have no idea what was meant by "defining the content and organization of publication structures".

[WEK 24 Jan 2010] Synthesized these two comments into a rewritten paragraph. Clarified "the content and organization of publication structures" as "(DITA maps)". One challenge in explaining all this is that maps have many different specific applications, of which representing publications is only one, although the most common.

Completed

[Eberlein, 9 January 2010] What is a "a typed relationship among two or more objects"?

[WEK 24 Jan 2010] Removed "typed" from the initial sentence and added more content around link types and the fact that not all DITA-defined links are explicitly typed. Added explanatory note.

Completed

[Eberlein, 9 January 2010] Regarding "DITA formally defines only explicit links, although processors may implement implicit links." Do we really want to imply that it is optional for processors to generate TOC hierarchies based on nesting of <topicref> elements in a DITA map?

[WEK 24 Jan 2010] Added clarifying example.

ToC hierarchy relationships are not implicit, they are explicit in the semantics of topicref elements and the collection-type attribute. By "implicit" is meant "links established based on same data relationship not established by the markup itself.

But having said that, I don't think that treating a topicref hierarchy as a ToC is mandatory since the meaning of a map is not constrained to publication structures. I would say that "if you are producing something that looks like a publication then you should produce something like a ToC using the navigation structure as defined by the topicrefs in the map."

Completed

[Eberlein, 9 January 2010] What do we mean by "a use-by-reference relationship"? Is this a conref? I also do not understand what is meant by "Use-by-reference relationships establish the effective structure and content of the information set."

[WEK 24 Jan 2010] Yes, conref is one form of use-by-reference relationship in DITA.

Completed

[Jeff, 5Jan 2010] This may be too picky, but are hyperlinks authored or are they rendered is some output types? It seems that we use markup to establish relationships and roles as well as to author links. The relationships, roles, and links are then rendered in various ways, possibly as hyperlinks, but possibly as lists or as words (see "xxxxx" on page "yy").

[WEK 24 Jan 2010] I use the term "hyperlink" to mean the relationship, not its expression in a particular rendition. Thus hyperlinks are always authored. "Navigable links" is the term I use to mean links as rendered so that you can click on them and go somewhere.

Completed

[Eberlein, 9 January 2010] Do we need all of the terminology that is introduced in this topic?

[WEK 24 Jan 2010] I don't see how I can clearly explain the concepts without defining these terms, so yes, we need them.

Completed

[Jeff, 5Jan 2010] This may be picky too, but how does the statement "In general, elements that take both the @href and @keyref attributes always act as navigation-link-defining elements" apply to something like <topicref> that take both @href and @keyref when no @href value is supplied directly using @href or indirectly from the key definition?

[WEK 24 Jan 2010] Added qualifier "within topics"

Completed

[Jeff, 5Jan 2010] This statement caught me off guard: "This case can be avoided by using a resource-only topic reference in the map tree to establish the dependency explicitly." Is this true?

[WEK 24 Jan 2010] Yes. Why wouldn't it be true? A resource-only topicref has the explicit purpose of establishing a dependency on a resource used for some other purpose (conref, xref, multiple topicrefs from a single map, etc.).

Completed

[Jeff, 5Jan 2010] Is the statement "In the specific case of cross references created using <xref>, the potential set of rules for constructing link text is essentially unbounded" limited to xref or does it apply to link and other linking elements that support @outputclass as well?

[WEK 24 Jan 2010] I suppose so. Added link within related links to this statement.

Completed

[Jeff, 5Jan 2010] In "links within maps" need to be clear about sequence relationships created or implied by the map hierarchy and relationships created using relationship tables. Mostly that these relationships can be rendered in different ways (as a TOC, as additional "related links", ...).

[WEK 24 Jan 2010] Added statement " The @collection-type attribute of the <topicref> element determines the relationships established between the topicref and its parent, sibling, and child topicrefs, as well as among its child topicrefs. "

Completed

[Jeff, 5Jan 2010] @processing-role="resource-only" is also used with conref targets (err, referenced elements).

[WEK 24 Jan 2010] It already say that, but in that exact way. Changed to "used only for content reference".

Completed

Paul [2009-12-14]: The next to last paragraph of the (long!) intro before "Links within maps", the last sentence reads:

Actually, such details are mostly in the purview of the style sheet, so we at least need to append:

or something similar.

[WEK 24 Jan 2010] Changed to "The details for how the link text for a given element should or may be generated are defined for that element type and may also be determined entirely by a rendition processor."

Redundant content

[Eberlein, 9 January 2010] The "Links within maps" section contains a lot of content that overlaps with material discussed in the DITA markup > DITA maps topics. I think that this is problematic. The material should be covered in one, not multiple places. Probably material not already covered in the DITA maps section should be moved there; I haven't seen much in this section that actually is related to processing.

[WEK 24 Jan 2010] Because maps are essentially entirely about linking, it follows that most of the discussion of maps would fall into the linking discussion.

Completed

Paul [2009-12-14]: In the table at the end, in the longdescref row, it says:

The second sentence is wrong. Instead it should read:

Robert, 2009-12-15 -- the longdescref is actually supposed to supplement <alt>, not replace it. More details below.

Paul [2009-12-21]: I know that longdescref supplements <alt>, whether given in the attribute or element form. Since we had @longdescref before, I was just thinking of saying that the longdescref element fills the same function as the @longdesref attribute. But you are right that we shouldn't define the element in terms of the (now deprecated) attribute, but rather describe its function.

Robert, 2010-01-05 -- Didn't mean to contradict you Paul - I mostly just meant to point out that I had a related comment below. Part of the pain of writing all my comments offline, then merging them with existing comments that nearly replicate them...

Completed

[RDAnderson, December 16 2009] In "Links within maps", paragraph 5, it says "...included in things like tables of contents using the @toc attribute." I'm not sure about "things like" - doesn't that directly control only a table of contents? Is there something else like a TOC that is affected by @toc? If so, it might be worth calling out another example of what is impacted.

[WEK 24 Jan 2010] I didn't see "ToC" as that general, but I don't see any reason to be fuzzier, so I have removed "thinks like"--the implication being that any hierarchical, sequential listing of the contents of a navigation tree is a table of contents.

Completed

[RDAnderson, December 16 2009] In "Links within maps", paragraph 5, it ends with "@collection attributes" - this should be "@collection-type attribute". @collection should also be @collection-type in the following paragraphs.

[RDAnderson, Jan 5 2010] -- completed this item while fixing an ID in the topic.

Completed

[RDAnderson, December 16 2009] In "Links within topics" - general comment - I'm not sure it is useful to clarify where the different links may occur? Specifically - it says that xref may be used in the topic abstract or body; but links with @keyref may also appear in the title and shortdesc. What about an xref that is placed in a phrase inside shortdesc - that is a valid construct, but this section implies that it is not.

[WEK 24 Jan 2010] Hmmm. One could argue that since the spec doesn't (currently) allow xref *directly* within <title> that the intent is that it shouldn't occur *anywhere* within <title> even though neither the DTD nor schema can disallow the case (which itself argues for relaxing the current constraint). That is why I didn't include it. I have removed all the location qualifications as being unhelpful and (potentially) inaccurate.

Redundant content

[Eberlein, 9 January 2010] I think that (not already covered) content of "Links within topics" should be moved into the DITA markup > DITA topics section. This content of the "Links within topics" section doesn't really have to do with processing.

[WEK 24 Jan 2010] I am thinking that the entire DITA Linking section is quite possibly more appropriate for the DITA markup section. Not entirely sure how to reconcile the Linking within maps topic with the more general Map markup topic, but we can discuss separately.

Completed

[RDAnderson, December 16 2009] In "Links within topics", <related-link> should be <related-links>

[WEK 24 Jan 2010] Fixed.

Completed

[RDAnderson, December 16 2009] In "Links within topics", it says that <longdescref> is an alternative for the <alt> element in image and object. The <longdescref> is intended for an extended description of the image (or object), which supplements the shorter alternative text; it should not be treated as an alternative. This matches the use in HTML: http://www.w3.org/TR/html4/struct/objects.html#adef-longdesc-IMG (specifically the first two sentences). See also the example of longdesc in that specification: 'The alt attribute provides a short description of the image. This should be sufficient to allow users to decide whether they want to follow the link given by the longdesc attribute to the longer description, here "sitemap.html".'

Completed

[Eberlein, 9 January 2010] In the "Summary of link-defining elements" section, some of these elements are discussed in the DITA maps or DITA topics section. Should the material be moved there? Or conreffed into both topics?

I'm really leery of duplication, for multiple reasons:

[WEK 24 Jan 2010] I am also sensitive to duplication. I think having this summary table somewhere is important because it is otherwise very difficult to work out all the elements that are in fact links of one form or another. The intent of the table is not be a full description of the elements. If we can re-use existing content in this table via conref I am cool with that. Alternatively, this topic could be moved to an appendix so that we do not have a normative duplication.

[Anderson, 17 March 2010] Made the following updates, based on the outcome of a meeting with several parties to discuss redundant content:

With the clarification in the short description, I think the topic is clearer, and it also makes clear that the content is not simply duplicating the definitions.

Completed

[RDAnderson, December 16 2009] In the table of elements - reltable - "each role in the table establishes" - is that supposed to be "each row in the table"? Also - the last sentence ends oddly - think it should be "by the map" in place of "by map".

[WEK 24 Jan 2010] Fixed as indicated.

Completed

[RDAnderson, December 16 2009] In the table of elements - navref - should end with "referencing map's key space" (added apostrophe)

[WEK 24 Jan 2010] Fixed as indicated.

Completed

[RDAnderson, December 16 2009] In the table of elements - longdescref - same comment as above

[WEK 24 Jan 2010] Corrected.

Completed

[Jeff, 5 Jan 2010] Is the table complete? What about author, data, fragref, lq, publisher, source, and synnoteref? Do we need to say something about <fn>?

[WEK 24 Jan 2010] Added entries for all the listed linking elements and fn.

Completed

[Jeff, 5 Jan 2010] Do we need/want both the table and the text or could we just use the table?

[WEK 24 Jan 2010] I assume you mean just the list of types without the notes? I think the notes are useful to make it clear how some elements are links.

[Anderson, 17 March 2010] I think that this is now covered by the addition of the short description, which explains why the notes are useful.

Completed

[MPriestley 17 December 2009] "A link may establish either a navigation relationship or a use-by-reference relationship." It may also do both (not just either/or)

[WEK 24 Jan 2010] Here "link" refers to the specific relationship, not the link-defining element. A link may have exactly one nature, a link-defining element may establish any number of relationships of any type. That's one reason to have the term "link-defining element" so that the distinction between the link (the relationship) and the definer of the link can be made clearer.

Completed

[Eberlein, 9 January 2010] Use sentence-style capitalization for titles, figure captions, and (here) table captions.

[WEK 24 Jan 2010] Fixed.

DITA addressing

@id attribute

All items complete on this single topic

Completed

[Jeff, 5 Jan 2010] The draft says "entire maps and the first or only topic in a topic document may be referenced without using an id". We should say something about the special case of a ditabase, where a topicref without an ID references all of the topics in the ditabase rather than just the first or only topic.

[WEK 31 Jan 2010] Added a statement that tries to include the two different ways that unqualified references to topic-containing documents are interpreted.

Completed

Paul [2009-12-14]: The last sentence of the penultimate paragraph reads:

That parenthetical phrase is confusing and misleading. I know it refers to topics that are nested via topicrefs, but a reader might think it could refer to topics nested directly within a topic in the same XML document, and that is not the case. The minimally acceptable rewording could be:

Robert [2009-12-15] My understanding is that an ID within one topic body may be the same as one within a nested topic. That is the primary purpose behind the #topicid/elementid referencing scheme; you may reference #parent/table in the parent topic and #child/table in the nested topic (whether that nesting structure was authored in a single document, or implied by chunking or by nested topicrefs).

I'll also note though that much of the info in this paragraph duplicates info that appears right before the table.

Paul [2009-12-21]: Robert is correct; my earlier comment is wrong. I keep forgetting that ids aren't XML ids, so non-uniqueness within a single document isn't a problem.

[WEK 31 Jan 2010] Rewrote to eliminate redundant normative text. Rewrote the normative statement of ID rules for non-topic elements to be more precise. Added non-normative note to make the implications of the formal rules clear. Moved summary table to end of topic, put in figure, added descriptive title.

Completed

[RDAnderson, December 17 2009] First sentence refers to "a mechanisms" (plural), should be "a mechanism".

[WEK 31 Jan 2010] Fixed.

Completed

[RDAnderson, December 17 2009] Within this topic, both "id attribute" and "@id attribute" are used extensively, with "id attribute" before the table and "@id attribute" after. It should be consistent within the topic (I realize it will not be consistent across the whole spec).

[WEK 31 Jan 2010] Corrected @id to "id" wherever it is talking about the attribute specifically, corrected "id" to "ID" where it is taking about the identifier, not the attribute.

Rejected

[DHelfinstine 20091228] First sentence says "DITA identity attribute." I think it should be "identifier attribute."

[WEK 31 Jan 2010] I don't necessarily disagree but "identity attribute" is how @id has been characterized since DITA 1.0 as far as I know.

Completed

[Jeff, 5 Jan 2010] Is the last sentenance something that was already said earler?

[WEK 31 Jan 2010] Redudancy eliminated. See above comments.

URI-based (direct) addressing

All items completed on this single topic

Completed

Paul [2009-12-14]: In "URIs and DITA fragment identifiers", the fourth para reads:

First, "a URI references must use" should be "a URI reference must use".

Second, I don't think "immediate parent topic element" is a good way to word it since the topic may not be the parent. Change "immediate parent topic element" to "closest ancestral topic element".

[WEK 31 Jan 2010] Fixed.

Completed

Paul [2009-12-14]: In "URIs and DITA fragment identifiers", the fifth para reads:

"elements that are unique" is poorly worded. Change to:

[WEK 31 Jan 2010] Done.

Completed

Paul [2009-12-14]: In "URIs and DITA fragment identifiers", the seventh para reads:

Change the first occurrence of "fragment" in that sentence to "element".

Change "URI" to "URI reference".

[WEK 31 Jan 2010] Done.

Completed

Paul [2009-12-21]:

On this page (Architectural specification, Base, DITA processing, DITA addressing, URI-base addressing) under Addressing DITA topics via URI, it says:

Note however in the third paragraph on the page at Language reference, Attributes, Complex attr defs, the href attr, it says:

I assume that "for the purposes of DITA addressing" is the same as "for the purpose of linking" and is not the same as "for the purposes of rendering", but I fear this wording will lead to confusion unless we are more explicit in the discussion on this page. After all, this page is supposed to be discussing "DITA processing", and "rendering" is certainly part of "processing" too.

[WEK 31 Jan 2010] Repeated the language from the lang ref and reworked the "For example" paragraph as a non-normative note, reflecting both cases. It's not clear to me how having a reference to a ditabase document result in all the topics in the base getting rendered would ever be either what you intended as an author or useful, but it's how things are defined. By the same token, having an unqualified reference to a ditabase file that renders only the first topic would only coincidently be what you wanted (unless you specifically organized your ditabase files such that the first topic was always the one you wanted to render and the others were dependencies of that topic or something. So neither possible behavior is particularly useful, which means it just complicates things unnecessarily to have the current behavior. Hmph.

Completed

[RDAnderson, December 17 2009] In the examples at the end - since we explictly say that you must have format="ditamap" to reference another map, I think it should say the same for referencing an element in another map. The default for @format is 'dita', so @format is required in situations like this: <topicref href="othermap.ditamap#topicset" format="ditamap"/>

[WEK 31 Jan 2010] Added a normative statement to that effect for references to map elements and added the statement to each example in the table.

Completed

[Jeff, 5 Jan 2010] The statement "For addressing DITA elements, URIs must use the appropriate DITA-defined fragment identifier." makes it sound as if I have to use a fragment identifier to address a DITA topic element (or a DITA map element).

[WEK 31 Jan 2010] Rewrote the lead-in to clarify when fragment identifiers are required.

Completed

[Jeff, 5 Jan 2010] We sort of jump into this and start talking about fragment identifiers. It might be good to say something about the syntax of URIs containing three parts: a base part (what is the real name for this?), a query, and a fragment identifier and say that references to DITA resources do not normally use queries. And then give some examples:

I see that we do give this info in a table at the end. Perhaps the table could come ealier and then the text could explain.

[WEK 31 Jan 2010] The RFC for URIs does not provide a name for the part of the URI that here you've called the "base". It makes taking about URI syntax details very difficult. This section is not a tutorial on URIs, so I'm not sure it's really appropriate to put the examples first.

[WEK 31 Jan 2010] For queries, added: URI references may also include a query component, introduced with "?". DITA processors may ignore queries on URI references to DITA resources.

We might also want to say that backslashes (\) are not allowed in URIs and that some other characters must be percent encoded when used in URIs. And that a few other characters must be encoded as XML character entities (or percent encoded).

[WEK 31 Jan 2010] Add a non-normative note that Windows paths are not valid URLs, since that's really the issue (a non-URL URI could have an escaped backslash of course, so it's not correct to say that URIs can't have backslashes, but it is correct to say that URLs cannot have backslashes.

[WEK 31 Jan 2010] I'm not actually sure what the requirements for escaping are for URIs held in documents, as opposed to URIs as supplied to user agents for resolution. My dim understanding is that processors should handle escaping characters that need to be escaped. But I really don't know. I'm not comfortable specifying escaping requirements without a definitive understanding of the rules.

Completed

[Jeff, 5 Jan 2010] When we say "Furthermore, a URI reference with no fragment identifier (and that therefore addresses the entire resource) is considered for the purposes of DITA addressing to reference the first topic element (in document order) within the resource addressed by the URI reference." we need to say something about topicref references to ditabases.

[WEK 31 Jan 2010] See comments above.

Completed

[Jeff, 5 Jan 2010] I'd like to avoid the "../" syntax in our examples if we can or at least not use them as the first example of a relative path. It would be good to reordere the examples in the table so that the more common filename examples come first.

[WEK 31 Jan 2010] What is wrong with "../"? It's a very common syntax and certainly something you're likely to have. However, I removed the "../" since it doesn't add anything to the example.

Key-based (indirect) addressing

Completed

Paul [2009-12-14]: The last para before "Addressing DITA resources and elements with keys" reads:

Change it to read:

[WEK 31 Jan 2010] Done.

Completed

Paul [2009-12-14]: Under "Processing key references", in the first bullet:

change "URI" to "URI reference"

[WEK 31 Jan 2010] Done.

Completed

Paul [2009-12-14]: Under "Figure 8. Redirect a link or xref", the last sentence of step 4:

change "URI" to "URI reference"

[WEK 31 Jan 2010] Done.

Completed

[RDAnderson, December 17 2009] For key definitions in a submap to be included in the key space, there must be a direct URI reference to that submap in the root map. This is misleading - it sounds like the root map (the one at the root of processing / key space construction) has to directly reference any submap that defines keys. In fact the root map can have a direct URI reference to a submap which in turn has a direct URI reference to a sub-submap that defines keys.

[WEK 31 Jan 2010] Corrected to "For key definitions in a submap to be included in the key space, there must be a direct URI reference to that submap from another directly-addressed map in the map tree."

Completed

[RDAnderson, December 17 2009] There appears to be a conflict in the section "Addressing DITA resources and elements with keys": For references to elements within maps and references to non-topic elements within topics, the value of the @keyref attribute is a key name, a solidus ("/"), and the ID of the target element: keyref="topic-key/some-element-id".

Further up under "Defining keys", it states that a key definition may be bound to DITA topics, DITA maps, branches within DITA maps, etc. So, the /element-id token should not be needed to reference an element within a map, because the key may already directly reference an element (branch) within the map. This raises the disturbing prospect that you could directly reference a phrase inside of topicmeta with map#phraseid, which is not the purpose here, but is a (probably unimportant) side effect.

[WEK 31 Jan 2010] Keys are only bound to topicref elements and we also say that a reference to a key is always to the target of the topicref, not the topicref itself. That means to me that in order to address the topicref element itself via key you must put an ID on it and use keyname/elementID.

It would make sense to me to say that to address a branch by key you must specify format="ditamap" on the reference, to distinguish the reference from a simple indirection through the key-defining topicref. Thus, the cases would be:

- Unqualified keyref from topicref with format="dita" indirects through the key-defining topicref - Unquaiflied keyref with format="ditamap" references the tree rooted at the key-defining topicref - Keyref/elementid where the key is bound to a map addresses the element with the specified ID and, if that element is a key-defining topicref, does not indirect through it.

This satisfies the need for use/mention distinctions for topicref elements and is, I think, consistent with the other rules for addressing map components.

I have updated the topic to indicate that references to non-topic elements within topics and non-topicref elements within maps use the keyname/elementID syntax, but references to topicrefs use bare keys and use @format to indicate a use or a mention of the topicref.

Completed

[Jeff, 5 Jan 2010] When we say "If both @keyref and @href are specified, the @href value is used as a fallback address when the key reference cannot be resolved." does "cannot be resolved" mean "when the key name is undefined" or is it "when the key name is undefined or when an @href value on a key definition cannot be resolved or the resource does not exist"?

[WEK 31 Jan 2010] Updated to "cannot be resolved to a resource", which makes it clear that all the cases Jeff lists constitute a failure to resolve. Being unable to resolve an href to a resource and a resource not existing are indistinguishable cases because we aren't checking HTTP response codes to distinguish different reasons why the resource couldn't be resolved, so we don't distinguish transient failures from permanent failures.

Completed

[RDAnderson, December 17 2009] When describing the first example, missing a "d" in "and": In this example, the topicref is acting as both a key definition an contributing ...

[WEK 31 Jan 2010] Fixed.

Completed

[RDAnderson, December 17 2009] In Figure 4's description, a nit-pick - I think it needs to add the bold clause here: In this case, the effective key definition is determined not just by the order in which the definitions occur (or something similar)

[WEK 31 Jan 2010] Done.

Completed

[RDAnderson, December 17 2009] In Figure 4, this is incorrect: Note that if no active value is specified for the @platform condition when determining the effective keys, then neither of the definitions is effective and the key is effectively undefined. The default value for filter values, when no conditions are specified, is to include them. In this case both the "osx" and the "windows7" values are defined, in which case the "osx" value wins (as in Figure 3).

A ditaval file may be used to specify that the default condition for @platform is to exclude the content, or that the default condition for all filter attributes is to exclude the content; if (and only if) such a ditaval is used, this portion of figure 4 would be correct.

[WEK 31 Jan 2010] Corrected the description to reflect normal default of "include" and added additional discussion of setting default to "exclude".

Completed

[RDAnderson, December 17 2009] Grammar issue in the first sentence of the last paragraph of figure 5 - modifications here in italic:

=> The binding for the key "toner-specs" in the root map is effective because it is the first encountered in a breadth-first traversal of the map tree.

[WEK 31 Jan 2010] Fixed.

Completed

[RDAnderson, December 17 2009] Figure 8, step 2, the example should use a0.dita in the text (to match the example, and to match content in the last step). Currently it says contains a link to a1.dita

[WEK 31 Jan 2010] Fixed.

Completed

[RDAnderson, December 17 2009] Figure 9 - this is no longer a proposal, it is part of the standard, so the text in the <note> should replace this: topic; this proposal does not remap the element IDs within the topic, only the pointer to the topic container.

with something like this: topic; changing the key definition only changes the pointer to the topic container, it does not remap element IDs within the topic.

[WEK 31 Jan 2010] Fixed.

Completed

[RDAnderson, December 17 2009] Figure 12 (the last one): Step 1 has a couple of problems. Two sentences in a row start with "But" - that word can safely be removed from each without further modification. More generally - the two coding examples use 4 blat-* keys, but the wording in step 1 says there are only three.

[WEK 31 Jan 2010] Fixed.

Completed

[DHelfinstine 20091229] This section has a LOT of good information in it. I think it might benefit from having this broken into more sections, so that the individual items that are used are defined. So breaking the topic into Defining keys, Key Binding, Key Space, etc. may give this a better flow. Otherwise it seems like the same information is given over again in different sections. Below I have included a "suggested" start to this topic and what might be in them. There is other information further below that also might go into those sections, but didn't want to reproduce the whole thing here.

Defining keys -

Keys are defined within maps. A key name is defined using the @keys attribute on a <topicref> element (or a specialization of topicref, such as <keydef>).

The value of the @keys attribute is one or more space separated key names. Case is significant, and the following characters are prohibited in key names: "{", "}", "[", "]", "/", "#", "?", and whitespace characters.

Key Binding -

A key definition may be bound to DITA topics, DITA maps, branches within DITA maps, non-DITA resources, and subelements of the key-defining topicref itself. Although a key definition cannot be bound to an element within a topic, a key name may be combined with an ID reference in a key-referencing attribute (@keyref, @conkeyref) to address non-topic elements within the topic bound to the key.

If the key-defining element specifies @keyref and the key reference can be resolved following key space construction, the key is bound to any directly-addressed resource bound to the referenced key (directly or indirectly). (It is an error for a topicref to refer directly or indirectly to any key that it defines.)

It is bound to the subelements of the <topicmeta> element within the key-defining element, if any are present.

Key Spaces -

A root map and its directly-addressed local-scope descendant maps establish a unique "key space" within which each unique key name has exactly one binding to a set of resources.

Note: Maps addressed by <navref> do not contribute to the key space of a map tree. Maps referenced by <navref> are equivalent to maps referenced with a scope of "peer" or "external" and therefore need not be present or available at the time the referencing map is processed for purposes of key space construction.

It is directly bound to the resource addressed by the @href attribute of the key-defining element, if specified and @keyref is either not specified or cannot be resolved following key space construction.

For the purposes of determining the effective key definitions for the key space represented by a given root map, a map tree is determined by considering only directly-addressed, local-scope maps descending from the root map. The order of subordinate maps is determined by the document order of the topicrefs that point to them. Indirect references to maps with key references are necessarily ignored until after the key space is determined.

Effective key definitions -

For a given key there is at most one effective definition within a key space. A key definition is the effective definition for a given key if it is the first, in document order, within the map document that contains it, and is the first in the map tree in breadth-first order. It is not an error for the same key name to be defined more than once within a map or map tree, and duplicate key definitions should be ignored without warning. ...

Processing key definitions in submaps - ...

or

Creating the key space - ...

Keys and conditional processing - ...

This may be more effective than the various notes. And this way the notes can be categorized and put under the subtopic.

[Eberlein, 5 April 2010] I've split this long (11 pages!) topic into smaller topics. Obviously, work continues to need to be done to implement the best information architecture of the "Processing" section and improve clarity.

Completed

[DHelfinstine20091229] Under Processing key references - paragraph 5, "If a referencing element contains..." The last sentence begins "It is an error for the element..." Some elements may be OK empty, so maybe it should be "If it is an error for the element..."

[WEK 31 Jan 2010] Added "If " to start of sentence.

Completed

[DHelfinstine20091229] The list under the paragraph "When attributes are combined,..." The list is numbered, but doesn't match the way the list is described. May be better as another type of list.

Completed

[DHelfinstine20091229] The 2nd part of figure 4 is also incorrect. As above (Robert's comment) that if neither value for platform is specified, then all values are valid. In this case the key definition for 'osx' would be chosen as the default. The 3rd value would not be chosen. It would take some special processing DITAVAL to remove the first two.

[WEK 31 Jan 2010] Corrected. See above comment.

Completed

[Jeff, 5 Jan 2010] Does this section make it clear that one can use a keydef/keyref to turn a link into a non-link? We have an example of using a keydef/keyref to "remove" content, but I didn't see one for disabling a link (and leaving it as content).

[WEK 31 Jan 2010] Not sure what is meant by "turn a link into a non-link".

[Anderson 15 March 2010] Added this paragraph to the "Processing Key References" section:

Also added an example to the non-normative examples section.

Content inclusion (conref)

Completed

[Jeff, 5 Jan 2010] The way this is written would lead people to think that conref and conkeyref only work with topics and not with maps, whcih isn't true.

[Anderson, 10 March 2010] Changed one of the headings from "Reference to content within a topic" by adding "or map" to the end. The section already mentioned maps, but only as an aside. Also changed one other location that mentioned topics without mentioning maps.

Completed

[Jeff, 5 Jan 2010] The statement "There are three ways to do this." is followed by either two or four sub-headings and after reading them, I am not sure what the "three ways" are.

[Anderson, 10 March 2010] Removed that clause, and reworded the sentence before it to be a more general lead-in.

Completed

[MPriestley 17 December 2009] xref at end uses title "Use by reference" which doesn't match target title (it is actually the title of the current topic) - make sure xrefs are empty to pull in current title. Also there are a lot of related info links at the end - make sure all are needed (if they are, raises the question of why there are so few elsewhere)

[RDAnderson 17 December 2009] The xref Michael mentions is also included in the related links immediately below the xref - should we remove either the xref or the link?

[Anderson, 10 March 2010] Removed the xref, and removed text from other <xref> elements to ensure they get the correct titles.

Completed

[RDAnderson, December 17 2009] In general, I'm not sure why the TOC doesn't match the topic title

[Anderson, 10 March 2010] Changed to match the TOC title (which was used in DITA 1.1)

Completed

[RDAnderson, December 17 2009] I'm confused that the short description says "and the <topicref> and <keydef> elements" - keydef is a specialization of topicref, with no more importance here than any other topicref specialization. I'm wary of the implication that it must be used - the same implication was made previously with topichead, leading implementers to code directly to <topichead> rather than to the more general "topicref with only a title".

[Anderson, 10 March 2010] Removed <keydef>

Completed

[RDAnderson, December 17 2009] Should the section heading "Pulling content to the referring element" be "Pulling content to the referencing element", to match other uses? Actually "referring" is used 3 times in this topic, while "referencing" is used 31 times (including link text).

[Anderson, 10 March 2010] Changed the 3 to "referencing"

Completed

[RDAnderson, December 17 2009] In the section "Pushing content from the referencing element" -- when content is rendered before or after the referenced element, it is not actually the content of the referencing element that is rendered; it is the content of the element before or after the referencing element. I'll leave it to the editor to re-word that, but here is an example based on the approved proposal:

<step conaction="mark" conref="example.dita#example/b"/>
<step conaction="pushafter"><cmd>Do this AFTER B</cmd></step>

or

<step conaction="pushbefore"><cmd>Do this AFTER B</cmd></step>
<step conaction="mark" conref="example.dita#example/b"/>

Replacing does use the content of the referencing element: <step conaction=“pushreplace” conref=“example.dita#example/rep”>
<cmd>Do this thing now</cmd>
</step>

[Anderson, 10 March 2010] Made the wording more general so that it doesn't say exactly what is pushed, and added a link to the detailed description.

Completed

[RDAnderson, December 17 2009] This is going to be a general problem for a topic that tries to describe both pulling and pushing at once, but the following paragraph is true only for pulling content. The problem is a bit worse because this appears right below the heading (maybe a definition list?) about pushing content:

The text should clarify that this is speaking about pulling content - the domains check for validity would be reversed (superset rather than subset) when pushing, and you would need to ensure validity in the referenced context rather than the referencing context.

The following paragraph also only speaks to replacing the "referencing" element, but is true whether pulling (replace the referencing element) or pushing (replace the referenced content). Maybe start the paragraph with "Replacement of content based on @conref occurs after..."

[Anderson, 10 March 2010] Clarified that it is pulling only, and added a paragraph to describe that pushing is the reverse. Also fixed the following paragraph as suggested.

Completed

[RDAnderson, December 17 2009] Uncertain if this is warranted, but in the paragraph about resolving a chain of conrefs, there are two referencing elements (in topicA and topicB) - so should we add the words here in bold? => The result, however it is achieved, must be equivalent to the result of resolving the conref pairs recursively starting from the original referencing element in topicA.

[Anderson, 10 March 2010] Done

Completed

[RDAnderson, December 17 2009] In the last paragraph before "Indirect addressing with keys", it would seem more consistent to replace "points to" with "references"

[Anderson, 10 March 2010] Done

Completed

[RDAnderson, December 17 2009] In the section "Indirect addressing with keys" - most of this seems to duplicate information in the previous topic on keys. If we are going to have this heading with an overview, I think the overview could be condensed to one paragraph rather than 4 paragraphs plus a link. If we keep some of the present wording, I'd strongly suggest replacing "better than those provided in prior releases of DITA" with something that won't be out of date in the 1.3 spec, such as "better than those provided prior to version 1.2 of DITA."

[Anderson, 17 March 2010] Removed the section, with a refocus of this topic to be solely about conref.

Completed

[DHelfinstine20091229] In the paragraph "More formally, the DITA @conref attribute can be considered..." the last line states that "A valid conref processor does not permit..." Perhaps this should just read "A processor should not, or must not" or whatever the correct word should be.

[Anderson, 10 March 2010] Done - changed to "A conref processor must not permit..."

Completed

[DHelfinstine20091229] In the paragraph "If the referenced element is the same type as the referencing element...". The last sentence begins "In the preferred approach, a processor resolving a conref should tolerate..." Here perhaps the first phrase should be eliminated completely and just state that "A processor should tolerate..."

[Anderson, 10 March 2010] Done as suggested

Completed

[DHelfinstine20091229] In the paragraph "A fragment of DITA content, such as a document containing only a single paragraph..." I am not sure what is being referred to here as invalid.

[Anderson, 10 March 2010] It means a document that contains nothing but a paragraph. Changed to read "A fragment of DITA content, such as an XML document containing only a single paragraph without a topic or map ancestor, ..."

No action

[Jeff, 5 Jan 2010] To answer Dave's question from above, what it is trying to say is that a document fragment does not or may not always contain all of the information needed (the @domains or @class attribute values for example) necessary to determine if the paragraph would be used as conref content. I think this is true, but if you could associate a document type with the fragment, you would probably have enough information to do the necessary validation.

[Anderson, 10 March 2010] I'm not sure that you would, and I think we're within our rights to say "no" ... the reason I think you wouldn't is that our conref resolution process says to check @domains on the ancestor map or topic, but if you don't have that ancestor, you can't follow the rules. You could query the DTD or Schema to discover what is defined in the domains entity, but that seems like too much to ask, and a reasonable thing not to allow.

Completed

[Jeff, 5 Jan 2010] Where do we describe the use of conkeyref with conrefend and the lack of a conkeyrefend attribute?

[Anderson, 10 March 2010] It is described with examples in the conrefend attribute description. I added a "for more info" xref to that topic from the section that says you can do this.

Completed

[DHelfinstine20091229] And just to add what has been said ... the topic title does not match this content (conref) and then it brings the whole thing in question of whether this should just talk about conrefs? It is a little confusing in the hierarchy of this... needs to be sorted out.

[Anderson, 10 March 2010] For now - changed the title back to conref. May still need to discard some of the info here.

[Anderson, 17 March 2010] As Dave suggested - revised the topic so that it only covers conref. The other information is all covered elsewhere.

Profiling with select attributes

All comments completed on this single topic

Completed

[Eberlein, 10 January 2010] I think that there is a significant problem with the information architecture of this topic collection. Currently, it looks like the following:

On quick first glance I'd suggest combining "Processing select attributes," "Filtering logic," and "Flagging logic." Then you could build a topic collection that looks like the following:

I'm not sure that we should be using the term "select attributes," but that's another issue

[RDAnderson, Jan 29 2010] Completed -- Combined these back into a single file, as they were in DITA 1.1 (see the next comment for some reasons behind this). Also removed all references to "select attributes", which was another (valid) issue.

Completed

[RDAnderson, December 18 2009] In general - I do not understand why this section was broken apart into 6 topics for the TOC. The examples at the bottom of this branch do not stand alone - they do not make sense when broken apart. I assume that is why they were all authored as nested topics in DITA 1.0 and 1.1.

If somebody is opposed to nested topics - though it should not be a problem - then it is better to convert the 4 branch topics into sections within the parent topic.

[RDAnderson, Jan 29 2010] Completed -- combined back into a single file, using sections rather than nested topics.

Completed

[RDAnderson 17 December 2009] The title of the topic does not match the title in the TOC - this seems odd. The TOC title - Conditional processing (profiling) - was the topic title in DITA 1.1; that seems more appropriate and closer to what a reader might be looking for.

[RDAnderson, Jan 29 2010] Completed -- changed the title back to the 1.1 value, to match the TOC.

Completed

[RDAnderson 17 December 2009] What is meant by "flagging (effectively)"? I don't understand the parenthetical.

Paul [2009-12-21]: I suspect the parenthetical is supposed to say "effectivity" (which I always thought was an odd word, but it's often used in mil-speak to mean something like profiling). I don't care if we just delete the parenthetical or not.

[RDAnderson, Jan 29 2010] Completed -- removed (effectively)

Completed

[MPriestley 17 December 2009] The topic says The props attribute and its specializations are referred to collectively as "select attributes." ... This is wrong - none of the "select atts" are specializations of props, and they should not be referred to this way. More info in the comments below.

[RDAnderson, Jan 29 2010] Completed -- Deleted this sentence

Completed

[MPriestley 17 December 2009] @rev has not previously been listed as a filterable attribute - it is only for revision based flagging

[RDAnderson 17 December 2009] See DITA 1.1 lang spec for info on which attributes were previously listed as filterable or as available for flagging: http://docs.oasis-open.org/dita/v1.1/OS/langspec/common/select-atts.html

[RDAnderson, Jan 29 2010] Completed -- listed @props and the 4 other common values, without rev, as the filter/flag values

Completed

[MPriestley 17 December 2009] This in general implies a relationship between conditional processing / flagging and the select-atts entity, which declares a number of other attributes not meaningful for conditional processing (like importance)

[RDAnderson 17 December 2009] Agree with what Michael says - and will point out that the grouping of "select-atts" in a single entity was only a (confusing) authoring convenience in the DITA 1.0 DTDs; with DITA 1.1 and 1.2, the five filter/flag attributes (audience, platform, product, otherprops, props + props extensions) are grouped in a more accurately named "filter-atts" entity, which is only one part of select-atts.

We should remove references to "select-atts" in this section of the docs. Its use is sure to cause confusion with the select-atts topic in the language spec, when the content does not apply to that group. We should refer to these as filtering, flagging, and/or conditional processing attributes instead. The DITA 1.1 spec referred to them as "Conditional processing attributes".

[RDAnderson, Jan 29 2010] Completed -- Removed all instances of "select" from the topic

Completed

[MPriestley 17 December 2009] We should add a link to the ditaval format in the langref

[RDAnderson, Jan 29 2010] Completed

Completed

[MPriestley 17 December 2009] We should mention that you can set default behaviors for all atts or specific atts - eg you can set platform to include by default, and product to exclude by default

[RDAnderson, Jan 29 2010] Completed -- Added to the "Filtering logic" section in this topic

Completed

[RDAnderson, December 18 2009] The topic says: DITA defines a starter set of specialized select attributes reflecting common classification domains (audience, platform, product, rev). None of those attributes are specializations, and as mentioned above, rev is not part of the filtering group.

[RDAnderson, Jan 29 2010] Completed -- Deleted the sentence

Completed

[RDAnderson, December 18 2009] The last paragraph again lists @rev as one of the required filterable attributes

[RDAnderson, Jan 29 2010] Completed -- removed @rev

No work required

[RDAnderson, December 18 2009] This topic should link to the topic on specialization of attributes

[RDAnderson, Jan 29 2010] Withdrawn -- I'm not sure where to link, so I'm not going to worry about it (there is not a topic solely dedicated to attribute specialization)

Completed

[DHelfinstine20091229] Paragraph 3: "At a minimum, processors should". If this is a minimum then this should read processors must. But I would suggest taking off the "At a minimum," and just leave the "Processors should".

[Eberlein, 10 January 2010] See also a discussion between Michael Priestley, Jeff Odgen, and Kris Eberlein in Introduction to DITA > Basic concepts > Conditional processing

[Jeff, 10 January 2010] I suggest taking Dave's suggestion and make this "Processors should".

[RDAnderson, Jan 29 2010] Completed -- removed "At a minimum"

Select attributes

All comments completed on this single topic

Completed

[RDAnderson, December 18 2009] This topic should be renamed back to "Conditional processing attributes"

[RDAnderson, Jan 29 2010] Completed

Completed

[Eberlein, 10 January 2010] Topic lacks a <shortdesc> element.

[RDAnderson, Jan 29 2010] Completed -- rather, no action, because this topic is now in a section.

Completed

[RDAnderson, December 18 2009] In the "otherprops" description, it might be better to say the grouping syntax "was deprecated in DITA 1.1" rather than "is deprecated"

[RDAnderson, Jan 29 2010] Completed

No work required

[RDAnderson, December 18 2009] In the map, this topic should use collection-type="sequence", so that a reader can read sequentially through the children

[RDAnderson, Jan 29 2010] No action -- these are back in a single topic, so this is not required

Completed

[DHelfinstine20091229] 1st paragraph "and can be used in coordination: for example..." Break into two sentences at the colon.

[RDAnderson, Jan 29 2010] Completed

Using select attributes

All comments completed on this single topic

Completed

[Eberlein, 10 January 2010] Topic lacks a <shortdesc> element.

[RDAnderson, Jan 29 2010] Completed (no action - now in a section rather than a topic)

Completed

[RDAnderson, December 18 2009] As above - should go back to the old title (Using metadata attributes) or something else besides select attributes.

[RDAnderson, Jan 29 2010] Completed -- changed to "Using conditional processing attributes"

Processing select attributes

All comments completed on this single topic

Completed

[Eberlein, 10 January 2010] Topic lacks a <shortdesc> element.

[RDAnderson, Jan 29 2010] Completed (no action, as above)

Completed

[RDAnderson, December 18 2009] This topic refers to an example in the previous topic, without actually saying so. The example does not make sense without the initial content - these should not be in two separate topics (they were together in DITA 1.1).

[RDAnderson, Jan 29 2010] Completed -- content is now in one topic again

Completed

[RDAnderson, December 18 2009] Instead of saying "(described in the DITA Language Specification)", we should link to the ditaval section in that part of the specification.

[RDAnderson, Jan 29 2010] Completed

[RDAnderson, December 18 2009] The example's syntax is a bit off. It is missing an alt-text element. It would also be good to add <val> in order to make it a complete DITAVAL file. That makes:
<val>

</val>

[RDAnderson, Jan 29 2010] Completed

[DHelfinstine20091229] "At processing time, you specify the values you want to include and/or exclude and the values you want to flag..." might better read "At processing time, values are specified to be included and/or excluded and values to flag using..." and then mention DITAVal file directly with a link.

[RDAnderson, Jan 29 2010] Completed -- added the link to the end. I didn't want to remove "you", because I didn't see a good way to do that without saying "should", but then I thought wait, this is "must", and then my head started to spin. I did simplify the sentence though: "At processing time, a DITAVAL conditional processing profile may be used to specify values you want to include, exclude, or flag."

Filtering logic

All comments completed on this single topic

[Eberlein, 10 January 2010] Topic lacks a <shortdesc> element.

[RDAnderson, Jan 29 2010] Completed (no action, as above)

[DHelfinstine20091229] 1st paragraph nit "a processor should...".

[RDAnderson, Jan 29 2010] Completed

[DHelfinstine20091229] 2nd paragraph "audience or platform that you aren't excluding." to "audience or platform that isn't being excluded."

[RDAnderson, Jan 29 2010] Completed -- changed to "that is not excluded"

[Yeo, 11 January 2010]. The topic is currently written as if only "exclude" statements affect filtering. It does not mention "include" statements. We should at least add a statement indicating that the two bullet points given apply only when the default is to include, and say that users can set the default to either include or exclude. It would be best to add a description of how processors should work when the default is to exclude. Here is a suggested rewording (please check that its message is correct!):

Filtering logic When deciding whether to include or exclude a particular element, processors should evaluate each attribute, and then evaluate the set of attributes.

If the DITAVAL file sets the default filtering behavior to include content unless explicitly excluded:

- If all the values in an attribute have been set to "exclude", the attribute evaluates to "exclude"

- If any of the attributes evaluate to exclude, the element is excluded.

For example, if a paragraph applies to three products and the publisher has chosen to exclude all of them, the process should exclude the paragraph; even if the paragraph applies to an audience or platform that you aren't excluding. But if the paragraph applies to an additional product that has not been excluded, then its content is still relevant for the intended output and should be preserved.

If the DITAVAL file sets the default filtering behavior to exclude content unless explicitly included:

- If any of the values in an attribute have been set to "include", the attribute evaluates to "include"

- If an attribute is not declared or does not have any values, the attribute evaluates to "include"

- If all of the attributes evaluate to include and none of the attributes evaluate to exclude, the element is included.

[RDAnderson, Jan 29 2010] Completed -- I do not like this rewording, mostly because it says the same thing in two different ways, and we should only say it once. That is - regardless of the default behavior - both sets of bullet points evaluate the same way (as they should). For example -- the first bullet in each case uses a different statement to describe the same logic for evaluating a single attribute. The last bullet in each case also uses a different statement to describe the same logic. The second bullet in the second list is always true as well, but I am not sure this is worth calling out.

I've updated this section in the following ways:

  1. Added a paragraph to start the section to explain that the values default to include, but that this default may be changed.
  2. Added a link to the ditaval topic in the lang spec, which now contains samples to show how to change the default
  3. Changed the wording of the two items. 1) Bolded the portions to stress the important items; 2) replaced "have been set to" with "evaluate to", because values may evaluate to "exclude" without explicitly being set to "exclude". The two bullets are now:

    • If all the values in a single attribute evaluate to "exclude", the attribute evaluates to "exclude".

    • If any single attribute evaluates to exclude, the element is excluded.

Flagging logic

All comments completed on this single topic

[Eberlein, 10 January 2010] Topic lacks a <shortdesc> element.

[RDAnderson, Jan 29 2010] Completed (no action, as above)

[RDAnderson, December 18 2009] Suggest changing the sample audience="ADMIN" to audience="administrator", so that it matches the earlier example

[RDAnderson, Jan 29 2010] Completed

[RDAnderson, December 18 2009] Suggest changing "should be output" to "should be rendered"

[RDAnderson, Jan 29 2010] Completed

[DHelfinstine20091229] 1st paragraph nit "a processor should...".

[RDAnderson, Jan 29 2010] Completed

Chunking

All comments complete on this single topic

Completed

[MPriestley 17 December 2009] I just want to make sure this topic reflects the logic described here:

[RDAnderson 17 December 2009] I'll check the resources in that presentation

[Anderson 10 March 2010] Updated to add 2 examples that were missing

[RDAnderson, December 18 2009] Under "Rendering the selection", last bullet in the to-content list, "If the copy-to attribute is specified" should be "if the copy-to attribute is not specified"

[GLJoseph 9 FEB 2010] Completed

[RDAnderson, December 18 2009] "does not inherit values from container elements" should be "does not cascade from container elements"

[GLJoseph 9 FEB 2010] Completed

[RDAnderson, December 18 2009] DITA 1.2 allows xml:lang on <dita>, so in the ditabase sample, for clarity, move all of the xml:lang="en-us" attributes up to <dita>

[GLJoseph 9 FEB 2010] Completed Added xml:lang to <dita> and removed from the <topic> elements.

[RDAnderson, December 18 2009] Example 6 is wrong - this would produce 2 documents (parentchunk.xxxx and nested1.xxxx). It would need a token of "to-content" on the parent1.dita topicref in order to create a single chunk.

[GLJoseph 9 FEB 2010] Completed Changed the example markup to the following:

<map chunk="by-document">
   <topicref href="parent1.dita" chunk="to-content" copy-to="parentchunk.dita">
      <topicref href="nested1.dita" chunk="select-branch"/>
   </topicref> 
</map>

[DHelfinstine20091229] Paragraph reads "When no chunk attribute values are given, chunking behavior is implementation dependent and may vary for different implementations." I think implementation dependent means what is in bold italic and that part can be eliminated.

[GLJoseph 9 FEB 2010] Completed

Printing

All comments completed on this single topic

[MPriestley 17 December 2009] "The distinction between @print="yes" and @print="printonly" is more semantic than functional.. Use @print="printonly" to identify transitional topics to be included exclusively in highly contextual or linear print-oriented output. Specialized processing may take advantage of the semantic. Use @print="yes" in more general contexts."

That's not true - printonly has a different functional effect. print=yes does not exclude content from other output formats, but print=printonly does.

[GLJoseph 9 FEB 2010] Completed I agree. I deleted the first and third sentences from this paragraph.

[RDAnderson, December 18 2009] 2nd paragraph - somebody had me remove the spelled-out "Portable Document Format (PDF)" from another topic, pointing out that PDF is widely understood. So, same comment here.

[GLJoseph 9 FEB 2010] Completed Removed as requested.

[RDAnderson, December 18 2009] Next sentence - should not call out topicgroup specifically - there is no reason to list that single topicref specialization in favor of others. It should either just say "topicref and subordinate map element" or "topicref, topicref specialization, and subordinate map element"

Actually - what is a "subordinate map in a DITA map"? It may be better to say something like:

The last sentence of the paragraph also should not call out topic groups, to avoid confusion with <topicgroup> - it would be better here to say "groups of topics", if that is needed.

[GLJoseph 9 FEB 2010] Completed Reworked using the suggested sentence above, and changed "topic groups" to "groups of topics".

[RDAnderson, December 18 2009] For -dita-use-conref-target - it would be better to replace the second sentence with

[GLJoseph 9 FEB 2010] Completed

[RDAnderson, December 18 2009] In the note after the table - the terminology is a bit off. A map cannot have an ancestor map (you cannot nest <map> within <map>, so map cannot be ancestor of map) - instead, a map can be referenced by another map. The @print value cascades to the referenced map (the term cascade now replaces inherit).

[GLJoseph 9 FEB 2010] Completed I reworked the note paragraph to read as follows: If a value for @print is not specified explicitly in a map element, but is specified in a map that references the map element, the @print value cascades to the referenced map. If the @print value is not specified on the referencing map, a default of "yes" is assumed.

[RDAnderson, December 18 2009] The last paragraph uses topicgroup and 'subordinate map' again. The last sentence is confusing - it sounds like it was probably edited together from a couple of sentences. Maybe just simplify the whole paragraph with this (I'm not sure the second sentence is needed):

[GLJoseph 9 FEB 2010] Completed Used the suggested wording to replace the original paragraph.

Collation

All comments completed on this single topic

Completed

[RDAnderson, December 18 2009] This topic seems to be a description of the <index-sort-as> element, but that description already exists in the language specification. It also implies that the <index-sort-as> element is a general collation mechanism that is typically used for indexing, but this element is only available for indexing. DITA (as of 1.2) does not have a general collation mechanism.

I think that this content can be removed, or replaced with a reference to the index-sort-as element.

[GLJoseph 9 FEB 2010] Removed from map Reintroduce this topic in a future release that supports collation. The current topic does not make sense since it's only supported in the index and the index lang ref topics cover this -- there is nothing to add to the arch spec for 1.2.

[RDAnderson, December 18 2009] The topic says that <index-sort-as> element may be used to specify a collation scheme - is that new? That was not part of DITA 1.1, and I do not remember any proposals to add this in 1.2.

[GLJoseph 9 FEB 2010] Removed from map See previous comment.

Translation and localization

All comments completed on this single topic

[RDAnderson, December 18 2009] Suggest ending the last sentence of the shortdesc with "...by the author or translator." Given that DITA can be authored in other languages, it may actually be the author that wants to localize the sort order.

[RDAnderson, Jan 29 2010] Completed

The xml:lang attribute

All comments completed on this single topic

[RDAnderson, December 18 2009] For consistency with other topics - the first sentence should be a sentence rather than a definition (with no subject).

[RDAnderson, Jan 29 2010] Completed

Paul [2009-12-21]: Second sentence of "Recommended use in topics" says:

but this is no longer true in DITA 1.2, so we need to rewrite this (or just delete this sentence).

[RDAnderson, Jan 29 2010] Completed -- deleted the sentence

[DHelfinstine20091229] Use in maps section paragraph "The xml:lang attribute cascades in the map within the same way that it cascades within a topic." The highlighted within can be removed.

[RDAnderson, Jan 29 2010] Completed

The dir attribute

All comments completed on this single topic

Paul [2009-12-14]: the third bullet point reads:

and the fourth reads:

and the draft comment in between says:

but that is wrong. The reference was an HTML reference, not an XML reference, and in XML, case is significant, and the case of the attribute values for the dir attribute in our DTDs and XSDs (and also that for XHTML) is lowercase, so we need to make a pass on this page changing at least the places where we are specifically talking about the attribute values to use lowercase.

[RDAnderson, December 18 2009] As Paul says, when talking about the actual value, it should still use lower case - for example, if somebody tries to set dir="RTL", the document will not parse correctly (that value is invalid). I'm afraid that saying the value "is set to LTR" will cause problems for new users. My suggestion would be to use lower case, with quotes, when talking about actual values, and to spell out left-to-right and right-to-left when talking generally about rendering order.

[RDAnderson, Jan 29 2010] Completed -- changed all usage of LTR (as discourse) to "left-to-right"; similar for RTL. When describing actual values, I used "ltr", "rtl", "lro", and "rlo" (with quotes).

[RDAnderson, December 18 2009] Suggest moving the last sentence of the shortdesc to be the first - to say what it is first, and then explain it, rather than explaining followed by saying what it is.

[RDAnderson, Jan 29 2010] Completed

[RDAnderson, December 18 2009] For the unordered list at the start - suggest changing the last 3 items to say "may be set" rather than "is set" (the first bullet already uses "may be set", which is more accurate here).

[RDAnderson, Jan 29 2010] Completed

[RDAnderson, December 18 2009] Second paragraph after the list, right after the link, there is a missing space: "either LTRor RTL"

[RDAnderson, Jan 29 2010] Completed

[RDAnderson, December 18 2009] Third paragraph after the list - suggest replacing "standard FOP from Apache" with "the Apache FOP tool" (since it is not a standard, it's just a program)

[RDAnderson, Jan 29 2010] Completed

[RDAnderson, December 18 2009] Under the heading "Recommended usage", second bullet in the list, vice-verse should be vice-versa

[RDAnderson, Jan 29 2010] Completed

[RDAnderson, December 18 2009] Under the heading "Recommended usage", third bullet, "Overrides are done using the LTR and RTL values" needs to be "Overrides are done using the LRO and RLO values" (or, based on the first comment above, 'using the "lro" and "rlo" values'). The current wording is broken, so this cannot be deferred to 1.3

[RDAnderson, Jan 29 2010] Completed

ditaProcessing3 (last edited 2010-04-06 14:16:29 by keberlein)