README-builds.html update

[Magnus Ihse Bursie]

On 2015-02-06 18:18, Martijn Verburg wrote:
> Hi all,
>
> So I started digging into this (just the HTML path to start with) and 
> the diff got pretty ridiculous. So I'm going to split the work into 
> several parts:
>
> 1.) Fix HTML warnings and convert HTML styling to CSS styling (using 
> internal stylesheet)
>
> 2.) Cosmetic changes to improve readability (change background to 
> white for contrast, pick a more web readable font etc) and cleaning up 
> any comments/whitespace in the document.
>
> 3.) Structural changes (moving sections around if that seems sensible, 
> I'll post suggestions first)
>
> 4.) Finicky detail changes (the bit that will require the detailed review)
>
> I may combine 1&2 if the diff isn't ridiculously different.
>
> ======
>
> If there's further consensus on Markdown then I can give that a go 
> later (HTML to Markdown converter to start with anyone? ;-)), but I 
> suspect Markdown readers aren't as ubiquitous as HTML readers and we'd 
> have also have to include an "export to output type X" step/tool, not 
> sure how much work that is, where it would get done etc.
>
> Sound reasonable?

If you're prepared to spend the time converting the README to markdown, 
maybe it's kind of waste of effort of first cleaning up the HTML? I'd 
very much appreciate if you would do that -- if was to do it, it would 
surely be put very far down my work queue. :(

I have only heard positive resonses so far (both on the list and in 
private) on going the markdown route, so I think we should at least 
seriously consider it.

As for HTML to markdown converter. I tried sudo apt-get install 
python-html2text, and this is what it produced:
http://cr.openjdk.java.net/~ihse/build-readme/README-builds.md

It's probably a good starting point. Possibly the best way to go forward 
for converting this is a combination of preparing the html document so 
it is easier for html2markdown to process, and a manual post-conversion 
cleanup.

For the next step, I tried sudo apt-get install markdown. As far as I 
can tell, this is the "official" markdown implementation from the guy 
who invented the format. The result of a roundtrip (feeding the 
unmodified README-builds.md from above) is here: 
http://cr.openjdk.java.net/~ihse/build-readme/README-builds-from-md.html

Apart from all the >, it looks pretty OK for something I spent < 5 
minutes on. :)

I also tried just removing the initial > and >>. This looks even better:
http://cr.openjdk.java.net/~ihse/build-readme/README-builds-cleaned.md 
and 
http://cr.openjdk.java.net/~ihse/build-readme/README-builds-cleaned-from-md.html, 
respectively.

Most notably is the lack of tables, which is a limitation in markdown.

I believe that we need to keep a html version in the repo as well, so 
we'd probably have to go by some solution where we have a script (or 
make target) that runs makedown on the .md file to produce the .html 
file, and we'd just have to run that manually when we change the .md 
file. (Judging by the frequency of updates to the README file in the 
past, this is not likely to be very often. :-/)  I can write that part.

/Magnus