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