Markup for element names, other syntax items

[mbakeranalecta]

Currently the markup of element names in the docs is inconsistent. I have found b, i, codeph, and quotation marks use, as well as no markup at all.

Personally, I think that element names are important enough in this doc set that they should have specific markup of their own that would identify the vocabulary they belong to. That would allow us to generate links to their respective language specs.

There are similar issues with the markup of API names and other syntax items such as CSS syntax.

We need a policy for these items as well.

[raducoravu]

Mark, can you give some examples about what you mean by "element names"?
And yes, we would need a policy for this. Any hints about how we should best approach this?

[mbakeranalecta]

I mean XML element names from DITA or DocBook or other languages such as "bookmap" or "codeph". There are quite a number of mentions of specific XML elements in the docs.

I will prepare a more comprehensive list of the issues I am seeing.

[raducoravu]

DITA 1.3 will have special elements added to the base DTDs for XML element/attribute/comment/processing-instruction names.
But what should we use in the meantime? Maybe "apiname" or "term"?

[georgebina]

Radu, what it will mean to integrate the xml domain? We already have the troubleshooting from DITA 1.3.

[raducoravu]

We should probably wait until the DITA 1.3 specs is adopted and the DTDs are included in a newer DITA OT version to get to use the new XML domain elements.

[mbakeranalecta]

Makes sense. In the meantime, I have been using [codeph], which is less semantically precise, but better than [term], [b], or [i], which is a lot of what I found when spell checking. This at least hides the element names from the spell checker, which reduced the number of false hits, which makes spell checking a much less time consuming activity.