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
