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
