search

oxygenxml / userguide

The oXygen XML userguide
41 stars 78 forks source link

Markup for element names, other syntax items #59

Open mbakeranalecta opened 10 years ago

mbakeranalecta commented 10 years ago

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 commented 10 years ago

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 commented 10 years ago

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 commented 10 years ago

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 commented 10 years ago

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

raducoravu commented 10 years ago

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 commented 10 years ago

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.