Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
8 posts
|
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 |
Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
Administrator
2681 posts
|
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]> wrote: Hey all, ... [show rest of quote] Dan Allen | http://google.com/profiles/dan.j.allen |
Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
Administrator
2681 posts
|
In reply to this post by Emmanuel Bernard
Btw, I'm thinking of a +/- prefix to allow substitutions to be added and removed without having to specify all of them. For instance: [source,xml] [subs="+attributes"]
.maven dependency ---- <dependency> <groupId>org.hibernate</groupId> <artifactId>hibernate-search</hibernate-search> <version>{version}</version>
</dependency> ---- This one would remove the callouts substitution: [subs="-callouts"]
The plus would always append to the default list. If you need a specific order, then you would need to specify it explicitly. (Unless you have another idea). -Dan On Mon, Jul 29, 2013 at 12:41 PM, Dan Allen <[hidden email]> wrote:
... [show rest of quote] Dan Allen | http://google.com/profiles/dan.j.allen |
Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
Administrator
2681 posts
|
In reply to this post by Emmanuel Bernard
https://github.com/asciidoctor/asciidoctor/issues/522 - Allow substitutions to be added or removed individually
-Dan On Mon, Jul 29, 2013 at 12:44 PM, Dan Allen <[hidden email]> wrote:
... [show rest of quote] Dan Allen | http://google.com/profiles/dan.j.allen |
Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
8 posts
|
In reply to this post by mojavelinux
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
... [show rest of quote]
|
Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
Administrator
2681 posts
|
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. 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:
... [show rest of quote] Dan Allen | http://google.com/profiles/dan.j.allen
|
Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
8 posts
|
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 ... [show rest of quote]
|
Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
Administrator
2681 posts
|
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. ... [show rest of quote] Dan Allen | http://google.com/profiles/dan.j.allen
|
Free forum by Nabble | Edit this page |