Suggestion: remove duplicate short descriptions from RNG

["Robert D Anderson" <robander@us.ibm.com>]

In the DITA 1.3 RelaxNG grammar files, every element includes an <a:documentation> annotation that looks like it matches the element definition. For example, you can see a definition for the <b> element as delivered in DITA 1.3 (this
https://github.com/oasis-tcs/dita/blob/1.3-Errata-02/doctypes/rng/base/rng/highlightDomain.rng#L112

Unfortunately this doesn't match the definition in the specification itself -- the differences are pretty trivial for this element, but I'm not sure about others:
http://docs.oasis-open.org/dita/dita/v1.3/errata01/os/complete/part2-tech-content/langRef/base/b.html#b

These definitions have existed in our XSD Schemas since DITA 1.0. It looks like this was automated in DITA 1.0 (maybe Eric can verify) because the scraped definitions at that point actually included DITA elements. They never existed in the DTDs. The current definition for <b> in the RNG matches what was shipped in the XSD for DITA 1.0.

I think these annotations are great + potentially useful, provided they can be automated. I think some tools can use them when working with the RNG as a way to provide tool tips or other help. But we should not be maintaining multiple copies of each element definition in the specification + in the RNG + potentially in the DTD.

But in the source as maintained in GitHub - I'd like to propose removing the descriptions at this point to reduce confusion, lower the burden on TC members trying to propose new elements, and resolve all current cases where we have out of date or even obsolete definitions in the grammar files. We might want to keep in some sort of hook to automate this later -- maybe a PI or <a:documentation> element that refers to the element -- but regardless, we should take out the old content.

Robert D. Anderson
DITA-OT lead and Co-editor DITA 1.3 specification
Marketing Services Center

E-mail: robander@us.ibm.com 11501 BURNET RD,, TX, 78758-3400, AUSTIN, USA