Slashdot Mirror
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."
Asking how to do this in Word is like asking how to cut a board in half with a hammer. In both cases, you're using the wrong tool for the job.
That said, I can tell you what we do for documentation. We have a wiki (Confluence, though any should work) that is perfectly capable of handling XML or any of a number of languages. We then have automated processes which periodically pull certain pages, strip the navigation elements and render them to PDF which, depending on the process, get transfered to various locations (samba fileshare, a couple of different intranet sites we maintain or into our CMS workflow to be approved and added to our public site).
Since it's a wiki, the input is easy and anyone in our company can contribute (if we were larger, we might add more access controls). Yet it also produces professional-looking PDF documents.
You may try StylusStudio's xml schema documentation generator or simpler/opensource/customizable dtdtoc written in python.
find -name "*base*" -exec chown us {} \; ; ln -s
Before you flog yourself too much with XML, check out JSON: http://www.json.org/.
It's supported by every language under the sun, and really simple to use. You may end up needing the extra capabilities of XML, but if you don't JSON is a much friendlier experience.
I thought that the point of XML was to embed the documentation in with the data, so that it was human-readable? This doesn't make any sense. If XML has to be documented anyway, then what's the point? To increase network traffic? To fill up "extra" hard drive space? Old fashioned character-delimited is a better way to go if you have to document the thing, anyway.
I don't respond to AC's.
If I understand the question right, how to present structured documents within human readable text then closest you will ever come to a right answer is YAML. look it up at wiki pedia.
Some drink at the fountain of knowledge. Others just gargle.
And then it uses an XPath-like syntax to point elements and attributes out and describe them, as in:
It's a very readable way to document and even people who normally only read examples have no problem parsing this. Smart developers on the receiving side code to this and don't bother with the XSD. People who are slaved to their XSD to Java tools have to use the XSD and end up in a world of pain.
oops, Here's the link. Also a word of advice: you can embed XML without modification in YAML just by indenting it. So you can have both in the same document. Unlike XML, YAML allows for some (limited) relational hierarchy and for type casting as part of the language itself. You can use this to simplify a highly nested XML document with lots of redundant entries. just make an !!xml type-def.
Some drink at the fountain of knowledge. Others just gargle.