Asciidoctor :: Discussion

Include in source block - how to disable the inclusion?

_‹ Previous Topic Next Topic _›

Classic

List

Threaded

8 messages Options

JezPrime

Include in source block - how to disable the inclusion?

Firstly, apologies for the fact that this is probably a noob question. I'm writing up a quick blog about using AsciiDoc, and I have an AsciiDoc source block which contains the following (note that blogpost1.adoc doesn't exist and I wouldn't want it included in that location, I'm actually trying to show the use of the include directive by saying "copy this text as is, into a new file"):-

[source,asciidoc]
----
= My Blog
Fred Bloggs <fred@example.com>

=== Our first blog post
*2014-09-05* +
include::blogpost1.adoc[tags=summary]
link:blogpost1.html[Read more]
----

When this adoc file passes through AsciiDoctor (1.5.0, OS X) then the following warning is observed, telling me that AsciiDoctor is trying to perform the include:-

include file not found: (full path)/blogpost1.adoc

This seems entirely reasonable (we might want to include a section of a source file, for example). My question is, how do I change this source block so that instead of trying to include the file, what is displayed in the generated html page is the source block as written above? I tried pass:[include...] and this displayed entirely as is, including the pass, so that didn't give the effect I wanted.

I hope this is clear, again apologies for the fact this is probably a noob question. Thanks for any help any of you more experienced guys can offer.

LightGuardjp

Re: Include in source block - how to disable the inclusion?

I haven't tried it, but you probably want to put the text (or just the line) in a pass through block.

—
Sent from Mailbox

On Sat, Sep 6, 2014 at 11:22 AM, JezPrime [via Asciidoctor :: Discussion] <[hidden email]> wrote:

Firstly, apologies for the fact that this is probably a noob question. I'm writing up a quick blog about using AsciiDoc, and I have an AsciiDoc source block which contains the following (note that blogpost1.adoc doesn't exist and I wouldn't want it included in that location, I'm actually trying to show the use of the include directive by saying "copy this text as is, into a new file"):-

[source,asciidoc]
----
= My Blog
Fred Bloggs <[hidden email]>

=== Our first blog post
*2014-09-05* +
include::blogpost1.adoc[tags=summary]
link:blogpost1.html[Read more]
----

When this adoc file passes through AsciiDoctor (1.5.0, OS X) then the following warning is observed, telling me that AsciiDoctor is trying to perform the include:-

include file not found: (full path)/blogpost1.adoc

This seems entirely reasonable (we might want to include a section of a source file, for example). My question is, how do I change this source block so that instead of trying to include the file, what is displayed in the generated html page is the source block as written above? I tried pass:[include...] and this displayed entirely as is, including the pass, so that didn't give the effect I wanted.

I hope this is clear, again apologies for the fact this is probably a noob question. Thanks for any help any of you more experienced guys can offer.

If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Include-in-source-block-how-to-disable-the-inclusion-tp2122.html

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

mojavelinux

Re: Include in source block - how to disable the inclusion?

Administrator

In reply to this post by JezPrime

On Sat, Sep 6, 2014 at 11:16 AM, JezPrime [via Asciidoctor :: Discussion] <[hidden email]> wrote:

This seems entirely reasonable (we might want to include a section of a source file, for example). My question is, how do I change this source block so that instead of trying to include the file, what is displayed in the generated html page is the source block as written above? I tried pass:[include...] and this displayed entirely as is, including the pass, so that didn't give the effect I wanted.

What you need to do is escape the include directive using a backslash. An include is a preprocessor directive (not a macro), which means that it is not aware of the current context in the document. Anywhere it exists, it is processed, unless it is escaped.

Here's what you'll want to type.

[source,asciidoc]
----
= My Blog
Fred Bloggs <[hidden email]>

=== Our first blog post

*2014-09-05* +

\include::blogpost1.adoc[tags=summary]

link:blogpost1.html[Read more]
----

Cheers,

-Dan

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

LightGuardjp

Re: Include in source block - how to disable the inclusion?

Thought about that, but wasn't 100% sure it would work.

On Sunday, September 7, 2014, mojavelinux [via Asciidoctor :: Discussion] <[hidden email]> wrote:

On Sat, Sep 6, 2014 at 11:16 AM, JezPrime [via Asciidoctor :: Discussion] <[hidden email]> wrote:
This seems entirely reasonable (we might want to include a section of a source file, for example). My question is, how do I change this source block so that instead of trying to include the file, what is displayed in the generated html page is the source block as written above? I tried pass:[include...] and this displayed entirely as is, including the pass, so that didn't give the effect I wanted.

What you need to do is escape the include directive using a backslash. An include is a preprocessor directive (not a macro), which means that it is not aware of the current context in the document. Anywhere it exists, it is processed, unless it is escaped.

Here's what you'll want to type.

[source,asciidoc]
----
= My Blog
Fred Bloggs <[hidden email]>

=== Our first blog post

*2014-09-05* +
\include::blogpost1.adoc[tags=summary]
link:blogpost1.html[Read more]
----

Cheers,

-Dan

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

If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Include-in-source-block-how-to-disable-the-inclusion-tp2122p2126.html

To start a new topic under Asciidoctor :: Discussion, email <a href="javascript:_e(%7B%7D,'cvml','ml-node%2Bs49171n1h37@n6.nabble.com');" target="_blank">ml-node+s49171n1h37@...
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML

Jason Porter
http://en.gravatar.com/lightguardjp

mojavelinux

Re: Include in source block - how to disable the inclusion?

Administrator

I added a clause to the user manual to cover this scenario.

http://asciidoctor.org/docs/user-manual/#include-directive

(We could do a better job explaining the include directive, but at least a start).

-Dan

On Sun, Sep 7, 2014 at 7:59 PM, LightGuardjp [via Asciidoctor :: Discussion] <[hidden email]> wrote:

Thought about that, but wasn't 100% sure it would work.

On Sunday, September 7, 2014, mojavelinux [via Asciidoctor :: Discussion] <[hidden email]> wrote:

On Sat, Sep 6, 2014 at 11:16 AM, JezPrime [via Asciidoctor :: Discussion] <[hidden email]> wrote:
This seems entirely reasonable (we might want to include a section of a source file, for example). My question is, how do I change this source block so that instead of trying to include the file, what is displayed in the generated html page is the source block as written above? I tried pass:[include...] and this displayed entirely as is, including the pass, so that didn't give the effect I wanted.

What you need to do is escape the include directive using a backslash. An include is a preprocessor directive (not a macro), which means that it is not aware of the current context in the document. Anywhere it exists, it is processed, unless it is escaped.

Here's what you'll want to type.

[source,asciidoc]
----
= My Blog
Fred Bloggs <[hidden email]>

=== Our first blog post

*2014-09-05* +
\include::blogpost1.adoc[tags=summary]
link:blogpost1.html[Read more]
----

Cheers,

-Dan

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

If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Include-in-source-block-how-to-disable-the-inclusion-tp2122p2126.html

To start a new topic under Asciidoctor :: Discussion, email <a href="javascript:_e(%7B%7D,'cvml',&#[hidden email]');" target="_blank">ml-node+s49171n1h37@...
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML

--
Jason Porter
http://en.gravatar.com/lightguardjp

If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Include-in-source-block-how-to-disable-the-inclusion-tp2122p2127.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

abelsromero

Re: Include in source block - how to disable the inclusion?

Would it be possible to add an attribute to the block to tell that all text should be escaped? Something like [literal] block?
Right now, having to escape every single line can be a nuisance.

Btw @Jez, you can use highlightjs as source-highlighter to add some color to asciidoc blocks ;) It's not perfect, but it's better than nothing.

mojavelinux

Re: Include in source block - how to disable the inclusion?

Administrator

On Mon, Sep 8, 2014 at 1:10 AM, abelsromero [via Asciidoctor :: Discussion] <[hidden email]> wrote:

Would it be possible to add an attribute to the block to tell that all text should be escaped? Something like [literal] block?

Not in this case. An include directive is processed (unless it's escaped) no matter where it appears. That's just the nature of the preprocessor directive.

-Dan

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

JezPrime

Re: Include in source block - how to disable the inclusion?

Fantastic - thank you so much guys for responding so quickly, with the right answer and an explanation even someone as stupid as me could understand.

I'll look into using the javascript syntax colouring as well, that would be really nice, so thanks also for that suggestion.