Draft 3 of XML mention Article

[Keith Schengili-Roberts <keith.roberts@ixiasoft.com>]

Hello there:

Please find attached the third draft of my XML Mention article. This incorporates comments/suggestions from Eliot Kimber and Tom Magliery.

While making changes I kept track of both Eliot's and Tom's suggestions and what I ended up doing. The "Detailed Responses" text file keeps track of the major suggestions and what path I ended up taking. I found their suggestions to be very useful and I have made what I hope are substantive changes.

Cheers! 

-

Keith Schengili-Roberts

DITA Information Architect / DITA Specialist

 

IXIASOFT 

825 Querbes, Suite 200, Montréal, Québec, Canada, H2V 3X1

tel  + 1 514 279-4942  /  toll free + 1 877 279-4942 

robertsk@ixiasoft.com  /  www.ixiasoft.com

Interested in attending? Visit our event website for more information. 

Attachment: xml_mention.pdf
Description: xml_mention.pdf

Eliot Kimber's comments

EK: Not sure "XML Content" is the best term to use here--at least when I think of "XML content" I think "content tagged with XML" not, mentions of XML elements and attributes. However, I appreciate that there's no obvious term that means "mentions of XML elements and attributes". 
KSR: Have changed title to say "Tagging XML Constructs in DITA 1.3" instead. I think "construct" fits as its definition is "to make or form by combining or arranging parts or elements", which seems appropriate. I am open to other ideas though.

EK: [general edits replacing "tags" with "elements"]
KSR: Agreed. While "tags" are a commonplace term for XML elements, specificity is needed here. If a style guide for articles for the DITA Adoption Committee is ever made, this ought to be one of the points.

EK: I would normally use <keyword> [replacing <q> with <keyword> in example]
KSR: I don't see a compelling reason to use keyword in this instance and I think it might confuse some readers. Since <q> seems to be causing odd formatting issues at output, have simply replaced them with quotation marks. 

EK: Note that "character entity" is not actually a defined term in XML. There are simply "text entities". We usually take "character entity" to mean a reference to a single non-ASCII character. The <textentity> element can be used for any text entity name (not that anyone should be using text entities and therefore should never need to mention them, but nevertheless, "character entity" is too narrow and is not actually a defined term.
KSR: An excellent point, and something I had not considered before. I now use "text entities" as suggested.

EK: This is not necessarily the case: there's no defined presentation convention for processing instructions and showing just the name wrapped in PI delimiters seems odd to me. More likely it would be shown in some distinguishing font.
KSR: Have double-checked the sample output and you are correct. Have changed the sentence to: "To describe processing instruction names in DITA 1.3, use the <xmlelement>xmlpi</xmlelement> element. The default behaviour by the DITA-OT is to display its contents using a different font.

EK: This is not the intended use of the xmlpi element. The xmlpi element is intended to identify mentions of PI *names*. It is not a way to tag examples of PIs. For that you should use <codeph>.
KSR: I have changed the examples accordingly in both the descriptive paragraph and its associated example. I would appreciate it if you could double-check my changes to ensure I have it right.

EK: Would somebody not integrate XML Mention but integration the markupname domain? Also, "constrain away" is not really the correct term here since you would never need to use a literal constraint, you would just not integrate the domain. I would say something like "If a given DITA document type does not include the XML Mention domain but does include the markup name domain, then... But that seems like an edge case that isn't very interesting.
KSR: I've used your suggested phrasing. I take your point that it is an edge case, but it is the only one I can think of where one might want to use the markupname element instead of a more semantically descriptive XML mention element. I am open to suggestions for other, more plausible scenarios! Alternately, would it make more sense to include information about this element at the beginning and say that everything in the XML mention domain is specialized from it and leave it at that, sans example (and implausible scenario)?

---------------------------------------------

Tom Maglery's edits:

TM: "Content" doesn't seem quite right here. Entire DITA topics are "XML Content". How about something like "XML Names"?
KSR: Eliot had the same issue with this word in the title. I don't think "Name" is better since there are some XML mention tags which are specific for things like "processing instruction names", so not everything is an XML name. Have changed it to say "Tagging XML Constructs in DITA 1.3" instead. I think "construct" fits as its definition is "to make or form by combining or arranging parts or elements", which seems appropriate. I am open to other ideas though.

TM: "XML constructs such as element and attribute names"
KSR: Have inserted your re-phrasing.

TM: Is it worth mentioning what support there is (or is not) already in the DITA OT? Do the HTML or PDF or other transforms already do angle brackets on xmlelements in 2.2.x? I'm only asking because I see that you've mentioned DITA OT support for numcharref below.
KSR: Good point. I have made changes describing what the DITA-OT does at output for each element described in the article.

TM: Some zero-width non-break spaces might not go amiss throughout this code sample.
KSR: Since I am using CDATA for the examples I cannot use non-breaking spaces. Not sure why the quote element is being spit across lines in my example. Have simply replaced with double-quotation marks.

TM: "&#931;" or "&#x3A3;"
KSR: Not "or", since these two examples show how the previously mentioned "&amp;#931; (decimal base) or &amp;#x3A3;" would be rendered respectively. 

TM: I'm guessing that the DITA OT did not do what you think it was going to do here ... need to pull out the angle bracket (character entities) and question marks.
KSR: You are correct! Based on Eliot's comments I have changed a lot in this topic, and in this instance have simply resorted to angle brackets and question marks to get what I required in this case.

TM: I think there are two key problems with this code example. One is that the "dbfo" name is actually the thing that's meant to be marked up with the xmlpi element -- not the entire PI.  Full PIs should be marked up with something like codeph. The other thing is that the full-PI example shown here is not actually a correct XML PI. There should be a space delimiter setting apart the PI name from the rest of it, i.e. where there is an underscore in this example, it should be a space. 
KSR: Eliot pointed out the same issue with the code example and the name of the process instruction. I believe that is now fixed. As for underscore, I have replaced it with a space in the example as you suggest. (I pulled the example from here: http://docbook.sourceforge.net/release/xsl/1.75.2/doc/pi/dbfo_sidebar-width.html and I suspect now that their use of the underscore is to replace a space in the URL of the webpage).