[ATfL] Add references to the standards support

[pawosm-arm]

No description provided.

[pawosm-arm]

Thanks @kiranchandramohan for providing the pages referenced from these files!

[tblah]

I think we should instead link to the markdown files within the repo. I think the on-website documentation is regenerated as things are changed in main, whereas what we want here is something frozen to this particular LLVM release

[kiranchandramohan]

I think the on-website documentation is regenerated as things are changed in main, whereas what we want here is something frozen to this particular LLVM release

I think this is for the main branch of arm-toolchain which is kept in sync with upstream LLVM main branch. So the documentation for the main branch should move with upstream.

[tblah]

I think the on-website documentation is regenerated as things are changed in main, whereas what we want here is something frozen to this particular LLVM release

I think this is for the main branch of arm-toolchain which is kept in sync with upstream LLVM main branch. So the documentation for the main branch should move with upstream.

If we link to the markdown files in this repo, then it will remain up to date with the main branch, but will also remain correct on a release branch. Linking to the online documentation feels like something which would be easy to forget to fix on a release branch and which doesn't have any upside (as github will render the markdown anyway).

[kiranchandramohan]

I think the on-website documentation is regenerated as things are changed in main, whereas what we want here is something frozen to this particular LLVM release

I think this is for the main branch of arm-toolchain which is kept in sync with upstream LLVM main branch. So the documentation for the main branch should move with upstream.

If we link to the markdown files in this repo, then it will remain up to date with the main branch, but will also remain correct on a release branch. Linking to the online documentation feels like something which would be easy to forget to fix on a release branch and which doesn't have any upside (as github will render the markdown anyway).

This is a good point.
But the docs repo of ATfL is a separate directory (https://github.com/arm/arm-toolchain/tree/arm-software/arm-software/docs). We do not copy all the documents from llvm-project/flang/docs to the ATfL docs repo. There could be links in the markdown that do not resolve after the copying.
We also would like to do the same thing for Flang as we do for Clang.

[kiranchandramohan]

@pawosm-arm Could you discuss with @tblah whether there is a better way to organize the documentation?

[kiranchandramohan]

@pawosm-arm Could you discuss with @tblah whether there is a better way to organize the documentation?

We should also look into how upstream LLVM does release notes and see whether we can do something similar. If nothing can be done, we should add a link to each of the relevant tool's page for a user to understand what are the changes in the release.

[pawosm-arm]

Will do

[pawosm-arm]

We've discussed it and came to some conclusions:

1. The md files across projects in this repo (arm-software/linux, clang, flang) should refer to each other using relative paths rather than URLs. Sadly, there's no good example for it in the LLVM itself, as llvm and clang docs don't refer to each other with relative paths, so we'd have to set standards here. The goal is to have them markdowns rendered properly in GitHub and refer to clang and flang documentation correctly.
2. As we decided to ship markdowns in the shipment packages, we need to take this relative linking into account. And this have a potential for creating some headaches. They can be easily avoided if we stop shipping docs in the shipment packages, instead, we should ship some minimal set of markdowns that would advertise and recommend the use of the online documentation.
3. The Release Notes LLVM prepares https://releases.llvm.org/20.1.0/docs/ReleaseNotes.html are in form of very detailed Changelog prepended with some Introduction. If we want to be the same, we can rename our Changelog into Release Notes and add some Introduction. The level of details would depend on how extensive the changes across releases would be, hopefully not much. Adding links to LLVM/clang/flang release notes (for further reading) wouldn't hurt.