Re: [dita] Re: [External] : [dita] Normative rule about @class and @specializations required on the root element of every topic and map

[Eliot Kimber <ekimber@contrext.com>]

I agree with Robert that the use of @specializations is implicitly required by the attribute domain facility, so not clear if it's useful or necessary to make a normative statement as long as it's clear that the *only* way a conforming DITA processor can know about an attribute specialization is via a @specializations value.

Note that when I refer to "document instance" I don't mean the xml data as written to disk, I mean the XML document *as parsed*.

That is, an attribute whose value is provided through a grammar file is "in the instance" when the document is parsed with respect to that grammar. If the document is not parsed with respect to a grammar that provides a default for the attribute then it must exist in the XML source.

DITA rules for documents are for the documents *as parsed*, so the question of *how* an attribute is supplied (literally in the markup or via grammar defaulting) is irrelevant as far as the normative rules about documents are concerned.

So we don't need to say anything about any requirements that any attributes be or not be declared--that's a syntax detail that is of no concern to the normative rules.

The rule is "if a document uses attribute domains those domains must be named in a @specializations attribute on the root map or topic element."

That makes it implicit that @specializations should not be specified if there are no attribute domains but it doesn't say it explicitly. 

I think I agree that we shouldn't *require it* when there are no attribute domains but it might be useful to explicitly say that it is not required when the value would be empty.

Cheers,

E.

--
Eliot Kimber
http://contrext.com
 

ïOn 6/10/21, 12:19 PM, "Robert Anderson" <dita@lists.oasis-open.org on behalf of robert.dan.anderson@oracle.com> wrote:


    Following up on our rules for the specializations attribute...


    As Kris noted in the meeting this week, we already state that every attribute domain MUST provide a token for the specializations attribute. I think that covers a lot of what we need. Ideally, we can rely on that to avoid extra overlapping normative rules.



    Beyond that rule, there are several places we might talk about the attribute:

    * When defining a topic or map specialization, the grammar module for that topic or map really should define @spcializations as a valid attribute. I don't think we need a normative rule here; if so, it cannot be MUST because there are edge cases where
     it's not relevant. I'd recommend a non-normative note though, that without this attribute, it will not be possible to integrate specialized attributes in a way that DITA processors will recognize.


    * When configuring a document-type-shell, the shell needs to declare which specialized attributes are included. I don't think this is a normative MUST thing so much as "this is just a rule for setting it up" -- without doing it, things won't work. The
     shell configuration sections already describe how to assemble those mandatory tokens from each attribute domain.



    * We should take care talking about document instances, because this attribute is almost never set within a document instance. Instead, it is picked up from default values in the grammar file. It is valid for that default value to be empty (no specialized
     attributes in use). It is also possible that someone specializes a topic or map without this attribute, in which case the document instance cannot set a value or pick up a default. In both of those cases, no attributes in the document would be recognized as
     valid attribute specializations.

    I'm less certain about where to include each of the items above (it's hard to agree on a location without a shared draft copy that we can all reference).


    Thanks,
    Robert


    ________________________________________
    From: dita@lists.oasis-open.org <dita@lists.oasis-open.org> on behalf of Kristen James Eberlein <kris@eberleinconsulting.com>
    Sent: Tuesday, June 8, 2021 9:34 AM
    To: DITA TC <dita@lists.oasis-open.org>
    Subject: [External] : [dita] Normative rule about @class and @specializations required on the root element of every topic and map 

    Hi, folk.
    The draft DITA 2.0 spec currently has the following normative rule:
    "The root element of every topic and map MUST declare the following attributes:

    * @class
    * @specializations"

    As part of the review of the proposal for "Relaxing specialization rules", we've had some commentary around this:

    * Robert Anderson 
    "If a topic has no integrated attribute domains in 2.0, the value of @specializations will be empty. Is this really a
    MUST? Should we clarify to indicate that this must be declared in the grammar, but does not necessarily need to have a value - I know that has caused confusion in the past for a tool that reported errors for empty @domains."


    * Eliot Kimber
    "If @specializations is only relevant to attribute specializations then I think it would be sensible to allow it to be omitted, with an omitted @specializations being equivalent to specializations="" (empty or whitespace-only value).
    The counter to that approach is that you can't easily distinguish between really having no attribute specializations and just forgetting to provide @specializations, but in that case I think you'd get runtime failures if you actually had specializations
     that weren't declared (i.e., your @props specializations aren't recognized so things don't filter correctly).
    Seems like an edge case in practice since DITA defines a number of out-of-the box attribute specializations, including now all of the original conditional attributes"


    * Kris Eberlein
    "We need to remove this normative rule from this topic. With the exception of specifying the @specializations attribute, it duplicates the normative statement that follows.


    What do we want to say about the @specialization attribute and where?"


    -- 
    Best,
    Kris

    Kristen James Eberlein
    Chair, OASIS DITA Technical Committee
    OASIS Distinguished Contributor
    Principal consultant, Eberlein Consulting LLC
    www.eberleinconsulting.com <https://urldefense.com/v3/__http://www.eberleinconsulting.com__;!!GqivPVa7Brio!LToLvAuQczxPWq2VL1XdgbWp2bvii-6J4jPbBigL1FnEPk0J5HwQ7ohZfe96wEK5oBkTCWE$>
    +1 919 622-1501; kriseberlein (skype)



    --------------------------------------------------------------------- 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 <https://urldefense.com/v3/__https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php__;!!GqivPVa7Brio!LToLvAuQczxPWq2VL1XdgbWp2bvii-6J4jPbBigL1FnEPk0J5HwQ7ohZfe96wEK5dAWAIhg$>