RFR: 8251551: Use .md filename extension for README

[Magnus Ihse Bursie]

Hi Erik,

On 2020-08-13 21:45, Erik Helin wrote:
> Hi all,
>
> please review this patch that adds the .md filename extension to the 
> README file. The README already utilizes the Markdown [0] markup 
> language even though it doesn't use the .md filename extension.
>
> I also tweaked the Markdown syntax slightly, I primarily made use of 
> Markdown for the links. Source code forges that support rendering 
> README files (e.g. GitLab, GitHub, BitBucket, SourceHut, Gitea) will 
> now display the README a bit better. For an example, see my personal 
> fork [1] and compare it with how the current README is displayed [2].
>
> Issue:
> https://bugs.openjdk.java.net/browse/JDK-8251551
>
> Webrev:
> http://cr.openjdk.java.net/~ehelin/8251551/00/
Thank you for doing this. I've been thinking about fixing it for quite 
some time. :)

I'm happy to see that you included the intended perma-link to the online 
html version of the build instructions, 
https://openjdk.java.net/groups/build/doc/building.html. However, if 
feels a bit sneaky to point the link to a completely different place 
than the human-readable description indicates. I'd be a bit upset if I 
followed such a link and it led me completely elsewhere, even if that 
was a page I really wanted to see.

When I wrote the original README, the only use-case I had in mind was 
for someone to have checked out the code locally, not someone seeing it 
as a project description on Github. So I'd suggest a change more along 
these lines:
---
For build instructions, please see the [online 
documentation](https://openjdk.java.net/groups/build/doc/building.html), 
or either of these files:

  - [doc/building.html](doc/building.html) (html version)
  - [doc/building.md](doc/building.md) (markdown version)
---

And possibly even without the link to the doc/building.* files; at least 
in github this works not so good for html so it might make a bad 
impression if someone tries to follow them.

(With reservation that I just wrote it in my mail client, and didn't 
check the markdown for correctness.)



/Magnus
>
> Thanks,
> Erik
>
> [0]: https://en.wikipedia.org/wiki/Markdown
> [1]: https://github.com/edvbld/jdk/tree/readme
> [2]: https://git.openjdk.java.net/jdk