Asciidoctor :: Discussion

Suppress "Section title out of order" warnings

_‹ Previous Topic Next Topic _›

Classic

List

Threaded

6 messages Options

rlarsen

Jan 07, 2016; 9:11pm

Suppress "Section title out of order" warnings

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

mojavelinux

Jan 07, 2016; 10:28pm

Re: Suppress "Section title out of order" warnings

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

mojavelinux

Jan 07, 2016; 10:29pm

Re: Suppress "Section title out of order" warnings

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

... [show rest of quote]

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

abelsromero

Jan 07, 2016; 10:50pm

Re: Suppress "Section title out of order" warnings

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.

rlarsen

Jan 07, 2016; 11:04pm

Re: Suppress "Section title out of order" warnings

In reply to this post by mojavelinux

Thanks. I will give this a try.

rlarsen

Jan 20, 2016; 8:34pm

Re: Suppress "Section title out of order" warnings

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.