README file for epub directory ------------------------------ This directory holds the scripts and programs used to build e-books of the books released by Project Aon. The build is automatic and based on the existing XML files. It currently holds: - build-epubs.sh: A shell script that runs a build of all of the books. The result of the build is a number of e-books in epub format which will be available once the script finishes in the English directory for ePubs (this directory is available at ../../en/epub/) - Makefile: a makefile file to build the ebooks (in all available formats) in the existing subdirectories. It will build the ePub files required and copy them to the appropiate subdirectory. If you want to add a book that is not currently available in this structure you just have to: - Create a sub-directory with the book code - Copy into this sub-directory the Makefile.basic file, rename it 'Makefile' and adjust its contents (book name, series) as required Once the structure is created you can either do a full build by running 'make' in the main directory or do a build of a book by running 'make' in its subdirectory. You can also generate the formats only for one language: 'make all-english' will run the generation of only the english books (Lone Wolf series, Grey Star series and Freeway Warriors) NOTES ---- - Conversion is done first using the Project's gbtoepub.pl script (which uses XALAN to transform the XML file using an XLST) and then several other programs to generate the final output which includes dbtoepub and Calibre's command-line interface. Once the ePub basic file is generated, all other e-books are converted from the 'standard' the ePub format into other common formats (such as .mobi or .pdb) using Calibre's 'ebook-convert' tool (see http://manual.calibre-ebook.com/cli/cli-index.html) For formats see http://en.wikipedia.org/wiki/Comparison_of_e-book_formats If you run 'make' (without arguments) the Makefile structure will automatically build the following formats: - .epub: ePub format - appropiate for most electronic Readers - .mobi: Mobipocket format - appropiate for the Kindle - .pdb: eReader / Palm Media format - appropiate for some PDAs (including Palm) - .lrf: Broadband eBooks (BBeB) format - appropiate for Sony ereaders Other formats can also be built, but they are not built by default nor will be removed if generated. WHAT WORKS --------- - Navigating the pages - Navigation to other illustrations (Random number table, map of Sommerlund, etc). - Zoom feature (in Kindle, maybe not in other readers) - Links outside the book (such as the frontmatter note about the errata asking anyone to contact Project Aon) SUGGESED IMPROVEMENTS --------------------- The following lists some improvements suggested by readers of the ebooks: * Improve navigation as it is sometimes a little unclear. Because page length and font size are variable with device settings, many sections wrap to a second page. In some sections the page might split between section choices. Readers might not detect that there are additional choices. There should be some kind of indicator to show the end of section pages. Otherwise there might be a page break and only way to be sure is to turn to the next page. Possible solution: - add an 'end of section' marker of some kind. - Maybe consider using a "Table of Contents" link similar to the one on the HTML book pages on the web site. * toc.ncx is basically a table of contents, so it could contain all entries in toc.htm. * More references to the content.opf's section. tags aren't clickable even if enclosed in . * ISO-8859-1 doesn't seem to be supported at all (I'm not sure if EPUBs require UTF-8). FIXED ISSUES ----------- - A cover is not provided. Some readers (Calibre) just pick an image at random do display as a cover. A generic 'all text title page' cover. (Name, series, author, illustrator, ProjAon note.. etc) should be created. DONE: Implemented through changes in the XSLT and also by generating a cover page JPEG through Imagemagick. In addition, if the project provides a "nice" cover page with a given illustration in the common/ subdirectory this will be used instead. - There is some metadata missing. The ebooks have the "Title" and "Language" set but are lacking "Author" and "Series" so sorting in an ebook manager is somewhat limited. DONE: Sources modified and the information is also extracted by the script that generated the ePub in order to set this in the file's metadata. - Metadata with multiple authors does not show up properly in Calibre, it is shown as a single author concatenating both names. DONE: Fixed in the XSL