New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Suppress warning about missing attribute reference when substituting value for doctitle attribute #4024
Comments
I recognize this still a compromise, but one that is grounded in practical usage. We can revisit the behavior in a future minor or major for further refinement. |
…stituting value for doctitle attribute suppress missing attribute warning when applying substitutions to implicit document title to assign to doctitle attribute
@graphitefriction The release notes / docs should state that if you want to use an attribute reference in the document title line (the level-0 section title), and you also need to reference the |
…cessing value for doctitle attribute suppress missing attribute warning when applying substitutions to implicit document title to assign to doctitle attribute
…cessing value for doctitle attribute suppress missing attribute warning when applying substitutions to implicit document title to assign to doctitle attribute author should assume there's an implicit attribute entry for doctitle directly after the document title (level-0 section title)
Another possible approach is to defer substituting attributes in the intrinsic doctitle attribute until the end of the document header. This has the drawback that if the document title contains an attribute reference, the author can't access the resolved value within the document header using the doctitle attribute even by reordering the attribute entries. I think it's more intuitive to assume that there's an implicit attribute entry for the doctitle attribute that immediately follows the document title (level-0 section title). That also gives the author the most control. Thus, I think the original proposal is the right one for now. |
…cessing value for doctitle attribute (PR asciidoctor#4025) suppress missing attribute warning when applying substitutions to implicit document title to assign to doctitle attribute author should assume there's an implicit attribute entry for doctitle directly after the document title (level-0 section title)
As a result of the fix for #3106, the processor began substituting attribute references in the document title line when assigning the
doctitle
attribute. (See example below). This meant that, now, any attribute referenced in the document title line must be defined above the document title line. Otherwise, the processor won't be able to resolve it.By default, the user won't notice this problem since the default behavior for a missing attribute is to skip it (i.e., leave it unresolved). Yet, if the
missing-attribute
attribute is set towarn
, then the processor will emit a warning. The problem is, it's unlikely the user will know why this warning is being emitted and it's equally unlikely it will have any impact on the document. It would only be a problem if the{doctitle}
attribute reference is used somewhere in the document, which is when the unresolved attribute reference would appear.The processor should be updated to skip missing attribute references in the document title line when assigning the
doctitle
attribute. (Keep in mind, these attribute references will still be resolved again the document title is displayed, at which point an actionable warning will be emitted if the attribute reference is still unresolved).Here's an example:
Incorrect
Correct
However, if you don't to make use of the
doctitle
attribute, either order is acceptable.The text was updated successfully, but these errors were encountered: