RFR: JDK-8139668 Generate README-build.html from markdown
Magnus Ihse Bursie
magnus.ihse.bursie at oracle.com
Thu Oct 15 14:38:22 UTC 2015
Finished.
The build documentation is currently available in README-build.html. The
problem with having the build instructions in html format is two-fold:
1) It is hard to read from a terminal
2) It is unnecessary difficult to modify
At least 2) means that it is an extra threshold to get over, in order to
update or rewrite the build documentation.
Instead, we should have the documentation in markdown format, which is
easy to read in a console even in source format, and is easy to modify.
From this source format, a html version can easily be generated.
In this change, I have intentionally *not* modified the contents of the
documentation. Instead, this patch will prepare the ground for future
fixes to the documentation. There are a few, minor changes that was
needed. Tables are not very easy to represent in markdown, so I replaced
a few tables with lists. I also modified a few places (e.g. when
refering to the documentation file as "html").
The markdown file originated from the old html file. I started out using
automated tools for converting html to markdown, but then spent some
time polishing the markdown to make sure the resulting html matched the
original file as closely as possible. I also wanted to make sure the
markdown was readable in itself, to address item 1 above.
Bug: https://bugs.openjdk.java.net/browse/JDK-8139668
WebRev:
http://cr.openjdk.java.net/~ihse/JDK-8139668-markdown-documentation/webrev.01
More information about the build-dev
mailing list