RFR: JDK-8179022 Add serialization spec as markdown

[Magnus Ihse Bursie]

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