Re: [docbook-apps] EPUB3: how to use base.dir ?

[Thomas Schraitle <tom_schr@web.de>]

Hi Bob,

thanks for your answer.

On Tue, 9 Apr 2013 09:28:09 -0700
"Bob Stayton" <bobs@sagehill.net> wrote:
>
> Try setting base.dir to "foo/OEBPS/".  That will put META-INF,
> mimetype, and OEBPS in foo/, which is what I think you want.

Yes, that works. :)


> As you know, the stylesheets write HTML output to $base.dir.  The
> default setting for base.dir in epub3 is "OEBPS/".  For the other
> epub files that are not in the HTML output directory, they are
> written relative to base.dir. That's how it was done in the Epub2
> stylesheet, and the Epub3 stylesheet maintained it for backward
> compatibility.

In that case, I think the behaviour of both is highly unfortunate. 

Usually, if a user defines a base directory, you normally don't expect
that a stylesheet writes to its parent(!) directory. As you probably
know, this is what a user gets:

  Writing foo/OEBPS/.....
  Writing foo/OEBPS/package.opf for book(dblayouttest)
  Writing foo/OEBPS/../META-INF/container.xml for book(dblayouttest)
  Writing foo/OEBPS/../mimetype for book(dblayouttest)
  Generating NCX file ...

Theoretically, if a user sets base.dir to the "wrong" path, writing to
its parent directory could be forbidden due to missing permissions.

My assumption was that the filenames are built by concatenating
$base.dir with the rest. This is exactly what the HTML stylesheets do.


> This could probably have been more clearly configured by leaving the
> default base.dir empty and instead defining a new param for the OEBPS
> directory name that would be appended to base.dir. Changing it for
> the next release would break existing implementations, though, but it
> might be worth it.

Not sure if we want break backward compatibility or not. I think the
current implementation is confusing. IF we want to do that, then better
sooner than later. 

Or, maybe invent some new variable and name it epub.base.dir which
serves as "the" base directory for everything. :)


Apart from the issue with base.dir, I have some additional points:

1. Parameter vs. Variables?
The EPUB3 stylesheet contains the following parameters:

  epub.oebps.dir='OEBPS'
  epub.metainf.dir='META-INF/'
  epub.ncx.filename='toc.ncx'
  epub.mimetype.filename='mimetype'
  epub.mimetype.value='application/epub+zip'
  epub.container.filename='container.xml'
  epub.package.filename='package.opf'

If I'm not mistaken, these parameters looks like constants. Isn't it
better to define them as variables? 

Parameters give the (wrong?) impression that they can be changed. I'm
not sure if the OEBPS directory can be named differently, but I guess
the parameters with epub.mimetype.value and epub.mimetype.filename stay
always the same. 
What does the EPUB3 spec says here?


2. Creating Manifest
Currently, the parameter generate.manifest is set to 0, deactivating
the manifest file.
I think it could be useful to have a manifest with *everything* in it
(be it images, callout and admon graphics as well as HTML files and the
EPUB3 files).

For example, such a manifest file could be used as an input file for
other tools copying callouts and admon graphics automatically etc.


Just my 2 cents... :)


-- 
Gruß/Regards,
    Thomas Schraitle