RFR: 8344056: Use markdown format for man pages
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. ------------- Commit messages: - Replace tabs with spaces - Remove logic for copying .1 man pages - Insert GPL header - Add missing Windows man pages for kerberos and accessibility - Replace generated troff man pages with markdown version Changes: https://git.openjdk.org/jdk/pull/22081/files Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=22081&range=00 Issue: https://bugs.openjdk.org/browse/JDK-8344056 Stats: 41443 lines in 65 files changed: 18943 ins; 22500 del; 0 mod Patch: https://git.openjdk.org/jdk/pull/22081.diff Fetch: git fetch https://git.openjdk.org/jdk.git pull/22081/head:pull/22081 PR: https://git.openjdk.org/jdk/pull/22081
On Wed, 13 Nov 2024 17:05:25 GMT, Magnus Ihse Bursie <ihse@openjdk.org> wrote:
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.
Without looking in detail at the changes, this is indeed a welcome and long-overdue change! ------------- PR Comment: https://git.openjdk.org/jdk/pull/22081#issuecomment-2474339519
On Wed, 13 Nov 2024 17:05:25 GMT, Magnus Ihse Bursie <ihse@openjdk.org> wrote:
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.
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.) ------------- PR Comment: https://git.openjdk.org/jdk/pull/22081#issuecomment-2474701337
On Wed, 13 Nov 2024 20:17:24 GMT, Kevin Walls <kevinw@openjdk.org> wrote:
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. ------------- PR Comment: https://git.openjdk.org/jdk/pull/22081#issuecomment-2474804913
On Wed, 13 Nov 2024 17:05:25 GMT, Magnus Ihse Bursie <ihse@openjdk.org> wrote:
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.
So glad to see progress here! https://github.com/openjdk/jdk/blob/1484153c1a092cefc20270b35aa1e508280843a4... should read `return findRootDir().resolve("src/jdk.javadoc/share/man/javadoc.md");` now. ------------- PR Comment: https://git.openjdk.org/jdk/pull/22081#issuecomment-2474760888
On Wed, 13 Nov 2024 17:05:25 GMT, Magnus Ihse Bursie <ihse@openjdk.org> wrote:
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.
Great to finally see this happen! Just one glitch with the GPL headers. Thanks src/java.base/share/man/java.md line 9:
7: # published by the Free Software Foundation. Oracle designates this 8: # particular file as subject to the "Classpath" exception as provided 9: # by Oracle in the LICENSE file that accompanied this code.
Documentation files should not have the Classpath exception. make/data/license-templates/gpl-header ------------- Changes requested by dholmes (Reviewer). PR Review: https://git.openjdk.org/jdk/pull/22081#pullrequestreview-2434474132 PR Review Comment: https://git.openjdk.org/jdk/pull/22081#discussion_r1841189067
On Wed, 13 Nov 2024 21:27:02 GMT, David Holmes <dholmes@openjdk.org> wrote:
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.
src/java.base/share/man/java.md line 9:
7: # published by the Free Software Foundation. Oracle designates this 8: # particular file as subject to the "Classpath" exception as provided 9: # by Oracle in the LICENSE file that accompanied this code.
Documentation files should not have the Classpath exception.
make/data/license-templates/gpl-header
Agree. ------------- PR Review Comment: https://git.openjdk.org/jdk/pull/22081#discussion_r1841231909
On Wed, 13 Nov 2024 21:55:53 GMT, Iris Clark <iris@openjdk.org> wrote:
src/java.base/share/man/java.md line 9:
7: # published by the Free Software Foundation. Oracle designates this 8: # particular file as subject to the "Classpath" exception as provided 9: # by Oracle in the LICENSE file that accompanied this code.
Documentation files should not have the Classpath exception.
make/data/license-templates/gpl-header
Agree.
Yeah, sorry for that, and thanks for catching it. I just copied the header from a build file, since it was conveniently already formatted with the leading `#`. I just assumed that this was the pure GPL and did not check close enough to verify. But it turns out that most of the build system files actually have the classpath exception, which makes no sense. I've filed https://bugs.openjdk.org/browse/JDK-8344191 to deal with that. ------------- PR Review Comment: https://git.openjdk.org/jdk/pull/22081#discussion_r1842039722
On Wed, 13 Nov 2024 17:05:25 GMT, Magnus Ihse Bursie <ihse@openjdk.org> wrote:
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.
A missing `.1` to `.md` file extension change in `javadoc`'s manpage self-test `CheckManPageOptions.java` is causing the CI to fail. Details in https://github.com/openjdk/jdk/pull/22081#issuecomment-2474760888 ------------- Changes requested by cstein (Committer). PR Review: https://git.openjdk.org/jdk/pull/22081#pullrequestreview-2434491865
On Wed, 13 Nov 2024 17:05:25 GMT, Magnus Ihse Bursie <ihse@openjdk.org> wrote:
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.
The jwebserver.md looks OK to me. ------------- PR Review: https://git.openjdk.org/jdk/pull/22081#pullrequestreview-2435435938
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.
Magnus Ihse Bursie has updated the pull request incrementally with two additional commits since the last revision: - Fix CheckManPageOptions test - Remove classpath exception ------------- Changes: - all: https://git.openjdk.org/jdk/pull/22081/files - new: https://git.openjdk.org/jdk/pull/22081/files/ffb41ba0..a8d4ea50 Webrevs: - full: https://webrevs.openjdk.org/?repo=jdk&pr=22081&range=01 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=22081&range=00-01 Stats: 106 lines in 36 files changed: 0 ins; 70 del; 36 mod Patch: https://git.openjdk.org/jdk/pull/22081.diff Fetch: git fetch https://git.openjdk.org/jdk.git pull/22081/head:pull/22081 PR: https://git.openjdk.org/jdk/pull/22081
On Thu, 14 Nov 2024 11:11:54 GMT, Magnus Ihse Bursie <ihse@openjdk.org> wrote:
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.
Magnus Ihse Bursie has updated the pull request incrementally with two additional commits since the last revision:
- Fix CheckManPageOptions test - Remove classpath exception
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? ------------- PR Comment: https://git.openjdk.org/jdk/pull/22081#issuecomment-2476233883
On Thu, 14 Nov 2024 12:29:38 GMT, Christian Stein <cstein@openjdk.org> wrote:
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. ------------- PR Comment: https://git.openjdk.org/jdk/pull/22081#issuecomment-2476258243
On Thu, 14 Nov 2024 11:11:54 GMT, Magnus Ihse Bursie <ihse@openjdk.org> wrote:
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.
Magnus Ihse Bursie has updated the pull request incrementally with two additional commits since the last revision:
- Fix CheckManPageOptions test - Remove classpath exception
Thanks for updating all the licenses to GPL. ------------- PR Review: https://git.openjdk.org/jdk/pull/22081#pullrequestreview-2436927254
On Thu, 14 Nov 2024 11:11:54 GMT, Magnus Ihse Bursie <ihse@openjdk.org> wrote:
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.
Magnus Ihse Bursie has updated the pull request incrementally with two additional commits since the last revision:
- Fix CheckManPageOptions test - Remove classpath exception
LGTM! ------------- Marked as reviewed by dholmes (Reviewer). PR Review: https://git.openjdk.org/jdk/pull/22081#pullrequestreview-2437489438
On Thu, 14 Nov 2024 11:11:54 GMT, Magnus Ihse Bursie <ihse@openjdk.org> wrote:
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.
Magnus Ihse Bursie has updated the pull request incrementally with two additional commits since the last revision:
- Fix CheckManPageOptions test - Remove classpath exception
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. ------------- PR Comment: https://git.openjdk.org/jdk/pull/22081#issuecomment-2477764902
On Fri, 15 Nov 2024 01:25:43 GMT, David Holmes <dholmes@openjdk.org> wrote:
Magnus Ihse Bursie has updated the pull request incrementally with two additional commits since the last revision:
- Fix CheckManPageOptions test - Remove classpath exception
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.
@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. ------------- PR Comment: https://git.openjdk.org/jdk/pull/22081#issuecomment-2479042569
On Thu, 14 Nov 2024 11:11:54 GMT, Magnus Ihse Bursie <ihse@openjdk.org> wrote:
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.
Magnus Ihse Bursie has updated the pull request incrementally with two additional commits since the last revision:
- Fix CheckManPageOptions test - Remove classpath exception
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. ------------- PR Comment: https://git.openjdk.org/jdk/pull/22081#issuecomment-2479038178
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.
Magnus Ihse Bursie has updated the pull request incrementally with one additional commit since the last revision: Fix regexes in CheckManPageOptions ------------- Changes: - all: https://git.openjdk.org/jdk/pull/22081/files - new: https://git.openjdk.org/jdk/pull/22081/files/a8d4ea50..dbef493e Webrevs: - full: https://webrevs.openjdk.org/?repo=jdk&pr=22081&range=02 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=22081&range=01-02 Stats: 12 lines in 1 file changed: 3 ins; 0 del; 9 mod Patch: https://git.openjdk.org/jdk/pull/22081.diff Fetch: git fetch https://git.openjdk.org/jdk.git pull/22081/head:pull/22081 PR: https://git.openjdk.org/jdk/pull/22081
On Fri, 15 Nov 2024 14:46:33 GMT, Magnus Ihse Bursie <ihse@openjdk.org> wrote:
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.
Magnus Ihse Bursie has updated the pull request incrementally with one additional commit since the last revision:
Fix regexes in CheckManPageOptions
test/langtools/jdk/javadoc/tool/CheckManPageOptions.java line 277:
275: 276: // In the defining areas, option names are represented as follows: 277: // `OPTION` or `OPTION`
`OPTION` or `OPTION` ... where's the difference? ------------- PR Review Comment: https://git.openjdk.org/jdk/pull/22081#discussion_r1843959156
On Fri, 15 Nov 2024 15:00:39 GMT, Christian Stein <cstein@openjdk.org> wrote:
Magnus Ihse Bursie has updated the pull request incrementally with one additional commit since the last revision:
Fix regexes in CheckManPageOptions
test/langtools/jdk/javadoc/tool/CheckManPageOptions.java line 277:
275: 276: // In the defining areas, option names are represented as follows: 277: // `OPTION` or `OPTION`
`OPTION` or `OPTION` ... where's the difference?
Some options have multiple variants displayed on a single row, like: `--classpath` or `-cp` This was handled in the troff format but not updated for markdown. ------------- PR Review Comment: https://git.openjdk.org/jdk/pull/22081#discussion_r1843969778
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.
Magnus Ihse Bursie has updated the pull request incrementally with one additional commit since the last revision: It's somewhat nicer to use \\s instead of space character in regex ------------- Changes: - all: https://git.openjdk.org/jdk/pull/22081/files - new: https://git.openjdk.org/jdk/pull/22081/files/dbef493e..7cba61b5 Webrevs: - full: https://webrevs.openjdk.org/?repo=jdk&pr=22081&range=03 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=22081&range=02-03 Stats: 1 line in 1 file changed: 0 ins; 0 del; 1 mod Patch: https://git.openjdk.org/jdk/pull/22081.diff Fetch: git fetch https://git.openjdk.org/jdk.git pull/22081/head:pull/22081 PR: https://git.openjdk.org/jdk/pull/22081
On Fri, 15 Nov 2024 14:50:21 GMT, Magnus Ihse Bursie <ihse@openjdk.org> wrote:
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.
Magnus Ihse Bursie has updated the pull request incrementally with one additional commit since the last revision:
It's somewhat nicer to use \\s instead of space character in regex
Marked as reviewed by cstein (Committer). ------------- PR Review: https://git.openjdk.org/jdk/pull/22081#pullrequestreview-2439039366
On Fri, 15 Nov 2024 14:50:21 GMT, Magnus Ihse Bursie <ihse@openjdk.org> wrote:
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.
Magnus Ihse Bursie has updated the pull request incrementally with one additional commit since the last revision:
It's somewhat nicer to use \\s instead of space character in regex
Marked as reviewed by iris (Reviewer). ------------- PR Review: https://git.openjdk.org/jdk/pull/22081#pullrequestreview-2441317522
On Fri, 15 Nov 2024 14:50:21 GMT, Magnus Ihse Bursie <ihse@openjdk.org> wrote:
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.
Magnus Ihse Bursie has updated the pull request incrementally with one additional commit since the last revision:
It's somewhat nicer to use \\s instead of space character in regex
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' ------------- PR Comment: https://git.openjdk.org/jdk/pull/22081#issuecomment-2486187436
On Tue, 19 Nov 2024 16:27:54 GMT, Eirik Bjørsnøs <eirbjo@openjdk.org> wrote:
Magnus Ihse Bursie has updated the pull request incrementally with one additional commit since the last revision:
It's somewhat nicer to use \\s instead of space character in regex
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'
@eirbjo Yes, that was not intentional. https://bugs.openjdk.org/browse/JDK-8344559. ------------- PR Comment: https://git.openjdk.org/jdk/pull/22081#issuecomment-2489029819
On Wed, 13 Nov 2024 17:05:25 GMT, Magnus Ihse Bursie <ihse@openjdk.org> wrote:
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.
This pull request has now been integrated. Changeset: 475feb06 Author: Magnus Ihse Bursie <ihse@openjdk.org> URL: https://git.openjdk.org/jdk/commit/475feb064bb6b9dfd34fc52762e3e0ab825254ec Stats: 41386 lines in 66 files changed: 18876 ins; 22500 del; 10 mod 8344056: Use markdown format for man pages Reviewed-by: cstein, iris, dholmes ------------- PR: https://git.openjdk.org/jdk/pull/22081
participants (8)
-
Christian Stein
-
Daniel Fuchs
-
David Holmes
-
Eirik Bjørsnøs
-
Iris Clark
-
Jonathan Gibbons
-
Kevin Walls
-
Magnus Ihse Bursie