Meaning of :pre snapshot

[Eric Sunshine]

Hi Denis,

I have two questions regarding layouts and snapshots.

First, I utilize a compile rule with multiple layouts:

compile '*' do
filter :erb
filter :kramdown
layout 'extra' if some_condition
layout 'default'
end

The nanoc3 documentation does not explicitly state whether multiple
'layout' invocations are allowed, although it works as expected
("extra" is applied before "default" if 'some_condition' is true). Is
this "correct" behavior intentional? If so, perhaps the documentation
should mention it.

Second, the documentation does not state the precise meaning of
the :pre snapshot when multiple layouts are involved. My expectation,
based upon the documentation (":pre - The content right before the
item is laid out"), had been that :pre would be the content just
before the first layout. In practice, however, it seems that :pre is a
snapshot just before the final layout. Is this intentional? In the
typical case, it seems like it would be more convenient for :pre to
represent content before the first layout (rather than having to take
a snapshot manually as a work-around).

-- ES

[Denis Defreyne]

On 07 Dec 2009, at 03:43, Eric Sunshine wrote:

> I have two questions regarding layouts and snapshots.
>
> First, I utilize a compile rule with multiple layouts:
>
> compile '*' do
> filter :erb
> filter :kramdown
> layout 'extra' if some_condition
> layout 'default'
> end
>
> The nanoc3 documentation does not explicitly state whether multiple
> 'layout' invocations are allowed, although it works as expected
> ("extra" is applied before "default" if 'some_condition' is true). Is
> this "correct" behavior intentional? If so, perhaps the documentation
> should mention it.

Hi Eric,

Laying out a page more than once is supported, and the behaviour is intentional. I’ll update the documentation and mention support for multiple layouts. (Not being able to layout a page twice was one of the limitations in nanoc 2.x that was removed in nanoc 3.x.)

> Second, the documentation does not state the precise meaning of
> the :pre snapshot when multiple layouts are involved. My expectation,
> based upon the documentation (":pre - The content right before the
> item is laid out"), had been that :pre would be the content just
> before the first layout. In practice, however, it seems that :pre is a
> snapshot just before the final layout. Is this intentional? In the
> typical case, it seems like it would be more convenient for :pre to
> represent content before the first layout (rather than having to take
> a snapshot manually as a work-around).

The :pre snapshot is indeed created right before a layout invocation, and an existing :pre snapshot will be overwritten. You are correct that this behaviour is indeed rather unintuitive, and I’m thinking of changing the behaviour in the next version of nanoc (3.1). Instead of doing (in Nanoc3::ItemRep#layout)

snapshot(:pre)

… I’d create the snapshot only if no existing snapshot exists yet, i.e.

snapshot(:pre) unless @content[:pre]

I’m not sure whether anyone relies on the current behaviour (pre being right before the last layout instead of right before the first layout), but changing the behaviour right now is risky, so it’ll have to be delayed until the next major version.

In the mean time, you can create your own snapshot before the first layout invocation, like this:

compile '*' do
filter :erb
filter :kramdown

snapshot :pre_all # <-- new snapshot created here

layout 'extra' if some_condition
layout 'default'
end

Hope this helps,

Denis

--
Denis Defreyne
denis.d...@stoneship.org

[Eric Sunshine]

Hi Denis,

Denis Defreyne wrote:
> The :pre snapshot is indeed created right before a layout
> invocation, and an existing :pre snapshot will be overwritten. You
> are correct that this behaviour is indeed rather unintuitive, and
> I'm thinking of changing the behaviour in the next version of nanoc

> (3.1). I'm not sure whether anyone relies on the current behaviour

> (pre being right before the last layout instead of right before the
> first layout), but changing the behaviour right now is risky, so
> it'll have to be delayed until the next major version.

Agreed. It's better to err on the side of safety and not change it
arbitrarily in a minor version. Clarifying the documentation should be a
good intermediate step.

> In the mean time, you can create your own snapshot before the first
> layout invocation, like this:

Indeed, I did exactly that.

-- ES