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

["John W. Shipman" <john@nmt.edu>]

On 09/11/2015 12:56 PM, Katie Welles wrote:
+--
| 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!
+--

I've been using DocBook as a vehicle for literate programming
for well over ten years now.  Here are several dozen examples
including one suite that contains roughly 50k lines of Python:

    http://www.nmt.edu/~shipman/soft/litprog/

Here's my stylesheet customization layer, also a literate program:

    http://www.nmt.edu/~shipman/doc/doc5style/

There is a reason for having both PDF and HTML output that I
rarely see mentioned.

When I read documentation for a tool I want to use, I want to be
sure that I've read or at least skimmed the complete
documentation.  Too often in my novice days I would read a
little, try to use the tool, and find out later that features
discussed in one of the parts I skipped could have made life much
easier.

A chunked HTML rendering is very convenient, but sometimes when
I'm clicking around a heavily cross-linked structure, I have to
wonder if I've seen all the content, especially if the HTML does
not provide a table of contents.  With a PDF, I can read (or
skim) the whole thing sequentially and be confident that I didn't
miss anything.

I am extremely grateful to the people who built DocBook, and
most especially to Norman Walsh who build the modular stylesheets,
and the indispensable Bob Stayton without whom I could never have
built a presentable style.

Happy documenting,
John Shipman (john@nmt.edu), Adjunct Professor of Computer Science
Cramer 212, New Mexico Tech, Socorro, NM 87801 (505)249-3839