Uploaded image for project: 'Technical Advisory Board'
  1. Technical Advisory Board
  2. TAB-1278

Inadequate definition of conformance targets for DITA processors

    XMLWordPrintable

    Details

    • Type: Bug
    • Status: New
    • Priority: Blocker
    • Resolution: Unresolved
    • Affects Version/s: Darwin Information Typing Architecture (DITA) Version 1.3 CSPRD01
    • Fix Version/s: None
    • Component/s: Public reviews
    • Labels:
      None
    • Environment:

      Conformance

    • Proposal:
      Hide

      Create meaningful conformance targets with numbered conformance clauses (as per the TC process by the way) that reference back to the normative text with specific references.

      You can reference the ODF 1.2 conformance clauses to get an idea of what one idea of conformance targets can look like. (apologies, not a self-reference, I proofed the clauses but Michael Brauer wrote them)

      I can try to find some time to work with your editors on the conformance target issues if that would be helpful to the TC. DITA adoption is such that clear conformance targets will help it spread more quickly. Which will reflect well on both the TC and OASIS.

      Show
      Create meaningful conformance targets with numbered conformance clauses (as per the TC process by the way) that reference back to the normative text with specific references. You can reference the ODF 1.2 conformance clauses to get an idea of what one idea of conformance targets can look like. (apologies, not a self-reference, I proofed the clauses but Michael Brauer wrote them) I can try to find some time to work with your editors on the conformance target issues if that would be helpful to the TC. DITA adoption is such that clear conformance targets will help it spread more quickly. Which will reflect well on both the TC and OASIS.

      Description

      4.3 Conformance of DITA processors reads in part:

      *****
      DITA-aware processor

      A processor that implements all required processing relevant to the vocabulary modules that it claims to support. A DITA-aware processor MUST support at least one map or topic type, whether defined by the DITA standard or defined as a custom vocabulary module.

      Specialization-aware processor

      A DITA-aware processor that can handle any document specialized from some set of DITA vocabulary modules, though it might not be able to support all base topic or map elements.

      Fully aware processor

      A DITA-aware processor that unconditionally supports all base vocabulary modules, which implies support for all non-vocabulary-specific DITA features, such as content references and key references. It applies relevant processing to all DITA elements based on their @class and @domains attribute values.
      *****

      As conformance targets, these definitions are wholly inadequate.

      As I mentioned under TAB-1264, TAB-1265, TAB-1266, TAB-1267 and TAB-1268, it may not be possible for an implementer to discern the requirements for any conformance target given the use of RFC 2119 keywords in the draft.

      Even when that deficit is corrected, any implementer will have to search for RFC 2119 keywords and hope that they have caught all of them for any particular conformance target.

      Contrast the difficulty of an implementer with the TC which has the knowledge already of what it means by "relevant processing to all DITA elements based on their @class and @domain attribute values." I rather doubt even a skillful reader could jump to a conclusion about "relevant processing."

      For example: "supports all base vocabulary modules." ? The phrase "base vocabulary" (in the all-inclusive version) occurs only one other time. Under 2.6.4.7 RELAX NG: Coding requirements for constraint modules, in the list item that reads in part:

      "Constraints may be chained so that each constraint imports another, until the final constraint imports the base vocabulary module."

      So, are there multiple "base vocabulary modules" or is there only one base vocabulary module?

      An outside reader, who will be the reader of the specification, can only rely on the terms in the document.

      This is perhaps the hardest ask of all my comments because defining a conformance target is a non-trivial task as it enumerates the requirements that a target MUST/SHOULD/MAY meet and references the normative text for the full definition of the requirement.

      Let's take fully aware processor for a sketch of an answer to this issue:

      *****
      A DITA-aware processor that unconditionally supports all base vocabulary modules, which implies support for all non-vocabulary-specific DITA features, such as content references and key references. It applies relevant processing to all DITA elements based on their @class and @domains attribute values.
      *****
      WARNING: You know the requirements and I don't. This is just an attempt to be clear, probably not very useful for your revision work.

      1. Fully Aware DITA Processors,

      1.a MUST support (sublist of all base vocabulary modules with references back to normative text sections)

      1.b MUST support (sublist of non-vocabulary-specific DITA features with references back to normative text sections)

      1.c MUST support processing as defined by @class and @domain (insert refs) attribute values.

      1.d continue with SHOULD/MAY requirements for Fully Aware DITA Processors

      being sure to also include what sort of SVG and MathML support is required. Yes, you can compel conformance to other standards, so long as it is specific enough to be meaningful. As I pointed out in TAB-1262, saying an implementer must conform to SVG 1.1 is meaningless without more.

        Attachments

          Activity

            People

            • Assignee:
              Unassigned
              Reporter:
              Patrick Patrick Durusau
            • Watchers:
              1 Start watching this issue

              Dates

              • Created:
                Updated: