Include sections of files

That is precisely one of the features on the roadmap. In fact, it's high priority because we need it to migrate the Arquillian tutorials to AsciiDoc (using Asciidoctor).

Where we are right now is sorting out the syntax for marking the code to be inserted and inserting the code.

My working proposal is to tag the code as follows:

// tag: classdef

class Foo {
    static greet() { "hello" }
}

// tag: classdef

Then use a block macro to insert it:

source::foo.groovy[classdef]

I'd also like to support a resolver that could locate the file in an archive like a jar, a path like an output directory or even a URL.

I'm open to support line number ranges in the include macro, but I don't want to recommend that as the way to go because it's terribly brittle. There will be times when it is needed, so I don't want to deny that ability. I was thinking something like:

include::foo.groovy[from=1, to=3]

I'll make sure there is an issue for this feature and link it here.

-Dan

On Apr 11, 2013 10:51 AM, "glaforge [via Asciidoctor :: Discussion]" <[hidden email]> wrote:

Hi all,

I don't think the genuine AsciiDoc supports this, nor AsciiDoctor, but please tell me if I'm wrong -- I'd be happy if I were!

Is there a way to just include certain bits of a file when using the include directive?

For example, I'd like to include some code samples in a document, by splitting the included file in several sections, separated by some narrative.

More concretely, imagine a Groovy script I want to embed, called foo.groovy:

    class Foo {
        static greet() { "hello" }
    }
    assert Foo.greet() == "hello"

I wish I could say:

    Given a class:
    include::foo.groovy[startLine=1, endLine=3]
    Then you can run the following assert:
    include::foo.groovy[startLine=4, endLine=4]

And you'd get the result:

    Given a class:
    class Foo {
        static greet() { "hello" }
    }
    Then you can run the following assert:
    assert Foo.greet() == "hello"

Basically, I'm looking forward to being able to put code snippets in external files and reference them easily, sometimes in chunks, in the document, so as to have the ability to run the external scripts as part of my unit tests, ie. I was thinking of using AsciiDoctor to write "executable specifications" :-)

Guillaume

---

If you reply to this email, your message will be added to the discussion below:

http://discuss.asciidoctor.org/Include-sections-of-files-tp106.html

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

Here's the issue about including source snippets into the document:

https://github.com/asciidoctor/asciidoctor/issues/89

I've created a new issue for adding line range support to the include macro:

https://github.com/asciidoctor/asciidoctor/issues/226

Feel free to comment there.

I think the line range support on include::[] can easily make it into the next release. The source snippet support may take longer.

-Dan

On Thu, Apr 11, 2013 at 11:49 AM, Dan Allen <[hidden email]> wrote:

That is precisely one of the features on the roadmap. In fact, it's high priority because we need it to migrate the Arquillian tutorials to AsciiDoc (using Asciidoctor).

Where we are right now is sorting out the syntax for marking the code to be inserted and inserting the code.

My working proposal is to tag the code as follows:

// tag: classdef

class Foo {
    static greet() { "hello" }
}

// tag: classdef

Then use a block macro to insert it:

source::foo.groovy[classdef]

I'd also like to support a resolver that could locate the file in an archive like a jar, a path like an output directory or even a URL.

I'm open to support line number ranges in the include macro, but I don't want to recommend that as the way to go because it's terribly brittle. There will be times when it is needed, so I don't want to deny that ability. I was thinking something like:

include::foo.groovy[from=1, to=3]

I'll make sure there is an issue for this feature and link it here.

-Dan

On Apr 11, 2013 10:51 AM, "glaforge [via Asciidoctor :: Discussion]" <[hidden email]> wrote:

Hi all,

I don't think the genuine AsciiDoc supports this, nor AsciiDoctor, but please tell me if I'm wrong -- I'd be happy if I were!

Is there a way to just include certain bits of a file when using the include directive?

For example, I'd like to include some code samples in a document, by splitting the included file in several sections, separated by some narrative.

More concretely, imagine a Groovy script I want to embed, called foo.groovy:

    class Foo {
        static greet() { "hello" }
    }

    assert Foo.greet() == "hello"

I wish I could say:

    Given a class:
    include::foo.groovy[startLine=1, endLine=3]
    Then you can run the following assert:
    include::foo.groovy[startLine=4, endLine=4]

And you'd get the result:

    Given a class:

    class Foo {
        static greet() { "hello" }
    }

    Then you can run the following assert:
    assert Foo.greet() == "hello"

Basically, I'm looking forward to being able to put code snippets in external files and reference them easily, sometimes in chunks, in the document, so as to have the ability to run the external scripts as part of my unit tests, ie. I was thinking of using AsciiDoctor to write "executable specifications" :-)

Guillaume

---

If you reply to this email, your message will be added to the discussion below:

http://discuss.asciidoctor.org/Include-sections-of-files-tp106.html

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

--

Dan Allen

Principal Software Engineer, Red Hat | Author of Seam in Action
Registered Linux User #231597

http://google.com/profiles/dan.j.allen
http://mojavelinux.com
http://mojavelinux.com/seaminaction

---

If you reply to this email, your message will be added to the discussion below:

http://discuss.asciidoctor.org/Include-sections-of-files-tp106p114.html

To unsubscribe from Include sections of files, click here.
NAML

Looking forward to those improvements!

When would you plan the next release with the include line range capability?

Guillaume

On Thu, Apr 11, 2013 at 10:58 PM, mojavelinux [via Asciidoctor :: Discussion] <[hidden email]> wrote:

Here's the issue about including source snippets into the document:

https://github.com/asciidoctor/asciidoctor/issues/89

I've created a new issue for adding line range support to the include macro:

https://github.com/asciidoctor/asciidoctor/issues/226

Feel free to comment there.

I think the line range support on include::[] can easily make it into the next release. The source snippet support may take longer.

-Dan

On Thu, Apr 11, 2013 at 11:49 AM, Dan Allen <[hidden email]> wrote:

That is precisely one of the features on the roadmap. In fact, it's high priority because we need it to migrate the Arquillian tutorials to AsciiDoc (using Asciidoctor).

Where we are right now is sorting out the syntax for marking the code to be inserted and inserting the code.

My working proposal is to tag the code as follows:

// tag: classdef

class Foo {
    static greet() { "hello" }
}

// tag: classdef

Then use a block macro to insert it:

source::foo.groovy[classdef]

I'd also like to support a resolver that could locate the file in an archive like a jar, a path like an output directory or even a URL.

I'm open to support line number ranges in the include macro, but I don't want to recommend that as the way to go because it's terribly brittle. There will be times when it is needed, so I don't want to deny that ability. I was thinking something like:

include::foo.groovy[from=1, to=3]

I'll make sure there is an issue for this feature and link it here.

-Dan

On Apr 11, 2013 10:51 AM, "glaforge [via Asciidoctor :: Discussion]" <[hidden email]> wrote:

Hi all,

I don't think the genuine AsciiDoc supports this, nor AsciiDoctor, but please tell me if I'm wrong -- I'd be happy if I were!

Is there a way to just include certain bits of a file when using the include directive?

For example, I'd like to include some code samples in a document, by splitting the included file in several sections, separated by some narrative.

More concretely, imagine a Groovy script I want to embed, called foo.groovy:

    class Foo {
        static greet() { "hello" }
    }

    assert Foo.greet() == "hello"

I wish I could say:

    Given a class:
    include::foo.groovy[startLine=1, endLine=3]
    Then you can run the following assert:
    include::foo.groovy[startLine=4, endLine=4]

And you'd get the result:

    Given a class:

    class Foo {
        static greet() { "hello" }
    }

    Then you can run the following assert:
    assert Foo.greet() == "hello"

Basically, I'm looking forward to being able to put code snippets in external files and reference them easily, sometimes in chunks, in the document, so as to have the ability to run the external scripts as part of my unit tests, ie. I was thinking of using AsciiDoctor to write "executable specifications" :-)

Guillaume

---

If you reply to this email, your message will be added to the discussion below:

http://discuss.asciidoctor.org/Include-sections-of-files-tp106.html

To start a new topic under Asciidoctor :: Discussion, email [hidden email]

To unsubscribe from Asciidoctor :: Discussion, click here.
NAML

--

Dan Allen

Principal Software Engineer, Red Hat | Author of Seam in Action
Registered Linux User #231597

http://google.com/profiles/dan.j.allen
http://mojavelinux.com
http://mojavelinux.com/seaminaction

---

If you reply to this email, your message will be added to the discussion below:

http://discuss.asciidoctor.org/Include-sections-of-files-tp106p114.html

To unsubscribe from Include sections of files, click here.
NAML

--
Guillaume Laforge
Groovy Project Manager
SpringSource, a division of VMware

Blog: http://glaforge.appspot.com/

Social: @glaforge / Google+

---

If you reply to this email, your message will be added to the discussion below:

http://discuss.asciidoctor.org/Include-sections-of-files-tp106p117.html

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

That is precisely one of the features on the roadmap. In fact, it's high priority because we need it to migrate the Arquillian tutorials to AsciiDoc (using Asciidoctor).

Where we are right now is sorting out the syntax for marking the code to be inserted and inserting the code.

My working proposal is to tag the code as follows:

// tag: classdef

class Foo {
    static greet() { "hello" }
}

// tag: classdef

Then use a block macro to insert it:

source::foo.groovy[classdef]

I'd also like to support a resolver that could locate the file in an archive like a jar, a path like an output directory or even a URL.

I'm open to support line number ranges in the include macro, but I don't want to recommend that as the way to go because it's terribly brittle. There will be times when it is needed, so I don't want to deny that ability. I was thinking something like:

include::foo.groovy[from=1, to=3]

I'll make sure there is an issue for this feature and link it here.

-Dan

On Apr 11, 2013 10:51 AM, "glaforge [via Asciidoctor :: Discussion]" <[hidden email]> wrote:

Hi all,

I don't think the genuine AsciiDoc supports this, nor AsciiDoctor, but please tell me if I'm wrong -- I'd be happy if I were!

Is there a way to just include certain bits of a file when using the include directive?

For example, I'd like to include some code samples in a document, by splitting the included file in several sections, separated by some narrative.

More concretely, imagine a Groovy script I want to embed, called foo.groovy:

    class Foo {
        static greet() { "hello" }
    }
    assert Foo.greet() == "hello"

I wish I could say:

    Given a class:
    include::foo.groovy[startLine=1, endLine=3]
    Then you can run the following assert:
    include::foo.groovy[startLine=4, endLine=4]

And you'd get the result:

    Given a class:
    class Foo {
        static greet() { "hello" }
    }
    Then you can run the following assert:
    assert Foo.greet() == "hello"

Basically, I'm looking forward to being able to put code snippets in external files and reference them easily, sometimes in chunks, in the document, so as to have the ability to run the external scripts as part of my unit tests, ie. I was thinking of using AsciiDoctor to write "executable specifications" :-)

Guillaume

---

If you reply to this email, your message will be added to the discussion below:

http://discuss.asciidoctor.org/Include-sections-of-files-tp106.html

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

I've implemented the lines feature on the include macro and submitted it as a pull request for review.

I decided to go with the attribute name `lines` instead of `range` or `from` and `to`. The reason is because both limit us to a single range of lines. The `lines` attribute, on the other hand, can accommodate multiple selections per file.

Let's assume we're including the file snippets.txt.

To include the whole file, you use:

include::snippets.txt[]

To include the first 5 lines:

include::snippets.txt[lines=1..5]

To include lines 1, 3 and 5:

include::snippets.txt[lines=1;3;5]

To include all lines starting at line 10:

include::snippets.txt[lines=10..-1]

To include multiple selections:

include::snippets.txt[lines=1;3;5..10;20..-1]

The syntax is as follows.

* Multiple selections are separated by a semi-colon (using a comma would require the value to be quoted)

* A range is defined as n..m

* -1 is a reference to the last line in the file (other negative values are not supported).

Do you like the syntax? Anyone want to review the PR (don't worry about the detail of the code so much as the requirements implemented):

https://github.com/asciidoctor/asciidoctor/pull/245

I haven't yet added support for selecting lines based on marked boundaries, as in:

include::snippets.txt[tags=example1]

I'll implement that next.

-Dan

On Thu, Apr 11, 2013 at 11:49 AM, Dan Allen <[hidden email]> wrote:

That is precisely one of the features on the roadmap. In fact, it's high priority because we need it to migrate the Arquillian tutorials to AsciiDoc (using Asciidoctor).

Where we are right now is sorting out the syntax for marking the code to be inserted and inserting the code.

My working proposal is to tag the code as follows:

// tag: classdef

class Foo {
    static greet() { "hello" }
}

// tag: classdef

Then use a block macro to insert it:

source::foo.groovy[classdef]

I'd also like to support a resolver that could locate the file in an archive like a jar, a path like an output directory or even a URL.

I'm open to support line number ranges in the include macro, but I don't want to recommend that as the way to go because it's terribly brittle. There will be times when it is needed, so I don't want to deny that ability. I was thinking something like:

include::foo.groovy[from=1, to=3]

I'll make sure there is an issue for this feature and link it here.

-Dan

On Apr 11, 2013 10:51 AM, "glaforge [via Asciidoctor :: Discussion]" <[hidden email]> wrote:

Hi all,

I don't think the genuine AsciiDoc supports this, nor AsciiDoctor, but please tell me if I'm wrong -- I'd be happy if I were!

Is there a way to just include certain bits of a file when using the include directive?

For example, I'd like to include some code samples in a document, by splitting the included file in several sections, separated by some narrative.

More concretely, imagine a Groovy script I want to embed, called foo.groovy:

    class Foo {
        static greet() { "hello" }
    }
    assert Foo.greet() == "hello"

I wish I could say:

    Given a class:
    include::foo.groovy[startLine=1, endLine=3]
    Then you can run the following assert:
    include::foo.groovy[startLine=4, endLine=4]

And you'd get the result:

    Given a class:
    class Foo {
        static greet() { "hello" }
    }
    Then you can run the following assert:
    assert Foo.greet() == "hello"

Basically, I'm looking forward to being able to put code snippets in external files and reference them easily, sometimes in chunks, in the document, so as to have the ability to run the external scripts as part of my unit tests, ie. I was thinking of using AsciiDoctor to write "executable specifications" :-)

Guillaume

---

If you reply to this email, your message will be added to the discussion below:

http://discuss.asciidoctor.org/Include-sections-of-files-tp106.html

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

--

Dan Allen

Principal Software Engineer, Red Hat | Author of Seam in Action
Registered Linux User #231597

http://google.com/profiles/dan.j.allen
http://mojavelinux.com
http://mojavelinux.com/seaminaction

---

If you reply to this email, your message will be added to the discussion below:

http://discuss.asciidoctor.org/Include-sections-of-files-tp106p141.html

To unsubscribe from Include sections of files, click here.
NAML

That's awesome!

I hadn't thought about multiple selections, but that's a really good addition, and the syntax definitely make sense with that ability in mind.

Guillaume

On Wed, Apr 17, 2013 at 10:04 PM, mojavelinux [via Asciidoctor :: Discussion] <[hidden email]> wrote:

I've implemented the lines feature on the include macro and submitted it as a pull request for review.

I decided to go with the attribute name `lines` instead of `range` or `from` and `to`. The reason is because both limit us to a single range of lines. The `lines` attribute, on the other hand, can accommodate multiple selections per file.

Let's assume we're including the file snippets.txt.

To include the whole file, you use:

include::snippets.txt[]

To include the first 5 lines:

include::snippets.txt[lines=1..5]

To include lines 1, 3 and 5:

include::snippets.txt[lines=1;3;5]

To include all lines starting at line 10:

include::snippets.txt[lines=10..-1]

To include multiple selections:

include::snippets.txt[lines=1;3;5..10;20..-1]

The syntax is as follows.

* Multiple selections are separated by a semi-colon (using a comma would require the value to be quoted)

* A range is defined as n..m

* -1 is a reference to the last line in the file (other negative values are not supported).

Do you like the syntax? Anyone want to review the PR (don't worry about the detail of the code so much as the requirements implemented):

https://github.com/asciidoctor/asciidoctor/pull/245

I haven't yet added support for selecting lines based on marked boundaries, as in:

include::snippets.txt[tags=example1]

I'll implement that next.

-Dan

On Thu, Apr 11, 2013 at 11:49 AM, Dan Allen <[hidden email]> wrote:

That is precisely one of the features on the roadmap. In fact, it's high priority because we need it to migrate the Arquillian tutorials to AsciiDoc (using Asciidoctor).

Where we are right now is sorting out the syntax for marking the code to be inserted and inserting the code.

My working proposal is to tag the code as follows:

// tag: classdef

class Foo {
    static greet() { "hello" }
}

// tag: classdef

Then use a block macro to insert it:

source::foo.groovy[classdef]

I'd also like to support a resolver that could locate the file in an archive like a jar, a path like an output directory or even a URL.

I'm open to support line number ranges in the include macro, but I don't want to recommend that as the way to go because it's terribly brittle. There will be times when it is needed, so I don't want to deny that ability. I was thinking something like:

include::foo.groovy[from=1, to=3]

I'll make sure there is an issue for this feature and link it here.

-Dan

On Apr 11, 2013 10:51 AM, "glaforge [via Asciidoctor :: Discussion]" <[hidden email]> wrote:

Hi all,

I don't think the genuine AsciiDoc supports this, nor AsciiDoctor, but please tell me if I'm wrong -- I'd be happy if I were!

Is there a way to just include certain bits of a file when using the include directive?

For example, I'd like to include some code samples in a document, by splitting the included file in several sections, separated by some narrative.

More concretely, imagine a Groovy script I want to embed, called foo.groovy:

    class Foo {
        static greet() { "hello" }
    }
    assert Foo.greet() == "hello"

I wish I could say:

    Given a class:
    include::foo.groovy[startLine=1, endLine=3]
    Then you can run the following assert:
    include::foo.groovy[startLine=4, endLine=4]

And you'd get the result:

    Given a class:
    class Foo {
        static greet() { "hello" }
    }
    Then you can run the following assert:
    assert Foo.greet() == "hello"

Basically, I'm looking forward to being able to put code snippets in external files and reference them easily, sometimes in chunks, in the document, so as to have the ability to run the external scripts as part of my unit tests, ie. I was thinking of using AsciiDoctor to write "executable specifications" :-)

Guillaume

---

If you reply to this email, your message will be added to the discussion below:

http://discuss.asciidoctor.org/Include-sections-of-files-tp106.html

To start a new topic under Asciidoctor :: Discussion, email [hidden email]

To unsubscribe from Asciidoctor :: Discussion, click here.
NAML

--

Dan Allen

Principal Software Engineer, Red Hat | Author of Seam in Action
Registered Linux User #231597

http://google.com/profiles/dan.j.allen
http://mojavelinux.com
http://mojavelinux.com/seaminaction

---

If you reply to this email, your message will be added to the discussion below:

http://discuss.asciidoctor.org/Include-sections-of-files-tp106p141.html

To unsubscribe from Include sections of files, click here.
NAML

--
Guillaume Laforge
Groovy Project Manager
SpringSource, a division of VMware

Blog: http://glaforge.appspot.com/

Social: @glaforge / Google+

---

If you reply to this email, your message will be added to the discussion below:

http://discuss.asciidoctor.org/Include-sections-of-files-tp106p142.html

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

Cool!!

I just implemented support for selected tagged lines instead of line numbers. The are mutually exclusive atm, so you can either select lines or you can selected tagged regions. (We can remove that restriction if we decide it's necessary).

Atm, to syntax highlight source code in the snippets, you would do:

[source,groovy]

----

include::example.groovy[tags=classdef]

----

The next progression is to combine source and include together so the block is created automatically:

source::example.groovy[tags=classdef]

The language is selected based on the extension, saving you from having to type it twice...though you could still be explicit:

source::snippets.txt[tags=classdef, language=groovy]

I'll create an issue for this feature shortly.

-Dan

On Wed, Apr 17, 2013 at 2:26 PM, glaforge [via Asciidoctor :: Discussion] <[hidden email]> wrote:

That's awesome!

I hadn't thought about multiple selections, but that's a really good addition, and the syntax definitely make sense with that ability in mind.

Guillaume

On Wed, Apr 17, 2013 at 10:04 PM, mojavelinux [via Asciidoctor :: Discussion] <[hidden email]> wrote:

I've implemented the lines feature on the include macro and submitted it as a pull request for review.

I decided to go with the attribute name `lines` instead of `range` or `from` and `to`. The reason is because both limit us to a single range of lines. The `lines` attribute, on the other hand, can accommodate multiple selections per file.

Let's assume we're including the file snippets.txt.

To include the whole file, you use:

include::snippets.txt[]

To include the first 5 lines:

include::snippets.txt[lines=1..5]

To include lines 1, 3 and 5:

include::snippets.txt[lines=1;3;5]

To include all lines starting at line 10:

include::snippets.txt[lines=10..-1]

To include multiple selections:

include::snippets.txt[lines=1;3;5..10;20..-1]

The syntax is as follows.

* Multiple selections are separated by a semi-colon (using a comma would require the value to be quoted)

* A range is defined as n..m

* -1 is a reference to the last line in the file (other negative values are not supported).

Do you like the syntax? Anyone want to review the PR (don't worry about the detail of the code so much as the requirements implemented):

https://github.com/asciidoctor/asciidoctor/pull/245

I haven't yet added support for selecting lines based on marked boundaries, as in:

include::snippets.txt[tags=example1]

I'll implement that next.

-Dan

On Thu, Apr 11, 2013 at 11:49 AM, Dan Allen <[hidden email]> wrote:

That is precisely one of the features on the roadmap. In fact, it's high priority because we need it to migrate the Arquillian tutorials to AsciiDoc (using Asciidoctor).

Where we are right now is sorting out the syntax for marking the code to be inserted and inserting the code.

My working proposal is to tag the code as follows:

// tag: classdef

class Foo {
    static greet() { "hello" }
}

// tag: classdef

Then use a block macro to insert it:

source::foo.groovy[classdef]

I'd also like to support a resolver that could locate the file in an archive like a jar, a path like an output directory or even a URL.

I'm open to support line number ranges in the include macro, but I don't want to recommend that as the way to go because it's terribly brittle. There will be times when it is needed, so I don't want to deny that ability. I was thinking something like:

include::foo.groovy[from=1, to=3]

I'll make sure there is an issue for this feature and link it here.

-Dan

On Apr 11, 2013 10:51 AM, "glaforge [via Asciidoctor :: Discussion]" <[hidden email]> wrote:

Hi all,

I don't think the genuine AsciiDoc supports this, nor AsciiDoctor, but please tell me if I'm wrong -- I'd be happy if I were!

Is there a way to just include certain bits of a file when using the include directive?

For example, I'd like to include some code samples in a document, by splitting the included file in several sections, separated by some narrative.

More concretely, imagine a Groovy script I want to embed, called foo.groovy:

    class Foo {
        static greet() { "hello" }
    }
    assert Foo.greet() == "hello"

I wish I could say:

    Given a class:
    include::foo.groovy[startLine=1, endLine=3]
    Then you can run the following assert:
    include::foo.groovy[startLine=4, endLine=4]

And you'd get the result:

    Given a class:
    class Foo {
        static greet() { "hello" }
    }
    Then you can run the following assert:
    assert Foo.greet() == "hello"

Basically, I'm looking forward to being able to put code snippets in external files and reference them easily, sometimes in chunks, in the document, so as to have the ability to run the external scripts as part of my unit tests, ie. I was thinking of using AsciiDoctor to write "executable specifications" :-)

Guillaume

---

If you reply to this email, your message will be added to the discussion below:

http://discuss.asciidoctor.org/Include-sections-of-files-tp106.html

To start a new topic under Asciidoctor :: Discussion, email [hidden email]

To unsubscribe from Asciidoctor :: Discussion, click here.
NAML

--

Dan Allen

Principal Software Engineer, Red Hat | Author of Seam in Action
Registered Linux User #231597

http://google.com/profiles/dan.j.allen
http://mojavelinux.com
http://mojavelinux.com/seaminaction

---

If you reply to this email, your message will be added to the discussion below:

http://discuss.asciidoctor.org/Include-sections-of-files-tp106p141.html

To unsubscribe from Include sections of files, click here.
NAML

--
Guillaume Laforge
Groovy Project Manager
SpringSource, a division of VMware

Blog: http://glaforge.appspot.com/

Social: @glaforge / Google+

---

If you reply to this email, your message will be added to the discussion below:

http://discuss.asciidoctor.org/Include-sections-of-files-tp106p142.html

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

--

Dan Allen

Principal Software Engineer, Red Hat | Author of Seam in Action
Registered Linux User #231597

http://google.com/profiles/dan.j.allen
http://mojavelinux.com
http://mojavelinux.com/seaminaction

Cool!!

I just implemented support for selected tagged lines instead of line numbers. The are mutually exclusive atm, so you can either select lines or you can selected tagged regions. (We can remove that restriction if we decide it's necessary).

Atm, to syntax highlight source code in the snippets, you would do:

[source,groovy]

----

include::example.groovy[tags=classdef]

----

The next progression is to combine source and include together so the block is created automatically:

source::example.groovy[tags=classdef]

The language is selected based on the extension, saving you from having to type it twice...though you could still be explicit:

source::snippets.txt[tags=classdef, language=groovy]

I'll create an issue for this feature shortly.

-Dan

On Wed, Apr 17, 2013 at 2:26 PM, glaforge [via Asciidoctor :: Discussion] <[hidden email]> wrote:

That's awesome!

I hadn't thought about multiple selections, but that's a really good addition, and the syntax definitely make sense with that ability in mind.

Guillaume

On Wed, Apr 17, 2013 at 10:04 PM, mojavelinux [via Asciidoctor :: Discussion] <[hidden email]> wrote:

I've implemented the lines feature on the include macro and submitted it as a pull request for review.

I decided to go with the attribute name `lines` instead of `range` or `from` and `to`. The reason is because both limit us to a single range of lines. The `lines` attribute, on the other hand, can accommodate multiple selections per file.

Let's assume we're including the file snippets.txt.

To include the whole file, you use:

include::snippets.txt[]

To include the first 5 lines:

include::snippets.txt[lines=1..5]

To include lines 1, 3 and 5:

include::snippets.txt[lines=1;3;5]

To include all lines starting at line 10:

include::snippets.txt[lines=10..-1]

To include multiple selections:

include::snippets.txt[lines=1;3;5..10;20..-1]

The syntax is as follows.

* Multiple selections are separated by a semi-colon (using a comma would require the value to be quoted)

* A range is defined as n..m

* -1 is a reference to the last line in the file (other negative values are not supported).

Do you like the syntax? Anyone want to review the PR (don't worry about the detail of the code so much as the requirements implemented):

https://github.com/asciidoctor/asciidoctor/pull/245

I haven't yet added support for selecting lines based on marked boundaries, as in:

include::snippets.txt[tags=example1]

I'll implement that next.

-Dan

On Thu, Apr 11, 2013 at 11:49 AM, Dan Allen <[hidden email]> wrote:

That is precisely one of the features on the roadmap. In fact, it's high priority because we need it to migrate the Arquillian tutorials to AsciiDoc (using Asciidoctor).

Where we are right now is sorting out the syntax for marking the code to be inserted and inserting the code.

My working proposal is to tag the code as follows:

// tag: classdef

class Foo {
    static greet() { "hello" }
}

// tag: classdef

Then use a block macro to insert it:

source::foo.groovy[classdef]

I'd also like to support a resolver that could locate the file in an archive like a jar, a path like an output directory or even a URL.

I'm open to support line number ranges in the include macro, but I don't want to recommend that as the way to go because it's terribly brittle. There will be times when it is needed, so I don't want to deny that ability. I was thinking something like:

include::foo.groovy[from=1, to=3]

I'll make sure there is an issue for this feature and link it here.

-Dan

On Apr 11, 2013 10:51 AM, "glaforge [via Asciidoctor :: Discussion]" <[hidden email]> wrote:

Hi all,

I don't think the genuine AsciiDoc supports this, nor AsciiDoctor, but please tell me if I'm wrong -- I'd be happy if I were!

Is there a way to just include certain bits of a file when using the include directive?

For example, I'd like to include some code samples in a document, by splitting the included file in several sections, separated by some narrative.

More concretely, imagine a Groovy script I want to embed, called foo.groovy:

    class Foo {
        static greet() { "hello" }
    }
    assert Foo.greet() == "hello"

I wish I could say:

    Given a class:
    include::foo.groovy[startLine=1, endLine=3]
    Then you can run the following assert:
    include::foo.groovy[startLine=4, endLine=4]

And you'd get the result:

    Given a class:
    class Foo {
        static greet() { "hello" }
    }
    Then you can run the following assert:
    assert Foo.greet() == "hello"

Basically, I'm looking forward to being able to put code snippets in external files and reference them easily, sometimes in chunks, in the document, so as to have the ability to run the external scripts as part of my unit tests, ie. I was thinking of using AsciiDoctor to write "executable specifications" :-)

Guillaume

---

If you reply to this email, your message will be added to the discussion below:

http://discuss.asciidoctor.org/Include-sections-of-files-tp106.html

To start a new topic under Asciidoctor :: Discussion, email [hidden email]

To unsubscribe from Asciidoctor :: Discussion, click here.
NAML

--

Dan Allen

Principal Software Engineer, Red Hat | Author of Seam in Action
Registered Linux User #231597

http://google.com/profiles/dan.j.allen
http://mojavelinux.com
http://mojavelinux.com/seaminaction

---

If you reply to this email, your message will be added to the discussion below:

http://discuss.asciidoctor.org/Include-sections-of-files-tp106p141.html

To unsubscribe from Include sections of files, click here.
NAML

--
Guillaume Laforge
Groovy Project Manager
SpringSource, a division of VMware

Blog: http://glaforge.appspot.com/

Social: @glaforge / Google+

---

If you reply to this email, your message will be added to the discussion below:

http://discuss.asciidoctor.org/Include-sections-of-files-tp106p142.html

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

--

Dan Allen

Principal Software Engineer, Red Hat | Author of Seam in Action
Registered Linux User #231597

http://google.com/profiles/dan.j.allen
http://mojavelinux.com
http://mojavelinux.com/seaminaction

---

If you reply to this email, your message will be added to the discussion below:

http://discuss.asciidoctor.org/Include-sections-of-files-tp106p143.html

To unsubscribe from Include sections of files, click here.
NAML

By the way, a quick question: the comments / tag lines are not included in the document?

Say if we have:

1: import foo

2: // tag classdef

3: class Bar {}

4: // tag classdef

The included snippet is just line 3?

Just so the artificial comment that we use doesn't appear in the final produced documentation :-)

Guillaume

On Wed, Apr 17, 2013 at 10:35 PM, mojavelinux [via Asciidoctor :: Discussion] <[hidden email]> wrote:

Cool!!

I just implemented support for selected tagged lines instead of line numbers. The are mutually exclusive atm, so you can either select lines or you can selected tagged regions. (We can remove that restriction if we decide it's necessary).

Atm, to syntax highlight source code in the snippets, you would do:

[source,groovy]

----

include::example.groovy[tags=classdef]

----

The next progression is to combine source and include together so the block is created automatically:

source::example.groovy[tags=classdef]

The language is selected based on the extension, saving you from having to type it twice...though you could still be explicit:

source::snippets.txt[tags=classdef, language=groovy]

I'll create an issue for this feature shortly.

-Dan

On Wed, Apr 17, 2013 at 2:26 PM, glaforge [via Asciidoctor :: Discussion] <[hidden email]> wrote:

That's awesome!

I hadn't thought about multiple selections, but that's a really good addition, and the syntax definitely make sense with that ability in mind.

Guillaume

On Wed, Apr 17, 2013 at 10:04 PM, mojavelinux [via Asciidoctor :: Discussion] <[hidden email]> wrote:

I've implemented the lines feature on the include macro and submitted it as a pull request for review.

I decided to go with the attribute name `lines` instead of `range` or `from` and `to`. The reason is because both limit us to a single range of lines. The `lines` attribute, on the other hand, can accommodate multiple selections per file.

Let's assume we're including the file snippets.txt.

To include the whole file, you use:

include::snippets.txt[]

To include the first 5 lines:

include::snippets.txt[lines=1..5]

To include lines 1, 3 and 5:

include::snippets.txt[lines=1;3;5]

To include all lines starting at line 10:

include::snippets.txt[lines=10..-1]

To include multiple selections:

include::snippets.txt[lines=1;3;5..10;20..-1]

The syntax is as follows.

* Multiple selections are separated by a semi-colon (using a comma would require the value to be quoted)

* A range is defined as n..m

* -1 is a reference to the last line in the file (other negative values are not supported).

Do you like the syntax? Anyone want to review the PR (don't worry about the detail of the code so much as the requirements implemented):

https://github.com/asciidoctor/asciidoctor/pull/245

I haven't yet added support for selecting lines based on marked boundaries, as in:

include::snippets.txt[tags=example1]

I'll implement that next.

-Dan

On Thu, Apr 11, 2013 at 11:49 AM, Dan Allen <[hidden email]> wrote:

That is precisely one of the features on the roadmap. In fact, it's high priority because we need it to migrate the Arquillian tutorials to AsciiDoc (using Asciidoctor).

Where we are right now is sorting out the syntax for marking the code to be inserted and inserting the code.

My working proposal is to tag the code as follows:

// tag: classdef

class Foo {
    static greet() { "hello" }
}

// tag: classdef

Then use a block macro to insert it:

source::foo.groovy[classdef]

I'd also like to support a resolver that could locate the file in an archive like a jar, a path like an output directory or even a URL.

I'm open to support line number ranges in the include macro, but I don't want to recommend that as the way to go because it's terribly brittle. There will be times when it is needed, so I don't want to deny that ability. I was thinking something like:

include::foo.groovy[from=1, to=3]

I'll make sure there is an issue for this feature and link it here.

-Dan

On Apr 11, 2013 10:51 AM, "glaforge [via Asciidoctor :: Discussion]" <[hidden email]> wrote:

Hi all,

I don't think the genuine AsciiDoc supports this, nor AsciiDoctor, but please tell me if I'm wrong -- I'd be happy if I were!

Is there a way to just include certain bits of a file when using the include directive?

For example, I'd like to include some code samples in a document, by splitting the included file in several sections, separated by some narrative.

More concretely, imagine a Groovy script I want to embed, called foo.groovy:

    class Foo {
        static greet() { "hello" }
    }
    assert Foo.greet() == "hello"

I wish I could say:

    Given a class:
    include::foo.groovy[startLine=1, endLine=3]
    Then you can run the following assert:
    include::foo.groovy[startLine=4, endLine=4]

And you'd get the result:

    Given a class:
    class Foo {
        static greet() { "hello" }
    }
    Then you can run the following assert:
    assert Foo.greet() == "hello"

Basically, I'm looking forward to being able to put code snippets in external files and reference them easily, sometimes in chunks, in the document, so as to have the ability to run the external scripts as part of my unit tests, ie. I was thinking of using AsciiDoctor to write "executable specifications" :-)

Guillaume

---

If you reply to this email, your message will be added to the discussion below:

http://discuss.asciidoctor.org/Include-sections-of-files-tp106.html

To start a new topic under Asciidoctor :: Discussion, email [hidden email]

To unsubscribe from Asciidoctor :: Discussion, click here.
NAML

--

Dan Allen

Principal Software Engineer, Red Hat | Author of Seam in Action
Registered Linux User #231597

http://google.com/profiles/dan.j.allen
http://mojavelinux.com
http://mojavelinux.com/seaminaction

---

If you reply to this email, your message will be added to the discussion below:

http://discuss.asciidoctor.org/Include-sections-of-files-tp106p141.html

To unsubscribe from Include sections of files, click here.
NAML

--
Guillaume Laforge
Groovy Project Manager
SpringSource, a division of VMware

Blog: http://glaforge.appspot.com/

Social: @glaforge / Google+

---

If you reply to this email, your message will be added to the discussion below:

http://discuss.asciidoctor.org/Include-sections-of-files-tp106p142.html

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

--

Dan Allen

Principal Software Engineer, Red Hat | Author of Seam in Action
Registered Linux User #231597

http://google.com/profiles/dan.j.allen
http://mojavelinux.com
http://mojavelinux.com/seaminaction

---

If you reply to this email, your message will be added to the discussion below:

http://discuss.asciidoctor.org/Include-sections-of-files-tp106p143.html

To unsubscribe from Include sections of files, click here.
NAML

--
Guillaume Laforge
Groovy Project Manager
SpringSource, a division of VMware

Blog: http://glaforge.appspot.com/

Social: @glaforge / Google+

---

If you reply to this email, your message will be added to the discussion below:

http://discuss.asciidoctor.org/Include-sections-of-files-tp106p145.html

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