HTML output in PDF from using "&" in attribute given through -a

[Hextremist]

== Demo
Oh why oh why __is {whatever} causing__ headaches?

Save this text to a file and then run:

[kjell@localhost tmp]$ asciidoctor-pdf -a whatever="Fish & Chips" test.adoc 
asciidoctor: ERROR: failed to parse formatted text: Oh why oh why <em>is Fish & Chips causing</em> headaches?
[kjell@localhost tmp]$

The resulting pdf looks like this:

Demo
Oh why oh why <em>is Fish & Chips causing</em> headaches?

A workaround is to do
asciidoctor-pdf -a whatever="Fish & Chips" test.adoc
which works, but is counterintuitive, especially since writing :whatever: Fish & Chips in the document header works fine.

Tried to fix this myself in asciidoctor, but I guess it is not the way to do it, since I got no comments (asciidoctor/asciidoctor#3484)

[mojavelinux]

The normal substitution order in the document is specialchars (i.e., XML special characters) followed by attributes. When you define attributes in the document, the specialchars substitution gets applied to the value (at assignment). This substitution is not applied to attributes passed via the CLI or API. Those values must be pre-escaped. This is just a rule.

So the correct usage is as follows:

asciidoctor-pdf -a whatever="Fish & Chips" test.adoc

The described behavior is over a decade old and changing it now would be very disruptive. So we could only do it behind a feature flag or by addressing it in the specification.

Since this behavior is in core, and Asciidoctor PDF has no control over it, I'm closing the issue on this side.

[mojavelinux]

docs issue: https://github.com/asciidoctor/asciidoctor.org/issues/922

[Hextremist]

OK, I understand. It helps that it how it works is documented.