Add crucial, missing sentence(s) to Sec. 13.4.1

[andrewcarver]

The section challenged the reader by, first, starting with a paragraph that's only about the "header" substitution group (no mention of attribute entries, which is what the section is allegedly about). Then it follows this paragraph with several that speak only of attribute-entry values (no mention of header substitution!). In vain does the reader scan the text for a link connecting paragraph 1 with the rest.

The minimal missing connection is the one in this text, which we have added to paragraph 2: [The header substitution group] "is applied also to attribute entries' values, whether those entries are in the header or elsewhere in the document".

Our argument for this addition is: 1) At least in our experience and tests of AsciiDoctor, attribute-entries' values do indeed behave as if attribute entries belong to the "header" substitution group described in this section; 2) Mentioning that fact, early in this section, is the only thing that would make the material that was already here hang together logically. 3) This point we suggest be made explicit is in fact the only main point that this section could have conceivably been intended to make. It's therefore arguably the sentence most important to make explicit.

I have taken this opportunity also to move two of paragraph 1's sentences into a new paragraph 2, where I've placed this new, "crucial" sentence. This restructuring intends to improve the topical flow within these paragraphs.

[mojavelinux]

Thank you for this detailed analysis. This is a tricky subject you are well on the way to getting it sorted out.

One of the outstanding problems is around this idea that substitutions are applied to the header. The header is only a conceptual idea. It's not actually the target of substitutions. Here's what's really happening.

It's possible to define attribute entries anywhere in the document (outside of a delimited block). An attribute entry has the following structure:

:name: value

When the attribute entry is processed, the value is the subject of substitutions. By default, the "header" substitution group is applied to the value, which is specialcharacters+attributes. The "header" substitution group is also used on the author names in the implicit author line. These are the only places the "header" substitution group is used (which should really be thought of as "attribute value substitution").

Only if the whole value is wrapped in an inline pass macro are different substitutions applied. For example, this value is configured to only receive the attributes substitution.

:name: pass:a[value]

Other substitutions applied to the value of an attribute depend on where the attribute is referenced. For example, if you use an attribute in a section title:

== {name}

then further substitutions are applied to the value of the referenced attribute. If you want to see the raw value stored in an attribute, you can use the following trick:

[subs=attributes]
++++
{name}
++++

Here you are saying to resolve the attribute, but to not apply any other substitutions.

[andrewcarver]

Excellent, thank you. Yes, I used something similar to that last thing, to test out what was really happening:

pass:a[ {name} ]

Dan, I'd love to see as clear an explanation as yours here, make its way into the User's Manual. But I know that's easier said than done... I'd be willing to try, to help figure out where to put what. Maybe what I've contributed in this PR can help get us started..?

[andrewcarver]

Your insight that the '"header" substitution group should really be thought of as "attribute value substitution"' is helpful. It's getting closer, at least, to the essence of this group.

[andrewcarver]

Dan, does the inline pass macro work at all in the implicit author line? I.e., is it an inherent part of this "header substitution group", wherever it applies? Or, does that macro apply only for attribute-entry values?

If the latter, one way to conceptualize this would be that we need to split them up into two different "substitution groups" (maybe "header" and "attribute-entry"). For otherwise, we've got in the top row of the "Substitution Groups" table (secs. 20.4, 40) an entry (in the Macros column) that cannot be filled in correctly to cover all cases (it would be "inline macro pass only", for attribute-entries; but for author lines, just "X").

[andrewcarver]

Wow, only now did I notice that all those "Elements subject to..." tables (Secs. 40.2-40.6) have a "Header" row, as well as what we've now called the "Attribute Entry Value" row! And, somewhat unsurprisingly, it has the wrong value (a check-mark) in the same two tables (40.5 and 40.6) where the "Attribute Entry Value" row had it wrong... But as you've pointed out, "Header" is not a terribly useful nomenclature, in the context of "Substitution Groups"...

[andrewcarver]

My tests, using 1.5.5-4, indicate that on the author line the inline pass macro does not work.

My suggestion would be, that there is no rationale for combining under the rubric "Header" two substitution scenarios that behave quite differently: they are really two different substitution groups--which could reasonably be called "author" and "attribute-entry", respectively.

[mojavelinux]

My tests, using 1.5.5-4, indicate that on the author line the inline pass macro does not work.

Correct. The inline pass macro is not processed in the implicit author and revision lines.

-which could reasonably be called "author" and "attribute-entry", respectively.

It's not just the author line. It's also the revision line.

When we say "header", what we really mean are the implicit metadata lines. I think we just need to make that clear and we'll have this explanation squared away. Then we can make a corresponding fix to the substitution reference tables.

Thanks for your effort to get this cleared up!

[andrewcarver]

Super! Works for me. Thanks very much, Dan! Let me know if I can help with the rest of the repairs.

[andrewcarver]

I went ahead and did half the remaining repairs (the obvious ones; PR #731 ). I'll defer to you for a good wording for the Macros column in the "Header" rows in Secs. 20.4 and 40.

Thanks again!!