OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

docbook-apps message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]

Subject: RE: DOCBOOK-APPS: best tool for docbook?

It's going to become a principle discussion (sorry for the long text, but I
could no longer hold my horses)... 

> -----Original Message-----
> From: Rafael 'Dido' Sevilla [mailto:sevillar@team.ph.inter.net]
> Sounds like it.  I think a lot of them haven't tried going through the
> complete list of all the elements defined in DocBook.  If they did,
> they might notice that DocBook is NOT a formatting markup language!

Well, this is true, but it's just a half of the publishing reality.
Unfortunately there seems not to be any expert system which is able to
assign a reasonable and really well-looking layout to these
non-layout-oriented markups, in particular for a "high-end" print backend

This has some severe impacts in practice:

* You either have a lot of manual work after each generation of a backend
format (e.g. eliminating orphan lines or words, modifying the page or line
breaks etc.), or you must adapt your DocBook customization layer in a way
which allows to insert layout-driven commands/attributes for avoiding this
job. (I should add, that - in my experience - a document usually is
generated more than once, due to some small changes or errors found after
the "final" generation)
For example I recently added a feature to our graphic tag (we are using an
older DocBook version) which allows to distinguish between printed output
and online output, because most graphics (apart from Screenshots) require a
different resolution on the two outputs (or they are ugly on printed output
or huge in an HTML browser). 

* Unless you are not interested in a more demanding ("chic") layout (I'd
expect that most commercial companies will require such a layout), you will
have to adapt the stylesheets (maybe even the DTD) in a more or less high
amount, for the more if you want to have an individual layout.

* For keeping the resulting efforts limited, you will have to reduce the
markup tags used in your documents to an absolute minimum; otherwise your
stylesheets (PDF, HTML, HTMLhelp, WinHelp, whatever) grow so complex due to
various combinations of tags that you can no longer handle them (unless you
have a development department for your documentation). 
Moreover your (or at least my) authors are going to kill you if too many
tags are available because they loose track of the tags. Even worse, there
are situations where it is hard to decide which tag to use. If a file is
also a command, you may use either use <command> or <filename>, and have to
decide it each time - which interrupts your writing flow each time. If you
mix the tags (because one time the semantic requires <filename>, but five
words later it requires <command> for the same word) it might look horribly

* In addition, we should not forget that probably none of the processing
engines available for DocBook documents are free of bugs, which complicates
the matter by far. 
We use jade for generating PDFs via RTF (plus HTML, HTMLhelp). For providing
a satisfying layout, I had to build a quite complex system of Perl scripts
and DSSSL stylesheet to surround all those bugs in either jade or the RTF
specification (or Word...). And I suppose there is no difference with other

In fact, you cannot (_cannot_, MUST NOT) ignore the layout when writing any
documentation, although this idea seems to be so impressive on the first
glance. We are not writing for machines, but for human readers, which have
certain - partially layout-driven (!) - principles how to read and how to
understand the things they are reading (simply a word hyphenated at the
wrong point is irritating and stops your reading flow). 
How can you wish to ignore the layout in this context ?! (not even talking
about sympathy and confidence which can be generated, confirmed, but also be
destroyed by a layout).

This is the reason why _I_ would prefer to have a good editor which provides
at least the most critical output view, the view of the printed output, in
WYSIWYG. And I believe that most "common" author's will agree here. Even
worse, I got the impression that people, who prefer the tag-oriented
editors, indeed tend to ignore the layout, somtimes leading to horrible
results, which would let me doubt whether I bought the right product...

> There are only a few elements in DocBook that actually directly
> control the formatting of the output...only one I can think of off the
> top of my head is <emphasis/>.  

Hu?? I don't regard <emphasis> as a formatting tag, as it serves to
_emphasize_ an expression. However, I think there should be two "emphasis"
tags, one for spoken emphasis (which usually is set as italic) and another
one for an optical emphasis (usually called "highlight" and set in
boldface). There is a significant semantic difference.

> Contrast this with XSL-FO and HTML,
> where you have lots and lots of elements that do control formatting,

I don't know XSL-FO, but most tags in early HTML, in fact, were semantical
tags, not format tags (apart from some inline tags, such as <b> and <i>).
The format tags and the stylesheets were added, because the formatting
results did not match the requirements (see above...)

To avoid misunderstanding: I do not doubt that SGML/XML and separating
contents and layout are powerful concepts, and I do not intend to switch
back to purely layout driven concepts (however, in FrameMaker and even in
Word you can (and should) realize stylesheets with semantic-oriented formats
instead of layout-oriented formats, as well). But I believe, at least for
commercial documentation applications, the whole concept needs further
improvement for coming to better, reader-oriented results which do not
require too specialised authors. And I think this can be achieved only if we
allow more layout orientation in the SGML/XML elements themselves (for
allowing a layout optimization) and - in particular - in the editors.

Kind regards 
Ekbert Mertens

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]

Powered by eList eXpress LLC