Markdown processor recommendation?

classic Classic list List threaded Threaded
10 messages Options
Reply | Threaded
Open this post in threaded view
|

Markdown processor recommendation?

Rik-4
Does anyone have a recommendation for a Markdown processor?  I did the
obvious thing and used the 'markdown' Debian package, but it is code from
2004 and does an awful job on the Octave NEWS file.  I want to convert the
NEWS file to something else, like HTML, so I can preview how it appears.

--Rik

Reply | Threaded
Open this post in threaded view
|

Re: Markdown processor recommendation?

Andrew Janke-2


On 10/21/19 7:52 PM, Rik wrote:
> Does anyone have a recommendation for a Markdown processor?  I did the
> obvious thing and used the 'markdown' Debian package, but it is code from
> 2004 and does an awful job on the Octave NEWS file.  I want to convert the
> NEWS file to something else, like HTML, so I can preview how it appears.

Kramdown, my man. And pandoc if you need conversions beyond what it
provides.

Cheers,
Andrew

Reply | Threaded
Open this post in threaded view
|

Re: Markdown processor recommendation?

Ardid, Salva-2
In reply to this post by Rik-4

El dilluns, 21 d’octubre de 2019, a les 19:52:38 EDT, Rik va escriure:

  Does anyone have a recommendation for a Markdown processor?  I did the
  obvious thing and used the 'markdown' Debian package, but it is code from
  2004 and does an awful job on the Octave NEWS file.  I want to convert the
  NEWS file to something else, like HTML, so I can preview how it appears.
 
  --Rik
 

I strongly recommend using discount:

http://www.pell.portland.or.us/~orc/Code/discount
https://github.com/Orc/discount
 



Reply | Threaded
Open this post in threaded view
|

Re: Markdown processor recommendation?

Rik-4
On 10/21/2019 05:05 PM, Ardid, Salva wrote:

> El dilluns, 21 d’octubre de 2019, a les 19:52:38 EDT, Rik va escriure:
>
>   Does anyone have a recommendation for a Markdown processor?  I did the
>   obvious thing and used the 'markdown' Debian package, but it is code from
>   2004 and does an awful job on the Octave NEWS file.  I want to convert the
>   NEWS file to something else, like HTML, so I can preview how it appears.
>  
>   --Rik
>  
>
> I strongly recommend using discount:
>
> http://www.pell.portland.or.us/~orc/Code/discount
> https://github.com/Orc/discount
>  

I tried discount Debian package and it produces the same odd rendering for
the first sentences of the NEWS file.  Dang!

The NEWS file begins

- The `intersect`, `setdiff', `setxor`, `union`, and `unique` functions
  accept a new sorting option `"stable"` which will return output values
  in the same order as the input, rather than in ascending order.

Either markdown or discount produce

<li><p>The <code>intersect</code>,
<code>setdiff',</code>setxor<code>,</code>union<code>,
and</code>unique<code>functions
accept a new sorting option</code>&ldquo;stable&rdquo;` which will return
output values
in the same order as the input, rather than in ascending order.</p></li>

The comma character ',' seems to be messing up the markdown parser. 
Instead of each single function name getting wrapped in <code>...</code>
blocks, the wrapping seems arbitrary.

--Rik

Reply | Threaded
Open this post in threaded view
|

Re: Markdown processor recommendation?

siko1056
On 10/22/19 9:35 AM, Rik wrote:

> On 10/21/2019 05:05 PM, Ardid, Salva wrote:
>> El dilluns, 21 d’octubre de 2019, a les 19:52:38 EDT, Rik va escriure:
>>
>>   Does anyone have a recommendation for a Markdown processor?  I did the
>>   obvious thing and used the 'markdown' Debian package, but it is code from
>>   2004 and does an awful job on the Octave NEWS file.  I want to convert the
>>   NEWS file to something else, like HTML, so I can preview how it appears.
>>  
>>   --Rik
>>  
>>
>> I strongly recommend using discount:
>>
>> http://www.pell.portland.or.us/~orc/Code/discount
>> https://github.com/Orc/discount
>>  
>
> I tried discount Debian package and it produces the same odd rendering for
> the first sentences of the NEWS file.  Dang!
>
> The NEWS file begins
>
> - The `intersect`, `setdiff', `setxor`, `union`, and `unique` functions
>   accept a new sorting option `"stable"` which will return output values
>   in the same order as the input, rather than in ascending order.
>
> Either markdown or discount produce
>
> <li><p>The <code>intersect</code>,
> <code>setdiff',</code>setxor<code>,</code>union<code>,
> and</code>unique<code>functions
> accept a new sorting option</code>&ldquo;stable&rdquo;` which will return
> output values
> in the same order as the input, rather than in ascending order.</p></li>
>
> The comma character ',' seems to be messing up the markdown parser. 
> Instead of each single function name getting wrapped in <code>...</code>
> blocks, the wrapping seems arbitrary.
>
> --Rik
>

Rik, I think all Markdown tools did a great job.  Our Markdown markup in
your mentioned case was bad, see

   https://hg.savannah.gnu.org/hgweb/octave/rev/7f1fbc0541bd

Markdown is a super plain robust standard, I can hardly imagine that
tools from 2004 would not do a great job, when neglecting GitHub
Flavored Markdown, Kramdown or other newer extensions.

Kai

Reply | Threaded
Open this post in threaded view
|

Re: Markdown processor recommendation?

Carnë Draug
On Mon, 21 Oct 2019 at 22:10, Kai Torben Ohlhus <[hidden email]> wrote:
> [...]
> Markdown is a super plain robust standard,
> [...]

Markdown is not standardised.  There are several markdown flavours
with different syntax differences, and even more implementations.

I guess it is fine for our simple needs in the NEWS file though.

Reply | Threaded
Open this post in threaded view
|

Re: Markdown processor recommendation?

Rik-4
In reply to this post by siko1056
On 10/21/2019 06:10 PM, Kai Torben Ohlhus wrote:

> On 10/22/19 9:35 AM, Rik wrote:
>> On 10/21/2019 05:05 PM, Ardid, Salva wrote:
>>> El dilluns, 21 d’octubre de 2019, a les 19:52:38 EDT, Rik va escriure:
>>>
>>>   Does anyone have a recommendation for a Markdown processor?  I did the
>>>   obvious thing and used the 'markdown' Debian package, but it is code from
>>>   2004 and does an awful job on the Octave NEWS file.  I want to convert the
>>>   NEWS file to something else, like HTML, so I can preview how it appears.
>>>  
>>>   --Rik
>>>  
>>>
>>> I strongly recommend using discount:
>>>
>>> http://www.pell.portland.or.us/~orc/Code/discount
>>> https://github.com/Orc/discount
>>>  
>> I tried discount Debian package and it produces the same odd rendering for
>> the first sentences of the NEWS file.  Dang!
>>
>> The NEWS file begins
>>
>> - The `intersect`, `setdiff', `setxor`, `union`, and `unique` functions
>>   accept a new sorting option `"stable"` which will return output values
>>   in the same order as the input, rather than in ascending order.
>>
>> Either markdown or discount produce
>>
>> <li><p>The <code>intersect</code>,
>> <code>setdiff',</code>setxor<code>,</code>union<code>,
>> and</code>unique<code>functions
>> accept a new sorting option</code>&ldquo;stable&rdquo;` which will return
>> output values
>> in the same order as the input, rather than in ascending order.</p></li>
>>
>> The comma character ',' seems to be messing up the markdown parser. 
>> Instead of each single function name getting wrapped in <code>...</code>
>> blocks, the wrapping seems arbitrary.
>>
>> --Rik
>>
> Rik, I think all Markdown tools did a great job.  Our Markdown markup in
> your mentioned case was bad, see
>
>    https://hg.savannah.gnu.org/hgweb/octave/rev/7f1fbc0541bd
>
> Markdown is a super plain robust standard, I can hardly imagine that
> tools from 2004 would not do a great job, when neglecting GitHub
> Flavored Markdown, Kramdown or other newer extensions.

Thanks, that fix takes care of it.

After clearing that hurdle, I reviewed the resulting HTML and there were a
few other places that didn't render well.  I fixed those up here
(https://hg.savannah.gnu.org/hgweb/octave/rev/207e0bc53cdd), although I bet
the double spaces at the end of one of the lines--which are required to
introduce a line break in HTML--get deleted in the future by someone intent
on cleaning trailing spaces.

--Rik

Now
> Kai
>
>
>


Reply | Threaded
Open this post in threaded view
|

Re: Markdown processor recommendation?

siko1056
On 10/22/19 11:59 AM, Rik wrote:

>
> After clearing that hurdle, I reviewed the resulting HTML and there were a
> few other places that didn't render well.  I fixed those up here
> (https://hg.savannah.gnu.org/hgweb/octave/rev/207e0bc53cdd), although I bet
> the double spaces at the end of one of the lines--which are required to
> introduce a line break in HTML--get deleted in the future by someone intent
> on cleaning trailing spaces.
>
> --Rik
>

Regarding the double spaces, you are right, this is "dangerous".  My
editor is likely to mess this up, because of automatic removal of
trailing white space.  A better solution might be to either use a sub list:

-    `Octave:colon-complex-argument`   : when any arg is complex
-    `Octave:colon-nonscalar-argument` : when any arg is non-scalar
+  - `Octave:colon-complex-argument`   : when any arg is complex
+  - `Octave:colon-nonscalar-argument` : when any arg is non-scalar

Or to use 8 spaces for indention to automatically get a code block [1]:

-    `Octave:colon-complex-argument`   : when any arg is complex
-    `Octave:colon-nonscalar-argument` : when any arg is non-scalar
+       Octave:colon-complex-argument   : when any arg is complex
+       Octave:colon-nonscalar-argument : when any arg is non-scalar

This might also apply for

-     `format long e uppercase loose`
+       format long e uppercase loose

There is per se no need to use inline code markers.  I used only 6
spaces, because for the Octave website, Jekyll translates Markdown using
Kramdown, for which this indention is sufficient...  Nasty details.

My recent approach was to overhaul the document while a release happens,
to have a nice page on the Octave website as well.  Thus at the moment I
do not care too much for the content formatting.


On 10/22/19 10:28 AM, Carnë Draug wrote:
> On Mon, 21 Oct 2019 at 22:10, Kai Torben Ohlhus <[hidden email]>
wrote:
>> [...]
>> Markdown is a super plain robust standard,
>> [...]
>
> Markdown is not standardised.  There are several markdown flavours
> with different syntax differences, and even more implementations.
>
> I guess it is fine for our simple needs in the NEWS file though.
>

You are right.  Please read "super plain robust markup,".  This was what
I tried to say.

Kai

[1] https://daringfireball.net/projects/markdown/syntax#list

Reply | Threaded
Open this post in threaded view
|

Re: Markdown processor recommendation?

Ardid, Salva-2
In reply to this post by Rik-4

El dilluns, 21 d’octubre de 2019, a les 22:59:10 EDT, Rik va escriure:

  On 10/21/2019 06:10 PM, Kai Torben Ohlhus wrote:
  > On 10/22/19 9:35 AM, Rik wrote:
  >> On 10/21/2019 05:05 PM, Ardid, Salva wrote:
  >>> El dilluns, 21 d’octubre de 2019, a les 19:52:38 EDT, Rik va escriure:
  >>>
  >>>   Does anyone have a recommendation for a Markdown processor?  I did the
  >>>   obvious thing and used the 'markdown' Debian package, but it is code from
  >>>   2004 and does an awful job on the Octave NEWS file.  I want to convert the
  >>>   NEWS file to something else, like HTML, so I can preview how it appears.
  >>>  
  >>>   --Rik
  >>>  
  >>>
  >>> I strongly recommend using discount:
  >>>
  >>> https://nam05.safelinks.protection.outlook.com/?url=http:%2F%2Fwww.pell.portland.or.us%2F~orc%2FCode%2Fdiscount&amp;data=02%7C01%7Csalva.ardid%40yale.edu%7C6fe96c26a0fb4347587e08d7569bdc77%7Cdd8cbebb21394df8b4114e3e87abeb5c%7C0%7C0%7C637073099741402165&amp;sdata=he07ZEYXceaq5q%2FLMSP0YnUnf7P1%2FcIdqMauwgxKDXI%3D&amp;reserved=0
  >>> https://nam05.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2FOrc%2Fdiscount&amp;data=02%7C01%7Csalva.ardid%40yale.edu%7C6fe96c26a0fb4347587e08d7569bdc77%7Cdd8cbebb21394df8b4114e3e87abeb5c%7C0%7C0%7C637073099741402165&amp;sdata=h%2BvR%2BRsX1zQ1C2IuO0RbMhtnEwv1q2fr4u%2BwvlOgg5s%3D&amp;reserved=0
  >>>  
  >> I tried discount Debian package and it produces the same odd rendering for
  >> the first sentences of the NEWS file.  Dang!
  >>
  >> The NEWS file begins
  >>
  >> - The `intersect`, `setdiff', `setxor`, `union`, and `unique` functions
  >>   accept a new sorting option `"stable"` which will return output values
  >>   in the same order as the input, rather than in ascending order.
  >>
  >> Either markdown or discount produce
  >>
  >> <li><p>The <code>intersect</code>,
  >> <code>setdiff',</code>setxor<code>,</code>union<code>,
  >> and</code>unique<code>functions
  >> accept a new sorting option</code>&ldquo;stable&rdquo;` which will return
  >> output values
  >> in the same order as the input, rather than in ascending order.</p></li>
  >>
  >> The comma character ',' seems to be messing up the markdown parser.
  >> Instead of each single function name getting wrapped in <code>...</code>
  >> blocks, the wrapping seems arbitrary.
  >>
  >> --Rik
  >>
  > Rik, I think all Markdown tools did a great job.  Our Markdown markup in
  > your mentioned case was bad, see
  >
  >    https://nam05.safelinks.protection.outlook.com/?url=https%3A%2F%2Fhg.savannah.gnu.org%2Fhgweb%2Foctave%2Frev%2F7f1fbc0541bd&amp;data=02%7C01%7Csalva.ardid%40yale.edu%7C6fe96c26a0fb4347587e08d7569bdc77%7Cdd8cbebb21394df8b4114e3e87abeb5c%7C0%7C0%7C637073099741412159&amp;sdata=P8tZHuNLhZi7Zirsfm2gkmMOf9%2FitAmEa0G1i3b4c7o%3D&amp;reserved=0
  >
  > Markdown is a super plain robust standard, I can hardly imagine that
  > tools from 2004 would not do a great job, when neglecting GitHub
  > Flavored Markdown, Kramdown or other newer extensions.
 
  Thanks, that fix takes care of it.
 
  After clearing that hurdle, I reviewed the resulting HTML and there were a
  few other places that didn't render well.  I fixed those up here
  (https://nam05.safelinks.protection.outlook.com/?url=https%3A%2F%2Fhg.savannah.gnu.org%2Fhgweb%2Foctave%2Frev%2F207e0bc53cdd&amp;data=02%7C01%7Csalva.ardid%40yale.edu%7C6fe96c26a0fb4347587e08d7569bdc77%7Cdd8cbebb21394df8b4114e3e87abeb5c%7C0%7C0%7C637073099741412159&amp;sdata=ZZqQ1nuVT9YW1kauPHEJIwXLcc1y81ims2Ytj7f6WII%3D&amp;reserved=0), although I bet
  the double spaces at the end of one of the lines--which are required to
  introduce a line break in HTML--get deleted in the future by someone intent
  on cleaning trailing spaces.
 
  --Rik
 
  Now
  > Kai
  >
  >
  >
 
 
Perhaps this is not that useful for your use case (and maybe other converters also do it), but just in case, with Discount you can pass markdown flavors/styles as arguments via a CSS file (I tried with Github and Markdown-here styles I found on the internet).

Using this you can anticipate how markdown files will look like in certain environments. Or, although I'm not totally sure this is an option in Discount's library, embed the library in Octave to make the conversion with the flavor you like (or create a new style specific for Octave; I did that myself cherry picking from Github and Markdown-here styles).



Reply | Threaded
Open this post in threaded view
|

Re: Markdown processor recommendation?

Rik-4
In reply to this post by siko1056
On 10/21/2019 08:51 PM, Kai Torben Ohlhus wrote:

> On 10/22/19 11:59 AM, Rik wrote:
>> After clearing that hurdle, I reviewed the resulting HTML and there were a
>> few other places that didn't render well.  I fixed those up here
>> (https://hg.savannah.gnu.org/hgweb/octave/rev/207e0bc53cdd), although I bet
>> the double spaces at the end of one of the lines--which are required to
>> introduce a line break in HTML--get deleted in the future by someone intent
>> on cleaning trailing spaces.
>>
>> --Rik
>>

For a simple language, this sure is getting complex.  I made two more
modifications here: https://hg.savannah.gnu.org/hgweb/octave/rev/5e1f2f1a7fcf.

> Regarding the double spaces, you are right, this is "dangerous".  My
> editor is likely to mess this up, because of automatic removal of
> trailing white space.  A better solution might be to either use a sub list:
>
> -    `Octave:colon-complex-argument`   : when any arg is complex
> -    `Octave:colon-nonscalar-argument` : when any arg is non-scalar
> +  - `Octave:colon-complex-argument`   : when any arg is complex
> +  - `Octave:colon-nonscalar-argument` : when any arg is non-scalar

This puts a bubble 'o' before each warning which I didn't like.  Instead I
used the blockquote operator '>'.  This gets me something I like visually,
but it still has the problem that the trailing spaces are *required* for
the line break.

> Or to use 8 spaces for indention to automatically get a code block [1]:
>
> -    `Octave:colon-complex-argument`   : when any arg is complex
> -    `Octave:colon-nonscalar-argument` : when any arg is non-scalar
> +       Octave:colon-complex-argument   : when any arg is complex
> +       Octave:colon-nonscalar-argument : when any arg is non-scalar
>
> This might also apply for
>
> -     `format long e uppercase loose`
> +       format long e uppercase loose

I made the change to use 8 spaces for an indented code block since that
produces a result similar to the plaintext output of Texinfo which will be
familiar to Octave users.

--Rik