Wednesday, May 18, 2016

How to create .epub and .mobi version of Gradle User Guide?

Gradle User Guide is written using docbook, and gradle build already have single HTML and pdf built. But I really want to load it into my kindle. Because docbook supports converting docbook to epub and epub3, I want to build it by myself.
You need to install docbook-xsl. On cygwin, I installed 1.77.1-1
$ cygcheck -c | grep docbook
build-docbook-catalog        1.5-2              OK
docbook-xsl                  1.77.1-1           OK

$ cygcheck -l docbook-xsl | grep epub
/usr/share/sgml/docbook/xsl-stylesheets/epub/bin/dbtoepub
/usr/share/sgml/docbook/xsl-stylesheets/epub/bin/lib/docbook.rb
/usr/share/sgml/docbook/xsl-stylesheets/epub/bin/xslt/obfuscate.xsl
/usr/share/sgml/docbook/xsl-stylesheets/epub/docbook.xsl
/usr/share/sgml/docbook/xsl-stylesheets/epub/README
/usr/share/sgml/docbook/xsl-stylesheets/epub3/chunk.xsl
/usr/share/sgml/docbook/xsl-stylesheets/epub3/chunkfast.xsl
/usr/share/sgml/docbook/xsl-stylesheets/epub3/docbook-epub.css.xml
/usr/share/sgml/docbook/xsl-stylesheets/epub3/docbook.xsl
/usr/share/sgml/docbook/xsl-stylesheets/epub3/epub3-chunk-mods.xsl
/usr/share/sgml/docbook/xsl-stylesheets/epub3/epub3-element-mods.xsl
/usr/share/sgml/docbook/xsl-stylesheets/epub3/profile-chunk.xsl
/usr/share/sgml/docbook/xsl-stylesheets/epub3/profile-docbook.xsl
/usr/share/sgml/docbook/xsl-stylesheets/epub3/README
/usr/share/sgml/docbook/xsl-stylesheets/epub3/titlepage.templates.xml
/usr/share/sgml/docbook/xsl-stylesheets/epub3/titlepage.templates.xsl
You’d better to read epub3/README, which describes the steps how to build a epub eBook from docbook. The command looks like this:
 xsltproc --stringparam base.dir ebook/OEBPS/ --xinclude /usr/share/sgml/docbook/xsl-stylesheets/epub3/chunk.xsl ../gradle/subprojects/docs/build/src/userguide.xml
One thing you need to pay more attention, you must have the last slash of ebook/OEBPS/. The above command will generate mimetype and META-INF in the directory ebook.
$ ls ebook
META-INF/  mimetype  OEBPS/
If you don’t append “/“, the command will create a directory ebook/OEBPS..
To build Gradle User Guide using docbook to epub, you need to do as follows:
  • You need to add cols="?" to <tgroup in the xml files in ~/gradle/subprojects/docs/src/docs/userguide. Otherwise, you will encounter the error Error: CALS tables must specify the number of columns. You can search the xml file using <tgroup> and cols="3" or cols="4".
    grep -R '<tgroup' ~/gradle/subprojects/docs/src/docs/userguide
    
  • You need to make build docs:userguide first. Because the document has a lot of sample codes, they are only added when you do a build. If you use userguide.xml in gradle/subprojects/docs/src/docs/userguide/userguid.xml, you won’t see the sample codes in the ebook.
  • After xlstproc, just run zip -r -X ../gradle-user-guide.epub mimetype META-INF OEBPS in ebook.
  • If you want .mobi for Kindle, convert the epub file in Calibre.

1 comment:

  1. I only work with MS Windows. Could you send an .epub or .mobi format of Gradle User Guide to me? TIA. My email:jrlin.kaohsiung@gmail.com

    ReplyDelete