Paragraph-level comments

Transcription

1 of 342 /2/205 2:04 PM The DITA markup for DITA vocabulary modules and DITA document types is available in several XML languages: RELAX NG, XML Document-Type Definitions (DTDs), and W3C XML Schema. The DITA markup for DITA vocabulary modules and DITA document types is available in several XML languages: RELAX NG (RNG), XML Document-Type Definitions (DTDs), and W3C XML Schema (XSD). spark updated change 25/0/204 0:56:27 DONE keberlein new comment 28/0/204 2:00:29 The DITA written specification is available in the following formats; the HTML is authoritative: Seems like if we only list XHTML (not HTML), then we should say that XHTML is authoritative. randerson updated comment 7/0/204 22:20:47 Done keberlein new comment 8/0/204 23:35:32 The DITA written specification is available in the following formats; the HTML is authoritative:

2 2 of 342 /2/205 2:04 PM The DITA written specification is available in the following formats; the XHTML is authoritative: spark updated change 25/0/204 0:57:20 -level comments Is this this the right place to explain that references to map and topic always refers to the DITA archetypes and all properly implemented specializations and shell configurations, regardless of who implements them? Where is the right place to say that any properly implemented shell comprised of any collection of properly implemented vocabularies is a DITA implementation? spark updated comment 25/0/204 :20:09 Not here. This is just a listing of the RFC-29 terminology. This is a topic mandated by OASIS. I'll "move" your comment to a more appropriate place so that it is not lost. keberlein new comment 27/0/204 08:7:38 XNAL (Kimber)

3 3 of 342 /2/205 2:04 PM I think we should list XNAL unless it runs into the same cost issues that the ISO ones have - we do have an XNAL domain specialization that is based on XNAL. randerson updated comment 7/0/204 22:27:38 Sent to Chet Ensign asking for a citation. keberlein new comment 20/0/204 23:35:49 Kris Eberlein: "It's available, but only if you purchase it. In fact, I cannot even get the citation information without purchasing it. I've sent a note to customerservice@iso.org." Whether or not the resource is free is not relevant: you wouldn't refuse to cite a book or scholarly article just because it's not free. Standards are available in libraries. If the standard is relevant we should cite it. I used the SGML Standard through the IBM corporate library. ekimber updated comment 24/0/204 3:30:8 If we cannot get accurate citation information, then we're really hamstrung. If you can get the standard from your local library, that's marvelous. Mine charges exorbitant interlibrary loan rates for most specialized material. IBM closed their library here in RTP long ago. keberlein new comment 24/0/204 6:8:46 -level comments

4 4 of 342 /2/205 2:04 PM Do we want to mention our source control tool and location of the soure DITA files? spark updated comment 25/0/204 :02:48 Look above :) keberlein new comment 3/0/204 8:50:27 As a result, I moved the topic to its current location in the "Introduction to DITA.3" section. Would it be better located in the appendix? I think it would make slightly more sense in the appendix. It's entirely about the source creation and publishing process, as opposed to being about the standard itself. randerson updated comment 7/0/204 22:5:53 Done keberlein new comment 20/0/204 23:25:22 <oxygen/> XML Editor Is this a specific tool? Or are we saying "Various XML authoring and editing tools"? spark updated comment 25/0/204 :0:40 Change to "oxygen XML Editor, XMetal Author, and Arbortext Editor" keberlein updated comment 3/0/204 8:45:49 DITAweb

5 5 of 342 /2/205 2:04 PM Mekon's DITAweb collaborative review tool spark updated change 25/0/204 :00:36 -level comments Can't comment on the figure, but just noting that the image capture for parent/previous/next links should at least be updated to use "DITA.3" in the footer. randerson updated comment 7/0/204 22:56:0 Removed the -specific info from the screen capture keberlein new comment 20/0/204 23:9:34 The DITA specification uses the content of the unique DITA <shortdesc> element to provide link previews for its readers. These link previews are visually highlighted by a border and a colored background. The link previews are not normative; they contain the content of the <shortdesc> element for the child topic, which is normatively rendered as the first paragraph of the child topic; the content is identical in both renditions. The link previews serve as enhanced navigation aids, enabling readers to more easily locate content. This usability enhancement is one of the ways in which the specification illustrates the capabilities of DITA and exemplifies DITA best practices. Editorial nit-pick -- "unique DITA <shortdesc>" -- not sure why the qualifier "unique"? randerson updated comment 7/0/204 22:53:54

6 6 of 342 /2/205 2:04 PM Removed the word "unique" keberlein new comment 20/0/204 23:3:46 The DITA specification uses the content of the unique DITA <shortdesc> element to provide link previews for its readers. These link previews are visually highlighted by a border and a colored background. The link previews are not normative; they contain the content of the <shortdesc> element for the child topic, which is normatively rendered as the first paragraph of the child topic; the content is identical in both renditions. The link previews serve as enhanced navigation aids, enabling readers to more easily locate content. This usability enhancement is one of the ways in which the specification illustrates the capabilities of DITA and exemplifies DITA best practices. If the link preview is not normative, what does it mean for it to be "normatively rendered"? In this case, I think the word normatively is not needed. rhamilton updated comment 28/0/204 7:4:08 Suggestion: "which is rendered in a normative context as the first paragraph..." randerson new comment 3/0/204 8:52:23 Background info: For DITA.2, the TC admin forced us to include this information. She originally wanted us to remove all link previews, which we resisted strongly. keberlein updated comment 3/0/204 8:52:4 Takes readers to the parent topic, which the topic referenced by the closest topic in the containment hierarchy I don't understand "which the topic referenced by the closest topic in the containment hierarchy"...? randerson updated comment 7/0/204 22:54:47 Changed to "which is the topic referenced by the closest topic in the containment hierarchy." keberlein new comment 20/0/204 23:29:38

7 7 of 342 /2/205 2:04 PM -level comments Correcting capitalization; also making it plural (l&t specializations) - we don't just have one single specialization. randerson updated comment 3/0/204 7:55:34 DITA is designed for creating new document types and describing new information domains based on existing types and domains. The process for creating new types and domains is called specialization. Specialization enables the creation of very specific, targeted document-type definitions that still can share the common output transformations and design rules developed for more general types and domains; this is similar to how classes in an object-oriented system can inherit the methods of ancestor classes. It's probably been here from DITA.0, but I'm now rethinking the reference to "document-type definitions" and "output transformations". How about a simpler sentence: "Specialization enables the creation of specific, targeted XML grammars that can still use tools and design rules that were developed for more general types and domains..." randerson updated comment 22/0/204 6:4:02 It is vocabularies, not document type definitions or grammars, that specialization enables ekimber new comment 24/0/204 3:35:26

8 8 of 342 /2/205 2:04 PM the creation of. Whether or not there is a formal grammar defined for a specialization is in fact not required by the specification: DITA explicitly allows grammar-less documents as long as attributes are present and the document otherwise conforms. So I think the better language would be "DITA is designed for creating new types of documents (maps and topics) and new information domains based on existing types and domains.... Specialization enables the creation of very specifci, targeted vocabularies..." Because DITA topics are XML conforming, they can be readily viewed, edited, and validated using standard XML tools, although realizing the full potential of DITA requires using DITA-aware tools. Because DITA documents must be conforming XML documents,... ekimber updated comment 24/0/204 3:36:2 -level comments Comment by Seth Park, moved from elsewhere in spec: "Is this this the right place to explain that references to map and topic always refers to the DITA archetypes and all properly implemented specializations and shell configurations, regardless of who implements them? Where is the right place to say that any properly implemented shell comprised of any collection of properly implemented vocabularies is a DITA implementation?" keberlein updated comment 27/0/204 08:8:36

9 9 of 342 /2/205 2:04 PM See comments towards beginning of topic. keberlein new comment 3//204 8:4:09 Suggested wording now attached to paragraph near start - "unqualified use of map or topic means..." randerson new comment 3//204 8:4:4 In general, the unqualified use of the term map or topic can be interpreted to mean "a <map> element and any specialization of a <map> element " or "a <topic> element or any specialization of a <topic> element." Expand to include specialization of <topicref> keberlein updated comment 3//204 8:23:32 Maybe "In general, the unqualified use of the term map or topic can be interpreted to mean "a <map> element and any specialization of a <map> element " or "a <topic> element or keberlein new comment 3//204 any specialization of a <topic> element." Similarly, these terms apply to the same elements 8:40:24 in any properly constructed DITA grammar or document type shell." Probably also want to include some body element - <ph> or <section> or similar. randerson new comment 3//204 8:25:47 A map branch consists of an element in a map, along with any child elements and all resources that are referenced by the original element or its children. Draft comment: robander open 2 April 204 Wondering if we should add "Also referred to simply as 'branch' when used in a map context", or perhaps change the term to "map branch or branch" - I do like having it sorted with the other map terms, and using "map branch" does that while keeping our current alphabetical order.

10 0 of 342 /2/205 2:04 PM I don't think "element in a map" is sufficiently precise, because there are many elements allowed in maps that do not define branches. I think better wording would be "A map branch consists of a topicref or specialization of topicref and its descendant elements, including topicrefs included through map references and navref references." ekimber updated comment 24/0/204 3:44:52 I am hesitant about explicitly listing <navref> here given that it has always been intended for display-time resolution - all processors I have worked with that work with DITA (before display time) are unable/unwilling to follow a navref reference, and would not be able to include those further references as part of a branch. randerson new comment 3//204 8:25:8 A vocabulary module that defines exactly one top-level map type or topic type. Structural modules also can define specializations of elements from domain modules. from domain modules or other structural modules. ekimber updated comment 24/0/204 3:49:5 Linking and addressing terms Just realized, after all that work on cleaning up the terms in the keys section, that we also define key terms here. Some terms overlap (key definition, key scope, key space), the rest do not. Those that overlap do not use the same definition. I'm on the fence about whether the terms should be in both spots. But if they are repeated, we should use conref, and use the definitions from the new keys section. We should also decide if the key terms that only appear here should appear in the other key topic: key randerson updated comment 24/0/204 0:44:28

11 of 342 /2/205 2:04 PM resolution context, key name. All formal definitions should be here and should not be repeated elsewhere in the spec. ekimber new comment 24/0/204 3:50:44 I don't think I could understand the keys topics without having that list of concepts available together with the content. I don't think most people read this topic in general when approaching the specification, and if we put keys definitions here (and only here) they will get lost. randerson new comment 3//204 8:30:00 We must have the key definitions in the keys topics. Otherwise, no one will read them or understand the material. Obviously, we must ensure that definitions are properly implemented using a reuse mechanism. keberlein new comment 3//204 8:29:9 Current plan: use conref for the <dl> of keys concepts so that they are consistent here and in the keys section. randerson new comment 3//204 8:34:55 A root map or section of a map hierarchy associated with a unique key space for purposes of key reference resolution. We have previously defined the term "map branch" and I think that is the better term then "section of a map hierarchy". ekimber updated comment 24/0/204 3:5:59 The set of unique key names that are defined for a given key scope. Within a given key scope, a key name has at most one definition, as determined by the key definition precedence rules.

12 2 of 342 /2/205 2:04 PM "has at most one effective definition" There may be any number of definitions for a key key name, but only one may be effective for a given processing instance (e.g., depending on active filtering conditions). The text as worded could be read as only allowing a single definition of a given key within a scope, even though that is not the intent of the definition. ekimber updated comment 24/0/204 3:52:49 Agree with Eliot - and this definition conflicts with the definition in the keys section, which allows for multiple definitions. randerson updated comment 3//204 8:3:47 Agree with your comment, but I think this definition is in conflict with the one in the keys section. keberlein updated comment 3//204 8:3:56 Example The following <step> element is a referencing element. It uses attribute to reference a <step> element in the installation-reuse.dita topic. <step conref="installation-reuse.dita#reuse/run-startcmd-script"> <cmd/> </step> Can we add the corresponding conkeyref example: The following step element is a referencing element. It uses attribute to reference a step element in the topic bound to the key "installation-reuse": <step conkeyref="installation-reuse/run-startcmd-script"> Â <cmd/> ekimber updated comment 24/0/204 3:57:46

13 3 of 342 /2/205 2:04 PM </step> We do not need two examples here. keberlein new comment 3//204 8:33:22 DITA provides two addressing mechanisms. DITA addresses either are direct, URI-based addresses, or they are indirect key-based addresses. Within DITA documents, individual elements are addressed by unique identifiers specified on attribute. DITA defines two fragment identifier syntaxes for addressing DITA elements, one for topics and elements within maps and another for non-topic elements within topics. See DITA addressing for more information. There's a missing space before the last sentence. I'm updating the spec topic to correct. randerson updated comment 24/0/204 0:58:3 A given DITA map or topic document is governed by a DITA document type that defines the set of structural modules (topic or map types), domain modules, and constraints modules that the map or topic can use. See Configuration for more information. Recommend removing the word "given" randerson updated comment 24/0/204 02:05:50 Agree ekimber updated comment 24/0/204 4:00:36 A given DITA map or topic document is governed by a DITA document type that defines the set of structural modules (topic or map types),

14 4 of 342 /2/205 2:04 PM domain modules, and constraints modules that the map or topic can use. See Configuration for more information. constraint modules ekimber updated comment 24/0/204 4:00:7 Constraint modules define additional constraints for corresponding vocabulary modules in order to restrict content models or attribute lists for specific element types, remove extension elements from an integrated domain module, or replace base element types with domain-provided extension element types. Constraint modules do not and cannot change element semantics, only the details of how element types can be used in the context of a specific concrete document type. Because constraints can make optional elements required, documents that use the same vocabulary modules may still have incompatible constraints. Thus the use of constraints can affect the ability for content from one topic or map to be used directly in another topic or map. See Constraints for more information. Recommend changing "element types" to "elements" in all instances. Also, change "concrete document type" to "document type". Possibly, remove word "still" from "...modules may still have incompatible constraints". Last, I think that "...affect the ability for..." sounds right, isn't it "...affect the ability of..."? Not sure with the full sentence. randerson updated comment 24/0/204 02:24:06 Changed to read as follows: "Constraint modules define additional constraints for vocabulary modules in order to restrict content models or attribute lists for specific element types, remove certain extension elements from an integrated domain module, or replace base element types with domain-provided, extension element types." keberlein new comment 28//204 5:35:30 "element types" is the correct term here: unqualified "element" means element instance but constraints (like all grammars) apply to all instances of a given element type. DITA does not define a facility for constraining specific element instances.â ekimber new comment 24/0/204 4:04:28

15 5 of 342 /2/205 2:04 PM Where typename is the name of the intended root topic or map type defined by the document type shell or, as needed, a name that clearly identifies both the intended root map or topic type and distinguishes the document type shell from other shells for the same root type. Unclear: does this definition of "typename", which allows flexibility, apply to all uses of "typename" below? That is - for the DTD, this section effectively means that that typename MUST be the name of the root topic, or instead you can use a name that clearly identifies the root topic but also adds some other value. So, for task, it MUST be task, unless it's generaltask. I think I've said before - I don't understand how it can be a MUST when there is flexibility to give whatever name you want. Also, to quibble, in XML <task> and <Task> are two different elements, so generaltask does not actually include the name of the root element. Regardless, does the same flexibility apply to uses of typename below? For example, if I create a root topic <blob> with the intention to provide a general and constrained, I can create generalblob.dtd and strictblob.dtd. Can my element module be generalblob.mod? randerson updated comment 24/0/204 02:50:52 We need to change the "MUST" to a "SHOULD". This is not enforceable. keberlein new comment 3//204 9:04:43 I'm not sure this clause is useful. I agree that this is really a should as the intent is to define conventions that foster consistency of file names. The names are discussed again in the coding requirements. Might be better to just refer there for naming rules for grammar ekimber updated comment 24/0/204 4:07:3 artifacts.

16 6 of 342 /2/205 2:04 PM If we do keep this section, "typename" needs to be defined so that it reflects the structural type ("task") and allows qualifiers as appropriate and otherwise leaves the value unconstrained. For example, the OASIS-provided document-type shells for technical content include two different document-type shells for the task topic type: task.dtd and generaltask.dtd, where task.dtd includes the strict task body constraint module and generaltask.dtd does not. For example, the OASIS-provided document-type shells for technical content include two different document-type shells for the task topic type: task.dtd and generaltask.dtd, where task.dtd includes the strict task body constraint module and generaltask.dtd does not. In this example, the root element for documents conforming to either of these DTDs is the same ("task"), but the DTDs they require unique file names because the represent different sets vocabulary modules. spark updated change 2/0/204 7:29:2 because they represent different sets of vocabulary and constraint modules. ekimber updated comment 24/0/204 4:09:57 constraintnameconstraint.mod constraintname Constraint.mod constraintnameconstraint.ent nharrison updated change 28/0/204 3:39:6 Will add a draft comment about this. Need to align with constraints topics. keberlein new comment 3//204 9:03:55 constraintnameconstraintintmod.xsd

17 7 of 342 /2/205 2:04 PM (May need more clarificatiton on why this is required; i'll keep reading and provide the clarification if I find it.) spark updated comment 2/0/204 7:32:04 DITA is designed to produce multiple deliverable formats from a single set of DITA content. This means that many rendition details are specified neither in the DITA specification nor in the DITA content; the rendition details are defined and controlled by the processors. DITA is designed to produce enable production of multiple deliverable formats from a single set of DITA content. This means that many rendition details are specified neither in the DITA specification nor in the DITA content; the rendition details are defined and controlled by the processors. ekimber updated change 24/0/204 4::25 The DITA specialization facility enables users to create the XML elements that are needed by a particular information set in order to provide appropriate rendition distinctions. In XML-based systems where the presentation details are defined as styles bound to elements, the more precise and detailed the markup, the easier it is to define presentation rendering. Because the use of specializations does not impede interchange or interoperability, DITA users can safely create the specializations that are demanded by their local delivery and rendition requirements, with a minimum of additional impact on the systems and business processes that depend on or use the content. While general XML practices suggest that element types should be semantic, specialization can be used to define element types that are purely presentational in nature. The highlighting domain is an example of such a specialization.

18 8 of 342 /2/205 2:04 PM Why is this here? If the point is to explain the role of specialization in enabling different deliverables from a common source, then we should perhaps say something like, "In cases where processing requires XML syntax triggers in order to provide specialized rendition handling, DITA specializations can be used provide new element classes that will not interfere with other rendition processors. spark updated comment 2/0/204 7:45:2 I think it's not very well worded, and that it's intended to convey two different things: A specialization can optionally provide special formatting based on the elements provided (to highlight that this is possible, but not required) To point out that you *can* specialize purely for presentational reasons, like highlighting domain randerson new comment 24/0/204 02:55:54 The keyref mechanism makes it possible to change variables for volatile content, redirect links, and reap the benefits of indirect addressing. This sentence seems... too complex. I don't think the phrase "change variables for volatile content" is at all consistent with other descriptions of keyref. Perhaps, given that this is an extremely high level description, something like - this makes it possible to "have key words or links display different values in different deliverables"? I'm also not sure about the grand statement that this lets you "reap the benefits of indirect addressing". We don't explain any of those benefits here, and many readers will not yet know of any benefits. Especially in an introduction topic, we shouldn't make a statement that makes users think they should already be familiar with this concept. Maybe something like: "The keyref mechanism makes it possible to have key words or links display different values in different deliverables. It also allows a single link to resolve randerson updated comment 24/0/204 03:06:4

19 9 of 342 /2/205 2:04 PM to different targets in different deliverables." I agree with Robert's reformulation. Might be useful to add that key definitions can be conditional and specific to a given deliverable. ekimber new comment 24/0/204 4:4:53 While DITA is independent of any particular delivery format, it is a standard that supports the creation of human-readable content. As such, it defines some fundamental document components including paragraphs, lists, and table. When there is a reasonable expectation that such basic document components be rendered consistently, the DITA specification defines default or suggested renderings. Ok, 2 things not worth 2 comments: "paragraphs, lists, and table" -- shouldn't table be plural? And in definition above, isn't the phrase "by its nature", rather than "by nature"? Or better, maybe we should just drop that clause? randerson updated comment 24/0/204 03:08:26 -level comments We do not describe the classification domain ANYWHERE in the architectural specification. This is a significant omission -- and maybe part of the reason that this domain is rarely used. If we were to add a topic or topic cluster, I'm not sure where it should go: Separate section in "DITA markup"? Maybe "DITA classification"? keberlein updated comment 23/0/204 22:30:36

20 20 of 342 /2/205 2:04 PM Section in "DITA maps" -- The domain is only available in maps. Section in "DITA metadat"? It is metadata... I think it makes sense under DITA maps. We have a " domains" topic under DITA topics; classification is a map domain; I think it makes sense to have a topic or topic cluster about classification under DITA maps, just before or after the Subject scheme cluster. randerson new comment 24/0/204 03:3:32 As far as I can tell, the subject as essential DITA features are not mentioned anywhere before the DITA Processing section and in that context the discussion comes out of the blue. While this focus of this section is on DITA markup generally (maps and topics), I think it would be appropriate to have a section that discusses attributes generally. ekimber updated comment 24/0/204 20:35:53 Kris and I agree that a topic about this would be extremely useful, but also note that it has not appeared in the three previous s of DITA (an oversight, but means we can get by without it if we have to). Marking this as accepted and hoping to have time to address. randerson new comment 3//204 9:4:4 -level comments

21 2 of 342 /2/205 2:04 PM DITA topics are used as components of by reference from DITA maps. DITA maps enable topics to be organized in a hierarchy for publication. Large units of content, such as complex reference documents or book chapters, are created by nesting topic references in a DITA map. The same set of DITA topics can be used in any number of maps. ekimber updated change 24/0/204 4:22:5 -level comments This topic and its descendant topics are not, strictly speaking, normative. I'm not objecting to there presence here, just observing that the DITA specification does not mandate writing practice and therefore this topic can't be normative. This is really tutorial information appropriate for technical writers applying DITA for highly structured content. ekimber updated comment 24/0/204 4:29:23 I think that makes sense, but given the nature of this spec (its presence in earlier s and our current status in.3 development), I think it's best to leave it here. randerson new comment 24/0/204 4:34:37 Agree. keberlein new comment 25/0/204 9:48:05 s written for reuse should be small enough to provide opportunities for reuse but large enough to be coherently authored and read. Since each topic is written to address a single subject, authors can organize a set of topics logically and achieve an acceptable narrative content flow.

22 22 of 342 /2/205 2:04 PM s written for reuse should be small enough to provide opportunities for reuse but large enough to be coherently authored and read. Since When each topic is written to address a single subject, authors can organize a set of topics logically and achieve an acceptable narrative content flow. ekimber updated change 24/0/204 4:24:52 Updated. randerson new comment 24/0/204 4:37:05 -level comments Readers who are trying to learn or do something quickly appreciate information that is written in a structure that is easy to follow and contains only the information needed to complete that task or grasp a fact. Recipes, encyclopedia entries, car repair procedures -- â all serve up a uniquely focused unit of information. The topic contains everything required by the reader. ekimber updated change 24/0/204 4:25:28

23 23 of 342 /2/205 2:04 PM -level comments Yes, the use should be attribute: attribute can be used to indicate the delivery target for an element. For example, you can specify "print" on a topicref to a topic that should only be used for printed or printable deliverables (e.g., PDF). ekimber updated comment 24/0/204 4:34:4 I think this topic is not appropriate in the spec. Recommend removing it entirely. spark updated comment 2/0/204 7:54:9 I am in agreement here. keberlein new comment 23/0/204 0:28:57 I'm happy with removing it. ekimber new comment 24/0/204 4:35:3 No strong opinion either way, but noting that this was added in DITA.2 because transitional text was a very hotly discussed topic for a while in that period. I think (but I'm not sure) that this topic was a compromise of sorts, removing the need to add new markup or features explicitly for transitional text. If the current TC does not feel the topic belongs in the spec (here or elsewhere) I'm happy to see it removed. randerson new comment 24/0/204 4:46:06 Talking with Kris, I agree this can be removed from.3. randerson new comment 3//204 9:22:00

24 24 of 342 /2/205 2:04 PM You need not use any of the currently-defined information types. However, where a currently defined information type matches the information type of your content, the currently defined information type should be used, either directly, or as a base for specialization. For example, information that is procedural in nature should use the task information type or a specialization of task. Consistent use of established information types helps ensure smooth interchange and interoperability of DITA content. You need not use any of the currently-defined information types. However, where a currently -defined information type matches the information type of your content, the currently -defined information type should be used, either directly, or as a base for specialization. For example, information that is procedural in nature should use the task information type or a specialization of task. Consistent use of established information types helps ensure smooth interchange and interoperability of DITA content. ekimber updated change 24/0/204 4:36:2 Done keberlein new comment 25/0/204 9:45:06 The topic body contains all content except for that contained in the title or the short description/abstract. The topic body can be specialized to impose constraints appropriate for the specific topic type even when titles and prolog are generic, or the topic body can be generic while the topic title and prolog are specialized.

25 25 of 342 /2/205 2:04 PM The topic body contains all content except for that contained in the title or the short description/abstract. The topic body can be specialized to remove specific elements from the content model or to add additional specialized elements to the content model impose constraints appropriate for the specific topic type even when titles and prolog are generic, or the topic body can be generic while the topic title and prolog are specialized. rthomas updated change 26/0/204 22:40:00 Suggest - change "to impose constraints" to "to impose structure" randerson new comment 3//204 9:26:38 div Looks like this is missing an <xmlelement> wrapper. randerson updated comment 2/0/204 6:58:8 Paragraphs, lists, and tables are types of "block" elements. As a class of content, they can contain other blocks, phrases, or text, though the rules vary for each structure. Paragraphs, lists, figures,â and tables are types of "block" elements. As a class of content, they can contain other blocks, phrases, or text, though the rules vary for each structure. ekimber updated change 24/0/204 4:4:54 Done keberlein new comment 25/0/204 9:40:9 Block-level elements can contain markup to label parts of a paragraph or parts of a sentence as having special semantic meaning or presentation characteristics, such as <uicontrol> or <b>. Phrases can usually contain other phrases and keywords as well as text. Keywords can only contain text.

26 26 of 342 /2/205 2:04 PM Sort-of-typo: This dlentry needs to start off with "Phrase level elements" rather than "Block level elements". randerson updated comment 2/0/204 6:59:20 -level comments The names of the modules for non-dtd grammars all need to end with "Mod", e.g. "highlightdomainmod.xsd". ekimber updated comment 24/0/204 4:44:58 This is a change from.2; why? keberlein new comment 25/0/204 9:43:06 Move to appendix. This might be removed from the appendix later, if everything this topic includes in covered in Robert's new appendix topics. keberlein updated comment 3//204 9:4:08 highlighting Highlighting keberlein updated comment 3//204 9:37:26

27 27 of 342 /2/205 2:04 PM DITA maps use <topicref> elements (or specializations of the <topicref> element) to reference DITA topics, DITA maps, and non-dita resources, for example, HTML and TXT files. The <topicref> elements can be nested or grouped to create relationships between the referenced topics, maps, and non-dita files; the <topicref> elements can be organized into hierarchies in order to represent a specific order of navigation or presentation. DITA maps use <topicref> elements (or specializations of the <topicref> element) to reference DITA topics, DITA maps, and non-dita resources, for example, HTML and TXT files. The <topicref> elements can be nested or grouped to create relationships between among the referenced topics, maps, and non-dita files; the <topicref> elements can be organized into hierarchies in order to represent a specific order of navigation or presentation. ekimber updated change 24/0/204 4:46:6 DITA maps also define keys and organize the contexts in which key references are resolved. A <topicref> or <map> element, or any specialization, may be used to create a new context for key definition and resolution. A <topicref> element, or specialized <topicref> such as <keydef>, may also be used to define a key which binds that key name to a specified resource for references in the same key scope. DITA maps also define keys and organize the contexts  ("key scopes")  in which key references are resolved. A <topicref> or <map> element, or any specialization, may be used to create a new context for key definition and resolution. A <topicref> element, or specialized <topicref> such as <keydef>, may also be used to define a key which binds that key name to a specified resource for references in the same key scope. ekimber updated change 24/0/204 4:53:46

28 28 of 342 /2/205 2:04 PM Delete last sentence keberlein new comment 3//204 9:46:50 Alternate suggestion: "A topicref or map element may be used to create a new context for key definition and resultion (by defining a new key scope)." randerson new comment 3//204 9:45:2 -level comments Maps can define keys, which provide an indirect addressing mechanism that enhances portability of content. The keys are defined by <topicref> elements or specialization s of <topicref> elements, such as <keydef>. The <keydef> element is a convenience element; it is a specialized type of a <topicref> element with the following attributes: A attribute attribute with a default value of "resource-only". ekimber updated change 24/0/204 4:55:30 A DITA map describes the relationships among a set of DITA topics. The DITA map and map group elements organize topics into hierarchies, groups, and relationships; they also define keys.

29 29 of 342 /2/205 2:04 PM A DITA map describes the relationships among a set of DITA topics. The DITA map and map group domainâ elements organize topics into hierarchies, groups, and relationships; they also define keys. ekimber updated change 24/0/204 5:02:38 Changed to "map-group domain elements" keberlein new comment 27/0/204 02:33:47 Relationship tables are defined with the <reltable> element. Relationship tables can be used to define relationships between DITA topics or between DITA topics and non-dita resources. In a relationship table, the columns define common attributes, metadata, or information types (for example, task or troubleshooting) for the resources that are referenced in that column. The rows define relationships between the resources in different cells of the same row. Relationship tables are defined with the <reltable> element. Relationship tables can be used to define relationships between among DITA topics or between among DITA topics and non-dita resources. In a relationship table, the columns define common attributes, metadata, or information types (for example, task or troubleshooting) for the resources that are referenced in that column. The rows define relationships between the resources in different cells of the same row. ekimber updated change 24/0/204 5:04:29 Must use the term "among", not "between", because relationship tables may relate more than 2 topics together into a single relationship. The <topichead> element provides a navigation title; it is an convenience element that is equivalent to a <topicref> element with a navigation title but attribute.

30 30 of 342 /2/205 2:04 PM The <topichead> element provides a navigation title; it is a n convenience element that is equivalent to a <topicref> element with a navigation title but attribute. ekimber referenced resource. updated change 24/0/204 5:05:45 Done keberlein new comment 27/0/204 02:39:32 The <navref> element represents a pointer to another map which should be preserved as a transcluding link rather than resolved. Output formats that support such linking will integrate the referenced resource when displaying the referencing map to an end user. The <navref> element represents a pointer to another map which should be preserved as a transcluding link in the result deliverableâ rather than resolved  when the deliverable is produced. Output formats that support such linking will SHOULD integrate the referenced resource when displaying the referencing map to an end user. ekimber updated change 24/0/204 5:6:42 Agree with wording changes, but I think the suggested SHOULD should actually be changed to "can" randerson new comment 3//204 9:49:35 DITA maps often encode structures that are specific to a particular medium or output, for example, Web pages or a PDF document. Attributes, such are designed to help processors interpret the DITA map for each kind of output. These attributes are not available in DITA topics; individual topics, once separated from the high-level structures and dependencies associated with a particular kind of output, should be entirely reusable regardless of the intended output format. attributes affect how related links are generated for topics that are referenced in the DITA map.

31 3 of 342 /2/205 2:04 PM DITA maps often encode structures that are specific to a particular medium or output, for example, Web pages or a PDF document. Attributes, such print deliverytarget are designed to help processors interpret the DITA map for each kind of output. These attributes are not available in DITA topics; individual topics, once separated from the ekimber high-level structures and dependencies associated with a particular kind of output, should be entirely reusable regardless of the intended output format. attributes affect how related links are generated for topics that are referenced in the DITA map. updated change 24/0/204 5:9: Done. keberlein new comment 27/0/204 02:28:5 In most situations, specifies whether a duplicate of the topic is created when it is transformed. This duplicate can be either literal or virtual. The value of attribute specifies the uniform resource identifier (URI) by which the topic can be referenced by attribute, <topicref> element, or <xref> element. The duplication is a convenience for output processors that use the URI of the topic to generate the base address of the output. attributes provide an alternative mechanism; they enable references to topics in specific-use contexts without making copies. In most situations, specifies whether a duplicate of the topic is created when it is transformed. This duplicate can be either literal or virtual. The value of attribute specifies the uniform resource identifier (URI) by which the topic can be referenced by attribute, <topicref> element, or <xref> element. The duplication is a convenience for output processors that use the URI of the topic to generate the base address of the output. attributes provide an alternative mechanism; they enable references to topics in specific-use contexts without making copies. ekimber updated change 24/0/204 5:23:58 I think I originally wrote "without making copies" but in fact you might want to make copies of topics when a navigation topicref has a key, so better to just leave that aspect out.

32 32 of 342 /2/205 2:04 PM The metadata attributes cascade; however, they are not additive for <topicref> elements that specify a different value for the specific metadata attribute. If the cascading value for an attribute is already merged based on multiple ancestor elements, that merged value continues to cascade until a new value is encountered (that is, setting cascade="nomerge" does not undo merging that took place on ancestors). The metadata attributes cascade; however, they are not additive for <topicref> elements that specify a different value for the a specific given metadata attribute. If the cascading value for an attribute is already merged based on multiple ancestor elements, that merged value ekimber continues to cascade until a new value is encountered (that is, setting cascade="nomerge" does not undo merging that took place on ancestors). updated change 24/0/204 5:26:28 Change to "a specific" keberlein new comment 3//204 9:50:24 -level comments This section never describes how you associate a subject scheme map with a "narrative" map, Maybe that's intentional, but a simple sentence somewhere saying that you associate a subject scheme with a map via a normal DITA map reference would be helpful, I think. Somewhat relatedly, the spec never discusses the key space implications of referencing a cnitchie updated comment 23/0/204 20:53:28 subject scheme map, with all its keydefs, from another map with its moreâ structural key definitions. I'm pretty sure that the keydefs from the subject scheme map get added to the key scope where they're included just based on the key space rules - i.e. subject schemes are not a special case vis-a-vis key definitions (which I'm not happy about but c'est la vie) - but that

33 33 of 342 /2/205 2:04 PM should probably be called out specifically. Yes, there is nothing special about subject scheme maps with regard to how the keys they define are processed. I would probably make having a subject scheme map define a clear scope name standard ekimber practice. Or not, if the key names are already sufficiently distinct, which is often the case if new comment 24/0/204 5:36:29 the subject scheme reflects an existing taxonomy where the keys reflect (or are identical to) the existing taxonomy's subject IDs. And that being the case, I'd want to make clear that the names identified by keys in a subject scheme can be referenced as-is in conditional processing attributes, and scopequalified names are not required. You'd only need to use a scope-qualified reference when/if referencing the keyâ ï» as a key, not as an enumerated value in a conditional processing attribute. (Can weâ ï» pleaseï» stop overloading topicref now?) cnitchie updated comment 24/0/204 8:30:26 The association description should NOT forbid associating a subject scheme map without a map reference. It should be possible to process a single topic and provide the subject scheme to the processor separately, just like you can provide a DITAVAL filter file. jelovirta new comment 24/0/204 9:56:07 Jarno, the TC already decided that it is perfectly acceptable to have subjectscheme maps specified for processors, ala DITAVAL files. keberlein new comment 27/0/204 02:27: Chris, the TC has not yet decided whether subject schems are a special case or not. That's an open question for the TC to resolve. I thnk that there are many reasons why subject schemes need to be handled differently... keberlein updated comment 27/0/204 02:24:47 Subject scheme maps and their usage

34 34 of 342 /2/205 2:04 PM Add clarification about how to reference subjectscheme maps -- ) Using a map reference, or 2) Parameter to processor, ala DITAVAL keberlein updated comment 3//204 9:57:00 Subject scheme maps can be used to define controlled values and taxonomies. The controlled values and taxonomic subjects can be bound to attributes and element and attribute pairs. Subject scheme maps can be used to define controlled values and taxonomies. The controlled values and taxonomic subjects can be bound to attributes and, element and attribute pairs. mark updated change 23/0/204 20:45:08 comma after "and" is incorrect (makes the sentence a comma splice). If there is concern about how "element and attribute pairs" is interpreted should reword to "and pairs of elements and attributes". ekimber updated comment 24/0/204 5:34:30 Changed to "The controlled values and taxonomic subjects can be bound to attributes, as well as element and attribute pairs." keberlein updated comment 27/0/204 02:22:4 A subject scheme map enables adopters to create custom controlled values and to manage metadata attribute values without having to write a DITA specialization. Subject scheme maps use key definition to define a collection of controlled values rather than a collection of topics.