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<tgroupin the xml files in~/gradle/subprojects/docs/src/docs/userguide. Otherwise, you will encounter the errorError: CALS tables must specify the number of columns. You can search the xml file using<tgroup>andcols="3"orcols="4".grep -R '<tgroup' ~/gradle/subprojects/docs/src/docs/userguide - You need to make build
docs:userguidefirst. Because the document has a lot of sample codes, they are only added when you do a build. If you useuserguide.xmlingradle/subprojects/docs/src/docs/userguide/userguid.xml, you won’t see the sample codes in the ebook. - After
xlstproc, just runzip -r -X ../gradle-user-guide.epub mimetype META-INF OEBPSinebook. - If you want
.mobifor Kindle, convert the epub file in Calibre.