RFR: 8320258: Refresh building.md [v3]

[Christoph Langer]

On Fri, 17 Nov 2023 13:24:56 GMT, Magnus Ihse Bursie <ihse at openjdk.org> wrote:

>> The contents of the build README has been poorly kept up to date in places. With the move to Github, the need to have markdown syntax that looks good on Github has become apparent. The entire document has been in need for a while of a comprehensive oversight to be made more consistent in language and formatting.
>> 
>> Here is a summary of the most important changes:
>> 
>> * The entire section on cross-compiling have been restructured to be more logical, and some parts have been rewritten, so it reads more coherent.
>> * A section on "make doctor" has been added
>> * The fixpath.sh script has been explained more in detail (and references to the old fixpath binary removed)
>> * Information about MSYS2 and WSL has been updated
>> * References to how things were done in the past, like the hg forest have been removed
>> * Version numbers have been updated where needed
>> * Some specific paragraphs about e.g. boot JDK detection have been clarified
>> * Example output have been updated
>> * Remaining references to `run-test` have been updated to just `test`
>> * Internal links have been fixed in a few places
>> * A few remaining places that confuses "OpenJDK" with the "JDK" have been fixed
>> * Markdown formatting has been improved in some places
>> * The entire file has gotten more normalized markdown formatting (fix bullet list indentation, add empty lines surrounding the code block markers, etc)
>> 
>> Note that this PR will can possibly create a merge conflict with 8317357 and 8264425; my intention is to integrate these two first and then resolve any conflicts in this PR.
>
> Magnus Ihse Bursie has updated the pull request incrementally with one additional commit since the last revision:
> 
>   FIx some review comments

doc/building.md line 5:

> 3: ## TL;DR (Instructions for the Impatient)
> 4: 
> 5: If you are eager to try out building the JDK, these simple steps works most of

could change works->work here

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

PR Review Comment: https://git.openjdk.org/jdk/pull/16696#discussion_r1397487827