Link to correct version of other manual with intersphinx linking

[sypets]

This issue was raised by @rowild in Slack:

• intersphinx linking not consistent concerning versions

and @DanielSiepmann added some ideas. Thank you!

The intersphinx linking (as specified in Settings.cfg) currently always go to "latest". This is also the case for older branches.

Should we change the links for the other branches in Settings.cfg to link to matching versions (or best match), e.g. branch 8.7 in "TYPO3 Explained" should link to branch 8.7 in TCA Reference?

There are several related issues (which have also been mentioned in Slack ):

• Not all repositories have an up-to-date "latest", sometimes "latest" is actually "7.6" or something else
• Not having the version selector easily visible is a real problem, I think. I don't think everyone is aware of the fact, that there are other versions available. See also Improve the version switcher - "unhide" it
• Branching out and keeping branches up-to-date.

[rowild]

Thank you very much for opening this ticket, @sypets ! The complexity of the documentation is indeed something that requires a team that is fully dedicated to it.
As for the visibility of the selector: the non-visibility is especially true for mobile phones...

[DanielSiepmann]

I guess this might work:

All repositories must contain the latest branch, following the structure to be the "default" if no version is added to the URL. We do not change anything within latest branch. The current behaviour is kept.

For each older branch, we adjust Settings.cfg to contain the version number within intersphinx URLs.
Therefore each repository must provide a branch / version for each LTS beforehand.

Once a new LTS is released, e.g. upcoming V10.x, we create a new Branch for older LTS (V9.5) within each repository and render those. Afterwards we can adjust the Settings.cfg of each repository to adjust the intersphinx URLs to point to 9.5 of each referenced manual.

This way each version should only contain links to the same version when cross referencing.

It's important to always use Sphinx :ref: text role to make use of intersphinx, and never to add raw external URLs, in order to make this work.

We should also coordinate this with Core Team and TYPO3 Inc. As CoreTeam is managing Systemenxtension Manuals and Changelog.
The TYPO3 Inc. is working on new URL structure and Rendering / Deployment of Manuals. Maybe they have also some input to that topic.

[sypets]

@DanielSiepmann It seems we should use "master" instead of "latest" (see #39), but this does not affect the general principles. But since main branch is currently not being used consistent, I thought I might mention it to see if this is something which must be coordinated with GmbH

I don't think we will always get an exact match.Right now, some repos have "latest" not being 9.5. For "Sitepackage Tutorial", it is 8.7. For "Fronend Localization Guide", it is 7.6. So sometimes it will link to same version and sometimes not (if same version is not available).

That is a little unfortunate, but I think we have to be pragmatic. In most of the cases, the behaviour will be improved.

And improvements in usability with version selector might help here as well.

So, it might look like this?

Settings.cfg of 7.6 branch of "TYPO3 Explained":

# these manuals only have one version
h2document    = https://docs.typo3.org/typo3cms/HowToDocument/
t3contribute  = https://docs.typo3.org/typo3cms/ContributionWorkflowGuide/
t3extbasebook = https://docs.typo3.org/typo3cms/ExtbaseFluidBook/


t3install     = https://docs.typo3.org/typo3cms/InstallationGuide/7.6/
t3start       = https://docs.typo3.org/typo3cms/GettingStartedTutorial/7.6
t3tca         = https://docs.typo3.org/typo3cms/TCAReference/7.6
...

[sypets]

I changed the Settings.cfg to link to same version in all official manuals.

[sypets]

I created a patch to make this change in the core as well: https://review.typo3.org/c/Packages/TYPO3.CMS/+/62814