xb95 (xb95) wrote in lj_dev,

Protocol Documentation Updating Reference

Hey everyone.

I figure that the following information might be useful to those of you who write patches. I know that I've had to dig and scrounge to find this information, and compiled it myself. This post outlines the ways to update the protocol documentation as well as how to build the documentation.

If anybody has any changes they can suggest to this document, or anything I have wrong, let me know. I'd appreciate the corrections, as this information is quite useful to me and I'd hate to be using the wrong info!


Documentation Types
There are two types of protocol documentation: flat and XML-RPC. If you're modifying the client protocol, you're going to have to modify both modes inside ljprotocol.pl, so you're going to have to modify both sets of documentation. If you don't do both, your patch will likely get rejected by the powers that be. I've found this out the hard way, heh.

Updating Flat Mode Documentation
This is the easier of the two types to update. Basically, all you have to do is modify the file htdocs/protocol.dat. It contains all of the flat modes in a fairly easy to understand format. I won't tell you how to modify the file--take a look and figure it out for yourself.

If you are creating an entirely new protocol mode, you can simply append it to the end of this file. Simple.

Updating XML-RPC Documentation
If you are simply making a change to an existing protocol mode, then you will need to modify the file doc/raw/build/protocol/name.xml where name is the mode. For example, if you want to make a change to the getevents protocol documentation, you'd modify the file doc/raw/build/protocol/getevents.xml. Once again, the actual format of the file will be up to you to decipher. It's not that hard, it's kinda like HTML.

On the other hand, if you are creating an entirely new protocol mode, you will need to do two things. First, create an XML file named mode.xml and put it in the doc/raw/build/protocol/ directory. You will need to model this file after the other XML files already in the directory. Take a look at them to find out how to structure your file and the particular elements to use. The second thing you will need to do is modify doc/raw/build/protocol/xmlrpc.xml. You should see a bunch of <!ENTITY ...> lines near the top; add a line like this after them:

<!ENTITY mode.name SYSTEM "name.mode.xml">

Replacing name with the name of your new protocol mode, of course. Then, scroll down some in the file until you see &mode... lines. Add a line like this:


Now, save the file and close it. You're done.

Generating the Documentation
I will assume, for the sake of discussion, that everyone is using goathack. If you aren't, then the procedure should be the same, but you're going to have to experiment on your own.

You will need to generate the docs every time you update any of the document files. This is a rather slow and tedious process--goathack will need 5-10 minutes to do it, depending on server load at the time.

It's a very simple command:

~/doc/raw/build/generate.pl --myxsl

The --myxsl option instructs generate.pl to use the version of XSL (or whatever it's called) installed on the server. The version installed works just fine with generate.pl, there's no need to try to get a new one or anything.
  • Post a new comment


    Anonymous comments are disabled in this journal

    default userpic

    Your reply will be screened

    Your IP address will be recorded 

  • 1 comment