Invalid warnings for section titles out of sequence

[odrotbohm]

I have an Asciidoctor setup producing HTML, EPUB3 and PDF output via Maven. Both HTML and PDF work flawlessly. However, the EPUB3 output spits out warnings about allegedly out of sequence section titles:

[INFO] --- asciidoctor-maven-plugin:1.5.3:process-asciidoc (html) @ spring-data-commons ---
[INFO] Rendered /Users/olivergierke/Documents/workspace/spring-data-commons/src/main/asciidoc/index.adoc
[INFO] 
[INFO] --- asciidoctor-maven-plugin:1.5.3:process-asciidoc (epub) @ spring-data-commons ---
asciidoctor: WARNING: dependencies.adoc: line 49: section title out of sequence: expected level 1, got level 2
asciidoctor: WARNING: dependencies.adoc: line 54: section title out of sequence: expected level 1, got level 2
asciidoctor: WARNING: repositories.adoc: line 16: section title out of sequence: expected level 1, got level 2
asciidoctor: WARNING: repositories.adoc: line 104: section title out of sequence: expected level 1, got level 2
asciidoctor: WARNING: repositories.adoc: line 181: section title out of sequence: expected level 1, got level 2
asciidoctor: WARNING: repositories.adoc: line 215: section title out of sequence: expected level 1, got level 2
asciidoctor: WARNING: repositories.adoc: line 398: section title out of sequence: expected level 1, got level 2
asciidoctor: WARNING: repositories.adoc: line 481: section title out of sequence: expected level 1, got level 2
asciidoctor: WARNING: repositories.adoc: line 631: section title out of sequence: expected level 1, got level 2
asciidoctor: WARNING: auditing.adoc: line 5: section title out of sequence: expected level 1, got level 2
asciidoctor: ERROR: index.adoc: line 26: invalid part, must have at least one section (e.g., chapter, appendix, etc.)
asciidoctor: WARNING: repository-namespace-reference.adoc: line 6: section title out of sequence: expected level 1, got level 2
asciidoctor: WARNING: repository-populator-namespace-reference.adoc: line 6: section title out of sequence: expected level 1, got level 2
asciidoctor: WARNING: repository-query-keywords-reference.adoc: line 5: section title out of sequence: expected level 1, got level 2
asciidoctor: WARNING: repository-query-return-types-reference.adoc: line 5: section title out of sequence: expected level 1, got level 2
asciidoctor: ERROR: index.adoc: line 35: invalid part, must have at least one section (e.g., chapter, appendix, etc.)
[INFO] Rendered /Users/olivergierke/Documents/workspace/spring-data-commons/src/main/asciidoc/index.adoc
[INFO] 
[INFO] --- asciidoctor-maven-plugin:1.5.3:process-asciidoc (pdf) @ spring-data-commons ---
[INFO] Rendered /Users/olivergierke/Documents/workspace/spring-data-commons/src/main/asciidoc/index.adoc

Steps to reproduce:

1. git clone https://github.com/spring-projects/spring-data-commons
2. cd spring-data-commons
3. mvn clean generate-resources -Pdistribute

Versions in use:

• Asciidoctor Maven plugin 1.5.3
• AsciidoctorJ PDF 1.5.0-alpha.11
• AsciidoctorJ EPUB3 1.5.0-alpha.6

[mojavelinux]

This is very closely related to #47. At the moment, Asciidoctor EPUB3 enforces a very strict structure described here: https://github.com/asciidoctor/asciidoctor-epub3#declaring-the-spine. We want to lift this requirement, which is the focus of #47.

[odrotbohm]

But the document is well structured, it just uses level offsets on imports?

[mojavelinux]

The spine document cannot contain any content other than include directives. I think that is the problem. Again, I want to get rid of this restriction...that's just how it works currently.

[mojavelinux]

I'm double checking that assessment.

[odrotbohm]

Okay, thanks for clarifying.

[mojavelinux]

First, for the Preface to show correctly, you need a blank line after the = Preface line in the preface.adoc.

Second, the content in the spine document outside of includes is simply ignored. It doesn't break the converter in anyway.

Finally, the problem is that the includes must start with a level-0 section. The problem right now is that you are using leveloffset: +1, which pushes it down to level-1 section. Take this away as well as the section titles in index.adoc and it will work.

The other converters need the chapter sections to be a level-1, so this is the setting I recommend in the header of the spine document.

ifndef::ebook-format[:leveloffset: 1]

I'd probably then exclude the parts from the EPUB3 as well using:

ifndef::ebook-format[]
[[reference-documentation]]
= Reference documentation
endif::[]

or as a one-liner:

ifndef::ebook-format[= Reference documentation [[reference-documentation]]]

[mojavelinux]

Here's how it looks when I finished editing it:

= Spring Data Commons - Reference Documentation
Oliver Gierke; Thomas Darimont; Christoph Strobl; Mark Pollack; Thomas Risberg
:revnumber: {version}
:revdate: {localdate}
:toc: macro
:doctype: book
ifndef::ebook-format[:leveloffset: 1]
imagesdir: images

(C) 2008-2015 The original authors.

NOTE: Copies of this document may be made for your own use and for distribution to others, provided that you do not charge any fee for such copies and further provided that each copy contains this Copyright Notice, whether distributed in print or electronically.

ifdef::basebackend-html[toc::[]]

include::preface.adoc[]

ifndef::ebook-format[= Reference documentation [[reference-documentation]]]

include::dependencies.adoc[]
include::repositories.adoc[]
include::auditing.adoc[]

ifndef::ebook-format[= Appendix [[appendix]]]

:numbered!:
include::repository-namespace-reference.adoc[]
include::repository-populator-namespace-reference.adoc[]
include::repository-query-keywords-reference.adoc[]
include::repository-query-return-types-reference.adoc[]

[mojavelinux]

With that new index, you can generate both a PDF and EPUB3 with no warnings.

[mojavelinux]

If you still want the parts "Reference documentation" and "Appendix" in the EPUB3, you'll need to create include files for them and use includes in those files to include the chapters. Except the chapters will then become sections.

This turns out to be a fairly helpful use case because it allows us to see all the dimensions that need to be considered when creating the EPUB3 divisions.

[mojavelinux]

Also, imagesdir must be set to images, which is this issue: #22. Otherwise, you get a broken image in the chapter header.

[daniellwu]

any update on this?

[mojavelinux]

I think I explained how to solve the problem. Is there a question you have about my explanation?

[daniellwu]

@mojavelinux , oh, I thought your explanation was more of a workaround, hence this issue is still open. (should this issue be closed?)

[mojavelinux]

Yes. Since this is addressed in the documentation, I will close this issue. If there is something that needs clarification, please reopen with a new request.