Suggestion: an option to split the XHTML files at a lower heading level

[programandala-net]

I'm finishing the manual of a software project of mine. The Asciidoctor source is built automatically by combining several documents of the project, including parts of the README, with a lot of information extracted from the source code, and marking the cross references during the process. Then the resulting Asciidoctor document is converted into EPUB, PDF and other formats.

The result is great, except one problem with the EPUB format: one of the chapters is a huge glossary (with subchapters for the initials), which becomes a 2-MiB XHTML file in the EPUB. This makes the document too slow to open and navigate.

I suggest an option to force the splitting of the contents into XHTML files at a certain heading level, equivalent to Pandoc's --epub-chapter-level.

[slonopotamus]

@programandala-net Great suggestion! I've just implemented this in #328. Would you like to review or test it before it gets merged into master?

[programandala-net]

I've just implemented this in #328. Would you like to review or test it before it gets merged into `master`?

Not necessary. I'l try the new feature as soon as it's merged. Thank you.

…

-- Marcos Cruz http://programandala.net

[slonopotamus]

Aaaaand... It's in the master!

[programandala-net]

Thank you. It works fine, now the glossary can be splitted into XHTML by subchapters. But its cross references don't work anymore because the target file is not included in the XHTML link, only the id. Unless you can guess the reason out of the recent code changes, I will do some tests with sample files and different values of `epub-chapter-level` in order to isolate the problem conditions.

…

-- Marcos Cruz http://programandala.net

[slonopotamus]

Could you provide a minimal asciidoctor file that reproduces the problem please?

[slonopotamus]

I found (and fixed) a bug in TOC when epub-chapter-level is > 1, but from what you said I guess you have a different issue.

[programandala-net]

I found (and fixed) a bug in TOC when epub-chapter-level is > 1, but from what you said I guess you have a different issue.

Thanks. Yes, probably it's different. But maybe it's related to another issue I was investigating: Calibre displayed (in its own contents tree dialog) the subchapters of my glossary twice: in its chapter and oustide, as independent chapters. I will test if your recent fix changes that. Sorry I had little time to finish isolate the error conditions into simple small files. I will post them as soon as possible.

…

-- Marcos Cruz http://programandala.net

[slonopotamus]

the subchapters of my glossary twice: in its chapter and outside, as independent chapters

Yeah, that's exactly what I fixed.

[slonopotamus]

@programandala-net ping?

[programandala-net]

@programandala-net ping?

I didn't forget this issue, but didn't had much time for it these days. I've tried to reproduce the cross references bug in small simplified versions of the original source, but somehow the XHTML splitting does not work in those small versions. I'm investigating the problem.

…

-- Marcos Cruz http://programandala.net

[programandala-net]

I have found the reason the XHTML splitting didn't work in my test files: :doctype: book was missing. Is this intended? I think I have read somewhere that "book" was always assumed in the EPUB conversion.

[slonopotamus]

Currently, yes:

When doctype attribute is set to book, each top-level section will become a separate ebook "chapter" file. This includes preface, bibliography, appendix, etc.

Otherwise, whole document is converted to a single ebook chapter.

So, currently epub-chapter-level changes at what level chapter splitting should happen (and it cannot be < 1) while doctype determines whether splitting is done at all.

Default doctype is article. Articles do not normally have chapters, don't they?

Technically, we could change the logic between doctype/epub-chapter-level and say that article defaults to epub-chapter-level=0 while book defaults to epub-chapter-level=1.

[programandala-net]

I see. I was confused. The current behaviour makes sense.

It seems epub-chapter-level=0 is currently ignored? The result is identical to epub-chapter-level=1, and no warning is displayed.

[programandala-net]

Here you are the test files, with epub-chapter-level values 1..3. Links pointing outside their final XHTML file don't work. This didn't happen before this attribute was implemented: links worked between chapters. Beside, when epub-chapter-level=3, something else fails (Calibre displays error messages, and fbreader displays blank pages).
cross_references_with_epub-chapter-level_test_files.zip

[slonopotamus]

Hmm... You're using inline anchors inside section titles. Is it valid at all?

Sections are normally given anchors via syntax like:

[#anchor]
== Section title

or

[[anchor]]
== Section title

[programandala-net]

Yes, it's valid according to the examples included in the manual, and it always worked before as I said.

[programandala-net]

I've moved the anchors outside the titles. Now the links work, but the subchapters are repeated in the TOC displayed by Calibre, except when epub-chapter-level=1. Please find the modified versions attached.

There's another difference: no warning about missing target ids is displayed anymore. This is a problem that already happened before epub-chapter-level was implemented. Therefore the warnings are caused by the inline anchor syntax, even if it works.
cross_references_with_epub-chapter-level_and_anchors_outside_titles_test_files.zip

[slonopotamus]

There's another difference: no warning about missing target ids is displayed anymore. This is a problem that already happened before epub-chapter-level was implemented. Therefore the warnings are caused by the inline anchor syntax, even if it works.

I'll split this into a separate issue. We are not currently able to properly handle inline anchors in section titles, that's why you see a warning. Unfortunately, it needs some fixes to asciidoctor core, so in nearest future just try to avoid inline anchors in section titles.

UPDATE: #331

[slonopotamus]

I've moved the anchors outside the titles. Now the links work, but the subchapters are repeated in the TOC displayed by Calibre, except when epub-chapter-level=1. Please find the modified versions attached.

I think you're using asciidoctor-epub without commit 861afde. I do not observe duplicate TOC entries on your test documents if using latest master branch.

[programandala-net]

I'll split this into a separate issue. We are not currently able to properly handle inline anchors in section titles, that's why you see a warning. Unfortunately, it needs some fixes to asciidoctor core, so in nearest future just try to avoid inline anchors in section titles.

UPDATE: #331

OK. I used the inline syntax because I needed two different anchors per glossary entry, in order to manage the homonyms. Example:

=== a

[#entry61-src-lib-assembler-fs]
==== [[entry61]]a
(...)

[#entry61-src-lib-memory-address_register-fs]
==== a
(...)

I will think an alternative.

[programandala-net]

I think you're using asciidoctor-epub without commit 861afde. I do not observe duplicate TOC entries on your test documents if using latest master branch.

You're right. Sorry. My local repository was updated indeed, but somehow something went wrong in my latest building and I didn't noticed. Now the TOCs are right.

[slonopotamus]

alpha-16 was just released, with this feature included.