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   Project Aon released books based on the existing XML files.
   7
   8   It currently holds:
   9
  10   - build-epubs.sh: A shell script that runs a build of all the books.
  11     The result of the build is a number of e-books in epub format
  12     which will be available once the script finishes in the English
  13     directory for ePubs (from this directory available at ../../en/epub/)
  14
  15   - Makefile: a makefile file to build the ebooks (in all available
  16     formats) in the existing subdirectories. It will build the ePub files
  17     required and copy them to the appropiate subdirectory.
  18
  19
  20 NOTES
  21 ----
  22
  23   - Conversion is done using Calibre's command-line interface. All ebooks are
  24     converted from the 'standard' the ePub format into other common formats
  25     (such as .mobi or .pdb)
  26
  27     (see http://manual.calibre-ebook.com/cli/cli-index.html)
  28
  29     For formats see http://en.wikipedia.org/wiki/Comparison_of_e-book_formats
  30
  31     If you run 'make' (without arguments) the Makefiles will automatically
  32     build the following formats:
  33
  34     - .epub: ePub format - appropiate for most electronic Readers
  35     - .mobi: Mobipocket format - appropiate for the Kindle
  36     - .pdb: eReader / Palm Media format - appropiate for some PDAs (including
  37             Palm)
  38     - .lrf: Broadband eBooks (BBeB) format - appropiate for Sony ereaders
  39
  40     Other formats can also be built but are not built by default nor removed
  41     if generated.
  42
  43
  44 WHAT WORKS
  45 ---------
  46
  47    - Navigating the pages
  48    - Navigation to other illustrations (Random number table, map of
  49      Sommerlund, etc).
  50    - Zoom feature (in Kindle, maybe not in other readers)
  51    - Links outside the book (such as the frontmatter note about the errata
  52      asking anyone to contact Project Aon)
  53
  54 SUGGESED IMPROVEMENTS
  55 ---------------------
  56
  57 The following lists some improvements suggested by readers of the ebooks:
  58
  59
  60  *  Improve navigation as it is sometimes a little unclear. Because page
  61     length and font size are variable with device settings, many sections wrap
  62     to a second page. In some sections the page might split between section
  63     choices.  Readers might not detect that there are additional choices.
  64
  65    There should be some kind of indicator to show the end of section
  66    pages. Otherwise there might be a page break and only way to be sure
  67    is to turn to the next page.
  68
  69     Possible solution:
  70        - add an 'end of section' marker of some kind.
  71        - Maybe consider using a "Table of Contents" link similar to the one on
  72          the HTML book pages on the web site.
  73
  74  * toc.ncx is basically a table of contents, so it could contain all
  75    entries in toc.htm.
  76
  77  * More references to the content.opf's <guide> section.
  78
  79     <reference type="toc" title="Table of Contents" href="toc.htm"/>
  80     <reference type="title-page" title="Title Page" href="title.htm"/>
  81     <reference type="dedication" title="Dedication" href="dedicate.htm"/>
  82     <reference type="acknowledgements" title="Acknowledgements"
  83 href="acknwldg.htm"/>
  84     <reference type="other.sections" title="Numbered Sections"
  85 href="numbered.htm"/>
  86     <reference type="text" title="Section 1" href="sect1.htm"/>
  87     <reference type="loi" title="Table of Illustrations" href="illstrat.htm"
  88
  89
  90
  91 KNOWN ISSUES
  92 ------------
  93
  94   - There's an Action Chart limitation. You need to have a pen and paper
  95     chart along with you while you read.
  96
  97     Possible alternative: Add a frontmatter link to PDF action charts and
  98     suggest ebook readers use it.
  99
 100   - Local linking to other books does not work. Linking from one book to
 101     others should be removed.
 102
 103     NOTE: Probably to be done in the XSTL files.
 104
 105   - The titles of the illustrations sometimes span multiple lines when they
 106     could show up in one single line.
 107
 108   - The ebooks could be improved by including the official covers (we
 109     currently do not hold distribution rights for covers as far as I know,
 110     however).
 111
 112   - Images (at least in my Android device) are not always scaled properly.
 113     Although my e-reader (Fbreader) can zoom in the images some could be
 114     scaled to fit better in the "page".
 115
 116     Note: This seems to be related to this issue posted in the mailing list:
 117
 118     " There seems to be an issue with viewing the images correctly on a
 119     Kindle. They are not correcly aligned and are chopped at page edges, etc.
 120
 121     All images seem to be within HTML tables, probably for layout, but this
 122     means that the Kindle cannot find the image size and correctly re-size the
 123     image to fit it on the page.
 124
 125     I used Calibre to do a very simple conversion on the original files from
 126     MOBI to MOBI with the 'linearize tables' option set. All other options I
 127     left at the Calibre default settings.
 128
 129     When using the new MOBI files on my Kindle all of the images are now
 130     automatically sized and centered, are not chopped at page edges, and they
 131     can be zoomed to full screen using the standard Kindle function by
 132     clicking on the image. I think that this is because the layout tables
 133     were hiding the real image details on the Kindle."
 134
 135   - The map is too large and not scrollable some readers (reported: Sony
 136     PRS-T1, Nook). Ebook readers might not allow zooming or panning of large
 137     images, so the map is of limited utility.
 138
 139     Alternatives to fix this:
 140      * providing a text alternate alongside the image.
 141      * split the map in two (like in the PDF files)
 142
 143   - In the Sony PRS-T1 a contributor indicates that:
 144
 145    * Thin space (U+2009) is rendered as a question mark.
 146       It says "The Story So Far?...?" in a few places.
 147    * PNG images don't render correctly at all. There is some kind of vertical
 148     banding resulting in lack of resolution and fewer shades of grey. GIF and
 149     JPG work fine though.
 150
 151     Some other problems with PRS-T1 not apparent in the ebooks as far as I
 152     could see:
 153
 154     * PRS-T1's ebook reader does not allow links for images to be followed:
 155       <IMG> tags aren't clickable even if enclosed in <A>.
 156     * ISO-8859-1 doesn't seem to be supported at all (I'm not sure  if EPUBs
 157       require UTF-8).
 158
 159 FIXED ISSUES
 160 -----------
 161
 162   - A cover is not provided. Some readers (Calibre) just pick an image
 163     at random do display as a cover. A generic 'all text title page' cover.
 164     (Name, series, author, illustrator, ProjAon note.. etc) should be
 165     created.
 166
 167    DONE: Implemented through changes in the XSLT and also by generating
 168     a cover page JPEG through Imagemagick. In addition, if the project
 169     provides a "nice" cover page with a given illustration in the common/
 170     subdirectory this will be used instead.
 171
 172   - There is some metadata missing. The ebooks have the "Title" and
 173     "Language" set but are lacking "Author" and "Series" so sorting in an
 174     ebook manager is somewhat limited.
 175
 176     DONE: Sources modified and the information is also extracted by the
 177      script that generated the ePub in order to set this in the
 178      file's metadata.
 179
 180   - Metadata with multiple authors does not show up properly in Calibre,
 181     it is shown as a single author concatenating both names.
 182
 183     DONE: Fixed in the XSL
 184