Sparse documentation format, rST vs MD

Sparse documentation format, rST vs MD

[Christopher Li]

I want to use some mark down format for the document
of sparse.

There is two choice here:

rST (reStructuredText)
https://en.wikipedia.org/wiki/ReStructuredText

MD (Mark Down)
https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet

Does any one care which format to use?

So far I am weak leaning towards MD but I can be convenience
otherwise. Mostly because MD render on github is very nicely.
I already use MD on other projects.

Here is my run down of Pros and Cons
rST Pros:

-  Linux kernel already using rST for documents like
   submiting-patches.rst. I need a file for sparse version of
   submitting-patches.

- might be more friendly to code syntax. But I am not going to use
  those really deep extensions any way.

rST Cons (for me):
- I don't know rST at all. I need to learn it.
- github does not recognized rST naturally.


MarkDown Pros:
- More friendly to web.
- Github etc can render .md properly on display.
- I already know how the syntax. No need to learn.

MarkdDown Cons:
- Kernel is using rST. I need to convert the format if I borrow
  some file from the Linux Kernel.

Feed back?

Chris

Re: Sparse documentation format, rST vs MD

[Luc Van Oostenryck]

On Mon, Aug 7, 2017 at 3:28 AM, Christopher Li <sparse@chrisli.org> wrote:
> I want to use some mark down format for the document
> of sparse.
>
> There is two choice here:
>
> rST (reStructuredText)
> https://en.wikipedia.org/wiki/ReStructuredText
>
> MD (Mark Down)
> https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet
>
> Does any one care which format to use?

Personally, I would stay with simple text files.
But as long as it is very readable as a text file I don't really care.

I often use the MediaWiki syntax when writing simple text because
I'm so used to it (it's what I have used for the instruction's doc) but
I would certainly not push for it.

MD is very fine for me.
The advantage that it's the format for github doesn't matter much
though since sparse is not hosted on github.

The real question to me is: do you intent to render it?

-- Luc

Re: Sparse documentation format, rST vs MD

[Christopher Li]

On Sun, Aug 6, 2017 at 9:44 PM, Luc Van Oostenryck
<luc.vanoostenryck@gmail.com> wrote:
>
> Personally, I would stay with simple text files.
> But as long as it is very readable as a text file I don't really care.

Both are close enough to text file and some what readable
as the raw form. I think md is slightly easier to read in raw form
than rST but I might be biased because I know MD already.

> I often use the MediaWiki syntax when writing simple text because
> I'm so used to it (it's what I have used for the instruction's doc) but
> I would certainly not push for it.
>
> MD is very fine for me.
> The advantage that it's the format for github doesn't matter much
> though since sparse is not hosted on github.

I am thinking if we want to invite other developers. It is more
likely for them to host on github than kernel.org. We can also keep a
github mirror of sparse. I have one but I haven't update it for a while.

> The real question to me is: do you intent to render it?

Oh, I often do. I have makefile that render md as pdf and html.
It is easier to pass around that way for people only need to read
it.

I also use the chrome plugin to view MD directly as the render
result. Things like tables in MD can translate to html tables which is
very nice.

I assume rST can do html table and render as pdf/html as well.

Chris

Re: Sparse documentation format, rST vs MD

[Josh Triplett]

On Sun, Aug 06, 2017 at 09:28:58PM -0400, Christopher Li wrote:
> I want to use some mark down format for the document
> of sparse.
> 
> There is two choice here:
> 
> rST (reStructuredText)
> https://en.wikipedia.org/wiki/ReStructuredText
> 
> MD (Mark Down)
> https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet
> 
> Does any one care which format to use?
> 
> So far I am weak leaning towards MD but I can be convenience
> otherwise. Mostly because MD render on github is very nicely.
> I already use MD on other projects.
> 
> Here is my run down of Pros and Cons
> rST Pros:
> 
> -  Linux kernel already using rST for documents like
>    submiting-patches.rst. I need a file for sparse version of
>    submitting-patches.
> 
> - might be more friendly to code syntax. But I am not going to use
>   those really deep extensions any way.
> 
> rST Cons (for me):
> - I don't know rST at all. I need to learn it.
> - github does not recognized rST naturally.
> 
> 
> MarkDown Pros:
> - More friendly to web.
> - Github etc can render .md properly on display.
> - I already know how the syntax. No need to learn.
> 
> MarkdDown Cons:
> - Kernel is using rST. I need to convert the format if I borrow
>   some file from the Linux Kernel.
> 
> Feed back?

I personally find the Markdown format *much* closer to normal text
formatting in email, and I'd highly recommend using it.  I'm not sure
why the kernel picked reStructuredText, but I don't think there's likely
to be a huge amount of cross-pollination between the two in terms of
documentation.  In particular, you're unlikely to want to borrow files
from the kernel given the different license.

Re: Sparse documentation format, rST vs MD

[Pavel Roskin]

Hello!

On Sun, Aug 6, 2017 at 6:28 PM, Christopher Li <sparse@chrisli.org> wrote:
> I want to use some mark down format for the document
> of sparse.

It would be great to have more sparse documentation!

> There is two choice here:
>
> rST (reStructuredText)
> https://en.wikipedia.org/wiki/ReStructuredText
>
> MD (Mark Down)
> https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet
>
> Does any one care which format to use?
>
> So far I am weak leaning towards MD but I can be convenience
> otherwise. Mostly because MD render on github is very nicely.
> I already use MD on other projects.
>
> Here is my run down of Pros and Cons
> rST Pros:
>
> -  Linux kernel already using rST for documents like
>    submiting-patches.rst. I need a file for sparse version of
>    submitting-patches.
>
> - might be more friendly to code syntax. But I am not going to use
>   those really deep extensions any way.
>
> rST Cons (for me):
> - I don't know rST at all. I need to learn it.
> - github does not recognized rST naturally.

Not true for that point:
https://github.com/torvalds/linux/blob/master/Documentation/process/submitting-patches.rst

> MarkDown Pros:
> - More friendly to web.

What does it mean exactly? Both should be convertable to HTML.

> - Github etc can render .md properly on display.
> - I already know how the syntax. No need to learn.
>
> MarkdDown Cons:
> - Kernel is using rST. I need to convert the format if I borrow
>   some file from the Linux Kernel.

I would say go with rST unless the major potential contributors insist
on Markdown. Capturing the knowledge is more important than selecting
the format. The format can be changed if a "wrong" choice is made.

Pavel

Re: Sparse documentation format, rST vs MD

[Luc Van Oostenryck]

On Mon, Aug 7, 2017 at 8:03 AM, Pavel Roskin <plroskin@gmail.com> wrote:
> Capturing the knowledge is more important than selecting
> the format. The format can be changed if a "wrong" choice is made.

Absolutely.

-- Luc

Re: Sparse documentation format, rST vs MD

[Christopher Li]

On Mon, Aug 7, 2017 at 2:03 AM, Pavel Roskin <plroskin@gmail.com> wrote:
> Hello!
>
> On Sun, Aug 6, 2017 at 6:28 PM, Christopher Li <sparse@chrisli.org> wrote:
>> I want to use some mark down format for the document
>> of sparse.
>
> It would be great to have more sparse documentation!

OK, if you have more wish list what area of sparse you want to
have. I can add that to my illusion list of sparse projects.


>> rST Cons (for me):
>> - I don't know rST at all. I need to learn it.
>> - github does not recognized rST naturally.
>
> Not true for that point:
> https://github.com/torvalds/linux/blob/master/Documentation/process/submitting-patches.rst

Oh, I did not know that. Thanks for pointing it out.

>
>> MarkDown Pros:
>> - More friendly to web.
>
> What does it mean exactly? Both should be convertable to HTML.


Mark Down can embed html tags easier. If you only care about using
Mark Down in the web, you can do some thing like this:

Disclaimer: I haven't try it myself though, I believe every thing I read
on the internet :-)

# Heading 1

<div class="something" markdown="1">
  ## Heading 2
  Some **bold** text.
</div>


> I would say go with rST unless the major potential contributors insist
> on Markdown. Capturing the knowledge is more important than selecting
> the format. The format can be changed if a "wrong" choice is made.

So far we have 2 on MD (Josh strongly).
You are on reStructuredText.

I just did a google trends comparing keyword "Markdown" and "reStructuredText"
It seems "Markdown" is overwhelming more popular then "reStructuredText".

If I try "RST" then "RST" is slightly ahead of "Markdown", but mostly
due to false positives. Google "RST" most result are not "reStructuredText"
related.

I think I will go with MarkDown for now. You are right the content is the
most important, not the format.

Chris

Re: Sparse documentation format, rST vs MD

[Christopher Li]

On Mon, Aug 7, 2017 at 12:56 AM, Josh Triplett <josh@joshtriplett.org> wrote:

> I personally find the Markdown format *much* closer to normal text

Same here. But I know I am biased.

> formatting in email, and I'd highly recommend using it.  I'm not sure
> why the kernel picked reStructuredText, but I don't think there's likely
> to be a huge amount of cross-pollination between the two in terms of
> documentation.  In particular, you're unlikely to want to borrow files
> from the kernel given the different license.

Mostly just submitting-patches.rst for the Signed-off-by part.
For the coding style we can just point to the Linux kernel one.

I think it is fine to have a few *documents* remain GPL in sparse.
It is not link to any source file. It is not a source file at all.
I don't think any one will nick pick the license detail on this.

Chris

Re: Sparse documentation format, rST vs MD

[Josh Triplett]

On Mon, Aug 07, 2017 at 07:46:25AM -0400, Christopher Li wrote:
> On Mon, Aug 7, 2017 at 12:56 AM, Josh Triplett <josh@joshtriplett.org> wrote:
> 
> > I personally find the Markdown format *much* closer to normal text
> 
> Same here. But I know I am biased.
> 
> > formatting in email, and I'd highly recommend using it.  I'm not sure
> > why the kernel picked reStructuredText, but I don't think there's likely
> > to be a huge amount of cross-pollination between the two in terms of
> > documentation.  In particular, you're unlikely to want to borrow files
> > from the kernel given the different license.
> 
> Mostly just submitting-patches.rst for the Signed-off-by part.
> For the coding style we can just point to the Linux kernel one.
> 
> I think it is fine to have a few *documents* remain GPL in sparse.
> It is not link to any source file. It is not a source file at all.
> I don't think any one will nick pick the license detail on this.

Purely procedural documentation seems fine, sure.

Re: Sparse documentation format, rST vs MD

[Randy Dunlap]

On 08/07/2017 04:29 AM, Christopher Li wrote:
> On Mon, Aug 7, 2017 at 2:03 AM, Pavel Roskin <plroskin@gmail.com> wrote:
>> Hello!
>>
>>
>>> MarkDown Pros:
>>> - More friendly to web.
> 
> So far we have 2 on MD (Josh strongly).
> You are on reStructuredText.

I prefer MD (or asciidoc :) FWIW.

> I just did a google trends comparing keyword "Markdown" and "reStructuredText"
> It seems "Markdown" is overwhelming more popular then "reStructuredText".
> 
> If I try "RST" then "RST" is slightly ahead of "Markdown", but mostly
> due to false positives. Google "RST" most result are not "reStructuredText"
> related.
> 
> I think I will go with MarkDown for now. You are right the content is the
> most important, not the format.


-- 
~Randy

Re: Sparse documentation format, rST vs MD

[Jonathan Corbet]

On Sun, 6 Aug 2017 21:56:12 -0700
Josh Triplett <josh@joshtriplett.org> wrote:

> I'm not sure
> why the kernel picked reStructuredText, but I don't think there's likely
> to be a huge amount of cross-pollination between the two in terms of
> documentation.

To address the "why the kernel picked RST" question, in case anybody's
curious...

We looked hard at MD, AsciiDoc, and RST; indeed, there were patches in
circulation for both MD and AsciiDoc before RST even entered the picture.
In the end RST won out because:

 - It allows the creation of large, integrated, multi-file documents.
   Every MD file is a world unto itself, and AsciiDoc is about the same.
   RST lets us put in nice things like global indexes and cross-references.

 - Some people want to do fancy tables.  It was argued that AsciiDoc is
   actually the best here; MD is not.

 - RST is actively developed and widely used.  AsciiDoc looks stale; MD is
   actively developed in a large number of mostly compatible variants.

 - Production of numerous output formats without the need for obnoxious
   toolchains.  This, alas, turned out not to be true for PDF output; if
   your docs are simpler, though, you might be able to use rst2pdf and
   avoid a lot of pain.

 - RST has a nice extension mechanism that makes it easy for us to add our
   own functionality.

...and probably something else I forgot.  

(I'm not arguing that sparse should or should not use RST, BTW, just
answering Josh's implied question for the kernel).

jon

Re: Sparse documentation format, rST vs MD

[Christopher Li]

On Mon, Aug 7, 2017 at 12:25 PM, Jonathan Corbet <corbet@lwn.net> wrote:
> To address the "why the kernel picked RST" question, in case anybody's
> curious...

Thanks for the explain that is interesting read.

>  - It allows the creation of large, integrated, multi-file documents.
>    Every MD file is a world unto itself, and AsciiDoc is about the same.
>    RST lets us put in nice things like global indexes and cross-references.

That is useful. MD do allow cross reference like html links but I don't know
about global indexes.

Chris