Hi Magnus,
Looks good, I checked the previous and new html content and found no
significant differences.
There are some content improvements that should be made but that's a
separate task.
Thanks, Roger
On 4/20/2017 2:51 PM, Roger Riggs wrote:
Hi Magnus,
How did you verify that the result was the same as the previous
specification?
It would have been good to separate the content changes from the other
parts
so they could be properly reviewed. The proposed markdown source does
not
favorably easily with the spec as I worked on it a couple of months ago.
That's going to take more work to verify.
Thanks, Roger
On 4/20/2017 2:47 PM, Magnus Ihse Bursie wrote:
On 2017-04-20 15:59, Alan Bateman wrote:
On 20/04/2017 14:49, Magnus Ihse Bursie wrote:
Here's the first step towards fixing JDK-8177434
<https://bugs.openjdk.java.net/browse/JDK-8177434>. A framework is
added for converting markdown specs to html using pandoc. The Java
serialization spec is added in markdown format as a proof of
concept. I also reintroduced the functionality to enable full docs
if all prerequisites are present.
Note that this fix is dependent on the patch for JDK-8178038 et al
that is currently out for review. The webrev is created with that
patch as baseline.
This fix is part of JEP 299. I intend to push it to jdk9.
Here's an example of the generated output:
http://cr.openjdk.java.net/~ihse/JDK-8179022-javadoc-output-demo/specs/serialization/
Bug: https://bugs.openjdk.java.net/browse/JDK-8179022
WebRev:
http://cr.openjdk.java.net/~ihse/JDK-8179022-add-markdown-serialization-spec/webrev.01
I just skimmed this and notice this adds class.gif with output that
I think is serialver. This tool has been changed in JDK 9 to drop
the GUI and so this image and the reference to the "Show" button are
now obsolete. I'm sure you don't want want to get into issues like
this but we will need to submit a few bugs to ensure that some of
the dusty documents are updated.
You are right that I do not want to make any substantial changes to
the documentation. I have made an effort to make sure the markdown is
of a high quality (like any other source code), so that it should be
easy to read and update. In this process I noticed a few minor issues
(like syntactic errors in the examples, or incorrect/inconsistent
formatting) which I have fixed.
I have also noticed some things that sound like they need to be
updated, like the serialver stuff. I'm no expert on serialization,
but perhaps I can have an offline chat with someone who are, and come
with a couple of suggestions on things to improve with the
documentation.
---
I just noticed that I had missed to do "hg add" so webrev did not
pick up my new script that creates the pandoc bundle. Here's an
updated webrev that added this:
http://cr.openjdk.java.net/~ihse/JDK-8179022-add-markdown-serialization-spec/webrev.02
/Magnus
-Alan
