8344056: Use markdown format for man pages #22081

magicus · 2024-11-13T17:05:25Z

Currently, the man pages are stored as troff (a text format) in the open repo, and a content-wise identical copy is stored as markdown (another text format) in the closed repo.

Since markdown is preferred to troff in terms of editing, we make changes to the man pages in markdown and then convert it to troff.

This closed-markdown to open-troff processing needs to be done manually by an Oracle engineer. This is done regularly at the start and end of a new release cycle, adding to the burden of creating a new release. It is also done (if any of the reviewers knows about the process) whenever an Oracle engineer updates a man page. If a community contributor changes the behavior of a tool, an Oracle engineer needs to change the documentation for them, since they cannot do it themselves.

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

Issue

JDK-8344056: Use markdown format for man pages (Bug - P3)

Reviewers

David Holmes (@dholmes-ora - Reviewer) Review applies to a8d4ea50
Christian Stein (@sormuras - Committer)
Iris Clark (@irisclark - Reviewer)

Reviewing

Using git

Checkout this PR locally:
$ git fetch https://git.openjdk.org/jdk.git pull/22081/head:pull/22081
$ git checkout pull/22081

Update a local copy of the PR:
$ git checkout pull/22081
$ git pull https://git.openjdk.org/jdk.git pull/22081/head

Using Skara CLI tools

Checkout this PR locally:
$ git pr checkout 22081

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

Using diff file

Download this PR as a diff file:
https://git.openjdk.org/jdk/pull/22081.diff

Using Webrev

Link to Webrev Comment

bridgekeeper · 2024-11-13T17:06:45Z

👋 Welcome back ihse! 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.

openjdk · 2024-11-13T17:07:32Z

@magicus This change now passes all automated pre-integration checks.

ℹ️ This project also has non-automated pre-integration requirements. Please see the file CONTRIBUTING.md for details.

After integration, the commit message for the final commit will be:

8344056: Use markdown format for man pages

Reviewed-by: cstein, iris, dholmes

You can use pull request commands such as /summary, /contributor and /issue to adjust it as needed.

At the time when this comment was updated there had been 84 new commits pushed to the master branch:

80e37a9: 8344265: RISC-V: Remove unused function get_previous_sp_entry
e1c4b49: 8343237: Improve the copying of the available set of Currencies
41a627b: 8343876: Enhancements to jpackage test lib
aa10ec7: 8343123: Nimbus: javax/swing/JInternalFrame/bug6726866.java does not have green undecorated window
fec0d1c: 8343777: Add since checker tests to Internationalisation modules
d0b770c: 8344289: SM cleanup in jdk.internal.util
a91d4c0: 8344233: Remove calls to SecurityManager and doPrivileged in java.net.ProxySelector and sun.net.spi.DefaultProxySelector after JEP 486 integration
d2e4b51: 8344186: Cleanup sun.net.www.MimeTable after JEP 486 integration
da40388: 8344315: Clean up sun.net.www.protocol.jrt.JavaRuntimeURLConnection after JEP 486 integration
2c509a1: 8344326: Move jpackage tests from "jdk.jpackage.tests" package to the default package
... and 74 more: https://git.openjdk.org/jdk/compare/7be77725eab6f45d8f8d23f2ba0d18d2d89a40aa...master

As there are no conflicts, your changes will automatically be rebased on top of these commits when integrating. If you prefer to avoid this automatic rebasing, please check the documentation for the /integrate command for further details.

➡️ To integrate this PR with the above commit message to the master branch, type /integrate in a new comment.

openjdk · 2024-11-13T17:08:30Z

@magicus The following labels will be automatically applied to this pull request:

build
client
compiler
core-libs
hotspot-jfr
javadoc
kulla
net
security
serviceability

When this pull request is ready to be reviewed, an "RFR" email will be sent to the corresponding mailing lists. If you would like to change these labels, use the /label pull request command.

jonathan-gibbons · 2024-11-13T17:53:11Z

Without looking in detail at the changes, this is indeed a welcome and long-overdue change!

mlbridge · 2024-11-13T18:11:11Z

Webrevs

kevinjwalls · 2024-11-13T20:17:24Z

I think this means the one-true-master copy of a man page is now the public .md file.
All contributors can now change and improve man pages, and would be expected to make necessary man page updates when making other changes.
(Which is great, I just didn't see it being explicitly said.)

sormuras · 2024-11-13T20:52:56Z

So glad to see progress here!

jdk/test/langtools/jdk/javadoc/tool/CheckManPageOptions.java

Line 141 in 1484153

return findRootDir().resolve("src/jdk.javadoc/share/man/javadoc.1");

should read return findRootDir().resolve("src/jdk.javadoc/share/man/javadoc.md"); now.

If only one could suggest changes in files not touched by a pull request: https://github.com/orgs/community/discussions/9099

jonathan-gibbons · 2024-11-13T21:18:34Z

I think this means the one-true-master copy of a man page is now the public .md file. All contributors can now change and improve man pages, and would be expected to make necessary man page updates when making other changes. (Which is great, I just didn't see it being explicitly said.)

Yes, related:
Non-trivial updates to these pages should be approved in a CSR, maybe along with any code changes that may make such an update necessary.

Also related:
Note the format is that supported by pandoc, as embodied in the build system. In particular, definition lists are used quite heavily in these pages, which may not be supported in live previews provided by an IDE. As with any doc change, authors/editors are strongly encouraged to review the generated form of any pages that are being edited.

dholmes-ora

Great to finally see this happen!

Just one glitch with the GPL headers.

Thanks

src/java.base/share/man/java.md

sormuras

A missing .1 to .md file extension change in javadoc's manpage self-test CheckManPageOptions.java is causing the CI to fail.

Details in #22081 (comment)

dfuch

The jwebserver.md looks OK to me.

sormuras · 2024-11-14T12:29:38Z

Now CheckManPageOptions finds the .md file (good) and its checks fail (bad). A candidate for an ignore list as fixing it is out of scope of this PR?

magicus · 2024-11-14T12:41:21Z

Now CheckManPageOptions finds the .md file (good) and its checks fail (bad).

sigh

A candidate for an ignore list as fixing it is out of scope of this PR?

Let me have a look at it first. It seems the test has the indention to handle markdown files, so maybe there is an easy fix.

irisclark

Thanks for updating all the licenses to GPL.

dholmes-ora

LGTM!

dholmes-ora · 2024-11-15T01:25:43Z

Now CheckManPageOptions finds the .md file (good) and its checks fail (bad).

sigh

A candidate for an ignore list as fixing it is out of scope of this PR?

Let me have a look at it first. It seems the test has the indention to handle markdown files, so maybe there is an easy fix.

I'm somewhat surprised that the full src tree is available to this test when it runs. I was expecting it to examine the .1 files in the JDK image.

magicus · 2024-11-15T14:39:39Z

The CheckManPageOptions test had regexps that were not up to date with the latest changes in the markdown file. I fixed those and now the test passes.

magicus · 2024-11-15T14:42:03Z

@dholmes-ora

I was expecting it to examine the .1 files in the JDK image.

It's been like that since the test was created in https://bugs.openjdk.org/browse/JDK-8274211, so there is no change in this PR.

test/langtools/jdk/javadoc/tool/CheckManPageOptions.java

magicus · 2024-11-18T09:22:47Z

/integrate

openjdk · 2024-11-18T09:23:50Z

Going to push as commit 475feb0.
Since your change was applied there have been 90 commits pushed to the master branch:

6c2ae44: 8344204: IGV: Button to enable/disable cutting of long edges
4a7ce1d: 8344205: [PPC]: failing assertion: sharedRuntime_ppc.cpp:1652: cookie not found
b6c2122: 8316151: [macos14] ActionListenerCalledTwiceTest.java fails on macOS 14
543e355: 8344298: Test tools/sincechecker/modules/jdk.hotspot.agent/JdkHotspotAgentCheckSince.java fails on platforms without sa
92b2631: 8327652: S390x: Implements SLP support
a47d9ba: 8344349: Problemlist jdk/jfr/jvm/TestVirtualThreadExclusion.java before JDK-8344199 resolved
80e37a9: 8344265: RISC-V: Remove unused function get_previous_sp_entry
e1c4b49: 8343237: Improve the copying of the available set of Currencies
41a627b: 8343876: Enhancements to jpackage test lib
aa10ec7: 8343123: Nimbus: javax/swing/JInternalFrame/bug6726866.java does not have green undecorated window
... and 80 more: https://git.openjdk.org/jdk/compare/7be77725eab6f45d8f8d23f2ba0d18d2d89a40aa...master

Your commit was automatically rebased without conflicts.

openjdk · 2024-11-18T09:24:05Z

@magicus Pushed as commit 475feb0.

💡 You may see a message that your pull request was closed with unmerged commits. This can be safely ignored.

eirbjo · 2024-11-19T16:27:54Z

Is the warning log when pandoc is not installed a bit loud?

% make images
Building target 'images' in configuration 'macosx-x86_64-server-release'
Warning: pandoc not found. Not generating man pages
Warning: pandoc not found. Not generating man pages
Warning: pandoc not found. Not generating man pages
Warning: pandoc not found. Not generating man pages
Warning: pandoc not found. Not generating man pages
Warning: pandoc not found. Not generating man pages
Warning: pandoc not found. Not generating man pages
Warning: pandoc not found. Not generating man pages
Warning: pandoc not found. Not generating man pages
Warning: pandoc not found. Not generating man pages
Warning: pandoc not found. Not generating man pages
Warning: pandoc not found. Not generating man pages
Warning: pandoc not found. Not generating man pages
Warning: pandoc not found. Not generating man pages
Warning: pandoc not found. Not generating man pages
Warning: pandoc not found. Not generating man pages
Warning: pandoc not found. Not generating man pages
Finished building target 'images' in configuration 'macosx-x86_64-server-release'

magicus · 2024-11-20T16:21:39Z

@eirbjo Yes, that was not intentional. https://bugs.openjdk.org/browse/JDK-8344559.

magicus added 4 commits November 13, 2024 18:01

Replace generated troff man pages with markdown version

4ef47b9

Add missing Windows man pages for kerberos and accessibility

ad85143

Insert GPL header

ae0ed4c

Remove logic for copying .1 man pages

04d9225

Replace tabs with spaces

ffb41ba

openjdk bot added the rfr Pull request is ready for review label Nov 13, 2024

dholmes-ora suggested changes Nov 13, 2024

View reviewed changes

src/java.base/share/man/java.md Outdated Show resolved Hide resolved

sormuras suggested changes Nov 13, 2024

View reviewed changes

dfuch reviewed Nov 14, 2024

View reviewed changes

magicus added 2 commits November 14, 2024 12:05

Remove classpath exception

8361cb4

Fix CheckManPageOptions test

a8d4ea5

irisclark reviewed Nov 14, 2024

View reviewed changes

dholmes-ora approved these changes Nov 15, 2024

View reviewed changes

openjdk bot added the ready Pull request is ready to be integrated label Nov 15, 2024

Fix regexes in CheckManPageOptions

dbef493

openjdk bot removed the ready Pull request is ready to be integrated label Nov 15, 2024

It's somewhat nicer to use \\s instead of space character in regex

7cba61b

sormuras reviewed Nov 15, 2024

View reviewed changes

test/langtools/jdk/javadoc/tool/CheckManPageOptions.java Show resolved Hide resolved

sormuras approved these changes Nov 15, 2024

View reviewed changes

magicus requested a review from dholmes-ora November 15, 2024 18:21

irisclark approved these changes Nov 18, 2024

View reviewed changes

openjdk bot added the ready Pull request is ready to be integrated label Nov 18, 2024

openjdk bot added the integrated Pull request has been integrated label Nov 18, 2024

openjdk bot closed this Nov 18, 2024

openjdk bot removed ready Pull request is ready to be integrated rfr Pull request is ready for review labels Nov 18, 2024

magicus deleted the open-markdown-man-pages branch November 18, 2024 09:25

8344056: Use markdown format for man pages #22081

8344056: Use markdown format for man pages #22081

Uh oh!

Conversation

magicus commented Nov 13, 2024 • edited by openjdk bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Progress

Issue

Reviewers

Reviewing

Uh oh!

bridgekeeper bot commented Nov 13, 2024

Uh oh!

openjdk bot commented Nov 13, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

openjdk bot commented Nov 13, 2024

Uh oh!

jonathan-gibbons commented Nov 13, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mlbridge bot commented Nov 13, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Webrevs

Uh oh!

kevinjwalls commented Nov 13, 2024

Uh oh!

sormuras commented Nov 13, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jonathan-gibbons commented Nov 13, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

dholmes-ora left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

sormuras left a comment

Choose a reason for hiding this comment

Uh oh!

dfuch left a comment

Choose a reason for hiding this comment

Uh oh!

sormuras commented Nov 14, 2024

Uh oh!

magicus commented Nov 14, 2024

Uh oh!

irisclark left a comment

Choose a reason for hiding this comment

Uh oh!

dholmes-ora left a comment

Choose a reason for hiding this comment

Uh oh!

dholmes-ora commented Nov 15, 2024

Uh oh!

magicus commented Nov 15, 2024

Uh oh!

magicus commented Nov 15, 2024

Uh oh!

Uh oh!

magicus commented Nov 18, 2024

Uh oh!

openjdk bot commented Nov 18, 2024

Uh oh!

openjdk bot commented Nov 18, 2024

Uh oh!

eirbjo commented Nov 19, 2024

Uh oh!

magicus commented Nov 20, 2024

Uh oh!

Uh oh!

magicus commented Nov 13, 2024 •

edited by openjdk bot

Loading

openjdk bot commented Nov 13, 2024 •

edited

Loading

jonathan-gibbons commented Nov 13, 2024 •

edited

Loading

mlbridge bot commented Nov 13, 2024 •

edited

Loading

sormuras commented Nov 13, 2024 •

edited

Loading

jonathan-gibbons commented Nov 13, 2024 •

edited

Loading