Help -- Asciidoctor relative includes broke with upgrade from 0.1.4 to 1.5

classic Classic list List threaded Threaded
7 messages Options
Reply | Threaded
Open this post in threaded view
|

Help -- Asciidoctor relative includes broke with upgrade from 0.1.4 to 1.5

vdanilchenko@vistaprint.com

Hi all,

 

According to Asciidoctor docs, the include directive is supposed to be relative to the current directory; but when I upgraded from Ubuntu 12 to 14, and installed Asciidoctor 1.5, suddenly my old relative includes all broke – now the include only works relative to the doc root, not relative to the current file.

 

Is there some config directive I should stick into site.yaml to get the includes to work relatively again? Or perhaps there’s a way to choose dynamically whether to include relatively or absolutely? (prefixing the include path with ‘./’ doesn’t seem to work).

 

Thanks.

 

Reply | Threaded
Open this post in threaded view
|

Re: Help -- Asciidoctor relative includes broke with upgrade from 0.1.4 to 1.5

LightGuard
Administrator
I've not had time to look at this, Asciidoctor 1.5.0 was released early this morning :)

Sent from Mailbox


On Tue, Aug 12, 2014 at 2:31 PM, Victor Danilchenko <[hidden email]> wrote:

Hi all,

 

According to Asciidoctor docs, the include directive is supposed to be relative to the current directory; but when I upgraded from Ubuntu 12 to 14, and installed Asciidoctor 1.5, suddenly my old relative includes all broke – now the include only works relative to the doc root, not relative to the current file.

 

Is there some config directive I should stick into site.yaml to get the includes to work relatively again? Or perhaps there’s a way to choose dynamically whether to include relatively or absolutely? (prefixing the include path with ‘./’ doesn’t seem to work).

 

Thanks.

 


Reply | Threaded
Open this post in threaded view
|

RE: Help -- Asciidoctor relative includes broke with upgrade from 0.1.4 to 1.5

vdanilchenko@vistaprint.com

Oh wow, so I just got that lucky with timing…

 

Well, I hope someone has a chance to figure out why the inclusion path resolution rules apparently changed.

 

 

From: Jason Porter [mailto:[hidden email]]
Sent: Tuesday, August 12, 2014 4:33 PM
To: [hidden email]
Cc: [hidden email]
Subject: Re: [awestruct] Help -- Asciidoctor relative includes broke with upgrade from 0.1.4 to 1.5

 

I've not had time to look at this, Asciidoctor 1.5.0 was released early this morning :)


Sent from Mailbox

 

On Tue, Aug 12, 2014 at 2:31 PM, Victor Danilchenko <[hidden email]> wrote:

Hi all,

 

According to Asciidoctor docs, the include directive is supposed to be relative to the current directory; but when I upgraded from Ubuntu 12 to 14, and installed Asciidoctor 1.5, suddenly my old relative includes all broke – now the include only works relative to the doc root, not relative to the current file.

 

Is there some config directive I should stick into site.yaml to get the includes to work relatively again? Or perhaps there’s a way to choose dynamically whether to include relatively or absolutely? (prefixing the include path with ‘./’ doesn’t seem to work).

 

Thanks.

 

 

Reply | Threaded
Open this post in threaded view
|

Re: Help -- Asciidoctor relative includes broke with upgrade from 0.1.4 to 1.5

mojavelinux
I ran smack into this issue when I upgraded the asciidoctor.org website. The internal configuration of Asciidoctor inside of Awestruct has a bug that it overwrites the `:base_dir` key if it is assigned the value of null (which is what we want in this case).

Until then, we can leverage Asciidoctor extensions to hack in a fix. Just grab what I'm using on asciidoctor.org.


You essentially need this at the top of your _ext/pipeline.rb file:

[source,ruby]
----
require 'asciidoctor'
require 'asciidoctor/extensions'

Asciidoctor::Extensions.register do
  # workaround for Awestruct 0.5.5
  # (change lib/awestruct/handlers/asciidoctor_handler.rb, line 108 to opts[:base_dir] = @site.config.dir unless opts.key? :base_dir)
  if (docfile = @document.attributes['docfile'])
    @document.instance_variable_set :@base_dir, File.dirname(docfile)
  end
end
----

-Dan


On Tue, Aug 12, 2014 at 3:12 PM, Victor Danilchenko <[hidden email]> wrote:

Oh wow, so I just got that lucky with timing…

 

Well, I hope someone has a chance to figure out why the inclusion path resolution rules apparently changed.

 

 

From: Jason Porter [mailto:[hidden email]]
Sent: Tuesday, August 12, 2014 4:33 PM
To: [hidden email]
Cc: [hidden email]
Subject: Re: [awestruct] Help -- Asciidoctor relative includes broke with upgrade from 0.1.4 to 1.5

 

I've not had time to look at this, Asciidoctor 1.5.0 was released early this morning :)


Sent from Mailbox

 

On Tue, Aug 12, 2014 at 2:31 PM, Victor Danilchenko <[hidden email]> wrote:

Hi all,

 

According to Asciidoctor docs, the include directive is supposed to be relative to the current directory; but when I upgraded from Ubuntu 12 to 14, and installed Asciidoctor 1.5, suddenly my old relative includes all broke – now the include only works relative to the doc root, not relative to the current file.

 

Is there some config directive I should stick into site.yaml to get the includes to work relatively again? Or perhaps there’s a way to choose dynamically whether to include relatively or absolutely? (prefixing the include path with ‘./’ doesn’t seem to work).

 

Thanks.

 

 




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

Re: Help -- Asciidoctor relative includes broke with upgrade from 0.1.4 to 1.5

mojavelinux
In reply to this post by vdanilchenko@vistaprint.com
Victor,

The inclusion path logic in Asciidoctor previously had a bug that ignored the base_dir in some cases (such as when safe was set to :unsafe). That bug was fixed, but now the right behavior is getting in our way because of how Asciidoctor is configured in Awestruct.

I proposed a fix in my other reply. The point of this reply is to provide some more insight about why this is a problem in the first place. The issue is that base_dir is trying to act as both a base path and a jail. To get this right, we need to split this into two separate settings in Asciidoctor. I hoped to get it fixed in 1.5.0, but there just wasn't time to solve it properly...so we deferred it to the next minor version. Here's the issue if you want to get more context or provide feedback.


I have some design notes that I still need to post to that issue about how this all relates to the jail directory. I'll post those as soon as I get a chance.

-Dan


On Tue, Aug 12, 2014 at 2:31 PM, Victor Danilchenko <[hidden email]> wrote:

Hi all,

 

According to Asciidoctor docs, the include directive is supposed to be relative to the current directory; but when I upgraded from Ubuntu 12 to 14, and installed Asciidoctor 1.5, suddenly my old relative includes all broke – now the include only works relative to the doc root, not relative to the current file.

 

Is there some config directive I should stick into site.yaml to get the includes to work relatively again? Or perhaps there’s a way to choose dynamically whether to include relatively or absolutely? (prefixing the include path with ‘./’ doesn’t seem to work).

 

Thanks.

 




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

RE: Help -- Asciidoctor relative includes broke with upgrade from 0.1.4 to 1.5

vdanilchenko@vistaprint.com

Thanks Dan, this was very useful and insightful.

 

The ironic thing is that the current incorrect behavior is actually what I had wanted in the beginning (I need to include a single global component in all documents of a project, including documents in subdirectory), but I can see how this would be a massive security hole.

 

So what you are saying is that the next AweStruct  release should revert the whole thing to the previous path resolution behavior, correct?

 

From: Dan Allen [mailto:[hidden email]]
Sent: Tuesday, August 12, 2014 5:49 PM
To: [hidden email]
Subject: Re: [awestruct] Help -- Asciidoctor relative includes broke with upgrade from 0.1.4 to 1.5

 

Victor,

 

The inclusion path logic in Asciidoctor previously had a bug that ignored the base_dir in some cases (such as when safe was set to :unsafe). That bug was fixed, but now the right behavior is getting in our way because of how Asciidoctor is configured in Awestruct.

 

I proposed a fix in my other reply. The point of this reply is to provide some more insight about why this is a problem in the first place. The issue is that base_dir is trying to act as both a base path and a jail. To get this right, we need to split this into two separate settings in Asciidoctor. I hoped to get it fixed in 1.5.0, but there just wasn't time to solve it properly...so we deferred it to the next minor version. Here's the issue if you want to get more context or provide feedback.

 

 

I have some design notes that I still need to post to that issue about how this all relates to the jail directory. I'll post those as soon as I get a chance.

 

-Dan

 

On Tue, Aug 12, 2014 at 2:31 PM, Victor Danilchenko <[hidden email]> wrote:

Hi all,

 

According to Asciidoctor docs, the include directive is supposed to be relative to the current directory; but when I upgraded from Ubuntu 12 to 14, and installed Asciidoctor 1.5, suddenly my old relative includes all broke – now the include only works relative to the doc root, not relative to the current file.

 

Is there some config directive I should stick into site.yaml to get the includes to work relatively again? Or perhaps there’s a way to choose dynamically whether to include relatively or absolutely? (prefixing the include path with ‘./’ doesn’t seem to work).

 

Thanks.

 



 

--

Reply | Threaded
Open this post in threaded view
|

Re: Help -- Asciidoctor relative includes broke with upgrade from 0.1.4 to 1.5

mojavelinux

On Wed, Aug 13, 2014 at 5:25 AM, Victor Danilchenko <[hidden email]> wrote:

The ironic thing is that the current incorrect behavior is actually what I had wanted in the beginning (I need to include a single global component in all documents of a project, including documents in subdirectory), but I can see how this would be a massive security hole.


At the moment, you can either have restricted or unrestricted behavior, but not something in between. We need that happy medium option made available in Asciidoctor that lets you set a jail (the project root) but not the base directory. Then, you'll get the expected behavior and the peace of mind of security. Until then, we have to do some sidestepping.
 

 

So what you are saying is that the next AweStruct  release should revert the whole thing to the previous path resolution behavior, correct?


The next Awestruct release should check to see if you are setting the base_dir explicitly to null (in YAML) and honor that by not overwriting the value. Null (which resolves to nil) is a meaningful value in Asciidoctor. You'll still need to set the base_dir to null in your _config/site.yml file, but at least you'll be able to control it :)