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

[Dan Heidinga]

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 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.

> 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].

Are both versions actually needed?

[1] http://openjdk.java.net/groups/build/ 
[2] http://openjdk.java.net/contribute/
[3] http://openjdk.java.net/guide/#building-the-jdk

-------------

PR: https://git.openjdk.java.net/jdk/pull/5417