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

Collapse
Posted by David Kuczek on
Hello World,

I wrote a brief HowTo on DocBook. You can find it inside
www.openacs.org/file-storage.

I hope that I didn't forget anything. I installed everything via rpm
on RH 6.2.

Write me whenever you see a mistake or something doesn't work. It
worked for me. The documentation is my witness.

Have fun.

Collapse
Posted by Joel Aufrecht on

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.

Collapse
Posted by Don Baccus on
Talk to Roberto Mello ... if you're hacking on the .xml in our tarball/CVS we don't have the corresponding DTD file and Roberto's working on regenerating it.
Collapse
Posted by Talli Somekh on
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

Collapse
Posted by Tilmann Singer on

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.

Get the docbook-xsl package from here and use an xsl processor that's available on your system, e.g. xsltproc

Converting single files is quite easy:


xsltproc /path/to/docbook-xsl/html/docbook.xsl singlefile.xml > singlefile.html

Dunno how it deals with collections of several docbook documents though.

You can even make aolserver do the conversion, if your ns_xml was compiled with xsl support!

The docbook-primer.html document from aD (in the acs-core-docs package) mentions some customized stylesheets especially for ACS documentation - I wonder if those are available?

Collapse
Posted by Don Baccus on
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.
Collapse
Posted by Joel Aufrecht on

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.
Collapse
Posted by Don Baccus on
PLEASE contact Roberto about docbooks ... let's not spawn parallel, uncoordinated efforts, OK?
Collapse
Posted by Vadim Nasardinov on
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"