Suppress "Section title out of order" warnings

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
6 messages Options
Reply | Threaded
Open this post in threaded view
|

Suppress "Section title out of order" warnings

rlarsen
Hello,

I have a project that uses Asciidoctor to generate documentation in several sectional documents that are included into the larger, final documentation. The project is built as part of a larger maven build.

If I can't selectively render only the final three or four documents, is there a way to suppress the maven warnings generated by the individual sections, which will never exist as standalone documents?

Rick Larsen
Reply | Threaded
Open this post in threaded view
|

Re: Suppress "Section title out of order" warnings

mojavelinux
Administrator
Rick,

If the individual sections won't exist as a standalone documents, then Maven should be configured to ignore those documents. This is possible either using the sourceDocumentName or by putting them in a directory that begins with an underscore.

Abel, I think the implicit ignores (files that begin with an underscore, etc) should be documented in the README for the Maven plugin. This actually comes from AsciidoctorJ. See https://github.com/asciidoctor/asciidoctorj/blob/master/asciidoctorj-core/src/main/java/org/asciidoctor/AsciiDocDirectoryWalker.java#L17.

-Dan

On Thu, Jan 7, 2016 at 2:11 PM, rlarsen [via Asciidoctor :: Discussion] <[hidden email]> wrote:
Hello,

I have a project that uses Asciidoctor to generate documentation in several sectional documents that are included into the larger, final documentation. The project is built as part of a larger maven build.

If I can't selectively render only the final three or four documents, is there a way to suppress the maven warnings generated by the individual sections, which will never exist as standalone documents?

Rick Larsen


If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Suppress-Section-title-out-of-order-warnings-tp4157.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML



--
Dan Allen | @mojavelinux | http://google.com/profiles/dan.j.allen
Reply | Threaded
Open this post in threaded view
|

Re: Suppress "Section title out of order" warnings

mojavelinux
Administrator
In reply to this post by rlarsen
To clarify, sourceDocumentName tells the Maven plugin which file to build (and the rest are ignored). If you have multiple top-level documents (i.e., indexes), then using the directory with the leading underscore trick is the way to go.

index.adoc
_sections/
  section-a.adoc
  section-b.adoc

-Dan

On Thu, Jan 7, 2016 at 3:37 PM, Dan Allen <[hidden email]> wrote:
Rick,

If the individual sections won't exist as a standalone documents, then Maven should be configured to ignore those documents. This is possible either using the sourceDocumentName or by putting them in a directory that begins with an underscore.

Abel, I think the implicit ignores (files that begin with an underscore, etc) should be documented in the README for the Maven plugin. This actually comes from AsciidoctorJ. See https://github.com/asciidoctor/asciidoctorj/blob/master/asciidoctorj-core/src/main/java/org/asciidoctor/AsciiDocDirectoryWalker.java#L17.

-Dan

On Thu, Jan 7, 2016 at 2:11 PM, rlarsen [via Asciidoctor :: Discussion] <[hidden email]> wrote:
Hello,

I have a project that uses Asciidoctor to generate documentation in several sectional documents that are included into the larger, final documentation. The project is built as part of a larger maven build.

If I can't selectively render only the final three or four documents, is there a way to suppress the maven warnings generated by the individual sections, which will never exist as standalone documents?

Rick Larsen


If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Suppress-Section-title-out-of-order-warnings-tp4157.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML



--
Dan Allen | @mojavelinux | http://google.com/profiles/dan.j.allen



--
Dan Allen | @mojavelinux | http://google.com/profiles/dan.j.allen
Reply | Threaded
Open this post in threaded view
|

Re: Suppress "Section title out of order" warnings

abelsromero
In reply to this post by rlarsen
I'd like to add that if you want to render 3 or 4 documents, in maven you can define one execution for each file.
Here is an example of different executions https://github.com/asciidoctor/asciidoctor-maven-examples/blob/master/asciidoc-multiple-inputs-example/pom.xml#L56-L97.
Note that common configurations can be set once on the common <configuration> section on top of the executions, then in each execution, you can use sourceDocumentName for each of the different names.
Reply | Threaded
Open this post in threaded view
|

Re: Suppress "Section title out of order" warnings

rlarsen
In reply to this post by mojavelinux
Thanks. I will give this a try.
Reply | Threaded
Open this post in threaded view
|

Re: Suppress "Section title out of order" warnings

rlarsen
In reply to this post by mojavelinux
Thanks again for your help with this. I moved all the "contents" files to underscore directories. This did prevent the partial files from rendering, but they did still generate the warnings in my output if:

a) I started a partial document at anything above a level 3 (==== Section Title)
b) I had any levels that repeated within the first 2 or 3 section headings.

For example, this would generate a warning:

=== Section title

content

==== Subsection 1

content

==== Subsection 2

content

but this wouldn't:

=== Section title

content

==== Subsection 1

content

===== Subsection 2

content...

I was able to make it work for my immediate needs, but wanted to point this out in case it is not the desired behavior.