Decide how to handle links that currently contain attributes

[aneta-petrova]

See LinkAttribute in https://github.com/jhradilek/asciidoctor-dita-vale?tab=readme-ov-file#available-rules:

DITA 1.3 does not allow references to reusable content in link URLs. Remove attribute references from the link or replace the entire link macro with an attribute reference.

We do this quite a lot, one example out of many is

foreman-documentation/guides/common/modules/con_smartproxy-networking.adoc

Line 32 in 0efc53b

* {InstallingServerDocURL}Port_and_firewall_requirements_{project-context}[Ports and firewall requirements] in _{InstallingServerDocTitle}_

The potential solutions I can see right now are:

1. Stop linking to individual sections and instead link to the whole guide. Links to whole guides could be still included as attributes -- if they consist of both the link and the link label. Example:
   :AdministeringDocURL: [https://docs.theforeman.org/3.15/Administering_Project/index-katello.html](Administering Foreman)].

2. Keep linking to individual sections but always include the whole link, no attributes. Example: Instead of {InstallingServerDocURL}Port_and_firewall_requirements_{project-context}[Ports and firewall requirements], this would be https://docs.redhat.com/en/documentation/red_hat_satellite/6.18/html-single/installing_satellite_server_in_a_connected_network_environment/index#Port_and_firewall_requirements_satellite. Repeat for each flavor (using ifdefs).

3. I wonder if we could leverage conditionals somehow. If the DITA migration tool consumes only content relevant for satellite, we could keep upstream links as they are (with ifndef::satellite[]) and only include hard-coded links for Satellite (with ifdef::satellite[]).

Note that neither of these solutions support defining a specific document version through an attribute, the way we do it now with {ProjectVersion}.

[ekohl]

Stop linking to individual sections and instead link to the whole guide. Links to whole guides could be still included as attributes -- if they consist of both the link and the link label. Example:

This feels like a step back in usability.

2. Keep linking to individual sections but always include the whole link, no attributes.

I'm not sure I quite understand what you mean. Are you implying we drop the attributes from the IDs? I think where possible that is a good idea. We have some cases where we do have that (for example, if you use a file more like a template and generate instructions for EL 8 & EL 9) but I think they're rare.

3. I wonder if we could leverage conditionals somehow. If the DITA migration tool consumes only content relevant for satellite, we could keep upstream links as they are (with ifndef::satellite[]) and only include hard-coded links for Satellite (with ifdef::satellite[]).

It's a good question how we're going to use the DITA migration tool in the first place. Does it render every file through asciidoc first and then converts that (so respecting attributes and conditionals) or is it smarter?

Without a better understanding of the conversion tool itself that may be hard to say.

Perhaps a reasonable start is to start removing them where possible and see what remains after.

[maximiliankolb]

Perhaps a reasonable start is to start removing them where possible and see what remains after.

Yes, I 💯 agree. We have actually started doing this to simplify maintenance; mostly when adding or renaming modules.

DITA 1.3 does not allow references to reusable content in link URLs. Remove attribute references from the link or replace the entire link macro with an attribute reference.

Interesting. Some numbers:

# get IDs that contain attributes
$ rg '^\[id="' | rg "\{" | wc -l
1105

# get affected xrefs
$ rg "xref:.*\{.*\[" | wc -l
506

It is duable & I have changed links many times over, but I just want to mention those numbers to give a feeling for the task ahead. Note that changes to anchors/xrefs on nightly makes cherry-picking more difficult.

[aneta-petrova]

I'm not sure I quite understand what you mean.

I expanded my original point 2 with an example.

[aneta-petrova]

3. I wonder if we could leverage conditionals somehow. If the DITA migration tool consumes only content relevant for satellite, we could keep upstream links as they are (with ifndef::satellite[]) and only include hard-coded links for Satellite (with ifdef::satellite[]).

It's a good question how we're going to use the DITA migration tool in the first place. Does it render every file through asciidoc first and then converts that (so respecting attributes and conditionals) or is it smarter?

Without a better understanding of the conversion tool itself that may be hard to say.

The https://github.com/jhradilek/asciidoctor-dita-topic migration tool can be instructed to process content defined by a certain attribute. The asciidoctor -r dita-topic -b dita-topic -a satellite con_upgrade-path-overview.adoc command will output the upgrade path overview as expected for Satellite.

But then there is the https://github.com/jhradilek/asciidoctor-dita-vale style package to be used with Vale as a pre-migration check. Vale cannot process only content behind certain conditions so it will keep reporting warnings when it detects a link with attributes.

The way I interpret this is that any link not included for Satellite can keep using attributes and it will not block the migration. Links included for Satellite must avoid attributes. However, Vale will keep reporting the links with attributes as errors.

[maximiliankolb]

any link not included for Satellite can keep using attributes

I strongly favor a solution/convention that applies to all builds. The overhead to differentiate between Satellite and non-Satellite builds will be bigger than just applying changes to non-Satellite modules too.

[aneta-petrova]

I gave this an honest try and attempted to find a solution that would apply to all builds. I couldn't find any.

Misha's Gemini gem instructions have a very good explanation of the issue: https://github.com/mramendi/asciidoctor-vale-assistant/blob/main/assistant/fixing-instructions-AI.md#linkattribute

It seems the only two options that won't block the DITA migration are this:

.Additional resources

* link:https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/8[RHEL 8 documentation]

or this:

:rhel_8_docs: link:https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/8[RHEL 8 documentation]

.Additional resources
* {rhel_8_docs}

and neither allows us to tailor the resulting link to different flavors.

Right now, I don't see any other solution than this:

.Additional resources
ifndef::satellite[]
* For more information, see {ManagingHostsDocURL}Administering_Hosts_managing-hosts[Administering hosts] in _{ManagingHostsDocTitle}_.
endif::[]
ifdef::satellite[]
* https://docs.redhat.com/en/documentation/red_hat_satellite/6.17/html-single/managing_hosts/index#Administering_Hosts_managing-hosts
endif::[]

although I'd be happy to be proven wrong :)

[ekohl]

Is this something that could be done in the conversion tool itself? Have we brought it back its maintainers?

[Lennonka]

Option 4: We will do replacement of attributes in sync post-processing in downstream if the DITA conversion will be done from the downstream repo.

But we still need more info from the tooling team.

[aneta-petrova]

Is this something that could be done in the conversion tool itself? Have we brought it back its maintainers?

Yes, we have. The DITA migration tooling maintainers support documentation teams by providing one mainstream conversion path. Teams might be free to pursue other paths by tweaking the tools but then the maintenance burden would be on those teams. For example, if we wanted to adjust the Vale rule set to ignore non-satellite content, we could: by forking the asciidoctor-dita-vale project and then being responsible for maintaining that fork.