Re: [gobo-eiffel-develop] DocBook

[Alexander K. <kw...@ah...>]

Eric Bezault wrote:

> Does anyone in this list have some experience using
> DocBook to write documentation? I suggested using
> DocBook to write the documentation of Gobo and I
> would like to know your opinion about that.

I  have some experience with DocBook and some other
issues discussed here last few days. Here are my comments:

1. DocBook

1.1. Writing

It seems to be the real way to write the documentation.
I cannot say that many products support this XML out
of the box, but there is enough tools to make the things
rolling. Even WYSIWYG can be approached to some
extent (I written a CSS that styles the DocBook document
under XMetal - XML editor).

1.2. Program code

DocBook is mostly developed to write texts rather than
code. There are some constructs that allow to write
class/feature declarations but not implementations. These
constructs are potentialy language-independent, but the
real tools support only C, C++, Java and, maybe, few
others - not Eiffel. If we talk about Norman Walsh XSLTs
it's possible to provide Eiffel rendering and ask him to
include it to the distribution.

1.3. Modularity

When I started to use XML DocBook (after using SGML
version), I tried to minimize elements/attributes I would use.
This is possible due to modular structure of the DocBook DTD.
However, that did not work. Day after day I included back
tables, cross-references, index terms, glossary elements,
footnotes, ... - almost everything DocBook gives.

The story is a little bit different with attributes. There are many
of them that I did not use. So, to simplify writing, a half of them
was excluded.

DocBook DTD allows to add elements and attributes that are not
the standard part of it. It might be possible to add Eiffel-specific
markup, but I have no actual experiance with it.

1.4. Colors

All output I've seen for DocBook documents is black-white.
I do not know whether multicolored schemes can be used for the
output.

2. HTML formatting

2.1. Problem with automatically generated HTML

The reasons of bad-looking HTML mostly deal with the
browser. The same HTML  looks very differently under
different browsers. Some of  them seem to expect
hand-written HTML. Reformating HTML to the "expected"
form improves the results. Examples of the formating
that tricks the browsers are: spaces around some elements,
elements not starting from the new line, new line inside the
element tag, "unexpected" combination of nested elements.
Fortunately, w3c provides a tool (tidy) that modifies HTML
to be in the most "expected" form. Other appoaches
like SED/AWK can be also used.

2.2. Styles

HTML can look much more attractive if it uses CSS.
The HTML output for DocBook document can include
classes for the elements, so customization via CSS becomes
a lot easier. Unfortunately, not all browsers support CSS
properly.

3. PDF output

Simple markup usually can be converted to PDF without
problems and the resulting PDF can look pretty good. When
the layout becomes complex, especially when complex tables
are used, the PDF is just unacceptable (I tried both free FOP
and commercial renderx).

Regards,
Alexander Kogtenkov
Object Tools, Moscow