asciidoctor / asciidoctor.org

:globe_with_meridians: Asciidoctor project site. Composed in AsciiDoc. Baked with Awestruct.
https://asciidoctor.org
Other
322 stars 805 forks source link

Emend "Header" rows, Elements tables, secs. 40.5-6 #731

Closed andrewcarver closed 6 years ago

andrewcarver commented 6 years ago

In Sections 40.5 (Macros substitutions) and 40.6 (Post Replacements substitutions), change the 2d column values, from check-marks to "X"s, in the "Header" rows in the "Elements subject to [whichever type of] text substitution" tables.

This is related to the repairs discussed in PRs #729 and #730.

mojavelinux commented 6 years ago

Thanks!

I wonder if we should put an asterisk on the X in the Header row for macros to say that the inline pass macro can be used. (Though it is processed first instead of in the normal order).

mojavelinux commented 6 years ago

Basically, the inline pass macro around an attribute value is checked first. If it is there, it changes the substitutions that are used. Otherwise, the value is processed with the header substitution group. So it's sort of a preprocessor.

andrewcarver commented 6 years ago

If you're talking about the table in 40.5, then the problem with doing that is that you've already covered that info in the table's top row (the "Attribute Entry Value" row--to which you added, quite rightly, the note "inline pass macro only"). What your question does bring to light, though, is that if we do indeed keep all these subs under the rubric "Header", then it's awkward to keep the row I'm talking about here named "Header", in parallel with a separate row about "Attribute Entry Value". Maybe to avoid confusion, rather than put in the asterisk you suggested we should rename that row (in Secs. 40.2-40.6) "Header metadata"...

andrewcarver commented 6 years ago

P.S. Your explanation about pass:[] being a sort of "preprocessor" there is helpful. It helps me see better that the subs in this "group," except for this exceptional, "preprocessor" twist, are all handled the same.

Nevertheless, we have, currently, in the Secs. 40.2-5 tables two pertinent rows. So, again, since both of them have to do with the "Header" substitution group, I think neither of them should be named "Header" -- too confusing.

andrewcarver commented 6 years ago

But I wouldn't mind if you wanted to add that helpful explanation about the "sort of a preprocessor", to your already useful clarifications in Sec. 13.4.1 :))

andrewcarver commented 6 years ago

For a first stab at which, please see now #733

andrewcarver commented 6 years ago

On 4th or 5th thought, "Header Metadata" is rather ambiguous. (Any attributes defined in the header are metadata.) So, to disambiguate the "Header" label, in its rows in Secs. 40.2-40.6, how about "Implicit Author/ Revision"?

mojavelinux commented 6 years ago

How about "Implicit Metadata" (or "Implicit Metadata Lines")? Let's follow-up on that using a separate issue.