Hello! On Sun, Aug 6, 2017 at 6:28 PM, Christopher Li <sparse@xxxxxxxxxxx> 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 -- To unsubscribe from this list: send the line "unsubscribe linux-sparse" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
