Re: Proposing new include directive

[Tristan Van Berkom <tristan vanberkom codethink co uk>]

Hi Jürg,

On Thu, 2018-04-12 at 07:50 +0200, Jürg Billeter wrote:
> Hi Tristan,
>
> This proposal looks good to me overall.
>
> On Fri, 2018-03-30 at 17:04 +0900, Tristan Van Berkom wrote:
> >   Note about junction paths
> >   ~~~~~~~~~~~~~~~~~~~~~~~~~
> >   Junction paths are "already a thing", however they are presently only
> >   used for display purposes.
> >
> >   That said, since `project.refs` work has recently landed, it has
> >   already become important to be able to address elements using these
> >   junction paths - some minor work needs to be done in order to support
> >   things such as:
> >
> >      bst track junction.bst:element.bst
>
> If we start supporting this everywhere, maybe we should reconsider
> supporting it also for dependencies for consistency? I don't like
> having two syntax variants for a single purpose but I do like
> consistency.

You mean in the YAML ?

Like this:

  depends:
  - junction.bst:element.bst

I don't know, I was reluctant about this because in the YAML we have a
consistent string-or-dict approach which I did not want to break.

I'm not sure that we would gain *much* consistency here, on the command
line it is impossible to specify a dict, so it seems natural to support
this only for display purposes and on the command line.

On the other hand, it's not a huge problem if we do support it in the
YAML I guess, but I would say this is straying off topic of the
proposal.

> >   How include composition works
> >   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> >   The composition of an included YAML file into the including
> >   dictionary works in the opposite direction of the (?) conditional
> >   directives.
> >
> >   With (?) directives, the conditional YAML fragment *overrides*
> >   what is declared in the dictionary declaring the conditional, one
> >   can say that the composited YAML fragment is "on top"
> >
> >   With the (@) include directive, composition happens the other way
> >   around, such that it first replaces the including dictionary, and
> >   the declaring dictionary is composited over the included one.
> >
> >   One can say then that an included YAML fragment is composited
> >   "underneath" the including dictionary.
>
> We need to clarify how this works with a list of includes. I would
> expect the first include to be composited underneath the second include
> and the result of that composition is then composited underneath the
> including dictionary. Does this match your plans?

Yes this matches the plan, I may have phrased this in a strange way
though.

Suffice to say that for the user: the effect is that every subsequent
include overrides the result of the previous include, and the including
dictionary overrides anything in the includes - I think that would be
the desired effect.

Cheers,
    -Tristan

>