8286185: The Java manpage can be more platform inclusive

Reviewed-by: sspitsyn, kvn, iklam

src/java.base/share/man/java.1

@@ -415,8 +415,8 @@ If you are expected to specify the percentage, then use a number from 0
 to 1.
 For example, specify \f[V]0.25\f[R] for 25%.
 .PP
-The following sections describe the options that are obsolete,
+The following sections describe the options that are deprecated,
-deprecated, and removed:
+obsolete, and removed:
 .IP \[bu] 2
 \f[B]Deprecated Java Options\f[R]: Accepted and acted upon --- a warning
 is issued when they\[aq]re used.
@@ -441,17 +441,22 @@ either \f[V]--\f[R]\f[I]name\f[R]\f[V]=\f[R]\f[I]value\f[R] or
 Loads the specified native agent library.
 After the library name, a comma-separated list of options specific to
 the library can be used.
+If the option \f[V]-agentlib:foo\f[R] is specified, then the JVM
+attempts to load the library named \f[V]foo\f[R] using the platform
+specific naming conventions and locations:
 .RS
 .IP \[bu] 2
-\f[B]Linux and macOS:\f[R] If the option \f[V]-agentlib:foo\f[R] is
+\f[B]Linux and other POSIX-like platforms:\f[R] The JVM attempts to load
-specified, then the JVM attempts to load the library named
+the library named \f[V]libfoo.so\f[R] in the location specified by the
-\f[V]libfoo.so\f[R] in the location specified by the
+\f[V]LD_LIBRARY_PATH\f[R] system variable.
-\f[V]LD_LIBRARY_PATH\f[R] system variable (on macOS this variable is
-\f[V]DYLD_LIBRARY_PATH\f[R]).
 .IP \[bu] 2
-\f[B]Windows:\f[R] If the option \f[V]-agentlib:foo\f[R] is specified,
+\f[B]macOS:\f[R] The JVM attempts to load the library named
-then the JVM attempts to load the library named \f[V]foo.dll\f[R] in the
+\f[V]libfoo.dylib\f[R] in the location specified by the
-location specified by the \f[V]PATH\f[R] system variable.
+\f[V]DYLD_LIBRARY_PATH\f[R] system variable.
+.IP \[bu] 2
+\f[B]Windows:\f[R] The JVM attempts to load the library named
+\f[V]foo.dll\f[R] in the location specified by the \f[V]PATH\f[R] system
+variable.
 .RS 2
 .PP
 The following example shows how to load the Java Debug Wire Protocol
@@ -966,7 +971,7 @@ running user cleanup code (such as closing database connections) at
 shutdown, even if the JVM terminates abruptly.
 .RS
 .IP \[bu] 2
-\f[B]Linux and macOS:\f[R]
+\f[B]Non-Windows:\f[R]
 .RS 2
 .IP \[bu] 2
 The JVM catches signals to implement shutdown hooks for unexpected
@@ -1012,13 +1017,13 @@ process \f[V]CTRL_C_EVENT\f[R], \f[V]CTRL_CLOSE_EVENT\f[R],
 .PP
 There are two consequences of specifying \f[V]-Xrs\f[R]:
 .IP \[bu] 2
-\f[B]Linux and macOS:\f[R] \f[V]SIGQUIT\f[R] thread dumps aren\[aq]t
+\f[B]Non-Windows:\f[R] \f[V]SIGQUIT\f[R] thread dumps aren\[aq]t
 available.
 .IP \[bu] 2
 \f[B]Windows:\f[R] Ctrl + Break thread dumps aren\[aq]t available.
 .PP
 User code is responsible for causing shutdown hooks to run, for example,
-by calling the \f[V]System.exit()\f[R] when the JVM is to be terminated.
+by calling \f[V]System.exit()\f[R] when the JVM is to be terminated.
 .RE
 .TP
 \f[V]-Xshare:\f[R]\f[I]mode\f[R]
@@ -1069,7 +1074,7 @@ Shows settings related to system properties.
 Shows the settings of the JVM.
 .TP
 \f[V]system\f[R]
-\f[B]Linux:\f[R] Shows host system or container configuration and
+\f[B]Linux only:\f[R] Shows host system or container configuration and
 continues.
 .RE
 .TP
@@ -1080,12 +1085,17 @@ or \f[V]M\f[R] to indicate MB, or \f[V]g\f[R] or \f[V]G\f[R] to indicate
 GB.
 The actual size may be rounded up to a multiple of the system page size
 as required by the operating system.
-The default value depends on the platform:
+The default value depends on the platform.
+For example:
 .RS
 .IP \[bu] 2
-Linux/x64 (64-bit): 1024 KB
+Linux/x64: 1024 KB
 .IP \[bu] 2
-macOS (64-bit): 1024 KB
+Linux/Aarch64: 2048 KB
+.IP \[bu] 2
+macOS/x64: 1024 KB
+.IP \[bu] 2
+macOS/Aarch64: 2048 KB
 .IP \[bu] 2
 Windows: The default value depends on virtual memory
 .PP
@@ -1251,8 +1261,8 @@ the identifier of the process is specified as \f[V]%p\f[R]):
 \f[V]-XX:ErrorFile=./hs_err_pid%p.log\f[R]
 .RE
 .IP \[bu] 2
-\f[B]Linux and macOS:\f[R] The following example shows how to set the
+\f[B]Non-Windows:\f[R] The following example shows how to set the error
-error log to \f[V]/var/log/java/java_error.log\f[R]:
+log to \f[V]/var/log/java/java_error.log\f[R]:
 .RS 2
 .RS
 .PP
@@ -1274,7 +1284,7 @@ Otherwise, if the file can\[aq]t be created in the specified directory
 (due to insufficient space, permission problem, or another issue), then
 the file is created in the temporary directory for the operating system:
 .IP \[bu] 2
-\f[B]Linux and macOS:\f[R] The temporary directory is \f[V]/tmp\f[R].
+\f[B]Non-Windows:\f[R] The temporary directory is \f[V]/tmp\f[R].
 .IP \[bu] 2
 \f[B]Windows:\f[R] The temporary directory is specified by the value of
 the \f[V]TMP\f[R] environment variable; if that environment variable
@@ -1406,7 +1416,7 @@ Disables the attempt to set the soft limit for the number of open file
 descriptors to the hard limit.
 By default, this option is enabled on all platforms, but is ignored on
 Windows.
-The only time that you may need to disable this is on Mac OS, where its
+The only time that you may need to disable this is on macOS, where its
 use imposes a maximum of 10240, which is lower than the actual system
 maximum.
 .TP
@@ -1485,7 +1495,7 @@ If the string contains spaces, then it must be enclosed in quotation
 marks.
 .RS
 .IP \[bu] 2
-\f[B]Linux and macOS:\f[R] The following example shows how the
+\f[B]Non-Windows:\f[R] The following example shows how the
 \f[V]-XX:OnError\f[R] option can be used to run the \f[V]gcore\f[R]
 command to create a core image, and start the \f[V]gdb\f[R] debugger to
 attach to the process in case of an irrecoverable error (the
@@ -1729,12 +1739,17 @@ Sets the Java thread stack size (in kilobytes).
 Use of a scaling suffix, such as \f[V]k\f[R], results in the scaling of
 the kilobytes value so that \f[V]-XX:ThreadStackSize=1k\f[R] sets the
 Java thread stack size to 1024*1024 bytes or 1 megabyte.
-The default value depends on the platform:
+The default value depends on the platform.
+For example:
 .RS
 .IP \[bu] 2
-Linux/x64 (64-bit): 1024 KB
+Linux/x64: 1024 KB
 .IP \[bu] 2
-macOS (64-bit): 1024 KB
+Linux/Aarch64: 2048 KB
+.IP \[bu] 2
+macOS/x64: 1024 KB
+.IP \[bu] 2
+macOS/Aarch64: 2048 KB
 .IP \[bu] 2
 Windows: The default value depends on virtual memory
 .PP
@@ -1772,13 +1787,13 @@ See the \f[V]-XX:ObjectAlignmentInBytes\f[R] option.
 .RE
 .TP
 \f[V]-XX:-UseContainerSupport\f[R]
-The VM now provides automatic container detection support, which allows
+\f[B]Linux only:\f[R] The VM now provides automatic container detection
-the VM to determine the amount of memory and number of processors that
+support, which allows the VM to determine the amount of memory and
-are available to a Java process running in docker containers.
+number of processors that are available to a Java process running in
+docker containers.
 It uses this information to allocate system resources.
-This support is only available on Linux x64 platforms.
+The default for this flag is \f[V]true\f[R], and container support is
-If supported, the default for this flag is \f[V]true\f[R], and container
+enabled by default.
-support is enabled by default.
 It can be disabled with \f[V]-XX:-UseContainerSupport\f[R].
 .RS
 .PP
@@ -1822,7 +1837,8 @@ the OS moves other pages around to create huge pages; this option is
 made available for experimentation.
 .TP
 \f[V]-XX:+AllowUserSignalHandlers\f[R]
-Enables installation of signal handlers by the application.
+\f[B]Non-Windows:\f[R] Enables installation of signal handlers by the
+application.
 By default, this option is disabled and the application isn\[aq]t
 allowed to install signal handlers.
 .TP
@@ -2782,8 +2798,8 @@ The following example shows how to set the default file explicitly
 \f[V]-XX:HeapDumpPath=./java_pid%p.hprof\f[R]
 .RE
 .IP \[bu] 2
-\f[B]Linux and macOS:\f[R] The following example shows how to set the
+\f[B]Non-Windows:\f[R] The following example shows how to set the heap
-heap dump file to \f[V]/var/log/java/java_heapdump.hprof\f[R]:
+dump file to \f[V]/var/log/java/java_heapdump.hprof\f[R]:
 .RS 2
 .RS
 .PP
@@ -2807,8 +2823,8 @@ By default, the file is created in the current working directory, and
 it\[aq]s named \f[V]hotspot.log\f[R].
 .RS
 .IP \[bu] 2
-\f[B]Linux and macOS:\f[R] The following example shows how to set the
+\f[B]Non-Windows:\f[R] The following example shows how to set the log
-log file to \f[V]/var/log/java/hotspot.log\f[R]:
+file to \f[V]/var/log/java/hotspot.log\f[R]:
 .RS 2
 .RS
 .PP
@@ -2831,7 +2847,7 @@ Enables printing of a class instance histogram after one of the
 following events:
 .RS
 .IP \[bu] 2
-\f[B]Linux and macOS:\f[R] \f[V]Control+Break\f[R]
+\f[B]Non-Windows:\f[R] \f[V]Control+\[rs]\f[R] (\f[V]SIGQUIT\f[R])
 .IP \[bu] 2
 \f[B]Windows:\f[R] \f[V]Control+C\f[R] (\f[V]SIGTERM\f[R])
 .PP
@@ -2848,7 +2864,7 @@ Enables printing of \f[V]java.util.concurrent\f[R] locks after one of
 the following events:
 .RS
 .IP \[bu] 2
-\f[B]Linux and macOS:\f[R] \f[V]Control+Break\f[R]
+\f[B]Non-Windows:\f[R] \f[V]Control+\[rs]\f[R] (\f[V]SIGQUIT\f[R])
 .IP \[bu] 2
 \f[B]Windows:\f[R] \f[V]Control+C\f[R] (\f[V]SIGTERM\f[R])
 .PP