On 2021-09-08 10: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 does indeed. We have a long history have keeping generated files in the repository, and getting rid of them is a good thing on its own.
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.
It was intended as implicit in option 2 that the links should then all be to pointing to .md since we are removing the .html files.
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].

I don't know of anyone uploading these .html files anywhere. As I understand it, they were added in the current form because on our old Mercurial servers, they could be conveniently browsed in raw form directly from the repository, much like .md files are easily browsed on Github. So my best guess is that they aren't needed, hence suggesting option 2.

This is basically something we haven't quite cleaned up since moving to Github.

/Erik


Reply via email to