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

[Warren Block <wblock@wonkity.com>]

On Sun, 13 Sep 2015, Gerard Nicol wrote:

> Tom,
>
> 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.