The Definitive Guide is a good start, but probably won't help you actually make a document.
You have two choices, XML or SGML (see the guide). I've always used SGML, but make it like XML (see below). This is because doing things like inserting a text file or program listing from a foreign file with XML requires all sorts of playing with tools that seem mostly to be based on Java, which sucks on any platform !x86, which I use a lot. It seems much easier to just use jade to get everything done.
Use the XML declaration for SGML so you can have closed tags (e.g. <tag />). I think this turns it into something defined as WebSGML. Close all your tags (such as <imagedata>) and make sure all your tags are lower case. This means if you want to make it XML later, you can. I've also found xsltproc does a better job at finding problems than jade.
You'll want a CSS file to style your HTML output. Create a DSSSL script that looks like below.
<!DOCTYPE style-sheet PUBLIC "-//James Clark//DTD DSSSL Style Sheet//EN" [ <!ENTITY docbook.dsl PUBLIC "-//Norman Walsh//DOCUMENT DocBook HTML Stylesheet//EN" CDATA dsssl> ]> <style-sheet> <style-specification id="html" use="docbook"> <style-specification-body> (define %stylesheet% "stylesheetname.css") </style-specification-body> </style-specification> <external-specification id="docbook" document="docbook.dsl"> </style-sheet>
Put your figures in with something like below and you can create both PDF and HTML output
<figure> <title>Figure title</title> <mediaobject> <imageobject> <imagedata fileref="figures/figure.eps" format="EPS" /> </imageobject> <imageobject> <imagedata fileref="figures/figure.png" format="PNG" /> </imageobject> <textobject> <phrase>About the figure.</phrase> </textobject> </mediaobject> </figure>
Create your output with the jw wrapper around jade.
HTML $ jw -o html -d stylesheet.dsl -f docbook -b html -l /usr/share/xml/declaration/xml.dcl docbook-file.sgml PDF $ jw -f docbook -b dvi -l /usr/share/xml/declaration/xml.dcl docbook-file.sgml $ dvipdf docbook-file.dvi