Asciidoctor :: Discussion

Re: Attribute substitution inside source block

Posted by mojavelinux on
URL: https://discuss.asciidoctor.org/Attribute-substitution-inside-source-block-tp406p421.html

Emmanuel,

Thank you for presenting this use case so thoroughly. I'm going to go stick my head in the think tank and work out some proposals to approaching it.

Btw, on a side note, there are two ways to define an attribute outside of the document. If you define it in the normal way, it takes precedence over the attribute in the document. For example:

-a name=value

However, you can define it so that it will only be applied if it's not already defined in the document by adding a trailing @ to the value. For example:

-a name=value@

In other words, you can control which source is the authority for a given attribute.

(Another point that needs documenting in the syntax quick reference).

-Dan


On Tue, Jul 30, 2013 at 1:20 AM, Emmanuel Bernard [via Asciidoctor :: Discussion] <[hidden email]> wrote:
I understand where you come from. Let me give you my use case.

hibernate.org is a product family with independent project life cycles.
In order to automatize things, we use site.yml as a metadata repo for
the latest stable release for each project etc. The structure is not too
complex but definitely more complex than the usual top level site.yml
variable

https://github.com/hibernate/hibernate.org/blob/hibernate-rebase-of-jbossorg/_config/site.yml#L13

Now comes a getting started guide where the project version is
mentioned. I'd like this to be the latest stable version taken from the
site.yml so that version numbers don't start to be duplicated. That has
been a big team concern to stream line releases and changes through the
IT nebula.

Due to the fairly complex data structure, copying the data inside
:asciidoctor or even a mechanism like you propose in

https://github.com/awestruct/awestruct/issues/328

is not quite enough.

To make the document independent but still (metadata) connected. We
could think of a binding approach between asciidoc attributes and
awestruct variables or computed values. We would need a default value
for these in the AsciiDoc document and an external structure defining
the binding.

That's the option I can think of but it is not quite satisfactory for a
few small reasons:

- default values will become out of date
- overriding the value defined in the asciidoc document with the
  computed value seem the exact opposite to the implicit rule: the
  closer to the doc the higher priority

How do you guys keep your asciidoc metadata in sync with other sources?

Emmanuel

On Mon 2013-07-29 17:38, mojavelinux [via Asciidoctor :: Discussion] wrote:

>
>
> Emmanuel,
>
> Since Haml interpolates all text, the trick of using Ruby variable
> expressions in AsciiDoc attribute assignments indeed works. As you have
> discovered, the same does not apply for standalone documents.
>
> There is an outstanding pull request to enable interpolation in AsciiDoc
> documents. However, I strongly advise against it because it couples the
> document to the Awestruct (and Ruby) environment. It's best that these
> variables be assigned externally to preserve the portability of the
> document (which, in this case, is far more than just dogmatic).
>
> I do think that it is reasonable to push the site variables into the
> AsciiDoc context as attributes and have filed an issue to track this
> enhancement.
>
> https://github.com/awestruct/awestruct/issues/328
>
> In the meantime, you can set these AsciiDoc attributes explicitly in
> _config/site.yml.
>
> -Dan
>
>
> On Mon, Jul 29, 2013 at 1:40 PM, Emmanuel Bernard [via Asciidoctor ::
> Discussion] <[hidden email]> wrote:

>
> > Cool :) that saves me from a nasty piece of haml.
> >
> > On a side note related to the asciidoctor + awestruct integration. I
> > managed to do the following in a haml file
> >
> > :asciidoc
> >   :tagline: #{site.tagline}
> >
> >   == Some title
> >
> >   My tagline is {tagline}
> >
> > Which lets me pass any data from Awestruct to Asciidoc and add some ruby
> > flexibility.
> >
> > I wanted to do the same on a 'pure' .adoc file but it seems the same trick
> > is not available.
> >
> > Is there a way to achieve that?
> > - pass the site data
> > - use ruby to compute some more complex aggregation
> >
> > Emmanuel
> >
> > On 29 juil. 2013, at 20:44, "mojavelinux [via Asciidoctor :: Discussion]" <[hidden
> > email] <http://user/SendEmail.jtp?type=node&node=410&i=0>> wrote:

> >
> > Emmanuel,
> >
> > Good news, AsciiDoc provides a way! (which is faithfully implemented by
> > Asciidoctor).
> >
> > Just about anywhere in AsciiDoc you can control which substitutions are
> > used. In your case, you are interested in the "attributes" substitution.
> >
> > Here's how to control it.
> >
> > [source,xml]
> > [subs="verbatim,attributes"]
> > .maven dependency
> > ----
> > <dependency>
> >   <groupId>org.hibernate</groupId>
> >   <artifactId>hibernate-search</hibernate-search>
> >   <version>{version}</version>
> > </dependency>
> > ----
> >
> > (I use two attribute lines to be compatible with AsciiDoc. Asciidoctor
> > properly handles putting them all in one line).
> >
> > The only downside is that you have to specify all the substitutions you
> > want when you override. That's why the "verbatim" is necessary. "verbatim"
> > is an alias for "specialcharacters,callouts". So the effective
> > substitutions are now "specialcharacters,callouts,attributes".
> >
> > Please note that this will not work in the preview on GitHub since it was
> > implemented in a later version than they are running (I'm still working on
> > getting them upgraded).
> >
> > Also, I'll add this to the quick reference guide since the question has
> > come up a few times now.
> >
> > -Dan
> >
> >
> > On Mon, Jul 29, 2013 at 7:45 AM, Emmanuel Bernard [via Asciidoctor ::
> > Discussion] <[hidden email]<http://user/SendEmail.jtp?type=node&node=407&i=0>
> > > wrote:

> >
> >> Hey all,
> >>
> >> I get that source blocks don't enjoy substitutions which would be
> >> dangerous OOTB but how would you solve such scenario
> >>
> >> = Some getting started guide
> >> Emmanuel
> >> :version: 1.0.0.Final
> >>
> >> To embed your library, use the following maven snippet
> >>
> >> [source, xml]
> >> .maven dependency
> >> ----
> >> <dependency>
> >>   <groupId>org.hibernate</groupId>
> >>   <artifactId>hibernate-search</hibernate-search>
> >>   <version>{version}</version>
> >> </dependency>
> >> ----
> >>
> >> Today the {version} string is reproduced verbatim. how would you address
> >> this use case?
> >>
> >> Emmanuel
> >>
> >> ------------------------------
> >>  If you reply to this email, your message will be added to the
> >> discussion below:
> >>
> >> http://discuss.asciidoctor.org/Attribute-substitution-inside-source-block-tp406.html
> >>  To start a new topic under Asciidoctor :: Discussion, email [hidden
> >> email] <http://user/SendEmail.jtp?type=node&node=407&i=1>
> >> To unsubscribe from Asciidoctor :: Discussion, click here.
> >> NAML<http://discuss.asciidoctor.org/template/NamlServlet.jtp?macro=macro_viewer&id=instant_html%21nabble%3Aemail.naml&base=nabble.naml.namespaces.BasicNamespace-nabble.view.web.template.NabbleNamespace-nabble.view.web.template.NodeNamespace&breadcrumbs=notify_subscribers%21nabble%3Aemail.naml-instant_emails%21nabble%3Aemail.naml-send_instant_email%21nabble%3Aemail.naml>
> >>
> >
> >
> >
> > --
> > Dan Allen | http://google.com/profiles/dan.j.allen
> >
> >
> > ------------------------------
> >  If you reply to this email, your message will be added to the discussion
> > below:
> >
> > http://discuss.asciidoctor.org/Attribute-substitution-inside-source-block-tp406p407.html
> >  To unsubscribe from Attribute substitution inside source block, click
> > here.
> > NAML<http://discuss.asciidoctor.org/template/NamlServlet.jtp?macro=macro_viewer&id=instant_html%21nabble%3Aemail.naml&base=nabble.naml.namespaces.BasicNamespace-nabble.view.web.template.NabbleNamespace-nabble.view.web.template.NodeNamespace&breadcrumbs=notify_subscribers%21nabble%3Aemail.naml-instant_emails%21nabble%3Aemail.naml-send_instant_email%21nabble%3Aemail.naml>
> >
> >
> >
> > ------------------------------
> >  If you reply to this email, your message will be added to the discussion
> > below:
> >
> > http://discuss.asciidoctor.org/Attribute-substitution-inside-source-block-tp406p410.html
> >  To start a new topic under Asciidoctor :: Discussion, email
> > [hidden email]
> > To unsubscribe from Asciidoctor :: Discussion, click here<

> > .
> > NAML<http://discuss.asciidoctor.org/template/NamlServlet.jtp?macro=macro_viewer&id=instant_html%21nabble%3Aemail.naml&base=nabble.naml.namespaces.BasicNamespace-nabble.view.web.template.NabbleNamespace-nabble.view.web.template.NodeNamespace&breadcrumbs=notify_subscribers%21nabble%3Aemail.naml-instant_emails%21nabble%3Aemail.naml-send_instant_email%21nabble%3Aemail.naml>
> >
>
>
>
> --
> Dan Allen | http://google.com/profiles/dan.j.allen
>
>
> _______________________________________________
> If you reply to this email, your message will be added to the discussion below:
> http://discuss.asciidoctor.org/Attribute-substitution-inside-source-block-tp406p411.html
>
> To unsubscribe from Attribute substitution inside source block, visit

To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML



--
Dan Allen | http://google.com/profiles/dan.j.allen
Free forum by Nabble Edit this page