Asciidoctor :: Discussion

Compiling all includes into a master Adoc file

_‹ Previous Topic Next Topic _›

Classic

List

Threaded

4 messages Options

traycerb

Oct 04, 2014; 4:13am

Compiling all includes into a master Adoc file

An Adoc file may have many includes, pointing to external adocs. For a convenient example, see the Asciidoc User Manual.

Is there a way to compile all of the 'includes' to yield one single unrendered .adoc file? Maybe this a noob question, but I didn't see any such option in the asciidoctor command line options.

If it's not an option, would it be possible to include such a feature? I assume asciidoctor has to do this internally before rendering anyway.

mojavelinux

Oct 09, 2014; 12:28am

Re: Compiling all includes into a master Adoc file

Administrator

I have good news for you. This is very straightforward to do as of Asciidoctor 1.5.0. You just need to load the AsciiDoc source without parsing, then access the reader and read all the lines. This will run all the preprocessor directives without parsing the AsciiDoc content.

[source,ruby]

----

source_file = ARGV[0]

doc = Asciidoctor.load_file source_file, safe: :safe, parse: false

puts doc.reader.read

----

You can use readlines instead of read if you want to get the lines as an array.

There is one caveat. None of the attributes in the header will be resolved as we aren't parsing. You may need to feed the attributes into the load method explicitly if they are needed for resolving includes. (There's a way to do this automatically, but it's a much more complicated invocation and kind of clunky atm).

I've added this script to the extensions-lab so that we don't lose it and we can build in more functionality as needed.

https://github.com/asciidoctor/asciidoctor-extensions-lab/blob/master/scripts/asciidoc-coalescer.rb

Asciidoctor preprocesses lines as they come during parsing. That's why we have to go straight to the reader and read all the lines eagerly to get a coalesced document.

Hope that helps! Cheers!

-Dan

On Fri, Oct 3, 2014 at 10:13 PM, traycerb [via Asciidoctor :: Discussion] <[hidden email]> wrote:

An Adoc file may have many includes, pointing to external adocs. For a convenient example, see the Asciidoc User Manual.

Is there a way to compile all of the 'includes' to yield one single unrendered .adoc file? Maybe this a noob question, but I didn't see any such option in the asciidoctor command line options.

If it's not an option, would it be possible to include such a feature? I assume asciidoctor has to do this internally before rendering anyway.

If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Compiling-all-includes-into-a-master-Adoc-file-tp2308.html

To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML

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

mojavelinux

Oct 09, 2014; 12:49am

Re: Compiling all includes into a master Adoc file

Administrator

In reply to this post by traycerb

I was thinking it might make sense to add a read method to either the Asciidoctor API or the Asciidoctor:: Document class. The read method would differ from load in that it would just run the preprocessor & return all the lines as an array. It would also handle the task of resolving document-level attributes so that the reader behaves in the same way as when the document is parsed.

This would be useful for an "effective AsciiDoc" preview window in the tooling.

If someone is interested to see this API method added, feel free to prose a change and I'll certainly consider adding it.

-Dan

abelsromero

Oct 09, 2014; 5:46am

Re: Compiling all includes into a master Adoc file

I'm no a ruby man, so maybe this question makes no sense, but, could it be possible to have that array in the load method?
Once integrated into the render methods in AsciidoctorJ this would open the possibility to abort a build (from maven/gradle) if an error is reported.

Right now, I achieved something like that by creating JUnits that renders adocs and redirecting the standard/error output to a String, then 'asserting a failure' if some words are found.
Maybe I'm dreaming, but I'm even thinking in the possibily of creating Junit compatible reports so that asciidoctor rendering can be integrated into CI's like jenkins.