On Wed, 8 Sep 2021 14:20:04 GMT, Dan Heidinga 
<github.com+8503711+danheidi...@openjdk.org> wrote:

> Discovered while working through the building guide.

When updating the .md doc files, you must also run the make target to generate 
the corresponding .html files and submit them together. In this case, changing 
the link to .md will change both the building.md and building.html file. I'm 
guessing that the original author assumed that the only file that would be 
browsed online was the html file, so it made sense to assume links to only 
apply to html files. This was back when we hosted the source on Mercurial. 
These days, online browsing of .md files is standard practice on sites like 
Github, so we may need to rethink this.

I don't think just changing the link here is the correct action. I see these 
potential options:

1. Create two links and mark them with .md and .html so that the reader may 
pick the one that makes sense depending on context.
2. Get rid of the html files since Github now naturally uses .md files rather 
than .html files for online reading.
3. Do nothing and continue to consider the html files as the official online 
documentation files.

I'm thinking 2 may be the preferred action, but would like more input from 
others. It would certainly make maintaining these files simpler as we no longer 
require the correct pandoc version present to update them.

-------------

PR: https://git.openjdk.java.net/jdk/pull/5417

Reply via email to