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

Reply via email to