[Feature]: Implement the LinkAttribute rule as a deterministic fix

[jhradilek]

Pre-submission Checklist

• I have searched existing issues to avoid duplicates
• I have checked the roadmap and known limitations
• This is not a bug report (use bug report template instead)

Problem Statement

In AsciiDoc, authors often use attribute references as part of URLs to be able to replace variable parts such as the website domain, the product version, or even the product name in the configuration file rather than hardcoding the URL. They often take one of the following two approaches, both of which are currently reported as a warning by the LinkAttribute Vale rule:

1. They compose the entire link as a combination of hardcoded parts and attribute references within the main body of the text, for example:

   For more information, see the link:{BaseURL}/{ProductVersion}/html/installation_guide[Installation Guide].

   This is problematic because DITA, just like all XML-based languages, does not allow any variable parts within the value of the href= attribute. It is possible to resolve AsciiDoc attribute references in links during conversion and turn them in hardcoded URLs in DITA, but if this is not the desired outcome, writers need to change these in AsciiDoc.

2. They compose part of the link as a combination of hardcoded parts and attribute references in the attribute definition file, and complete the link macro in the main body of the text:

   // Incomplete reusable link defined in the attributes definition file (notice the missing link: marco):
   :LinkInstallGuide: {BaseURL}/{ProductVersion}/html/installation_guide[Installation Guide]
   
   // Incomplete reusable link referenced in the text (notice the missing brackets that are defined within the attribute:
   For more information, see link:{LinkInstallGuide}.

   This is problematic for the conversion because to be able to retain attributes as reusable values, they are purposefully not defined during conversion so that they can be replaced with the conref attribute in DITA. However, when part of the link macro is defined within the attribute, asciidoctor fails to recognize the text as a link:

   $ echo 'See link:{LinkInstallGuide}.' | asciidoctor -s -
   <div class="paragraph">
     <p>See link:{LinkInstallGuide}.</p>
   </div>

Proposed Solution

Offer the user to choose how they prefer links to be fixed, both solutions are fully deterministic:

1. Replace attribute references within links with their value:

   For more information, see the link:https://example.com/ExampleProduct/1.3/html/installation_guide[Installation Guide].

   As long as this forms a complete link macro in the main body of the text, it fixes both issues described in the Problem Statement.

2. Create a new attribute in the attribute definition file for the first issue described in the Problem Statement, or correct an existing one to form a complete link for the second issue described in the Problem Statement:

   // A complete reusable link defined in the attributes definition file (notice the full link macro used):
   :LinkInstallGuide: link:{BaseURL}/{ProductVersion}/html/installation_guide[Installation Guide]
   
   // A reusable link referenced in the text (notice no part of the link macro is used):
   For more information, see {LinkInstallGuide}.

   Preferably the solution should not create a duplicate definition for each corrected link.

Feature Category

Auto-fixing & Transformations

Priority Level

Medium - Would significantly improve my workflow

Use Cases

• When working with repositories with a large number of links that need to be fixed.

Alternatives Considered

No response

Example Implementation

Contribution Interest

• I would be willing to submit a PR for this feature
• I can help with testing the implementation
• I can provide additional use cases or feedback
• I prefer to wait for maintainer implementation

Additional Context

No response