• 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
  

posted at: Fri, 04 Nov 2005 23:25 | in /linux | permalink | add comment (0 others)