Quantcast

RFR: JDK-8179022 Add serialization spec as markdown

classic Classic list List threaded Threaded
7 messages Options
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

RFR: JDK-8179022 Add serialization spec as markdown

Magnus Ihse Bursie
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

/Magnus
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: RFR: JDK-8179022 Add serialization spec as markdown

Alan Bateman
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.

-Alan
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: RFR: JDK-8179022 Add serialization spec as markdown

Erik Joelsson
In reply to this post by Magnus Ihse Bursie
The build changes look good to me. I can't comment on the actual .md files.

/Erik


On 2017-04-20 15: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
>
> /Magnus

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: RFR: JDK-8179022 Add serialization spec as markdown

Magnus Ihse Bursie
In reply to this post by Alan Bateman
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

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: RFR: JDK-8179022 Add serialization spec as markdown

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

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: RFR: JDK-8179022 Add serialization spec as markdown

Mandy Chung
In reply to this post by Magnus Ihse Bursie

> On Apr 20, 2017, at 11:47 AM, Magnus Ihse Bursie wrote:
>
> http://cr.openjdk.java.net/~ihse/JDK-8179022-add-markdown-serialization-spec/webrev.02

A passing comment.

Copyright header is missing in make/devkit/createPandocBundle.sh

Mandy

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: RFR: JDK-8179022 Add serialization spec as markdown

roger riggs
In reply to this post by 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
>>
>

Loading...