Includes - Linking instead of Inlining

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

Includes - Linking instead of Inlining

ghillert
Hi,

Maybe I am missing the obvious - How can Asciidoctor be instructed to create links to other sections rather than inlining them when doing a "include::GettingStarted.asciidoc[]"? E.g. for docbook I would rather like to generate

<xi:include href="./GettingStarted.xml"/> instead of inlining the contents of the file.

How can that be done?

Thanks a lot!

Cheers,

Gunnar
Reply | Threaded
Open this post in threaded view
|

Re: Includes - Linking instead of Inlining

mojavelinux
Administrator
Gunnar,

I never thought about this use case, but it makes a lot of sense.

There are two parts to this:

1. The referenced files need to be processed individually (from AsciiDoc to DocBook)
2. The include::[] macro needs to insert an <xi:include> instead of reading the content into the AsciiDoc source being processed

This can be accomplished today in Asciidoctor using a deprecated API. I say deprecated because it was a stopgap for handling include files before Asciidoctor had a proper secure mode. It will be replaced with proper extension callbacks.

Here's how you could get it done today (I'm assuming in this code you are working only w/ DocBook):

Asciidoctor.render_file('master.ad', :in_place => true, :backend => :docbook, :safe => :safe) {|file, doc|
  # carry over the attributes to the linked document
  attributes = doc.attributes.dup
  # remove doctitle so that the document title is not added to the linked file
  attributes.delete('doctitle')
  Asciidoctor.render_file(file, :in_place => true, :backend => :docbook, :base_dir => doc.base_dir, :safe => doc.safe, :attributes => attributes)
  %(++++
<xi:include href="./#{file.sub('.ad', '.xml')}"/>

++++).lines.entries
}

What this code is invoke the closure each time an include::[] macro is encountered. The referenced file is rendered using the Asciidoctor render API. An <xi:include> is then returned to replace the include::[] macro line. You may have to tune the parameters you pass to the nested Asciidoctor.render_file invocation.

I'm currently working on designing an extension mechanism for Asciidoctor. When that's in place, the closure would be replaced with a registered handler, something roughtly like:

Asciidoctor.register_handler(:include, DocBookIncludeLinker)

-Dan



On Tue, Jun 4, 2013 at 6:59 PM, Gunnar Hillert [via Asciidoctor :: Discussion] <[hidden email]> wrote:
Hi,

Maybe I am missing the obvious - How can Asciidoctor be instructed to create links to other sections rather than inlining them when doing a "include::GettingStarted.asciidoc[]"? E.g. for docbook I would rather like to generate

<xi:include href="./GettingStarted.xml"/> instead of inlining the contents of the file.

How can that be done?

Thanks a lot!

Cheers,

Gunnar


If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Includes-Linking-instead-of-Inlining-tp279.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: Includes - Linking instead of Inlining

mojavelinux
Administrator
In reply to this post by ghillert
One more thing to note. You have to use the latest master to do this since the second argument (the document) was not being passed to the block until just now :)

-Dan


On Thu, Jun 6, 2013 at 2:37 AM, Dan Allen <[hidden email]> wrote:
Gunnar,

I never thought about this use case, but it makes a lot of sense.

There are two parts to this:

1. The referenced files need to be processed individually (from AsciiDoc to DocBook)
2. The include::[] macro needs to insert an <xi:include> instead of reading the content into the AsciiDoc source being processed

This can be accomplished today in Asciidoctor using a deprecated API. I say deprecated because it was a stopgap for handling include files before Asciidoctor had a proper secure mode. It will be replaced with proper extension callbacks.

Here's how you could get it done today (I'm assuming in this code you are working only w/ DocBook):

Asciidoctor.render_file('master.ad', :in_place => true, :backend => :docbook, :safe => :safe) {|file, doc|
  # carry over the attributes to the linked document
  attributes = doc.attributes.dup
  # remove doctitle so that the document title is not added to the linked file
  attributes.delete('doctitle')
  Asciidoctor.render_file(file, :in_place => true, :backend => :docbook, :base_dir => doc.base_dir, :safe => doc.safe, :attributes => attributes)
  %(++++
<xi:include href="./#{file.sub('.ad', '.xml')}"/>

++++).lines.entries
}

What this code is invoke the closure each time an include::[] macro is encountered. The referenced file is rendered using the Asciidoctor render API. An <xi:include> is then returned to replace the include::[] macro line. You may have to tune the parameters you pass to the nested Asciidoctor.render_file invocation.

I'm currently working on designing an extension mechanism for Asciidoctor. When that's in place, the closure would be replaced with a registered handler, something roughtly like:

Asciidoctor.register_handler(:include, DocBookIncludeLinker)

-Dan



On Tue, Jun 4, 2013 at 6:59 PM, Gunnar Hillert [via Asciidoctor :: Discussion] <[hidden email]> wrote:
Hi,

Maybe I am missing the obvious - How can Asciidoctor be instructed to create links to other sections rather than inlining them when doing a "include::GettingStarted.asciidoc[]"? E.g. for docbook I would rather like to generate

<xi:include href="./GettingStarted.xml"/> instead of inlining the contents of the file.

How can that be done?

Thanks a lot!

Cheers,

Gunnar


If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Includes-Linking-instead-of-Inlining-tp279.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML



--



--