RFR: 8273497: Building.md should link to testing md file rather than html

[erik.joelsson at oracle.com]

On 2021-09-08 10:44, Dan Heidinga wrote:
> On Wed, 8 Sep 2021 16:14:36 GMT, Aleksey Shipilev <shade at openjdk.org> wrote:
>
>> (2) looks appealing for me, for a different reason: if you regenerate `.md` -> `.html`, and choose the unexpected pandoc version (for example one provided by distro), then `.html` diff would have a lot of fluff not related to the actual change. And that would keep happening as people regenerate `.html` with their own versions of pandocs :) Removing `.html` from repo resolves this problem at its core.
It does indeed. We have a long history have keeping generated files in 
the repository, and getting rid of them is a good thing on its own.
> It still leaves the original question though - should the `.md` file link to the `.html` or the `.md` version?  My preference is the `.md` file as markdown is more readable, IMO, for both offline and github viewing.
It was intended as implicit in option 2 that the links should then all 
be to pointing to .md since we are removing the .html files.
>> We can still rewire `make update-build-docs` to e.g. `make generate-build-docs` and put the resulting HTML to `build/` somewhere, so whoever deploying the HTML files on their site can still get it easily.
> I looked for links to the HTML files and found some on the build group's page [1] and in the "How to contribute" page [2].  Overall usage is inconsistent as the markdown files are also linked from related pages [3].

I don't know of anyone uploading these .html files anywhere. As I 
understand it, they were added in the current form because on our old 
Mercurial servers, they could be conveniently browsed in raw form 
directly from the repository, much like .md files are easily browsed on 
Github. So my best guess is that they aren't needed, hence suggesting 
option 2.

This is basically something we haven't quite cleaned up since moving to 
Github.

/Erik