2 README file for epub directory
3 ------------------------------
5 This directory holds the scripts and programs used to build e-books of the
6 books released by Project Aon. The build is automatic and based on the
11 - build-epubs.sh: A shell script that runs a build of all of the books.
12 The result of the build is a number of e-books in epub format
13 which will be available once the script finishes in the English
14 directory for ePubs (this directory is available at ../../en/epub/)
16 - Makefile: a makefile file to build the ebooks (in all available
17 formats) in the existing subdirectories. It will build the ePub files
18 required and copy them to the appropiate subdirectory.
20 If you want to add a book that is not currently available in this structure
23 - Create a sub-directory with the book code
24 - Copy into this sub-directory the Makefile.basic file, rename it
25 'Makefile' and adjust its contents (book name, series) as required
27 Once the structure is created you can either do a full build by running
28 'make' in the main directory or do a build of a book by running 'make' in
31 You can also generate the formats only for one language: 'make all-english'
32 will run the generation of only the english books (Lone Wolf series, Grey
33 Star series and Freeway Warriors)
39 - Conversion is done first using the Project's gbtoepub.pl script
40 (which uses XALAN to transform the XML file using an XLST) and then
41 several other programs to generate the final output which includes
42 dbtoepub and Calibre's command-line interface.
44 Once the ePub basic file is generated, all other e-books are converted
45 from the 'standard' the ePub format into other common formats (such as
46 .mobi or .pdb) using Calibre's 'ebook-convert' tool
48 (see http://manual.calibre-ebook.com/cli/cli-index.html)
50 For formats see http://en.wikipedia.org/wiki/Comparison_of_e-book_formats
52 If you run 'make' (without arguments) the Makefile structure will automatically
53 build the following formats:
55 - .epub: ePub format - appropiate for most electronic Readers
56 - .mobi: Mobipocket format - appropiate for the Kindle
57 - .pdb: eReader / Palm Media format - appropiate for some PDAs (including
59 - .lrf: Broadband eBooks (BBeB) format - appropiate for Sony ereaders
61 Other formats can also be built, but they are not built by default nor
62 will be removed if generated.
68 - Navigating the pages
69 - Navigation to other illustrations (Random number table, map of
71 - Zoom feature (in Kindle, maybe not in other readers)
72 - Links outside the book (such as the frontmatter note about the errata
73 asking anyone to contact Project Aon)
78 The following lists some improvements suggested by readers of the ebooks:
81 * Improve navigation as it is sometimes a little unclear. Because page
82 length and font size are variable with device settings, many sections wrap
83 to a second page. In some sections the page might split between section
84 choices. Readers might not detect that there are additional choices.
86 There should be some kind of indicator to show the end of section
87 pages. Otherwise there might be a page break and only way to be sure
88 is to turn to the next page.
91 - add an 'end of section' marker of some kind.
92 - Maybe consider using a "Table of Contents" link similar to the one on
93 the HTML book pages on the web site.
95 * toc.ncx is basically a table of contents, so it could contain all
98 * More references to the content.opf's <guide> section.
100 <reference type="toc" title="Table of Contents" href="toc.htm"/>
101 <reference type="title-page" title="Title Page" href="title.htm"/>
102 <reference type="dedication" title="Dedication" href="dedicate.htm"/>
103 <reference type="acknowledgements" title="Acknowledgements"
104 href="acknwldg.htm"/>
105 <reference type="other.sections" title="Numbered Sections"
106 href="numbered.htm"/>
107 <reference type="text" title="Section 1" href="sect1.htm"/>
108 <reference type="loi" title="Table of Illustrations" href="illstrat.htm"
115 - There's an Action Chart limitation. You need to have a pen and paper
116 chart along with you while you read.
118 Possible alternative: Add a frontmatter link to PDF action charts and
119 suggest ebook readers use it.
121 - Local linking to other books does not work. Linking from one book to
122 others should be removed.
124 NOTE: Probably to be done in the XSTL files.
126 - The titles of the illustrations sometimes span multiple lines when they
127 could show up in one single line.
129 - The ebooks could be improved by including the official covers (we
130 currently do not hold distribution rights for covers as far as I know,
133 - Images (at least in my Android device) are not always scaled properly.
134 Although my e-reader (Fbreader) can zoom in the images some could be
135 scaled to fit better in the "page".
137 Note: This seems to be related to this issue posted in the mailing list:
139 " There seems to be an issue with viewing the images correctly on a
140 Kindle. They are not correcly aligned and are chopped at page edges, etc.
142 All images seem to be within HTML tables, probably for layout, but this
143 means that the Kindle cannot find the image size and correctly re-size the
144 image to fit it on the page.
146 I used Calibre to do a very simple conversion on the original files from
147 MOBI to MOBI with the 'linearize tables' option set. All other options I
148 left at the Calibre default settings.
150 When using the new MOBI files on my Kindle all of the images are now
151 automatically sized and centered, are not chopped at page edges, and they
152 can be zoomed to full screen using the standard Kindle function by
153 clicking on the image. I think that this is because the layout tables
154 were hiding the real image details on the Kindle."
156 - The map is too large and not scrollable some readers (reported: Sony
157 PRS-T1, Nook). Ebook readers might not allow zooming or panning of large
158 images, so the map is of limited utility.
160 Alternatives to fix this:
161 * providing a text alternate alongside the image.
162 * split the map in two (like in the PDF files)
164 - In the Sony PRS-T1 a contributor indicates that:
166 * Thin space (U+2009) is rendered as a question mark.
167 It says "The Story So Far?...?" in a few places.
168 * PNG images don't render correctly at all. There is some kind of vertical
169 banding resulting in lack of resolution and fewer shades of grey. GIF and
170 JPG work fine though.
172 Some other problems with PRS-T1 not apparent in the ebooks as far as I
175 * PRS-T1's ebook reader does not allow links for images to be followed:
176 <IMG> tags aren't clickable even if enclosed in <A>.
177 * ISO-8859-1 doesn't seem to be supported at all (I'm not sure if EPUBs
183 - A cover is not provided. Some readers (Calibre) just pick an image
184 at random do display as a cover. A generic 'all text title page' cover.
185 (Name, series, author, illustrator, ProjAon note.. etc) should be
188 DONE: Implemented through changes in the XSLT and also by generating
189 a cover page JPEG through Imagemagick. In addition, if the project
190 provides a "nice" cover page with a given illustration in the common/
191 subdirectory this will be used instead.
193 - There is some metadata missing. The ebooks have the "Title" and
194 "Language" set but are lacking "Author" and "Series" so sorting in an
195 ebook manager is somewhat limited.
197 DONE: Sources modified and the information is also extracted by the
198 script that generated the ePub in order to set this in the
201 - Metadata with multiple authors does not show up properly in Calibre,
202 it is shown as a single author concatenating both names.
204 DONE: Fixed in the XSL