Review comments and resolutions

Language_specification_comments_from_Paul_Grosso
Language_specification_comments_from_Rob_Frankland

Questions that need answers for the DITA 1.2 Language Specification

These questions reflect language specification material that is incomplete in DITA 1.2 proposals.

  1. GENERAL: The ditaval file is an xml file that contains alternate text. Should it have xml:lang on <val> or on all of the elements?

  2. GENERAL: What sort of behavior should be described for <q>, if any?

  3. GENERAL: How to define attribute data types and defaults (CDATA, NMTOKEN, #IMPLIED, #REQUIRED) http://lists.oasis-open.org/archives/dita/200902/msg00000.html

  4. GENERAL: How to describe behavior for topichead (pseudo-topics, etc)
  5. GENERAL: There is a question about what is valid in copy-to. Other discussions indicated that copy-to can contain a DITA file name or a file name with no extension, but there are questions about paths, relative paths, copy-to that tries to overwrite a system file, etc. Should the spec address this? Indicate that tools are responsible for handling that as they see fit?
  6. GENERAL: Question about legal characters in URI: http://lists.oasis-open.org/archives/dita/200902/msg00007.html

  7. GENERAL: Reviewer commented that the "Inheritance" section is confusing to non-technical folks. We should explain what this sections means in a "Reading the Lang Spec" topic. In addition, should we change the title from Inheritance to something like "Specialization ancestry"?
  8. GENERAL: What is up with spectitle? Is it deprecated?
  9. GENERAL: Should the xmlns definition be included in the attribute tables?
  10. GENERAL: The description for @base is too long to appear in multiple attribute tables. We should either create a new topic for it, or refer to the architectural specification; on hold until we determine if the core architectural spec and lang spec will be combined.
  11. Item 12011: More general task type: The proposal was approved with the new specification language as "To be supplied." It has not been supplied, so definitions are minimal and need extra review.
  12. Item 12014: Review comment asks if we could use @idref instead of @id on <anchorid>. I don't remember why we went with id, though I feel this was discussed.

  13. Item 12026: The proposal for glossPartOfSpeech notes that the default value with the "standard enumeration" is noun, but that the standard enumeration may be modified. Should this include a link to information about Controlled Values? Same question for glossStatus. Resolution: should distribute the the enumerations. Similar to UBL, could distribute in another directory with the DTDs. Should have a link to Controlled Values from the spec.

  14. Item 12026: What are the meanings of @name and @datatype on glossPartOfSpeech? They are present because glossPartOfSpeech includes all of the data element attributes, but should they be removed?
  15. Item 12026: Similar to @name/@datatype ... does @href have any meaning on glossPartOfSpeech? Does it refer to a definition to the part of speech, or should it be removed (along with scope/format/type)?
  16. Item 12026: There is a new element <glossSymbol>, which specializes from image. It allows @longdescref, but not <longdescref>, even though DITA 1.2 deprecates the attribute in favor of the element. Should we swap what's available on glossSymbol? I think this raises the same question for a new image specialization in the Hazard domain.

  17. Item 12026: Related to the previous - is there any reason to have @alt, which is deprecated on images, or should we only allow the element?

Resolved questions that have not yet been included in the spec

  1. GENERAL: Need a 'resources' page that lists referenced RFC's, etc.

Completed questions resolved by talking to proposal owners

  1. Problem: the machine industry task domain defines a <person> element, which is already part of the XNal domain. Do we want to define two versions of the same element, and if so, how to handle in the specification? This means that the two domains could never be used together and seems likely to cause confusion for readers of the specification. Resolution: person element modified to personnel element.

  2. Item 12007: When conkeyref is used to reference a topic (or a map element), may it still be used with a range? The proposal states that conrefend implies the same key, followed by an element id, such as conkeyref="config/step1" conrefend="step3" to bring in steps 1 to 3 of the "config" topic. If instead conkeyref is a topic or map branch - such as conkeyref="config" - is there any way to turn it in to a range? Resolution: Robert corrected his misinterpretation of the conrefend syntax when used with conkeyref. Updated the conrefend topic to explain how it is combined with conkeyref.

  3. Item 12008: Where is the definition of the new note values (caution1, caution2, notice, warning)? Reused the definitions from the hazardstatement reference topic.

  4. Item 12011: Need an example for the process element; RESOLVED

  5. Item 12011: The proposal says that no new behaviors are defined in the proposal, yet it notes that "specialized processing is required to avoid numbering <stepsection> elements." Is the special numbering a required behavior, or is it optional? Resolution: DITA applications which render stepsection elements among the step elements must provide a way to number the steps without numbering the stepsection elements (although this does not need to be the only or default presentation).

  6. Item 12013: When resolving conref, the ID of the target is not preserved, though most other attributes are. Is the same true for a range (ID on start and end are not preserved)? What about elements between the start and end? Resolution: ID on start and end are not preserved (as with conref); IDs for intermediate and child nodes are preserved, although applications may recover by changing IDs or warning a user if resolution results in conflicting IDs (multiple topics with the same ID, or multiple elements sharing the same ID within a topic).

  7. Item 12013: What about attribute overrides when conrefend is present? With conref, attributes on the referencing element are preserved (including @id). With range we cannot preserve ID on both. Resolution: ID of the referencing element is preserved on the start of the range. Other attributes are only preserved on elements of the same type. For example, if a range of steps is pulled with conref, non-ID attributes may be preserved on every pulled element. If a range of (ol, p, ol) is pulled, non-ID attributes will only be preserved on the <ol> elements.

  8. Item 12014: For delayed conref resolution, should the spec address how to deal with usage in scenarios where conref cannot be delayed - or is that too much for the spec? For example, in scenarios like PDF. Resolution: make clear that the instructions related to this element only apply for deliverable scenarios that support it. Scenarios that do not support delayed resolution need not attempt to delay the resolution.

  9. Item 12014: Delayed conref gives examples that will delay resolution of "step1", with no topic ID given. When this is defined in a topic, the relationship is straightforwrad. When it is defined in a map through topicmeta, it is less clear. Does it only apply to id="step1" within the first or root topic? Resolution: applies only to the first or referenced topic. Need to explain why topicid is not included with element id (in order to allow use of delayed key/id) Can it apply to the ID on a topic or sub-topic? Resolution: it can be the ID of the topic you are referencing through the topicref, but no other (no sub-topics). If task with id="step1" has step with id="step1", anchorid of step1 refers to the topic. In order to delay resolution in a sub-topic, does one need to reference that sub-topic directly from the map, defining keys or anchors in that location? Resolution: yes

  10. Item 12014: When an ID is specified with anchorid, it applies to usage of that ID within that specific topic. When a key is specified with anchorkey, does it apply to all usages of that key? Is there a difference between anchorkey specified in the topic, and specified in the map? That is, it seems that an anchorkey specified in the map could logically affect all references to that key. However, it does not seem logical for this to be the case when anchorkey is specified in a prolog. Resolution: should not be a difference between an anchorkey specified in topic or in map. Using in the topic does delay resolution of that key for an information set. However defining the key this way in a topic is not recommended.

  11. Item 12014: If key abc and ID step1 are both exported, then conkeyref="abc/step1" will be preserved in content generated from DITA. What about if step2 is not exported - is conkeyref="abc/step2" preserved? In other words, when using a key, does the ID still need to be exported? Resolution: conref resolution of step2 is not delayed; otherwise, defining a key with anchorkey would force you to delay resolution of conref to every item within that topic.

  12. Item 12015: When push/replacing with conref, how do attributes resolve? Assuming it is similar to when resolving conref, where values on the element doing the push win over values on the target. This is actually the same as conref, where the attributes on the element that use conref win. Resolution: assumption is correct.

  13. Item 12015: Is it valid to push multiple items before a target using conref push? Current assumption is yes, with no definition of the order in which those elements are resolved. Resolution: assumption is correct.

  14. Item 12018: Adding navtitle to topicmeta means that navtitle is available for topicgroup. The proposal states that in this case, navtitle has no defined purpose. Should processors be instructed to ignore the navtitle in this case, or is it implementation dependent? Resolution: Yes, processors should ignore navtitles on <topicgroup>, and topichead without navtitle is also considered an error condition

  15. Item 12026: Need a good markup example for glossProperty, glossScopeNote Resolution: Erik provided examples.

  16. Item 12026: How much of the glossAcronym special behaviors belong in the language spec, and how much in the architectural spec? Resolution: They all belong in the language spec.

  17. Item 12031: If defaultSubject defines a default for @platform, may @platform still inherit a value from an ancestor, or does the default value override the inherited value? Robert taking this to the TC list Resolution: default precedence now defined in the docs

  18. Item 12031: The subjectRelHeader element appears to be specialized from relrow instead of relcolspec. Is this correct? Either way, the proposal does not define this element, so the lang spec contains only a guess at a description and needs to be checked. Resolution: subjectRelHeader should be specialized from relcolspec. Description has been updated.

  19. Item 12031: The topicSubjectHeader element appears to be specialized from relrow instead of relcolspec. Is this correct? The spec needs an example (the current may not be accurate). The description of topicSubjectHeader also needs to be verified / updated. Resolution: should be specialized from relcolspec. Erik updated the example. Description has been updated.

  20. Item 12031: Based on previous input, the defaultSubject element has the same attribute set as subjectdef. Given that it cannot contain other topicref based elements, is there any reason for collection-type? Resolution: remove @collection-type

  21. Item 12031: Need examples for elementdef, subjectHead, subjectHeadMeta Resolution: Erik provided examples.

  22. Item 12031: Need special attention to the example in subjectRelTable - need to improve the subjectRole and subjectRelHeader examples in that example with something that is valid. Resolution: Erik cleaned up the example

  23. Item 12031: Need an example for topicapply. The description was taken directly from the proposal, but I do not understand what the element means as it is described now. Resolution: Erik provided an example

  24. Item 12031: For all of the has* elements, is there a reason that scope does not allow the value "peer", instead only allows local/external? Resolution: usual meaning of peer does not make sense in this context. Will put it in so there are fewer questions, though peer and external would seem to be equal here.

  25. Item 12031: Rows in a topic subject table contain a column for topic references, followed by any number of columns for subject references. If there are 2 columns for subjects, are those subjects related to each other as they would be in a normal reltable? Does some relationship between the subject carry through to the scheme? Resolution: no relationship defined between adjoining subjects. The relationship is independent of the scheme.

  26. Item 12047: The proposal for anchorref states: The copied child elements can be suppressed in the current context by setting the toc attribute on the child elements to "yes" and on the <anchorref> element to "no". However, based on comments from Erik Hennum (the originator of the requirement), the content of the anchorref is always removed from its original location. Unsure how to reconcile this. Resolution: the contents are not removed from the original location.

  27. Item 12047: Is it correct to say that, for situations that do not support reuse of a topicset as an independent unit, applications may treat the topicsetref element in a manner similar to conref? Wondering about the current wording, which would seem to say that PDF must find a way to use the same independent set of information when it is used more than once, rather than copying it twice. Resolution: when cannot support managing collections, treat as conref.

  28. Item 12047: The contents of an anchorref in a map are copied to a new location when resolved. From which context does it inherit metadata values? From the original context (values can be set on the anchorref and its ancestors), from the resolved context (values set on ancestors of the anchor), or from both? If both, which first? Resolution: reason for authoring in another context may be inheriting metadata, so should inherit in authoring context.

  29. Item 12047: Is there a distinction between run-time versus build-time resolution of the anchor? Do applications that support build-time resolution delay, while applications that do not (PDF) resolve during the build, or is there some other way to determine this? Resolution: same as topicsetref - treat as push conref when no runtime resolution is available.

  30. Item 12047: If an anchorref references an ID that does not exist or is not part of the current information set, may an application choose to ignore the reference and/or generate an error, while keeping the content in its original location? The proposal indicates that the anchorref content is always kept in place, regardless of whether the target is found, so this question applies only to the error behavior. Resolution: if target is unavailable, processor can choose what to do (tolerate, warn, etc). Content cannot be displayed. Anchorref is always removed from its original context.

  31. Item 12047: When anchorref contents are copied to an anchor, does the resulting tree still contain the anchor, or is it replaced? May multiple anchorref elements point to the same anchor? If so - the current assumption is that each anchorref copies after the anchor, with no defined order, and that the anchor does remain in the result tree. Resolution: assumption is correct - order within anchorref is preserved, order of anchorref is undetermined.

  32. Item 12050: The longdescref attribute description references a W3C page as an example of how this value may be used. The updated description leaves this out when removing other content - should the example be preserved? Resolution: The example will be preserved

  33. Item 12050: Revised description for lq/@type removes the definition for bibliographic and -dita-use-conref-target, and says that the other two values are allowed but deprecated. It appears this was written under the assumption that the type attribute would be un-enumerated. It was not, so I assume that all should still be described, and should not be called deprecated? Resolution: item 12050 itself instructs that lq/@type should not be enumerated, so the text in the proposal is correct.

  34. Learning specialization: nothing contains the lcDescription element. Should it be removed? Resolution: yes, it should be removed

  35. General: in DITA 1.1, the attribute description for @domains actually listed the values shipped in the default document types. The current plan for 1.2 is to indicate that this value changes in every document type, and give a single sample value that may not be correct for most doctypes. Does that sound correct? Resolution: yes, that is correct.

Questions_for_1.2_Lang_Spec (last edited 2009-08-12 18:02:43 by localhost)