How do I update java manual pages with Homebrew?

Question

I am using Homebrew to install AdoptOpenJDK 11. I want to see the documentation via the manual pages.

Symptoms

When I run man java, I see documentation from 2004. At the bottom:

SEE ALSO
       javac(1), jdb(1), javah(1), jar(1),

       See (or search java.sun.com) for the following:

       The Java Extensions Framework @
         http://java.sun.com/j2se/1.5.0/docs/guide/extensions/index.html

       Security Features @
         http://java.sun.com/j2se/1.5.0/docs/guide/security/index.html

                                 23 June 2004                          java(1)

When I run man javac, I see documentation from 2002. At the bottom:

SEE ALSO
       jar(1), java(1), javadoc(1), javah(1), javap(1), jdb(1)

       See or search the Java web site for the following:

       The Java Extensions Mechanism @
                 http://java.sun.com/j2se/1.5/docs/guide/extensions/index.html

                                 05 March 2002                        javac(1)

I find the location of the java manual:

man -w java
# /usr/share/man/man1/java.1

I see Homebrew is storing manuals for other software: /usr/local/share/man.

Based on the cask source, I do not see man pages installed, but I don't know what OpenJDK11U-jdk_x64_mac_hotspot_11.0.8_10.pkg is doing. When I run fswatch /usr/local/share/ while reinstalling adoptopenjdk11, I do not see any changes.

brew cask cat adoptopenjdk11

# cask 'adoptopenjdk11' do
#   version '11.0.8,10'
#   sha256 'c9ce3e78a7ec7f8c23041af63a66bfe18bbf75c7bfa8f8a51148a098f3653699'
# 
#   url 'https://github.com/AdoptOpenJDK/openjdk11-binaries/releases/download/jdk-11.0.8%2B10/# OpenJDK11U-jdk_x64_mac_hotspot_11.0.8_10.pkg'
#   appcast "https://github.com/AdoptOpenJDK/openjdk#{version.major}-binaries/releases/latest"
#   name 'AdoptOpenJDK 11'
#   homepage 'https://adoptopenjdk.net/'
#   pkg 'OpenJDK11U-jdk_x64_mac_hotspot_11.0.8_10.pkg'
#   postflight do
#     system_command '/usr/sbin/pkgutil', args: ['--pkg-info', 'net.adoptopenjdk.11.jdk'], print_stdout: true
#   end
#   uninstall pkgutil: 'net.adoptopenjdk.11.jdk'
# end

What I tried

I read Are my macOS man pages outdated?, but I do not think the answer applies here, because Java is not an old Unix tool, and I have installed Java with Homebrew.

I checked that I have the latest version of AdoptOpenJDK 11 installed:

brew reinstall adoptopenjdk11
# ==> Downloading https://github.com/AdoptOpenJDK/openjdk11-binaries/releases/download/jdk-11.0.8%2B10/OpenJDK11U-jdk_x64_mac_hotspot_11.
# Already downloaded: /Users/alex.ordonez/Library/Caches/Homebrew/# downloads/1d0d41e7cf8f14ebb4df0ff39fa16e0fe2a1ac85f05ae404c62841c6ff01d4c8--OpenJDK11U-jdk_x64_mac_hotspot_11.0.8_10.pkg
# ==> Verifying SHA-256 checksum for Cask 'adoptopenjdk11'.
# ==> Uninstalling Cask adoptopenjdk11
# ==> Uninstalling packages:
# net.adoptopenjdk.11.jdk
# ==> Purging files for version 11.0.8,10 of Cask adoptopenjdk11
# ==> Installing Cask adoptopenjdk11
# ==> Running installer for adoptopenjdk11; your password may be necessary.
# ==> Package installers may write to any location; options such as --appdir are ignored.
# installer: Package name is AdoptOpenJDK
# installer: Upgrading at base path /
# installer: The upgrade was successful.
# package-id: net.adoptopenjdk.11.jdk
# version: 11.0.8+10
# volume: /
# location: Library/Java/JavaVirtualMachines/adoptopenjdk-11.jdk# 

I can verify the versions are correct:

java -version
# openjdk version "11.0.8" 2020-07-14
# OpenJDK Runtime Environment AdoptOpenJDK (build 11.0.8+10)
# OpenJDK 64-Bit Server VM AdoptOpenJDK (build 11.0.8+10, mixed mode)

javac -version
# javac 11.0.8

Also, I am able to compile and run Java 11 code.

Additional information: I am using macOS Catalina 10.15.6 (19G2021). My shell is Fish. I also have AdoptOpenJDK 8 installed.

Answer 1

I have a solution, but if anyone finds a simpler solution, then I will accept it. Here is mine.

Remember, I am using fish.

~/.config/fish/functions/java8.fish

function java8
    if set --local idx (contains --index -- $JAVA_HOME $fish_user_paths)
        # Remove other JAVA_HOME from path
        # Otherwise it will take priority
       set --erase fish_user_paths[$idx]
    end

    set --export JAVA_HOME /Library/Java/JavaVirtualMachines/adoptopenjdk-8.jdk/Contents/Home

    # We do not need JAVA_HOME on the path for the executables
    # We need it for the man pages, so man will search $JAVA_HOME/man
    # If we add $JAVA_HOME/bin to the path, then man erroneously searches $JAVA_HOME/bin/man
    set fish_user_paths $fish_user_paths $JAVA_HOME
end

I copied and adjusted this script for Java 11 (abbreviated):

~/.config/fish/functions/java11.fish

function java11
    if set --local idx (contains --index -- $JAVA_HOME $fish_user_paths)
       set --erase fish_user_paths[$idx]
    end
    set --export JAVA_HOME /Library/Java/JavaVirtualMachines/adoptopenjdk-11.jdk/Contents/Home
    set fish_user_paths $fish_user_paths $JAVA_HOME
end

Now my fish_user_paths (and PATH) have JAVA_HOME:

echo $fish_user_paths
# /usr/local/sbin /Library/Java/JavaVirtualMachines/adoptopenjdk-11.jdk/Contents/Home

echo $PATH
# /usr/local/sbin /Library/Java/JavaVirtualMachines/adoptopenjdk-11.jdk/Contents/Home /usr/local/bin /usr/bin /bin /usr/sbin /sbin

This means manpath also has $JAVA_HOME/man (abbreviated):

manpath
# /usr/local/share/man:/Library/Java/JavaVirtualMachines/adoptopenjdk-11.jdk/Contents/Home/man:/usr/share/man

And it means man reads from the correct directory:

man --path java
# /Library/Java/JavaVirtualMachines/adoptopenjdk-11.jdk/Contents/Home/man/man1/java.1

And I can switch to Java 8 and back to Java 11:

java8
man --path java
# /Library/Java/JavaVirtualMachines/adoptopenjdk-8.jdk/Contents/Home/man/man1/java.1

java11
man --path java
# /Library/Java/JavaVirtualMachines/adoptopenjdk-11.jdk/Contents/Home/man/man1/java.1

---

There is a separate problem, which is that JDK 11 seems to ship with JDK 8's documentation.

man -M /Library/Java/JavaVirtualMachines/adoptopenjdk-11.jdk/Contents/Home/man javac | tail -n 1
# JDK 8                            03 March 2015                        javac(1)