[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... K. --------------------------- On Sep 13, 2015, at 6:36 AM, Gerard Nicol <gerard.nicol@gazillabyte.com> 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 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? Gerard -----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 Shouldn't be too difficult. ;) I'd happily pay a few thousand a year for a subscription to a hosted 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 * https://www.suse.com/documentation/sles-12/pdfdoc/book_sle_admin/book_sle_admin.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 -- Gruß/Regards 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]