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
