Handbook with docbook

Moin

I just played around with docbook. I comited the result of my work. Man,
docbook is not really well documented. There is no small HOWTO guide.

cd doc/
./generate_handbook
get a coffee (takes 2 minutes on my dualcore here…)

That results in a handbook.html-file which is quite nice.

Carsten

Moin

I tried to start the handbook for Avogadro. I have a basic .docbook file done
but have no idea how to “compile” it to HTML.

In KDE we are using a cmake-macro which does all the dirty stuff. The probelm
is that we cannot use it here as it is using many other KDE macros and
even “meinproc4” which is a KDE-specific docbook-tool (KDEs proc).

The only other cmake-based docbook file I found is inside PLPlot. That
CMake-file is 200 lines long and I don’t understand it at all.

Reading this mail

http://www.mail-archive.com/cmake%40cmake.org/msg11987.html

it seems CMake isn’t really supporting Docbook natively (yet). I will ask Alex
for detail (he’s a friend of mine).

Carsten

I tried to start the handbook for Avogadro. I have a basic .docbook
file done
but have no idea how to “compile” it to HTML.

I obviously don’t know dockbook either. Will we be doing the help
system with dockbook too?

Qt 4.4 looks like it uses straight HTML:
http://doc.trolltech.com/main-snapshot/qthelp.html

I mention this because I see a few areas for user documentation:

  1. User handbook
  2. Inline help system in Avogadro itself
  3. Tutorials and screencasts on Avogadro website

Anything I missed?

Thanks!
-Geoff

On Saturday 01 March 2008 07:48:20 Carsten Niehaus wrote:

I tried to start the handbook for Avogadro. I have a basic .docbook file
done but have no idea how to “compile” it to HTML.

In KDE we are using a cmake-macro which does all the dirty stuff. The
probelm is that we cannot use it here as it is using many other KDE macros
and even “meinproc4” which is a KDE-specific docbook-tool (KDEs proc).

The only other cmake-based docbook file I found is inside PLPlot. That
CMake-file is 200 lines long and I don’t understand it at all.

Reading this mail

http://www.mail-archive.com/cmake%40cmake.org/msg11987.html

it seems CMake isn’t really supporting Docbook natively (yet). I will ask
Alex for detail (he’s a friend of mine).

Apparently SWIG are also using cmake and generating their docs using DocBook.
That could be another one for us to look at. In all honesty when we do
releases most packagers appreciate having a prebuilt PDF at least and many
projects I have dealt with have done this. That could be an option if we have
lots of trouble with cmake and DocBook but I am sure we will get it
sorted :slight_smile:

Looking around DocBook certainly seems like a good option. Tim and I had been
talking about getting something going. Can we just make a docs directory in
trunk and start playing with the source, may be with a link to how we build
for now.

Going forward to need a cmake target to generate the doxygen API documentation
as well as a cmake target to build the docs as PDF and HTML in my opinion.

Thanks,

Marcus

Am Samstag, 1. März 2008 17:13:57 schrieb Marcus D. Hanwell:

Looking around DocBook certainly seems like a good option. Tim and I had
been talking about getting something going. Can we just make a docs
directory in trunk and start playing with the source, may be with a link to
how we build for now.

Going forward to need a cmake target to generate the doxygen API
documentation as well as a cmake target to build the docs as PDF and HTML
in my opinion.

In my Git I have the .docbook file in avogadro/doc/. Shall I simply commit the
file?

Carsten

On Mar 2, 2008, at 5:58 AM, Carsten Niehaus wrote:

In my Git I have the .docbook file in avogadro/doc/. Shall I simply
commit the
file?

Sounds good.

Cheers,
-Geoff

On Sun, Mar 2, 2008 at 4:32 PM, Geoffrey Hutchison
geoff.hutchison@gmail.com wrote:

On Mar 2, 2008, at 5:58 AM, Carsten Niehaus wrote:

In my Git I have the .docbook file in avogadro/doc/. Shall I simply
commit the
file?

I made a small change to the declaration to make it not depend on kde.
But I was unable to declare the &language; “ENTITY”.

Tim

Moin

Ok, the PDF generation is now working. The script now looks like this:

#/bin/sh
echo "Generating PDF in the subdirectory ‘pdf’"
docbook2pdf -o pdf index.docbook

echo "Generating HTML in the subdirectory ‘html’"
docbook2html --output html index.docbook

I seems that for some reasons the docbook2* tools are almost 100 times faster
than xmlproc… The generation takes about 5 seconds now, perhaps even less.

Do you like this?

Carsten

I seems that for some reasons the docbook2* tools are almost 100
times faster
than xmlproc… The generation takes about 5 seconds now, perhaps
even less.

What’s not to like? PDF and HTML documentation in a few seconds? It’s
hard to complain about 100x faster. :slight_smile:

Cheers,
-Geoff

Am Dienstag, 4. März 2008 17:09:53 schrieb Geoffrey Hutchison:

I seems that for some reasons the docbook2* tools are almost 100
times faster
than xmlproc… The generation takes about 5 seconds now, perhaps
even less.

What’s not to like? PDF and HTML documentation in a few seconds? It’s
hard to complain about 100x faster. :slight_smile:

Yes, the generation of HTML and PDF takes really just a few seconds. The
output quality is really nice, I think… You need to install docbook-tools
to “compile” the PDF and HTML-files.

The current handbook has a screenie, a couple of chapters, some annotation,
some links. If you plan to contribute content I think you should find
examples how to do things.

Carsten

On Tue, Mar 4, 2008 at 9:03 AM, Carsten Niehaus cniehaus@gmx.de wrote:

Am Dienstag, 4. März 2008 17:09:53 schrieb Geoffrey Hutchison:

I seems that for some reasons the docbook2* tools are almost 100
times faster
than xmlproc… The generation takes about 5 seconds now, perhaps
even less.

What’s not to like? PDF and HTML documentation in a few seconds? It’s
hard to complain about 100x faster. :slight_smile:

Yes, the generation of HTML and PDF takes really just a few seconds. The
output quality is really nice, I think… You need to install docbook-tools
to “compile” the PDF and HTML-files.

The current handbook has a screenie, a couple of chapters, some annotation,
some links. If you plan to contribute content I think you should find
examples how to do things.

It only takes me slightly over 1s to build the html using xsltproc
here. I believe you can get slow builds if you don’t have the docbook
dtd installed locally. xsltproc then goes out and downloads it, which
can take some time. On Debian/Ubuntu systems having the docbook-xml
package should speed things up. You might also want docbook-xsl but
I’m not sure if that has anything to do with the speed.

I’ll try to help out with documentation where I can (silly PhD taking
all my time) :slight_smile:

-Jordan

Jordan,

is the xsltproc technically better than the docbook2pdf or
docbook2html solution? I see no real difference beside the much easier
syntax of the docbook2*-applications.

Carsten

2008/3/5, Jordan Mantha jordan.mantha@gmail.com:

It only takes me slightly over 1s to build the html using xsltproc
here. I believe you can get slow builds if you don’t have the docbook
dtd installed locally. xsltproc then goes out and downloads it, which
can take some time. On Debian/Ubuntu systems having the docbook-xml
package should speed things up. You might also want docbook-xsl but
I’m not sure if that has anything to do with the speed.

I’ll try to help out with documentation where I can (silly PhD taking
all my time) :slight_smile:

-Jordan