[jdk8u-dev] RFR: 8323197: [8u] building doc fixes

[Andrew John Hughes]

On Thu, 8 Feb 2024 14:44:00 GMT, Andrew John Hughes <andrew at openjdk.org> wrote:

>> Fixes for various issues in "building" doc:
>> - removed information about mercurial and replaced with git as appropriate (as mercurial repos are no longer active)
>> - fixed broken section references
>> - fixed broken links, updated to web archive, where original site no longer exists ( with exception of `Windows FreeType DLL build instructions` link, where archived page is not available :( )
>> - updated md tables to use `|`, so they would correctly display in GH (e.g. compare [old](https://github.com/openjdk/jdk8u-dev/blob/d898d4018e0a16f2115f4b1cbf93eb5e653b789b/doc/building.md#cygwin) [new](https://github.com/zzambers/jdk8u-dev/blob/fix-doc/doc/building.md#cygwin))
>> - avoided use of block quotes (using `>`) in md, as it produces ugly result in GH (e.g. compare [old](https://github.com/openjdk/jdk8u-dev/blob/d898d4018e0a16f2115f4b1cbf93eb5e653b789b/doc/building.md#configure-options) [new](https://github.com/zzambers/jdk8u-dev/blob/fix-doc/doc/building.md#configure-options))
>> - regenerated html (visual changes in generated html are quite minor)
>
> Most of these changes don't strike me as unique to 8u, but I can also see how they are mixed up with other changes that don't apply to 8u in later versions.
> 
> I would at least separate out the table changes as this is [JDK-8306408](https://bugs.openjdk.org/browse/JDK-8306408) and also needs backporting to 11 & 17. The git changes are also [JDK-8251549](https://bugs.openjdk.org/browse/JDK-8251549), which should be backported as it was to 11u.
> 
> The use of `>` seems to have been removed with [JDK-8179892](https://bugs.openjdk.org/browse/JDK-8179892): "Update build documentation for JDK 9" so it looks ok to do here.

> @gnu-andrew Thanks for your feedback.
> 
> I was not sure if it was worth doing some changes, as they would not necessarily be very similar diff-wise (rather in spirit). 

Yes, I understand docs is difficult in this way and thanks for taking this on. To clarify, I'm happy with using this PR to do most of the changes which are in the spirit of changes already in later JDKs, but where the existing change is not really backportable.

> I can however try to break this changeset and do hg->git and tables issue as backports in separate PRs.
> 
> Yes, I should backported [JDK-8306408](https://bugs.openjdk.org/browse/JDK-8306408) to (17, 11) either way, I had it in my plans, but forgot about that.. :(

Yes, those two were my concerns. The tables change is a recent one missing from most of the later JDKs too, so it makes sense to handle that separately. With the `git` bug, it seemed there was more detail in 8251549 that could probably be reused in 8u (e.g. the bit about Git clients), though the Mercurial->git replacements will differ in 8u.

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

PR Comment: https://git.openjdk.org/jdk8u-dev/pull/416#issuecomment-1939539706