OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

docbook message

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

Subject: Re: [docbook] Toolchain for beginner?

If you need line numbers in programlistings, you should probably use Saxon. There is some help in this chapter of my online book for setting up Saxon and the extensions:


See the sections title "Installing Saxon" and "Using Saxon"

Bob Stayton
Sagehill Enterprises

From: "Bob Plantz" <rgplantz@outlook.com>
Sent: Tuesday, April 09, 2013 12:01 PM
To: <docbook@lists.oasis-open.org>
Subject: [docbook] Toolchain for beginner?

I hope this is the proper list for my questions.

I am almost there but cannot seem to get a good toolchain for writing a programming book with docbook. I have written, and self-published (lulu.com), a 568-page programming book using LaTeX, so I'm comfortable with markup languages, etc.

My requirements (desires) are to produce three versions: online (html), ereader (epub), and paperback (pdf). I learned from my current book that LaTeX does not have a reasonable path to html (and thus, not to epub).

Another important point is that I want to be able to include external files (that contain code) when processing the text. I like being able to test each program that I include in my book. Copy and paste leads to errors, and I dislike books that have programs that don't work.

I prefer doing this on my Ubuntu 12.10 but am willing to do it on my Windows 8 installation. This book will be free or very low cost, so I do not want to buy commercial software to write it. (I own a copy of MS Word, but previous experience suggests it is useless for this application.)

Since I'm new to docbook, my take is that I should start with 5.0.

I have gotten xsltproc to do what I want, except that it does not allow me to use linenumbering with my code listings. This version of Ubuntu installs libxslt 10126. Perhaps I need the latest version?

Saxon and Xalan both give me error messages. Sorry, I forget what they were. I uninstalled them, thinking that I probably installed the wrong versions. For example, I just ran across (http://www.microhowto.info/howto/process_an_xml_document_using_an_xslt_stylesheet.html) that seems to indicate I should install Saxon-B.

I have also done some preliminary work with Pandoc, which seems to do what I want so far. But it's simplicity causes me to worry that it will be limiting down the road. I also believe that docbook's use of xml makes more sense, at least in the long run.

I feel like I'm very close, but I'm stuck. Most of the documentation that I have found is out of date or incomplete (for a beginner). For example, everything I've found on 5.0 assumes that I am familiar with 4.x. It doesn't seem to make sense that I should set everything up for 4.x, learn how to use that, and then convert to 5.0.

So I wonder if anybody can point a beginner like me to a good source for helping me to get going on actually writing a book. As when I learned LaTeX, I'm sure there will be many learning experiences as I write. But I would like to avoid taking too many dead end paths.


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

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