Converter should be able to process any AsciiDoc document

[mojavelinux]

Currently, the converter is very picky about the structure of the AsciiDoc document. When the document isn't exactly as it expects (see https://github.com/asciidoctor/asciidoctor-epub3#declaring-the-spine), it fails in often spectacular ways. This problem appears in all of the following issues:

• Provide more detail about required file structure for chapters #45
• Table of Contents renders as Untitled in eBook readers other than iBooks #42
• Can't generate epub: undefined method `to_ios'  #25
• Fails during generation with "undefined method `to_ios'" #7
• no mobi file generated #6
• Fix epub2 toc untitled #40

Instead, the converter should be able to handle any AsciiDoc document and do what it can to produce a sane result (or issue a clear error or warning otherwise). Naturally, the best result will be achieved when the structure is followed, but that should be a refinement rather than a prerequisite.

This is an umbrella issue to aggregate all these issues into one and clearly specify what needs to happen to fix it.

[chloerei]

Current asciidoctor-epub3 create epub spine(structure) by IncludeProcessor, I think epub spine should be create from document internal structure, for example, split document by level 1 sections.

[mojavelinux]

I'm leaning that way. We did it the way it is now as an experiment to see if we could use the include as a way to demarcate the boundaries between the entries so that it could be controlled by the author. I still think this is an interesting approach, but I think it should be an option to divide the book using the structure instead. So perhaps we want both ways to be supported.

The problem with dividing on the structure is that we still don't have proper support in the AST to split the document. It mostly works, but there are some things that don't get reparented correctly. We'll need to (finally) address them to support this change.

[ciampix]

Referred to here: https://groups.google.com/forum/#!topic/asciidoc/h6dP5CodLmI

[vinipsmaker]

I'm not convinced why I should include multiple document level headers. I'm creating one document, not several of them. The document header is the one which will receive the author and so on attributes.

I'm not convinced I should pervert my document structure to please asciidoctor.

Level 1 sections are what I'd see as chapters.

[gdamore]

Actually using the include files to demarcate document structure hurts me pretty badly. I want to build a combined reference manual that is built up using man pages, and I have a section chapter (e.g. section 3 for library API calls) that then does sub-includes (with level offsets) for each of those included files. This falls down hard with the epub generator.