RE: DOCBOOK: markup suggestions for protocol descriptions?

["Gershon Leib Joseph" <gershon at mainsoft dot com>]

Mark,

I've resolved similar problems by writing extensions to DocBook. Modifying
the DTD however is the easy part. Updating the stylesheets, especially if
you publish via Jade, can be a trying process, due to limitations in the
back-ends that don't always do what you expect them to...

My rule of thumb is: if there are a lot of these items you want to mark up,
go for extending the DTD. If there are only a few, use tables.

The decision also depends on how you publish your documentation. If you
publish to multiple formats, you have to modify multiple stylesheets after
you modify the DTD.

I don't fully understand what you are trying to do, but based on the
information you supplied, you could perhaps add something like the following
to a DocBook driver file (untested):

<!ELEMENT packet - - ( title, field+ ) >

<!ELEMENT field - - ( type, size, name, required, range ) >

<!ELEMENT (type | size | name | range) #PCDATA >

<!ELEMENT required - o EMPTY >
<!ATTLIST required yesno "no" >

Now authoring will be a breeze. You have to add support for these new
elements to your stylesheets.

I hope this helps

Gershon

| -----Original Message-----
| From: owner-docbook@lists.oasis-open.org
| [mailto:owner-docbook@lists.oasis-open.org]On Behalf Of Mark W. Eichin
| Sent: Thursday, March 30, 2000 7:14 AM
| To: docbook@lists.oasis-open.org
| Subject: DOCBOOK: markup suggestions for protocol descriptions?
|
|
| I've documented a moderate sized software system, which includes
| several components that send binary messages to each other.  I'm using
| a variablelist for abstract descriptions of the messages; now I need to
| describe the protocol at the byte-level.  Is there something more
| abstract than a table that would be appropriate?  I think about the
| packets as being a collection of fields, with type, size, name, "is
| optional", perhaps range for some types.  I've done this in raw HTML
| before with tables, each packet identified in a span and then the
| fields each individual rows - which is tolerable for output, but I'd
| hoped to do better for input...  suggestions?
|
|