[
https://issues.apache.org/jira/browse/SOLR-10297?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=16003676#comment-16003676
]
Hoss Man commented on SOLR-10297:
---------------------------------
After a lot of cleanup work, there are currently only 2 build errors -- and
*_only_* when building the PDF...
{noformat}
[asciidoctor:convert] asciidoctor: ERROR: about-this-guide.adoc: line 1:
invalid part, must have at least one section (e.g., chapter, appendix, etc.)
[asciidoctor:convert] asciidoctor: ERROR: solr-glossary.adoc: line 1: invalid
part, must have at least one section (e.g., chapter, appendix, etc.)
{noformat}
The pages themselves are well formed -- the crux of the problem seems to
related to where/how they get included in the final PDF. Notably: *asciidoctor
will sometimes complain about invalid syntax in included files because of
problems that occur in the content that comes before the included file*
In practice the root issue seems to be:
* something about the fact that {{about-this-guide.adoc}} is the first child of
{{index.adoc}} is why we get an error about it -- reorder the children so any
other {{file.adoc}} is the first child in the list and the error will move to
that file
* something about the fact that {{solr-glossary.adoc}} is the next (top level)
section after {{further-assistance.adoc}} is the reason we get an error about
it. reorder the children of {{index.adoc}} so that any other {{file.adoc}}
comes after {{further-assistance.adoc}} and you'll get the error about that
file instead.
Note these relevant links i found and some of the details in them that hint at
similar problems...
https://github.com/asciidoctor/asciidoctor/issues/1704
bq. A missing include file is reported as a syntax error in the next included
file
bq. This is likely due to the unique combination of leveloffset and the secure
mode. ... Actually, the leveloffset probably doesn't have anything to do with
it in this case (but there are cases when that might be a factor).
https://github.com/asciidoctor/asciidoctor-epub3/issues/65
bq. But the document is well structured, it just uses level offsets on imports?
bq. 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.
> Resolve Ref Guide build errors
> ------------------------------
>
> Key: SOLR-10297
> URL: https://issues.apache.org/jira/browse/SOLR-10297
> Project: Solr
> Issue Type: Sub-task
> Security Level: Public(Default Security Level. Issues are Public)
> Components: documentation
> Reporter: Cassandra Targett
> Attachments: build-errors-HTML-20170315.txt,
> build-errors-PDF-20170315.txt
>
>
> The asciidoctor tools used to build the HTML and PDF versions of the Ref
> Guide validate the pages during the build and throw errors during the build
> when there are problems. Usually these problems are not fatal, but they do
> indicate inconsistencies in the content that should be resolved. Almost all
> of the time they are problems with inconsistent heading levels - a h5 follows
> a h2 for example.
> These errors should be cleaned up so we only see errors we should worry about
> going forward.
--
This message was sent by Atlassian JIRA
(v6.3.15#6346)
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
