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

[Zdenek Zambersky]

On Mon, 12 Feb 2024 20:43:04 GMT, Andrew John Hughes <andrew at openjdk.org> wrote:

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

@gnu-andrew What do you think about adding ([JDK-8306408](https://bugs.openjdk.org/browse/JDK-8306408), [JDK-8251549](https://bugs.openjdk.org/browse/JDK-8251549))  here using `/issue add`?

Backport of [JDK-8306408](https://bugs.openjdk.org/browse/JDK-8306408) (Fix the format of several tables in building.md) to 17 has been done, PR for 11 is [waiting for review](https://github.com/openjdk/jdk11u-dev/pull/2533).

I took a look at additional info about git clients in [JDK-8251549](https://bugs.openjdk.org/browse/JDK-8251549), but `Special Considerations` section does not exist on 8. Section was introduced as part of [JDK-8179892](https://bugs.openjdk.org/browse/JDK-8179892) (Update build documentation for JDK 9). It is then [referenced](https://github.com/openjdk/jdk/blob/5cae7d20adf9828e05d3cd2823c6b95ee1ab6db4/doc/building.md#windows) from Windows section in newer jdks. Maybe section could be added to jdk8 (possibly in separate PR).

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

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