Tribeless Nomad (tribelessnomad) wrote in lj_biz,
Tribeless Nomad
tribelessnomad
lj_biz

lj_doc: XML DTD for protocol documentation

I've created a DocBook-compatible DTD for LiveJournal's client-server protocol documentation.

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.
The DTD is written specifically for the protocol documentation, based on the structure of the existing HTML pages. It can be adapted as necessary to support other document structures that writers come up with.

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:
January 15-17
February 20-21
February 26-28
Subscribe
  • Post a new comment

    Error

    Anonymous comments are disabled in this journal

    default userpic

    Your reply will be screened

    Your IP address will be recorded 

  • 10 comments