Adding subs="attributes" to source block breaks callout rendering and shows (invalid) warnings

[egoexpress]

Using the callout example from the docs, everything is rendered correctly in the resulting PDF.

[source,ruby]
----
require 'asciidoctor'  # <1>

Asciidoctor.convert_file 'mysample.adoc'  # <2>
----
<1> Imports the library
<2> Reads, parses, and converts the file

Adding subs="attributes" to it (so I can use attributes in the form of variables inside the source block) throws (imho invalid) warnings during the callout parsing. Code example:

:myvar: 123
[source,ruby,subs="attributes"]
----
require 'asciidoctor'  # <1>
{myvar}

Asciidoctor.convert_file 'mysample.adoc'  # <2>
----
<1> Imports the library
<2> Reads, parses, and converts the file

The result of the asciidoctor-pdf call:

asciidoctor: WARNING: arc42-template.adoc: line 41: no callouts refer to list item 1
asciidoctor: WARNING: arc42-template.adoc: line 42: no callouts refer to list item 2
Failed to parse formatted text: require 'asciidoctor'  # <1>
123
Asciidoctor.convert_file 'mysample.adoc'  # <2>

The resulting PDF shows the callouts under the code example. However, the references inside the source code (e.g. "# <1>") are not rendered correctly. So this is a combination of invalid rendering in the final PDF and warning to invalid callout references which are not correct.

[ysb33r]

Try subs="+attributes"

[mojavelinux]

Exactly. subs="attributes" does exactly what you ask it to do. It only substitutes attributes and nothing else. It's the equivalent of a passthrough block.

You either need to specify the complete list of substitutions, subs="verbatim,attributes" or, as @ysb33r recommended, you can use the shorthand, subs="+attributes". But what you probably want to do is substitute attributes first, which would be subs="attributes+" (or even shorter, subs=attributes+).

[mojavelinux]

@egoexpress I'm curious, did you read somewhere that subs="attributes" would work? I ask because people keep getting confused about this and I want to know if there's some documentation that needs to be updated.

Btw, here's the documentation on incremental substitutions: http://asciidoctor.org/docs/user-manual/#incremental-substitutions

[egoexpress]

@mojavelinux @ysb33r Thanks for the pointers and the explanation.

I stumbled on a blog post during my Google search (http://mrhaki.blogspot.de/2014/05/awesome-asciidoc-substitute-attribute.html - at nr. 2 in my Google search ranking for 'asciidoctor subs attributes') that explained the attributes attribute without mentioning that it overwrites the default replacement behaviour.

As callouts are replaced by default without specifying a parameter, I thought this behaviour would stay and subs="attributes" would be additional. The part you mentioned in the docs now makes it much clearer.

[mojavelinux]

Thanks for pointing that out, @egoexpress. I let Hubert know and he's already updated the post. Copy-paste power has been restored!

[kameshsampath]

I am having a similar issue when using code blocks within tabset (https://gitlab.com/antora/antora-asciidoctor-extensions/tree/master/tabs-block) and define a partial like:

#tag::istio-rules[]
[tabs]
=====
kubectl::
+
--
[#istio-rules-{doc-sec}-{istio-file}]
[source,bash,subs="+macros,+attributes"]
----
kubectl -n tutorial{namespace-suffix} {k8s-cmd-opt} -f link:{github-repo}/{istiofiles-dir}/{istio-file}[istiofiles/{istio-file}]
----
--
oc::
+
--
[#istio-rules-oc-{doc-sec}-{istio-file}]
[source,bash,subs="+macros,+attributes"]
----
oc -n {tutorial}{namespace-suffix} {k8s-cmd-opt} -f link:{github-repo}/{istiofiles-dir}/{istio-file}[istiofiles/{istio-file}]
----
--
=====
#end::istio-rules[]

And use include like:

:doc-sec: cb-timeout
:k8s-cmd-opt: create
:istio-file: virtual-service-recommendation-timeout.yml
include::ROOT:partial$command-snippets.adoc[tag=istio-rules]

I am seeing the vars that I pass are not used in source block and I keep getting warnings like skipping reference to missing attribute: istio-file

@mojavelinux any thoughts ?

[mojavelinux]

@kameshsampath Are you using Asciidoctor PDF? Because this issue is about Asciidoctor PDF, not the built-in HTML converter (or Antora).

As a side note, attributes should (almost) never be applied last. The subs should be:

subs="attributes+,+macros"

Your problem seems to be specific to Antora (for whatever reason).

[kameshsampath]

sorry @mojavelinux - I noticed after posting, reposted the issue in Antora https://gitlab.com/antora/antora/issues/426

[mojavelinux]

Thanks.