Embedding XML In Docs?

An anonymous reader writes "Now that XML is the de facto standard (for good or ill) for doing message passing, I find that I need to give XML examples in the documentation that we produce. We're stuck with Word and up till now I've just been doing the examples as cut and paste from the log files. We include schemas in the appendix but it seems that the clients like the 'readability' of the raw XML over other approaches we've tried. I'm wondering what everyone else is doing in the world of XML documentation."

Comments

Tibco TurboXML DTD Diagrams

[Cheefachi]

We publish tons of documentation that has to explain XML formats. What we do is include DTD diagrams in our documentation that shows the structure of the XML document graphically. The tool we use to generate them is Tibco's TurboXML and we've been using it for years. Obviously we include examples, but the DTD diagrams really show you all you need to know. I know, I know its commercial software. Maybe there's something open source out there that does something similar, not sure. Hope this helps!

Choose a good schema language

[srussell]

If you're using XMLSchema, then ditch that crap and use RelaxNG, which is actually readable. There's a compact syntax that is even more user-friendly. As an example, the schema for:

<addressBook>
<card>
<name>John Smith</name>
<email>js@example.com</email>
</card>
<card>
<name>Fred Bloggs</name>
<email>fb@example.net</email>
</card>
</addressBook>

looks like this:

element addressBook {
element card {
element name { text },
element email { text }
}*
}

Use your imagination to pretend that /. preserves indentation. --- SER