I'm posting this today in case 'dormando' or any other XML expert wants to look it over and/or start creating tools for it. Those of you who aren't familiar with XML, please hold any questions for a day or two until I can post some decent stylesheets as well. At that point, it should become apparent (at least to users of Internet Explorer 5) what the point of this exercise is. We may not need to rewrite the protocol docs, but lacking better suggestions, 'dormando' and I decided to use them as a test case while a documentation system is put in place.
Here are the files I've posted:
- checkfriends.xml -- an XML version of the online documentation for the checkfriends protocol mode.
- protocol.xml -- an XML version of protocol.bml. Right now, this pulls in checkfriends.xml at the end, just to show it can be done, but soon I'll find a better way to tie the pages together.
- protocol.dtd -- the document type definition (DTD)
- iso-num.ent -- XML entity definitions for numeric and special graphic characters. Raise your hand if you knew that ¶ ( ¶ ) is called a "pilcrow". This file is copied without modification from DocBook.org.
- protocol.xsl -- a crude stylesheet, which is barely enough to create a usable page layout for either of the .xml files.
Dormando, I suppose this is just stating the obvious, but if you write tools based on this DTD, don't hard-code any of the specific tags, attributes, or entities -- they should all be read from the DTD. We need the ability to replace the DTD quickly as writers request additions, and that won't be possible if tools have to be updated at the same time. What I've posted, however, should give you a fairly accurate idea of what tricks your tools will need to perform.
With this done, I'll turn my attention to (1) writing some sample stylesheets and scripts for viewing the documents as formatted pages, and (2) explaining in simple English (HTML, actually) how to create documents that conform to the DTD.
Earlier related threads: