If I were a reader of a specification that had a "Rendering" section explicitly showing on some elements, and especially if I were an implementor of said rendering, my preference would be to see some kind of explicit "None" statement on the ones that have none.
TPILB.
mag
From: dita@lists.oasis-open.org [mailto:dita@lists.oasis-open.org] On Behalf Of Robert D Anderson
Sent: Tuesday, February 16, 2016 12:16 PM
To: Richard Hamilton
Cc: dita
Subject: Re: [dita] DocBook Conformance Statement and rendering expectations
One additional comment about this:
> 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.
At some point we'll need to decide how language reference topics will be formatted in future versions. After working with / editing those topics for so many years, I will admit to having some ideas.
One thing I've considered is this idea of a standard "Rendering" section, similar to the standard sections we have today. As with many ideas, this has pros and cons. For example, one pro is that it would presumably pull any rendering info out from other text about the purpose of the element, into easily findable (or filterable) sections that could be published on their own. One con would be the extra space taken up by having such a section on elements that don't really need them.
Alternatively, this could be a standard section that appears only for those elements with normative expectations regarding rendering.
Robert D Anderson
IBM Authoring Tools Development
Chief Architect, DITA Open Toolkit (http://www.dita-ot.org/)
<dita@lists.oasis-open.org> wrote on 02/16/2016 01:19:31 PM:
> From: Richard Hamilton <hamilton@xmlpress.net>
> To: dita <dita@lists.oasis-open.org>
> Date: 02/16/2016 01:19 PM
> Subject: [dita] DocBook Conformance Statement and rendering expectations
> Sent by: <dita@lists.oasis-open.org>
>
> 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,
> Dick
> -------
> XML Press
> XML for Technical Communicators
> http://xmlpress.net
> hamilton@xmlpress.net
>
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe from this mail list, you must leave the OASIS TC that
> generates this mail. Follow this link to all your TCs in OASIS at:
> https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php
>