Conceptual Questions and Customizations Regarding EPUB2 Stylesheets

[Thomas Schraitle <tom_schr@web.de>]

Hi,

currently, I'm trying to understand some design decisions around the
EPUB2 stylesheets:

1. base.dir

   HTML files are generated relative to "base.dir", but the OEBPS and
   META-INF directories are _not_ created relative to "base.dir" but
   rather relative to the current working directory (if using the
   default). The paths have to explicitly be specified with
   "epub.oebps.dir" and "epub.metainf.dir". This behaviour is
   unexpected and does not make sense.

   Solution:
   Paths specified with "epub.oebps.dir" and "epub.metainf.dir" should
   be treated as being relative to "base.dir":

   Wrong (current behavior):
   base.dir         /tmp/my_epub
   epub.oebps.dir   /tmp/my_epub/OEBPS
   epub.metainf.dir /tmp/my_epub/META-INF

   Correct (expected behavior):
   base.dir         /tmp/my_epub
   epub.oebps.dir   OEBPS             (=> /tmp/my_epub/OEBPS)
   epub.metainf.dir META-INF          (=> /tmp/my_epub/META-INF)

   Furthermore, if you set "epub.oebps.dir" to an absolute path, this
   path will be used as a value for <rootfile full-path="PATH"> element
   in META-INF/container.xml, creating an invalid EPUB archive.


2. No admonition graphics

   see
   https://sourceforge.net/tracker/?func=detail&aid=2849681&group_id=21935&atid=373747


3. Complicated zip file generation (manifest wanted) 

   The easiest way to create the EPUB zip-file would be to write a
   zip-readable manifest file. The stylesheets already "know" the
   complete filelist - it is written to OEBPS/content.opf anyway.
   Writing a manifest file (when "generate.manifest" is set to 1) to
   use with zip is much more effective than parsing content.opf or
   trying to determine which files to put into the archive by other
   means.

   Such a manifest would also help to solve a problem with the
   callout-graphics. Callout-graphics are _only_ listed in
   OEBPS/content.opf if they are referenced in the HTML (that is, of
   the profiled XML contains <co> or <calloutlist> elements and
   callout.graphics is set to 1). If the XML sources do not contain
   <co>/<calloutlist> they are not referenced in  OEBPS/content.opf.
   The EPUB zip file must only contain files that are referenced in
   OEBPS/content.opf, otherwise it will not validate.
   As a consequence, a check for callouts need to be performed before
   creating the zip archive. In addition to this,
   callout.graphics.number.limit and callout.graphics.extension need to
   be checked as well in order to get a list with the needed callout
   graphics. (The ruby script to generate the EPUBs does all this).
   
   The same would apply to admonition graphics if they would be
   supported by the EPUB stylesheets.

   This creates a massive overhead for the EPUB post processing step
   (aka copying the files and creating the archive) which could totally
   be avoided by creating a manifest.


4. Modularisation
   Probably a minor issue, but a stylesheet with more than 1700 lines
   should be split into separate files. :)


5. xsl:element vs. literal 
   
   Maybe this is a matter of taste, but the EPUB2 stylesheet 
   contains sometimes a lot of verbose structures, for example:
     <xsl:element  namespace="http://www.idpf.org/2007/opf";
                   name="package">
   This could be expressed more compact as:
     <package xmlns="http://www.idpf.org/2007/opf";>
   Is there a reason why to use xsl:element instead of the literal
   element?


What do you think?



-- 
Gruß/Regards,
    Thomas Schraitle