Join GitHub today
GitHub is home to over 36 million developers working together to host and review code, manage projects, and build software together.Sign up
Converter should be able to process any AsciiDoc document #47
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:
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.
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.
referenced this issue
Jan 7, 2016
Referred to here: https://groups.google.com/forum/#!topic/asciidoc/h6dP5CodLmI
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.
This was referenced
Apr 9, 2017
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.