Include sections of files

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

Include sections of files

glaforge
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
Reply | Threaded
Open this post in threaded view
|

Re: Include sections of files

mojavelinux
Administrator

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
Reply | Threaded
Open this post in threaded view
|

Re: Include sections of files

mojavelinux
Administrator
In reply to this post by glaforge

Btw, there is a filter available for AsciiDoc called source extractor that does this. However, I don't like AsciiDoc filters because they use system calls and I don't liked the filter syntax in AsciiDoc because it requires you have a delimited block when one isn't necessary.

...you can also do this in a custom block_paragraph template in Asciidoctor, but that's kind of a hack. If I get a chance I'll make an example.

-Dan

--
Sent from my CyanogenMod-powered
Android device, an open platform for
carriers, developers and consumers.

On Apr 11, 2013 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
Reply | Threaded
Open this post in threaded view
|

Re: Include sections of files

LightGuardjp
In reply to this post by mojavelinux



On Thu, Apr 11, 2013 at 11:50, mojavelinux [via Asciidoctor :: Discussion] <[hidden email]="mailto:[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.

​What about

include::foo.groovy[range=1..3]

?

-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



If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Include-sections-of-files-tp106p108.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML
Reply | Threaded
Open this post in threaded view
|

Re: Include sections of files

mojavelinux
Administrator



On Thu, Apr 11, 2013 at 2:22 PM, lightguard.jp [via Asciidoctor :: Discussion] <[hidden email]> wrote:



On Thu, Apr 11, 2013 at 11:50, mojavelinux [via Asciidoctor :: Discussion] <[hidden email]="mailto:[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.

​What about

include::foo.groovy[range=1..3]

Yep, I like that. I was thinking we could even make range (or lines) a positional attribute so it can be written shorthand as:

include::foo.groovy[1..3]

We have to be sure, though, that there is no better use for the first positional attribute. We could start with range (or lines) and then decide later to introduce the shorthand.

include::foo.groovy[lines=1..3]

-Dan

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

Reply | Threaded
Open this post in threaded view
|

Re: Include sections of files

mojavelinux
Administrator
In reply to this post by glaforge
Here's the issue about including source snippets into the document:


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


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

Reply | Threaded
Open this post in threaded view
|

Re: Include sections of files

glaforge
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:


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


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




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

Reply | Threaded
Open this post in threaded view
|

Re: Include sections of files

mojavelinux
Administrator
My goal is to try to get 0.1.2 finished by the end of the week. Since it always takes me several days longer than estimated, I set the milestone for next Tuesday (Apr 23).

I'll keep the milestone updated in the issue tracker as a way of reporting the progress and to give folks an opportunity to pitch in.

-Dan


On Fri, Apr 12, 2013 at 1:49 AM, glaforge [via Asciidoctor :: Discussion] <[hidden email]> wrote:
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:


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


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




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




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



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

Reply | Threaded
Open this post in threaded view
|

Re: Include sections of files

mojavelinux
Administrator
In reply to this post by glaforge
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):


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

Reply | Threaded
Open this post in threaded view
|

Re: Include sections of files

glaforge
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):


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




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

Reply | Threaded
Open this post in threaded view
|

Re: Include sections of files

mojavelinux
Administrator
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):


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




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




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

Reply | Threaded
Open this post in threaded view
|

Re: Include sections of files

mojavelinux
Administrator
In reply to this post by glaforge
Btw, I also allow the use of a comma if you quote the value

include::snippets.txt[lines="1, 3, 5..10"]

The semi-colon just allows you to skip the quotes*

-Dan

* I'd like to solve this problem generally in AsciiDoc by allow commas in attribute values if bounded on either side by non-whitespace. But I'm still thinking about it.


On Wed, Apr 17, 2013 at 2:34 PM, Dan Allen <[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):


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




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




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




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

Reply | Threaded
Open this post in threaded view
|

Re: Include sections of files

glaforge
In reply to this post by mojavelinux
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):


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




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




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




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

Reply | Threaded
Open this post in threaded view
|

Re: Include sections of files

LightGuardjp
Great work Dan!


On Wed, Apr 17, 2013 at 3:10 PM, glaforge [via Asciidoctor :: Discussion] <[hidden email]> wrote:
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):


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




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




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




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




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



--
Reply | Threaded
Open this post in threaded view
|

Re: Include sections of files

mojavelinux
Administrator
In reply to this post by glaforge
On Wed, Apr 17, 2013 at 3:10 PM, glaforge [via Asciidoctor :: Discussion] <[hidden email]> wrote:
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?

That is correct.
 

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

Exactly. It's a throwaway line.

Btw, I updated the syntax to be more AsciiDoc-like and less likely to match something it shouldn't:

// tag::classdef[]
class Bar {}
// end::classdef[]

Cheers,

-Dan


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

Reply | Threaded
Open this post in threaded view
|

Re: Include sections of files

glaforge
mojavelinux wrote
[...]
Exactly. It's a throwaway line.
Perfect!

mojavelinux wrote
[...]
Btw, I updated the syntax to be more AsciiDoc-like and less likely to match
something it shouldn't:

// tag::classdef[]
class Bar {}
// end::classdef[]
Right, that makes sense, and is indeed coherent with AsciiDoc's usual syntax.
And as you said, it'll avoid some wrong matches where it shouldn't.

Thanks again for this effort!