OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

dita message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

Subject: DocBook Conformance Statement and rendering expectations

Regarding the question in today's meeting about the DocBook Conformance Statement, here is the complete conformance statement for DocBook 5.0 (the only change I made was to show MUST and SHOULD in caps; the DocBook spec uses italics for normative text):

This specification normatively defines DocBook V5.0 with a RELAX NG grammar and a set of Schematron assertions. A conformant DocBook V5.0 document MUST be valid according to both the grammar and the assertions.

The reference documentation describes additional constraints and processing expectations. A conformant DocBook V5.0 document SHOULD respect those constraints and anticipate those processing expectations.

DocBook 5.0: the Definitive Guide is listed as a normative reference, and it is, along with some other normative references, what the conformance statement refers to when it says "reference documentation."

Given the significant differences between DITA and DocBook, especially the degrees of conformance specified for processors, I'm not sure the conformance statement gives us much that's relevant for the DITA conformance statement. However, I do think the "Conformance of DITA documents" clause could be tightened with normative wording. For example, "A conforming DITA document MUST meet the following criteria:" rather than "A conforming DITA document is a document that meets all of the following criteria:"

However, the DocBook conformance statement has some wording that might help with the question of normative statements regarding rendering. The statement turns things around a bit. Instead of saying that processors SHOULD follow processing expectations, it says that conforming documents SHOULD anticipate processing expectations. That is (ignoring the grammatical anomaly of a document, rather than its author, anticipating anything:-), a processing expectation isn't a requirement on a processor, it's a statement warning authors that a processor will likely handle things in certain ways. So, if you're using <q>, you SHOULD expect that many processors will generate quotation marks.

I doubt that every rendering expectation can be inverted, but this might be an option for some.

One final thought on processing expectations. The DocBook Definitive Guide includes a processing expectations section on each element reference page. I think that would be a good way to handle processing expectations for DITA, too (though you probably don't need that section on every element). You wouldn't need a separate document or appendix, and the information would be right where people will probably expect to find it. And if you want to make those statements non-normative, that can be handled in a blanket statement.

Best regards,
XML Press
XML for Technical Communicators

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]