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

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:


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


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

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

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