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

[Erik Joelsson]

On Wed, 8 Sep 2021 14:20:04 GMT, Dan Heidinga <github.com+8503711+DanHeidinga at openjdk.org> wrote:

> Discovered while working through the building guide.

When updating the .md doc files, you must also run the make target to generate the corresponding .html files and submit them together. In this case, changing the link to .md will change both the building.md and building.html file. I'm guessing that the original author assumed that the only file that would be browsed online was the html file, so it made sense to assume links to only apply to html files. This was back when we hosted the source on Mercurial. These days, online browsing of .md files is standard practice on sites like Github, so we may need to rethink this.

I don't think just changing the link here is the correct action. I see these potential options:

1. Create two links and mark them with .md and .html so that the reader may pick the one that makes sense depending on context.
2. Get rid of the html files since Github now naturally uses .md files rather than .html files for online reading.
3. Do nothing and continue to consider the html files as the official online documentation files.

I'm thinking 2 may be the preferred action, but would like more input from others. It would certainly make maintaining these files simpler as we no longer require the correct pandoc version present to update them.

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

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