Re: epub init file, and questions

[Patrice Dumas]

On Sat, Dec 25, 2021 at 09:42:57AM -0800, Per Bothner wrote:
> 
> > * is it better to have split or non split files for epub?
> 
> Is there any reason not to treat this like html output?
> I.e. honor the --split and --no-split options in the same way?

It works that way, my question was more for the choice of the default.
Right now the default is split by node, but it is not clear that it is
the best as a default for epub.

> > * I did not output any header, so no mini_toc nor node
> >    directions.  Also no horizontal rules.  Is it how it should be?
> 
> Those seems reasonable.  An e-reader can supply extra mini-tocs or
> lines, or adding using stylesheet (or JavaScript).  Of course that also 
> applies
> to web documentation, too, so perhaps such things should be optional
> for html, too.

It is definitively not optionnal for HTML.  calibre supplies a table of
contents which is not there in the default case, but easy to make
appear, but I haven't seen any way to add a mini toc or anything else.

> > * should the navigation nav category TOC be used as a table of contents?
> >    I do not think so since it uses <ol> which looks strange.
> 
> That can be fixed with styling.  I'm not very concerned about how things
> look without css, as long as it's not too horrible.

Note that the navigation nav category TOC is quite constrained/specified
in the standard, see
 https://www.w3.org/publishing/epub3/epub-packages.html#sec-package-nav
I guess there could be CSS, though.  If it seems better to use that file
than a TOC as usually generated in the HTML code, someone (not me...)
would have to come up with the CSS that should be used.

> > * how are indices handled in epub?
> > * how are cross manual references handled in epub?
> > * how are list of tables/floats handled in epub?
> 
> Until we find a reason not to, just do like you would for web pages.

For cross manual references, there is no reason why it would work, I did
not fully test, but there does not seem to be a way to refer to another
epub book, for instance installed alongside, as far as I can tell.
calibre creates a link to an internal sandox for for external manuals,
but I do not know how it is supposed to work.

For list of tables, indices, it looks basically ok as web pages.

However, if cross manual links do not work, indices and list of floats
are not well integrated, it cannot really be a replacement for Info for
instance.

> I tend to think of the js-info interface as a simple but functional
> e-reader.  It seems useful and reasonable to include info.js in
> an epub document.  You should be able to unzip an epub (or use a web server
> that does so on-the-fly); if you then browse to the top page, you
> should get an experience more-or-less the same as browsing plain html,
> including using info.js if that was included.

It is indeed well documented in the EPUB specification that it is what
is intended.  However, my very little experience with calibre made me
unset COPIABLE_ANCHORS as it lead to a suboptimal result.  It is not
clear to me that something more complex will be handled better.

That being said, there is an interface for info.js with INFO_JS_DIR, so
it would make sense to include that in the epub when INFO_JS_DIR is set,
I'll have a try.

-- 
Pat