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

Gerard's points 1 and 2 are quite valid.

Setting up my DocBook toolchain was quite the graduate course in frustration. I wrote up notes about how I set it up here: http://www.millermattson.com/blog/docbook-toolchain/, mostly so I could do it again years later after forgetting! 

And my client wanted quite a few customizations, so I had to delve very deeply into the XSLT which is an intricate tapestry of spaghetti. I ended up with a pretty intense customization chain, but even then, there were some nits I was never quite able to figure out. If I can find those notes I’ll post those on my blog, too.

I still say that the power of DocBook is not in its ability to create documents, but in its ability to output a document **and** HTML from the same source. But when 
i worked with it, we only generated HTML. And for all the monumental hassle of dealing with the toolchain + tortuously laboring in the XSLT, to just get a simple HTML site at the end was sad: I could have created something so much nicer in just straight HTML +CSS!

I've seen some pretty nice documents in this thread, but not so many HTML-plus-PDF pairs of documents (although I have yet to sit down and look at all the responses to this thread yet).  I think a nice looking document is fine — but it is a nice-looking document **paired with** navigable HTML is the real win.

The HSA Foundation specs, PDF and HTML, were output from a single data source.  http://www.hsafoundation.com/html/HSA_Library.htm   We used Madcap Flare for this project, which is a fantastic tool with a price tag and learning curve which IMHO removes it from consideration outside of the corporate setting. So I’m still looking… and I’m not sure DocBook will cure this ill...


On Sep 13, 2015, at 6:36 AM, Gerard Nicol <gerard.nicol@gazillabyte.com> 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 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.

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.

There clearly was, and still remains a need for Docbook. If you are supporting a technical project, the language itself meets most, if not all of your requirements outside the box.

But when I see the examples that have been provided as a result of the original question, I see documents that range from amazing to pretty ordinary. This not only shows the strength of the platform, but also the weakness.

As a Docbook user, and advocate, the amazing documents antagonize me the most, because I'm not sure I have the time and the will to understand how they were created.

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?

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.

Is Docbook really that obscure?


-----Original Message-----
From: Thomas Schraitle [mailto:tom_schr@web.de]
Sent: Sunday, September 13, 2015 5:39 AM
To: docbook-apps@lists.oasis-open.org
Subject: Re: [docbook-apps] Show off what you've done with Docbook

Hi Gerhard,

Am Samstag, 12. September 2015, 11:35:11 schrieb Gerard Nicol:
I'm surprised nobody has put together a Linux VM image with Git and
Docbook etc.

Shouldn't be too difficult. ;)

I'd happily pay a few thousand a year for a subscription to a hosted
or packaged Docbook environment if the results looked as good as some
of the better examples provided.

You can look at some of our examples which we created by our DAPS toolchain, here PDF:

* http://opensuse.github.io/daps/doc/pdf/art.daps.quick_color_en.pdf

Of course, it is a customization layer on top of the original DocBook XSL
stylesheets. :-) Meanwhile they are quite complicated now.

The stylesheets are released in GitHub: https://github.com/openSUSE/suse-xsl

 Thomas Schraitle

To unsubscribe, e-mail: docbook-apps-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: docbook-apps-help@lists.oasis-open.org

To unsubscribe, e-mail: docbook-apps-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: docbook-apps-help@lists.oasis-open.org

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