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

Thu Sep 9 10:34:10 UTC 2021

Ok, let me shed some light on this discussion. :-)

First, as Erik assumed, the link was created only for the html version, 
since this was the only way in which clickable links made sense. If you 
read the markdown file at the terminal, you'd still had to type "less 
testing.md" or whatever, so no formal link would make sense.

This premise has changed with the advent of GitHub, and more advanced 
markdown editors.

Secondly, the generated html file is by no means dead! It is still the 
official build description, as published at 
https://openjdk.java.net/groups/build/doc/building.html. (This URL 
"redirects" to the latest version of building.html on github.)

I made a lot of effort some years ago to purge all sites from different 
kinds of links to different, bad and/or outdated build instructions, and 
replace them with this new canonical URL. I am sad to see that I have 
still not succeeded, and that even the new official Guide provides an 
incorrect link. I will submit a fix for this. The "How to contribute" 
page is *really* old and broken. I think the plan is to remove it 
completely and replace it with the Guide, when it get's to a more mature 
state.

The problem here is that the markdown parser used by Github is quite 
simplistic, and do not allow for the OpenJDK branded css formatting, nor 
some of the markdown syntax that is used in building.md and testing.md. 
So clicking on the building.md on Github gives you a rough idea what it 
is about, but it is not presented as intended.

I do agree though that we should add a link to the markdown version as 
well, so it is easy to click through to that. Basically, option 1 as 
Erik listed them.

Since changes in building.md requires running pandoc using a make 
target, I can offer to take over the bug and do the fix for you, if you 
want.

/Magnus

On 2021-09-08 19: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 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