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

[Warren Block <wblock@wonkity.com>]

On Fri, 11 Sep 2015, Katie Welles wrote:

> It’s been a while since I’ve used Docbook or participated in this forum.
>
> I used Docbook a number of years ago to put together a web-based API reference system. To be frank, I found it to be a pretty painful project, but mainly because I thought it was downright foolish to jump through all those Docbook hoops just to output simple HTML. It seems to me that the power of Docbook is when your single XML source is used for multiple outputs.
>
> I support a consortium that manages 12+ open APIs, and we’ve been re-examining the tools we use to output published specs. We know we want **all** our API specs to be available as PDF and also HTML, but are not sure which tool to bank on. So far we’ve been looking at asciidoc, which I find pretty underwhelming.
>
> Have any of you PDF + HTML output with Docbook? If anyone has such a project and will be willing to show it off, send some URLs!

We use it for most of the FreeBSD documentation:
https://www.freebsd.org/docs/books.html

The FreeBSD Handbook is the most famous:
https://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/

The Porter's Handbook is also a full book:
https://www.freebsd.org/doc/en_US.ISO8859-1/books/porters-handbook/index.html

We also have a book for people contributing to the documentation:
https://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/index.html

DocBook, XSLT, and Fop are used to generate HTML, PDF, plain text, 
PostScript, RTF, and some compressed versions of those.

> As an aside: Have any of you used asciidoc?

I use AsciiDoc for my own articles:
http://www.wonkity.com/~wblock/docs/

The PXE article is fairly in-depth.

For me, DocBook is powerful but a pain to write.  AsciiDoc is simple to 
write, but does not have the semantic markup power of DocBook.