8323197: [8u] building doc fixes

[zzambers]

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 new)
• avoided use of block quotes (using >) in md, as it produces ugly result in GH (e.g. compare old new)
• regenerated html (visual changes in generated html are quite minor)

---

Progress

• Change must be properly reviewed (1 review required, with at least 1 Reviewer)
• Change must not contain extraneous whitespace
• Commit message must refer to an issue
• JDK-8323197 needs maintainer approval

Issue

• JDK-8323197: [8u] building doc fixes (Enhancement - P4)

Reviewing

Using git

Checkout this PR locally:
$ git fetch https://git.openjdk.org/jdk8u-dev.git pull/416/head:pull/416
$ git checkout pull/416

Update a local copy of the PR:
$ git checkout pull/416
$ git pull https://git.openjdk.org/jdk8u-dev.git pull/416/head

Using Skara CLI tools

Checkout this PR locally:
$ git pr checkout 416

View PR using the GUI difftool:
$ git pr show -t 416

Using diff file

Download this PR as a diff file:
https://git.openjdk.org/jdk8u-dev/pull/416.diff

Using Webrev

Link to Webrev Comment

[bridgekeeper]

👋 Welcome back zzambers! A progress list of the required criteria for merging this PR into master will be added to the body of your pull request. There are additional pull request commands available for use with this pull request.

[mlbridge]

Webrevs

• 00: Full (c225e969)

[bridgekeeper]

@zzambers This pull request has been inactive for more than 4 weeks and will be automatically closed if another 4 weeks passes without any activity. To avoid this, simply add a new comment to the pull request. Feel free to ask for assistance if you need help with progressing this pull request towards integration!

[zzambers]

Some additional notes:

• apart from hg->git info, this PR only does fixes to formating/style/links
• there are probably no more useful doc backports for 8u (as far as I know), last one was JDK-8176509, following change is JDK-8179892 (Update build documentation for JDK 9)

[gnu-andrew]

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 and also needs backporting to 11 & 17. The git changes are also JDK-8251549, which should be backported as it was to 11u.

The use of > seems to have been removed with JDK-8179892: "Update build documentation for JDK 9" so it looks ok to do here.

[zzambers]

@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). 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 to (17, 11) either way, I had it in my plans, but forgot about that.. :(

[gnu-andrew]

@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 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.

[bridgekeeper]

@zzambers This pull request has been inactive for more than 4 weeks and will be automatically closed if another 4 weeks passes without any activity. To avoid this, simply add a new comment to the pull request. Feel free to ask for assistance if you need help with progressing this pull request towards integration!

[zzambers]

@gnu-andrew What do you think about adding (JDK-8306408, JDK-8251549) here using /issue add?

Backport of JDK-8306408 (Fix the format of several tables in building.md) to 17 has been done, PR for 11 is waiting for review.

I took a look at additional info about git clients in JDK-8251549, but Special Considerations section does not exist on 8. Section was introduced as part of JDK-8179892 (Update build documentation for JDK 9). It is then referenced from Windows section in newer jdks. Maybe section could be added to jdk8 (possibly in separate PR).

[openjdk]

❗ This change is not yet ready to be integrated.
See the Progress checklist in the description for automated requirements.

[bridgekeeper]

@zzambers This pull request has been inactive for more than 4 weeks and will be automatically closed if another 4 weeks passes without any activity. To avoid this, simply add a new comment to the pull request. Feel free to ask for assistance if you need help with progressing this pull request towards integration!

[bridgekeeper]

@zzambers This pull request has been inactive for more than 8 weeks and will now be automatically closed. If you would like to continue working on this pull request in the future, feel free to reopen it! This can be done using the /open pull request command.

[gnu-andrew]

@zzambers do you still want to proceed with this and openjdk/jdk11u-dev#2533 ?

[zzambers]

/open

[zzambers]

@gnu-andrew I do, I have reopened these PRs :)

[openjdk]

@zzambers This pull request is now open

[bridgekeeper]

@zzambers This pull request has been inactive for more than 4 weeks and will be automatically closed if another 4 weeks passes without any activity. To avoid this, simply add a new comment to the pull request. Feel free to ask for assistance if you need help with progressing this pull request towards integration!

[zzambers]

keep open

[bridgekeeper]

@zzambers This pull request has been inactive for more than 4 weeks and will be automatically closed if another 4 weeks passes without any activity. To avoid this, simply add a new comment to the pull request. Feel free to ask for assistance if you need help with progressing this pull request towards integration!