Support nested attributes

[nipafx]

Problem

As it stands, to define nested YAML with Asciidoc attributes requires "inline YAML". E.g.:

header:
  color: black
  image: url

:page-header: { color: black, image: url }

This has several disadvantages:

• the syntax is cumbersome (especially when nested deeper) and easy to get wrong
• it mixes Asciidoc attributes (with two colons) and YAML hashes (single colon)
• the parsed attribute replaces any existing value

For the latter consider the case that header/color was already defined (e.g. in _config.yml) and the document contains this:

:page-header: { image: url }

This unsets header/color, which is neither expected nor desired (typically).

Acceptance

A great way to fix this would be a syntax that makes it easy and natural to define nested attributes in pure Asciidoc. That should fix the first two problems and completely circumvent the third.

[djencks]

This seems like a project for the AsciiDoc spec project, not a user of Asciidoctor.

[mojavelinux]

I think it comes down to intent. If the point is to provide a way to pass data to the templates so that they can more easily access complex information, then this does pertain to this integration.

Right now, there is no plan to supported nested data in AsciiDoc attributes as it really goes outside of the scope of what they were designed for. But the page attributes in Jekyll are different. They are not really designed for AsciiDoc, but rather as an integration for passing data from the document to the template. Therefore, I think this should still be considered in this integration.

The goal of the AsciiDoc spec is not to start defining new things out of the blue. It's about standardizing things that exist. So this idea has to first be proven in software, and this is as good a place as any for doing that.

[djencks]

I see how the integration could support nested global attributes set in _config.yml , but I don't see how the integration could alter Asciidoctor's header parsing to allow a pure AsciiDoc syntax for nested attributes. What do have in mind?

[mojavelinux]

Argh. What I had in my mind doesn't work out in practice. I was thinking that the page attribute parser could recognize multi-line YAML and parse it appropriately. But that turns out to be problematic since Asciidoctor collapses newlines.

Without any change, it's already possible to spread the attribute value over multiple lines. However, it does require the use of value continuation characters:

:page-header: { \
  color: black, \
  image: url \
}

This equates to:

:page-header: { color: black, image: url }

Regarding this part of the request:

the parsed attribute replaces any existing value

The page attribute processor could consider whether the new and old value are both maps and do a merge instead. Though we'd have to think about how to express that intent. And that adds extra complexity.

Regarding this part of the request:

it mixes Asciidoc attributes (with two colons) and YAML hashes (single colon)

This is just the nature of the integration. AsciiDoc itself doesn't recognize YAML values. We added that to this integration so you could take it further. But we're not going to address the fact that these two models are different. They are different. That's the whole point.

In the end, perhaps there really isn't much we can do here (without some fundamental change in AsciiDoc itself). This is just taking AsciiDoc attributes much further than what they are designed to do. In this particular case, front matter would be the better choice.

[djencks]

I'm not sure what you mean by "collapses newlines" here.

= Things to do
:ex1: this is a multi-line
 attribute how does it turn
 out.
:ex2: foo

{ex1}
{ex2}

renders as

Things to do
this is a multi-line foo

I don't know what happened to the two lines in between the attribute names in the header.

It would involve a change to Asciidoctor header parsing, and thus, as I originally said, presumably an AsciiDoc spec change, but it seems plausible to me that header attributes (those before the first blank line) could extend from the attribute name (delineated by ::) to the next attribute name or blank line. This would be a string when used in AsciiDoc and the jekyll adapter could continue to convert it to yaml, no longer insisting on one line.

I also don't understand your position on new AsciiDoc features. You've blocked implementing things like nested open blocks in Asciidoctor on the grounds that they need to be spec changes first, and here you seem to be saying that the spec can't consider a change without an existing implementation. How can a new spec feature come to be?

How could I propose a change to header attribute parsing in Asciidoctor with a path forward?

[mojavelinux]

I don't know what happened to the two lines in between the attribute names in the header.

You are missing the line continuation character. Without it, the value will terminate and so will the header. See https://docs.asciidoctor.org/asciidoc/latest/attributes/wrap-values/ (that page is missing some important terminology)

[mojavelinux]

You've blocked implementing things like nested open blocks in Asciidoctor on the grounds that they need to be spec changes first

No, I only blocked them while the spec process was getting established so that we weren't trying to hit a moving target. And, in truth, it wasn't me who blocked it but it rather the request came from the community.

[mojavelinux]

How could I propose a change to header attribute parsing in Asciidoctor with a path forward?

First, I think it should be documented here that it's possible to define a YAML value using multiple lines by making use of a line continuation, as I showed. It's not the most elegant syntax in the world, but it is possible and should at least be presented.

The next step would be to consider whether to support merging map values when an attribute is defined in both the document and the config file. If the answer is no, that it won't be possible, then that's the decision.

As for AsciiDoc, frankly, I don't think the attribute parsing should be changed, at least not in this way. AsciiDoc is not YAML and shouldn't try to be. If there is any change, it should be that it should be a) simpler to define multi-line attribute values and b) a way to preserve the newlines. That would then enable an integration like this one without actually supporting it directly. And that should be raised with the asciidoc-lang project in the weeks to come.

[djencks]

I don't know what happened to the two lines in between the attribute names in the header.

You are missing the line continuation character. Without it, the value will terminate and so will the header. See https://docs.asciidoctor.org/asciidoc/latest/attributes/wrap-values/ (that page is missing some important terminology)

My point with this example was that having non-blank non-attribute lines in the header doesn't appear to totally break Asciidoctor header parsing. For instance, there's no visible error and it doesn't end the header. Therefore, that might be a hint that multi-line attribute values can plausibly be parsed as such without too many giant breaking changes.

[djencks]

First, I think it should be documented here that it's possible to define a YAML value using multiple lines by making use of a line continuation, as I showed. It's not the most elegant syntax in the world, but it is possible and should at least be presented.

That's easy at least!

[djencks]

The next step would be to consider whether to support merging map values when an attribute is defined in both the document and the config file. If the answer is no, that it won't be possible, then that's the decision.

Thinking about this makes me think that interpretation as yaml is currently happening at the wrong time. Asciidoctor can't deal with a yaml value, but having a yaml expression string as an attribute value set in _config.yml should be supported. Therefore I think the interpretation as yaml should occur when converting AsciiDoc page attributes to Jekyll page variables.

Perhaps attributes that are intended to be translated to Jekyll page variables as yaml with merging could be under a separate key in the config. The merging has to happen after both inputs, from the config and the page, have been converted to objects. This needs a whole new mechanism, and rather than trying to squeeze a "mergeable" flag onto the existing key a new flag seems appropriate.

[djencks]

As for AsciiDoc, frankly, I don't think the attribute parsing should be changed, at least not in this way. AsciiDoc is not YAML and shouldn't try to be. If there is any change, it should be that it should be a) simpler to define multi-line attribute values and b) a way to preserve the newlines. That would then enable an integration like this one without actually supporting it directly. And that should be raised with the asciidoc-lang project in the weeks to come.

I thought it went without saying that AsciiDoc attributes need to be string values, so the change there could only be to make explicitly multi-line attribute values in the header recognized/supported, and that any conversion to another format is not going to be part of AsciiDoc/Asciidoctor. My example seemed to indicate that although multi-line yaml isn't currently recognized as a single attribute, at least it didn't cause loud explosions :-)

[mojavelinux]

I think the interpretation as yaml should occur when converting AsciiDoc page attributes to Jekyll page variables.

Agreed, though that's how it currently works. https://github.com/asciidoctor/jekyll-asciidoc/blob/master/lib/jekyll-asciidoc/integrator.rb#L69-L74