RE: DOCBOOK: Templates for SQL database table doc

[David Cramer <dcramer@broadjump.com>]

Hajo,
Refentry is one way to go. I'm not sure how suited it is to tables in a
data model. You'd probably want to modify the xsls to get the look you
want for your reference. 

I went a different route when faced with a similar task:

1) I created a simple DTD to describe the data and included DocBook.
Make sure that the element names in your DTD collide with DocBook
element names. Something like this:

<database:root>
<database:subsystem name="ABC">
<database:description>
	<para>Blah blah</para>
</database:description>
<database:table name="PFoobar">
	<database:descripton>
		<para>
			This table contains configuration data for the
Foobar
	            thingbag. I can put docbook in his description, for
example
	            I might mention the <database
class="table">PWooga</database>
	            table and have my xsls automagically create a
hyperlink to 
	            <database class="table">PWooga</database> and create
an indexterm
                  for <database class="table">PWooga</database>here.
		</para>
	</database:description>
	<database:column name="name">
	<database:description>
	      <para>
		      This is the name of this particular Foobar. 
             </para>
	</database:description>
      <database:example>
	       Snafu
	</database:example>
	<database:format type="VARCHAR" size="256" nullable="false"/>
	</database:column>
</database:table>
....

2) I used a script to convert the source .sql file to this markup (with
empty descriptions and examples). I sent these to developers so they
could fill in the descriptions. I didn't require them to put in anything
but text in the description and example elements. I edited this text and
added docbook markup that was needed. The structure of my dtd was simple
enough that they saw what they were supposed to do. 

3) I wrote an xsl to convert this to a docbook file that I included in a
larger book. Each table in the database became a CALS table in a
section. The intermediary docbook file that is sucked into the larger
book isn't very semantic (in the sense that CALS tables are in the gray
area between semantics and presentation), but that doesn't matter
because it's a throw-away. I can do any interesting transformations I
need to select the subset of the database descriptions I want from the
real source (my specialized dtd). The xsls that take me from my dtd to
pure docbook also add indexterms where they find <database> tags inside
of descriptions and hyperlink from things tagged as <database> to the
appropriate table description in the reference. This is pretty easy
since the content gives you ready-made unique IDs. There were a few
other things the xsls could automate that were unique to my project.

4) I used ERwin to capture the diagrams. It saves as .jpg and you can
print to .ps/.pdf and get an .eps file from that for print. We did 'mini
ERwins' for pieces of the data model and included those as graphics at
appropriate places in the reference. We're also doing a poster of the
whole thing, but that doesn't involve docbook.

I'm not sure if this was the right way to do it, there were certainly
any number of ways to go about it. This way fit my situation and
definitely made the project more manageable for me. 

David

> -----Original Message-----
> From: Hajo Lemcke [mailto:hajo@lemcke.com]
> Sent: Sunday, March 10, 2002 9:47 AM
> To: docbook@lists.oasis-open.org
> Subject: DOCBOOK: Templates for SQL database table doc
> 
> 
> Dear all,
> 
> I'm currently documenting a database structure (with docbook of 
> course). Are there any known templates out in this world for table 
> definitions? Currently I use a 'refentry', which is not bad, 
> but lacks 
> features to produce SQL-DDL output and keep that in alignment 
> with the real database structure.
> 
> Anybody using DIA for database ER-diagrams in conjunction with 
> docbook?
> 
> Greetings Hajo
>