RFR: JDK-8176509 Use pandoc for converting build readme to html

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

RFR: JDK-8176509 Use pandoc for converting build readme to html

Magnus Ihse Bursie
Since JDK-8139668, the build README html file has been generated from a
markdown source.

Unfortunately, this implementation used the original markdown (from
https://daringfireball.net/projects/markdown/), which was quite limited,
and did not for instance allow for tables.

Now that JEP 299 is about to standardize on using pandoc to convert
markdown to man pages, I think it would be reasonable to use it to
convert the build README to html as well.

I also used this opportunity to clean up redundant and/or incorrect
information spread in the READMEs all over the forest, and to move the
build READMEs to a better location.

Please note that the *content* of the README file is severly outdated
(not to mention unstructured and sometimes irrelevant), but updating
that is not part of the scope for this bug. I will follow up on it, though.

Bug: https://bugs.openjdk.java.net/browse/JDK-8176509

There's no easy way to get WebRev to both incorporate cross-repo files
*and* show diffs for moved files.

So here's one that shows all files:
WebRev:
http://cr.openjdk.java.net/~ihse/JDK-8176509-use-pandoc-for-build-readme/webrev.01

And here's one that shows the diff for the moved files:
http://cr.openjdk.java.net/~ihse/JDK-8176509-use-pandoc-for-build-readme/webrev.03

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

Re: RFR: JDK-8176509 Use pandoc for converting build readme to html

Erik Joelsson
Hello,

Nice to see this handled by make.

In UpdateBuildDocs.gmk, the test for PANDOC can be moved out of the
macro body and just be executed once. In the recipe, you call
CheckLineLength, which I don't see defined anywhere, but then the logic
just after the call looks like what would be the implementation.

/Erik


On 2017-03-10 15:50, Magnus Ihse Bursie wrote:

> Since JDK-8139668, the build README html file has been generated from
> a markdown source.
>
> Unfortunately, this implementation used the original markdown (from
> https://daringfireball.net/projects/markdown/), which was quite
> limited, and did not for instance allow for tables.
>
> Now that JEP 299 is about to standardize on using pandoc to convert
> markdown to man pages, I think it would be reasonable to use it to
> convert the build README to html as well.
>
> I also used this opportunity to clean up redundant and/or incorrect
> information spread in the READMEs all over the forest, and to move the
> build READMEs to a better location.
>
> Please note that the *content* of the README file is severly outdated
> (not to mention unstructured and sometimes irrelevant), but updating
> that is not part of the scope for this bug. I will follow up on it,
> though.
>
> Bug: https://bugs.openjdk.java.net/browse/JDK-8176509
>
> There's no easy way to get WebRev to both incorporate cross-repo files
> *and* show diffs for moved files.
>
> So here's one that shows all files:
> WebRev:
> http://cr.openjdk.java.net/~ihse/JDK-8176509-use-pandoc-for-build-readme/webrev.01
>
> And here's one that shows the diff for the moved files:
> http://cr.openjdk.java.net/~ihse/JDK-8176509-use-pandoc-for-build-readme/webrev.03 
>
>
> /Magnus

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

Re: RFR: JDK-8176509 Use pandoc for converting build readme to html

Magnus Ihse Bursie
On 2017-03-13 09:17, Erik Joelsson wrote:
> Hello,
>
> Nice to see this handled by make.
>
> In UpdateBuildDocs.gmk, the test for PANDOC can be moved out of the
> macro body and just be executed once.
I started out that way, but thought the check more properly belonged in
the function. But then again, the entire file depends on pandoc, so
sure, I'll move it back :-)

> In the recipe, you call CheckLineLength, which I don't see defined
> anywhere, but then the logic just after the call looks like what would
> be the implementation.

Yeah... It used to be a separate function but then I inlined it. Removed
the call now.

Updated webrev:
http://cr.openjdk.java.net/~ihse/JDK-8176509-use-pandoc-for-build-readme/webrev.04

/Magnus

>
> /Erik
>
>
> On 2017-03-10 15:50, Magnus Ihse Bursie wrote:
>> Since JDK-8139668, the build README html file has been generated from
>> a markdown source.
>>
>> Unfortunately, this implementation used the original markdown (from
>> https://daringfireball.net/projects/markdown/), which was quite
>> limited, and did not for instance allow for tables.
>>
>> Now that JEP 299 is about to standardize on using pandoc to convert
>> markdown to man pages, I think it would be reasonable to use it to
>> convert the build README to html as well.
>>
>> I also used this opportunity to clean up redundant and/or incorrect
>> information spread in the READMEs all over the forest, and to move
>> the build READMEs to a better location.
>>
>> Please note that the *content* of the README file is severly outdated
>> (not to mention unstructured and sometimes irrelevant), but updating
>> that is not part of the scope for this bug. I will follow up on it,
>> though.
>>
>> Bug: https://bugs.openjdk.java.net/browse/JDK-8176509
>>
>> There's no easy way to get WebRev to both incorporate cross-repo
>> files *and* show diffs for moved files.
>>
>> So here's one that shows all files:
>> WebRev:
>> http://cr.openjdk.java.net/~ihse/JDK-8176509-use-pandoc-for-build-readme/webrev.01
>>
>> And here's one that shows the diff for the moved files:
>> http://cr.openjdk.java.net/~ihse/JDK-8176509-use-pandoc-for-build-readme/webrev.03 
>>
>>
>> /Magnus
>

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

Re: RFR: JDK-8176509 Use pandoc for converting build readme to html

Erik Joelsson
Looks good.

/Erik


On 2017-03-13 09:32, Magnus Ihse Bursie wrote:

> On 2017-03-13 09:17, Erik Joelsson wrote:
>> Hello,
>>
>> Nice to see this handled by make.
>>
>> In UpdateBuildDocs.gmk, the test for PANDOC can be moved out of the
>> macro body and just be executed once.
> I started out that way, but thought the check more properly belonged
> in the function. But then again, the entire file depends on pandoc, so
> sure, I'll move it back :-)
>
>> In the recipe, you call CheckLineLength, which I don't see defined
>> anywhere, but then the logic just after the call looks like what
>> would be the implementation.
>
> Yeah... It used to be a separate function but then I inlined it.
> Removed the call now.
>
> Updated webrev:
> http://cr.openjdk.java.net/~ihse/JDK-8176509-use-pandoc-for-build-readme/webrev.04
>
> /Magnus
>>
>> /Erik
>>
>>
>> On 2017-03-10 15:50, Magnus Ihse Bursie wrote:
>>> Since JDK-8139668, the build README html file has been generated
>>> from a markdown source.
>>>
>>> Unfortunately, this implementation used the original markdown (from
>>> https://daringfireball.net/projects/markdown/), which was quite
>>> limited, and did not for instance allow for tables.
>>>
>>> Now that JEP 299 is about to standardize on using pandoc to convert
>>> markdown to man pages, I think it would be reasonable to use it to
>>> convert the build README to html as well.
>>>
>>> I also used this opportunity to clean up redundant and/or incorrect
>>> information spread in the READMEs all over the forest, and to move
>>> the build READMEs to a better location.
>>>
>>> Please note that the *content* of the README file is severly
>>> outdated (not to mention unstructured and sometimes irrelevant), but
>>> updating that is not part of the scope for this bug. I will follow
>>> up on it, though.
>>>
>>> Bug: https://bugs.openjdk.java.net/browse/JDK-8176509
>>>
>>> There's no easy way to get WebRev to both incorporate cross-repo
>>> files *and* show diffs for moved files.
>>>
>>> So here's one that shows all files:
>>> WebRev:
>>> http://cr.openjdk.java.net/~ihse/JDK-8176509-use-pandoc-for-build-readme/webrev.01
>>>
>>> And here's one that shows the diff for the moved files:
>>> http://cr.openjdk.java.net/~ihse/JDK-8176509-use-pandoc-for-build-readme/webrev.03 
>>>
>>>
>>> /Magnus
>>
>

Loading...