RFR: JDK-8179022 Add serialization spec as markdown

[Roger Riggs]

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
>>
>