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
