common/epub/README.txt

   1
   2 README file for epub directory
   3 ------------------------------
   4
   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
   7   existing XML files.
   8
   9   It currently holds:
  10
  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/)
  15
  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.
  19
  20   If you want to add a book that is not currently available in this structure
  21   you just have to:
  22
  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
  26
  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
  29   its subdirectory.
  30
  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)
  34
  35
  36 NOTES
  37 ----
  38
  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.
  43
  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
  47
  48     (see http://manual.calibre-ebook.com/cli/cli-index.html)
  49
  50     For formats see http://en.wikipedia.org/wiki/Comparison_of_e-book_formats
  51
  52     If you run 'make' (without arguments) the Makefile structure will automatically
  53     build the following formats:
  54
  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
  58             Palm)
  59     - .lrf: Broadband eBooks (BBeB) format - appropiate for Sony ereaders
  60
  61     Other formats can also be built, but they are not built by default nor
  62     will be removed if generated.
  63
  64
  65 WHAT WORKS
  66 ---------
  67
  68    - Navigating the pages
  69    - Navigation to other illustrations (Random number table, map of
  70      Sommerlund, etc).
  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)
  74
  75 SUGGESED IMPROVEMENTS
  76 ---------------------
  77
  78 The following lists some improvements suggested by readers of the ebooks:
  79
  80
  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.
  85
  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.
  89
  90     Possible solution:
  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.
  94
  95  * toc.ncx is basically a table of contents, so it could contain all
  96    entries in toc.htm.
  97
  98  * More references to the content.opf's <guide> section.
  99
 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"
 109
 110
 111
 112 KNOWN ISSUES
 113 ------------
 114
 115   - There's an Action Chart limitation. You need to have a pen and paper
 116     chart along with you while you read.
 117
 118     Possible alternative: Add a frontmatter link to PDF action charts and
 119     suggest ebook readers use it.
 120
 121   - Local linking to other books does not work. Linking from one book to
 122     others should be removed.
 123
 124     NOTE: Probably to be done in the XSTL files.
 125
 126   - The titles of the illustrations sometimes span multiple lines when they
 127     could show up in one single line.
 128
 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,
 131     however).
 132
 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".
 136
 137     Note: This seems to be related to this issue posted in the mailing list:
 138
 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.
 141
 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.
 145
 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.
 149
 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."
 155
 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.
 159
 160     Alternatives to fix this:
 161      * providing a text alternate alongside the image.
 162      * split the map in two (like in the PDF files)
 163
 164   - In the Sony PRS-T1 a contributor indicates that:
 165
 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.
 171
 172     Some other problems with PRS-T1 not apparent in the ebooks as far as I
 173     could see:
 174
 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
 178       require UTF-8).
 179
 180 FIXED ISSUES
 181 -----------
 182
 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
 186     created.
 187
 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.
 192
 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.
 196
 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
 199      file's metadata.
 200
 201   - Metadata with multiple authors does not show up properly in Calibre,
 202     it is shown as a single author concatenating both names.
 203
 204     DONE: Fixed in the XSL
 205