Forum OpenACS Q&A: HowTo on DocBook written...

I can't find this in /new-file-storage. Can someone with access to

I tried to update some documentation by working on the docbook and then converting it. After many hours of looking for documentation, I have accomplished the following:

1) I can go into PSGML mode in emacs and have it recognize the DocBook DTD, parse it, and validate against it.

!2) When I try and use openjade to create HTML documentation, it croaks as follows:

openjade -t sgml -d /usr/share/sgml/docbook/dsssl-stylesheets-1.59/print/docbook.dsl index.xml
openjade:index.xml:7:0:E: URL not supported by this version
openjade:index.xml:7:0:E: DTD did not contain element declaration for document type name

I'm getting ready to start solving this problem, but I've put maybe six hours or more into working on documentation and I still haven't accomplished anything. This is very frustrating; if documentation is important, it should be easy to work on. So how about some documentation on documentation. I would be more than happy to write or update a simple one-page document on how to set up your environment for working on DocBook, if only I could figure out how myself.

Joel,

Just today I was speaking with Roberto on this very problem! This weekend he promised to put together his thoughts on the documentation effort. Vinod and I will be helping him coordinate this.

In fact, I began studying the DocBook docs this afternoon and figured that setting up Jade with emacs or vi might be, like all things software, hell setting up. So I think we would appreciate your help a great deal!

talli

They aren't available at the URL mentioned in the .xml docs themselves.  I've not been working on this personally so I don't know if Roberto et al have had any luck locating them.  Roberto was going to write his own if necessary.

Dennis, I wasn't able to get anywhere with that URL - it seems to get mangled when used.

For those keeping score at home, here's where I'm at trying to convert a Docbook xml file to HTML:

Previously:

1) mucked with catalog files until emacs agreed to parse xml DTDs in psgml mode

2) tried to use openjade to convert xml to html

Most Recently:

1) As per advice, downloaded docbook-xsl. Used this command:

xsltproc --catalogs --nonet --verbose /usr/share/sgml/docbook-xsl-1.45/html/docbook.xsl index.xml
  (gazillions of lines like 
    xsltParseStylesheetTemplate: mode  
    set.titlepage.recto.auto.mode
    xsltCompilePattern : parsing 'legalnotice'
    xsltCompilePattern : parsed legalnotice, default priority 0.000000
   omitted)
parsed 12 templates
Attempt to load network entity http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd
requirements.xml:151: error: Entity 'nbsp' not defined
           
               ^
requirements.xml:609: error: chunk is not well balanced

^
index.xml:140: error: Entity value required
    &requirements;
                 ^
requirements.xml:151: error: Entity 'nbsp' not defined
           
               ^
unable to parse index.xml

When I removed the references to the child documents, I got an HTML output. So then I put the references back in and removed the nbsp tag, and got valid output, a non-quite-clean-looking HTML document in which all three xml documents were present in sequence. *shrug* That's at least enough to start working on documentation. I'll retrace my steps and write up a mini-howto, I guess.

I think jade only deals with sgml conversions using dsssl stylesheets, while your docbook files seem to be xml, for which I think only xsl stylesheets can be used.

I think XML documents that conform to the Docbook XML DTD also happen to conform to the Docbook SGML DTD, which means you can use DSSSL stylesheets, if you choose to. I haven't tried converting Docbook to HTML with DSSSL, but I did convert a whole bunch of ACS Java CMS docs (written in Docbook XML) to RTF using OpenJade and Docbook DSSSL stylesheets. I had to change the doctype FPI from "-//AD//DTD DocBook XML V4.1.2-Based Extension//EN" to "-//OASIS//DTD DocBook V4.1//EN"