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] | [List Home]

Subject: RE: [docbook-apps] Show off what you've done with Docbook

On Sun, 13 Sep 2015, Gerard Nicol wrote:


I've been giving this some thought, and what had become evident to me is that I have no problem at all with the Docbook language.

After all, you can either learn to code it by hand, or use an editor like Oxygen. Either way, you do need to know the possibilities of the language, to know the best way to mark-up your document, but that's not really a problem.

There can be a serious learning curve even just for DocBook markup. Learning just the most-used tags and how to use them is a big deal, particularly for people used to presentation-based markup languages used for wikis.

There are 2 problems that I suspect for many make the difference between using the product and not:

1. The complexity of setting up an environment: Download stylesheets, download toolchain (which includes numerous choices), create a directory structure for your own document.

FreeBSD uses a "docproj" meta-port that brings in all the tools and components. Other systems probably have similar packaging.

2. The complexity of customizing the default look of the documents, which look OK, but don't look as good as they would need to be to be put in front of a client.

That is difficult. Based on my unscientific sampling, XSL is not well-regarded. As languages go, it's rarely used and poorly understood. And then there is the separation between print and other media, which usually means also dealing with XSL-FO and Fop. Fop has its own set of problems.

The question remains unanswered, having learned the Docbook language, why should somebody then have to face a much greater challenge to produce a document that looks presentable?

It's just part of the price for the way to tool is built. That does not mean it could not be improved.

Does anybody sell a commercial Docbook customization layer? If this was Joomla, or Wordpress, or MediaWiki there would be a whole marketplace of free and commercial presentation layers.

I don't know of any, but would be interested. Maybe there is a place with downloadable DocBook "themes", or maybe it is time for that.

Is Docbook really that obscure?

It is, yes. Part of that is just that documentation is still mostly seen as an afterthought, and DocBook takes a commitment to use successfully.

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