Normative statements and file-naming conventions

[Kristen James Eberlein <kris@eberleinconsulting.com>]

As I worked through incorporating content for the RELAX NG proposal into the spec, I noticed the following discrepancies relating to constraint module names:

• The conventions that we explicate for the names of constraint modules (literals & meaning of variables) do not match the constraint module names that we use in the examples.
• The conventions that we explicate for the names of constraint modules (literals & meaning of variables) do not match the constraint module names that we shipped for DITA 1.2

We used a normative SHOULD in our statements about constraint module names. (For a reminder about what the normative RFC-2119 terms mean, see http://docs.oasis-open.org/dita/v1.2/os/spec/introduction/c-terminology.html#terminology.

Regarding this specific issue, my personal suggestion is that we should change the file-naming syntax that is explicated in the spec to match the examples and the names of the DITA 1.2 files.

I'm a little at a loss to understand why we used a SHOULD statement, since I don't think that file names really affect exchange and interoperability. (If we are mandating conventions for file names to assist in the construction of automated generators for document type shells, then I think we ought to say so.)

And then I looked at the "File naming conventions" topic in the DITA 1.2 spec: http://docs.oasis-open.org/dita/v1.2/os/spec/archSpec/fileext.html#fileext . In this topic, we used a normative MUST about file names for the following objects:

• Document type shells
• Structural modules
• Domain modules
• Constraint modules

In this topic, at least the literal components of the explicated naming conventions match the examples and files shipped with DITA 1.2. (The variables used are either not explained or so loose that anything could match them.)

I suggest that we (at least) relax this normative MUST to a SHOULD and correct the naming conventions here to match the examples and names of the DITA 1.2 files.

--
Best,
Kris

Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Principal consultant, Eberlein Consulting
www.eberleinconsulting.com
+1 919 682-2290; kriseberlein (skype)