Skip to content
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

Closed
mojavelinux opened this issue Apr 17, 2021 · 3 comments
Assignees
Labels
bug v2.0.14 Issues resolved in the 2.0.14 release
Milestone

Comments

@mojavelinux
Copy link
Member

mojavelinux commented Apr 17, 2021

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 to warn, 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

= {project-name} Docs
:project-name: ACME

{doctitle}

Correct

:project-name: ACME
= {project-name} Docs

{doctitle}

However, if you don't to make use of the doctitle attribute, either order is acceptable.

@mojavelinux mojavelinux self-assigned this Apr 17, 2021
@mojavelinux mojavelinux added this to the v2.0.x milestone Apr 17, 2021
@mojavelinux
Copy link
Member Author

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.

@mojavelinux mojavelinux changed the title Silence warning about missing attribute reference when computing doctitle attribute Suppress warning about missing attribute reference when computing doctitle attribute Apr 17, 2021
@mojavelinux mojavelinux changed the title Suppress warning about missing attribute reference when computing doctitle attribute Suppress warning about missing attribute reference when substituting value of doctitle attribute Apr 17, 2021
@mojavelinux mojavelinux changed the title Suppress warning about missing attribute reference when substituting value of doctitle attribute Suppress warning about missing attribute reference when substituting value for doctitle attribute Apr 17, 2021
mojavelinux added a commit to mojavelinux/asciidoctor that referenced this issue Apr 17, 2021
…stituting value for doctitle attribute

suppress missing attribute warning when applying substitutions to implicit document title to assign to doctitle attribute
@mojavelinux
Copy link
Member Author

@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 doctitle attribute in the document, then any attributes referenced by the document title line need to be defined before that line (aka follow document order, just like any other attribute entry).

mojavelinux added a commit to mojavelinux/asciidoctor that referenced this issue Apr 18, 2021
…cessing value for doctitle attribute

suppress missing attribute warning when applying substitutions to implicit document title to assign to doctitle attribute
mojavelinux added a commit to mojavelinux/asciidoctor that referenced this issue Apr 18, 2021
…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)
@mojavelinux
Copy link
Member Author

mojavelinux commented Apr 18, 2021

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.

@mojavelinux mojavelinux added the v2.0.14 Issues resolved in the 2.0.14 release label Apr 18, 2021
ggrossetie pushed a commit to ggrossetie/asciidoctor that referenced this issue Jun 12, 2021
…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)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
bug v2.0.14 Issues resolved in the 2.0.14 release
Projects
None yet
Development

No branches or pull requests

1 participant