Re: [tlug] Docbook XML for documenting database tables

["Michael(tm) Smith" <smith@example.com>]

Hi Josh,

> Docbook experts (this means you, Smith!), I would like to use Docbook
> to document some MySQL database tables. It seems that if I do it
> right, not only can I generate HTML documentation from it,

Also PDF, and groff man pages (if you want), Eclipse Help, even
Microsoft HTMLHelp.

> but also the actual SQL statements to create the tables, so I
> can be sure that my tables are in sync with the docs.

I reckon that part will require you to do some custom XSLT coding.

> I found the online version of "Docbook: The Definitive Guide":
> 
> http://www.docbook.org/tdg/en/html/docbook.html

That is a good reference, and more up to date than the print
version.

> I am pretty sure that Gentoo is still on Docbook 4.4, which is why I
> am not using Docbook 5.0, before you ask.

Yeah, DocBook 5 has not been packaged yet, I think.

> Any tips?

As far as other packages to install, you want to get:

  docbook-xsl (v1.69.1 is the latest upstream)
  xsltproc
  libxml2 (the GNOME XML C library)
  libxslt

The above should be all you need for generating (X)HTML output
from DocBook source. (Note that xsltproc depends on libxslt and
libxml.)

There are some other things you might optionally install:

  nXML mode for GNU Emacs (excellent XML authoring mode)
  fop (an XSL-FO engine, for generating PDF output)
  xmlto (a "convenience" front-end)
  saxon (v6.5.x, a Java-based XSLT engine, alternative to xsltproc)
  dblatex (frontend to LaTeX/Tex-based system for generating PDF)

> Any pointers to documentation that would take me through the
> specific steps needed?

There is only one place you need look -- Bob Stayton's "DocBook
XSL: The Complete Guide" -

  http://sagehill.net/docbookxsl/index.html
  http://www.amazon.com/gp/product/0974152129/

Bob is one of the 4 core XSLT developers involved with the DocBook
project, and is by far the most active person on the DocBook
mailings lists, as far as answering questions and responding to
bug reports goes. His covers everything so thoroughly in that book
that we don't even try to provide detailed how-to guidelines in
the DocBook XSL doc distro any more (though we still ship very
detailed reference docs).

You'll also probably want to subscribe to the docbook-apps mailing
list so that you can ask questions there and follow discussions
from others -

  http://wiki.docbook.org/topic/DocBookAppsMailingList
  http://wiki.docbook.org/topic/DocBookMailingList

There is also an IRC channel -

  irc://irc.freenode.net/docbook

I am on there every day, and usually there are a few others on
there that are happy to answer questions and help.

The DocBook Wiki is also a good place to go to get "situated" -

  http://wiki.docbook.org/topic/FrontPage

It mostly just provides general information, not how-to
guidelines. The DocBook FAQ can also be useful -

  http://www.dpawson.co.uk/docbook/

> I don't have a lot of time to properly learn Docbook right now, so a
> recipe that would help me get started would be greatly appreciated.

Easiest way to get started is to grab nXML mode and create some
DocBook XML source, then try use "xmlto" to generate HTML -

  xmlto html foo.xml

> Once I start using Docbook, I am sure I will be so blown away by its
> features that I will make time for reading the book in its entirety!

Well, "DocBook: The Definitive Guide" is basically a reference
guide to all the elements in the DocBook schema/DTD. So if you
take time to read something through, it should be Bob Stayton's
"DocBook XSL: The Complete Guide".

And as far as being blown away, I guess you may not necessarily be
blown away in a good way :) DocBook can be a little daunting; it
has around 400 elements -- most of which you probably will never
need, but you may find that you still have to kind of slog through
list of element names to find what you need.

And if you get to the point where you want to do much
customization of your output, you may that to be a bit of work
too, because the DocBook XSL stylesheets are fairly complex. And
learning XSLT is not a particularly pleasant experience --
especially XSLT 1.0 (as opposed to XSLT 2.0, which is still not a
final W3C rec yet and basically has only one implementation so
far), and especially for programmers with a lot of experience in
procedural programming languages.

There are many things that are very simple to do in C, C++, Java,
Perl, or whatever that are annoying complicated in XSLT 1.0.
String manipulations, for one thing (XSLT 1.0 lacks regular-
expression support). Or things like just iterating over a loop.

Anyway, there are some decent books on XSLT. If you get far into
it at all, you need to get this book:

  XSLT Programmer's Reference 2nd Edition (Michael Kay)
  http://www.amazon.com/gp/product/1861005067/

That is the XSLT bible. People cite it chapter and verse. But it
is not a how-guide by any means. But there are few of those:

  XSLT Cookbook (Sal Mangano)
  http://www.oreilly.com/catalog/xsltckbk/

  Learning XSLT (Michael Fitzgerald)
  http://www.oreilly.com/catalog/learnxslt/

  XSLT (Doug Tidwell)
  http://www.oreilly.com/catalog/xslt/

"XSLT Cookbook" is a particularly outstanding book, one of the
best books of its kind I have ever come across. The other two
above are OK as starting points.

-- 
Michael(tm) Smith
http://www.oreillynet.com/pub/au/890
http://tokyo.metblogs.com/

Attachment: smime.p7s
Description: application/pkcs7-signature