baseURL parameter not fulfilling upstream requirements - how to handle URLS about foreman-documentation

[lzap]

Yeah we need to get rid of absolute URLs, there is a macro for base url when needed.

[melcorr]

Hi @spetrosi @lzap

I see that the baseURL is a common attribute that is not defined dependent on upstream/downstream

Are we in a position now to set the upstream baseurls?

@spetrosi there are only small guides that are left to migrate upstream, aren't there?

[spetrosi]

I will test how guides work with BaseURL pointing to docs.theforeman

[spetrosi]

My tests resulted in sad results:
Let's compare links for the same section up- and downstream:

• https://docs.theforeman.org/master/Administering_Red_Hat_Satellite/index-foreman.html#sect-Red_Hat_Satellite-Administering_Red_Hat_Satellite-Installing_the_Katello_Root_CA_Certificate
• https://access.redhat.com/documentation/en-us/red_hat_satellite/6.7/html/administering_red_hat_satellite/chap-red_hat_satellite-administering_red_hat_satellite-accessing_red_hat_satellite#sect-Red_Hat_Satellite-Administering_Red_Hat_Satellite-Installing_the_Katello_Root_CA_Certificate

The way the sections are "reffered" in the URLs are very different. If we were to use the BaseURL attribute, the links would look like that:

• {BaseURL}Administering_Red_Hat_Satellite-Installing_the_Katello_Root_CA_Certificate
• {BaseURL}/administering_red_hat_satellite/chap-red_hat_satellite-administering_red_hat_satellite-accessing_red_hat_satellite#sect-Red_Hat_Satellite-Administering_Red_Hat_Satellite-Installing_the_Katello_Root_CA_Certificate
  I will try to investigate if we have something to do to make the paths in links identical.

[melcorr]

Thanks @spetrosi
I had similar findings yesterday...but i was hoping it was because I was doing something stupid because I forget things.

[melcorr]

@lzap
Any idea how we can get around this without writing ifevals for links?

[spetrosi]

My idea is that we need to somehow publish the upstream documentation in the same way that the downstream docs are published:

1. To publish in multi-paged HTML.

2. To ensure that the URLs upstream use the same format that downstream does - {BaseURL}/guide_name/chapter_name#section_name.

I now look at how we can accomplish this.

[lzap]

Option 1: Ignore.

This will be only temporary problem until we migrate all books. We can simply ignore this problem and prefer Red Hat Satellite links (so Foreman links are broken for some time - it's WIP anyway and not many of them are broken). The idea is to never use absolute URLs across documentations (even versions), always stick with asciidoc xref.

Option 2: Use symlinks

We can probably setup symlinks on our upstream site so it works. Multipage links are completely different from what we have upstream:

• https://access.redhat.com/documentation/en-us/red_hat_satellite/6.7/html/administering_red_hat_satellite/chap-red_hat_satellite-administering_red_hat_satellite-accessing_red_hat_satellite#sect-Red_Hat_Satellite-Administering_Red_Hat_Satellite-Installing_the_Katello_Root_CA_Certificate

However if you switch over to Single page HTML it's much more close:

• https://access.redhat.com/documentation/en-us/red_hat_satellite/6.7/html-single/administering_red_hat_satellite/index#sect-Red_Hat_Satellite-Administering_Red_Hat_Satellite-Installing_the_Katello_Root_CA_Certificate

Now, the idea is to create symlink upstream: administering_red_hat_satellite/index -> Administering_Red_Hat_Satellite/index-foreman.html and then we can keep the downstream links "as is" and they should work for both. We can create those links automatically during the build process so it will not mess up our source folder but we need to be maintaining those manually.

Option 3: Adopt downstream building procedure

While the cleanest option, the big problem with this one is that I don't necessary understand the tooling behind this and I won't be able to provide much help. If you find a commitment from somebody with the know how, it should be relatively easy to switch. However one thing to keep in mind is that we now use GithHub Actions to do the builds and it only provides Ubuntu containers. If the tools do only work on RHEL/CentOS/Fedora than it's a major problem.

[lzap]

This is being discussed in the issue #192. In this case, this module is likely to be reused, and if it is reused in another guide, xref won't work. Hence the link.

This is a followup of the IPv6 PR discussion (see above).

Are you saying that if a link targets module, we can't use reference? What is the point? I hope we can actually converge to having just xrefs without absolute URLs.

[spetrosi]

New option has arrived:
Downstream, we can link to the single-paged html version of docs. This will require manually changing all the links that are currently used. For example, chang this link:
https://access.redhat.com/documentation/en-us/red_hat_satellite/6.7/html/administering_red_hat_satellite/chap-red_hat_satellite-administering_red_hat_satellite-accessing_red_hat_satellite#sect-Red_Hat_Satellite-Administering_Red_Hat_Satellite-Setting_a_Custom_Login_Message
To this:
https://access.redhat.com/documentation/en-us/red_hat_satellite/6.7/html-single/administering_red_hat_satellite/index#sect-Red_Hat_Satellite-Administering_Red_Hat_Satellite-Setting_a_Custom_Login_Message

And upstream this link has the following format:
https://docs.theforeman.org/master/Administering_Red_Hat_Satellite/index-foreman.html#sect-Red_Hat_Satellite-Administering_Red_Hat_Satellite-Setting_a_Custom_Login_Message

The format for single-paged html is the same upstream and downstream, therefore we will be able to make use of the BaseURL attribute, the resulting link will be:
{BaseURL}administering_red_hat_satellite/index#sect-Red_Hat_Satellite-Administering_Red_Hat_Satellite-Setting_a_Custom_Login_Message

The drawback is that we historically use links to multi-paged html across the who docs department because this way users do not need to download the whole book when they need to read only one section, so this is something that I need to negotiate with managers.

But at the same time, things are changing quickly in Red Hat and any other decision might stop working in several months because something might change.

[spetrosi]

One more difference in the single-paged html links: Foreman uses index-foreman.html and Satellite uses index. Where does this come from? It will be great if we can make Foreman do just index, but at the same time we can use an attribute to manipulate this.

[melcorr]

Single paged HTML causes accessibility issues for our customers in low bandwidth and that is the motivation behind multi-page HTML being the default.

I think this would be a bad solution..

[lzap]

Foreman uses index-foreman.html and Satellite uses index. Where does this come from? It will be great if we can make Foreman do just index

Well upstream have multiple kinds of documentation, foreman and debian. We cannot just use index.html, it needs to be different at some point.

I think this would be a bad solution..

Then let's find a better one. But sometimes a bad solution is better than no solution. Compare this to 404... :-)

[lzap]

Another idea: I can write a script that will change links during downstream syncing process. I assume that all links are on single line (no links are broken into multiple lines) therefore this would be possible with just sed command.

[melcorr]

I take back what I said about accessibility earlier because this practice will be done away with regardless of whether it is a good or bad move.

[maximiliankolb]

Hey all.
We at ATIX are currently evaluating how to incorporate upstream documentation to our own downstream docs. We settled on asciidoc as per requirement by Red Hat and choose Antora to built the website.

We are using xref:path/to/file.adoc[fancy title] to set internal cross references from one page to another.

I would prefer a solution that allows us to comfortably change links (both their source and their title) via an attribute as in guides/common/attributes.adoc.
I wrote a python script to do exactly that (which I'd also share if you're interested).

If anyone wants to talk about Antora, please feel free to message me! I'd be happy so share some insights. :)

[lzap]

Antora's output looks great, however I wonder how much compatible this can be with the original AsciiDoc (which is written in Ruby). Red Hat documentation team uses the original AsciiDoc with some legacy pipeline which generate artifacts. That's why we started with less intrusive make. Granted the final output is not ideal and this is something we yet need to solve.

My idea was set of Makefiles and shell scripts to produce plain HTML/PDF files in varius subdirectories like /master and /2.3. No searching, no fancy features, plain CSS. But if we find a way to integrate Antora in a way that it also works with the legacy AsciiDoc and the pipeline, then we could use it. Searching is particularly great and finds relevant results.

[maximiliankolb]

The main selling point for me is the optional search capabilities as well as the navigation. Having a lot of stand alone html output files is not always sufficient. Let me know if I can showcase something to you.

Apart from that (and back to topic), I hope as much as possible customisation can be handled via variables as seen in the attributes.adoc file.

[melcorr]

Thanks for your work on this @spetrosi

[lzap]

Cheers!