4 ms·

I found that I've moved on to reStructuredText. It doesn't seem to be marketed as much as Markdown (the only reason I know about it is because of Sphinx) but I

by wreel 14y ago

I found that I've moved on to reStructuredText. It doesn't seem to be marketed as much as Markdown (the only reason I know about it is because of Sphinx) but I feel that it's a bit more capable. Simple tables are exceptionally easy and it handles URLs with parens in it just fine (a common pain when trying to link to Wikipedia articles with Markdown).

rogerbinns 14y ago
I use rst for everything due to using Sphinx heavily. Trivial tables are easy in any markup, but non-trivial ones are a pain. I use table mode in emacs, but we can't require everyone to use emacs. I hate its URL handling. And of course it needed Sphinx to make it work across more than one source file which means we now have two dialects. I do wish everyone would just agree on one syntax and be done with it.
- bookweevil 14y ago
  Have you tried using the list-table directive? I find it's a much easier way to create tables - it's based on writing indented lists which mirror the logical structure of the table (i.e., table / row / cell), rather than trying to produce ASCII art.
  - rogerbinns 14y ago
    It isn't listed in the Sphinx doc http://sphinx.pocoo.org/rest.html#tables http://sphinx.pocoo.org/rest.html#tables - and it points to rst doc only showing those two as well http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#tables http://docutils.sourceforge.net/docs/ref/rst/restructuredtex... All my doc is in Sphinx so I play it safe, and all directives need to be supported in whatever version of docutils and rst2pdf are installed across the various developer machines. So for the moment I am stuck with ascii art.
- tadhg 14y ago
  Regarding the URL handling, I also used to hate it, but wrote a tool to make it easier to deal with; details are here if you're interested (despite the title, the relevant tool is not Vim-only): <http://tadhg.com/wp/2012/10/07/tools-for-writing-restructuredtext-in-vim/#restructuredtext-references&#62 http://tadhg.com/wp/2012/10/07/tools-for-writing-restructure...;
  - rogerbinns 14y ago
    The bit I hate is that I have no desire to have a global list of URLs and manage them. So instead I have to put a double underscore suffix after every url otherwise you get bizarre error messages. eg `foo <foo.com>`__
- gordonguthrie 14y ago
  But sphinx produces tables with an inline border="1" in them. Plowing through the sources to figure out where that happens... (docutils?). Any thoughs/pointers would be welcome from a passing reader of this comment...
uvtc 14y ago
I wrote up a little comparison of reST and Pandoc-Markdown, http://www.unexpected-vortices.com/doc-notes/markdown-and-rest-compared.html http://www.unexpected-vortices.com/doc-notes/markdown-and-re... , which might be of interest to some.
riffraff 14y ago
rst is definitely better than markdown. Honestly I also prefer textile to markdown. And I sorta believe wikicreole is better than markdown. I cannot understand for what reason MD has become popular, it has an annoying and confusing syntax for half of the things, supports many less things than others and is not stricly better in any way I can think of.
- lmm 14y ago
  Supporting many less things is markdown's big advantage. It's a format that makes everything as simple as possible, but no simpler; it's the perfect format for "almost-plain" text like I often want in a readme - mostly plain text, but with headings, bulleted lists and the occasional hyperlink. Compared to rst it's a lot easier to write links. I hadn't even heard of textile, but its link syntax also seems harder to write than markdown's. WikiCreole might be better, but right now figuring out what syntax a given wiki will support is far more of a crapshoot than using an arbitrary markdown implementation.
Ingaz 14y ago
I'm in the same boat as you. I'm using reST for everything: docs for people (converting them to html and doc before sending), doc-comments in every language I use, be python, T-SQL, java or F# I don't think it's ideal but it's just works

by wreel 14y ago

rogerbinns 14y ago

I use rst for everything due to using Sphinx heavily. Trivial tables are easy in any markup, but non-trivial ones are a pain. I use table mode in emacs, but we can't require everyone to use emacs. I hate its URL handling. And of course it needed Sphinx to make it work across more than one source file which means we now have two dialects. I do wish everyone would just agree on one syntax and be done with it.

bookweevil 14y ago
Have you tried using the list-table directive? I find it's a much easier way to create tables - it's based on writing indented lists which mirror the logical structure of the table (i.e., table / row / cell), rather than trying to produce ASCII art.
- rogerbinns 14y ago
  It isn't listed in the Sphinx doc http://sphinx.pocoo.org/rest.html#tables http://sphinx.pocoo.org/rest.html#tables - and it points to rst doc only showing those two as well http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#tables http://docutils.sourceforge.net/docs/ref/rst/restructuredtex... All my doc is in Sphinx so I play it safe, and all directives need to be supported in whatever version of docutils and rst2pdf are installed across the various developer machines. So for the moment I am stuck with ascii art.
tadhg 14y ago
Regarding the URL handling, I also used to hate it, but wrote a tool to make it easier to deal with; details are here if you're interested (despite the title, the relevant tool is not Vim-only): <http://tadhg.com/wp/2012/10/07/tools-for-writing-restructuredtext-in-vim/#restructuredtext-references&#62 http://tadhg.com/wp/2012/10/07/tools-for-writing-restructure...;
- rogerbinns 14y ago
  The bit I hate is that I have no desire to have a global list of URLs and manage them. So instead I have to put a double underscore suffix after every url otherwise you get bizarre error messages. eg `foo <foo.com>`__
gordonguthrie 14y ago
But sphinx produces tables with an inline border="1" in them. Plowing through the sources to figure out where that happens... (docutils?). Any thoughs/pointers would be welcome from a passing reader of this comment...

uvtc 14y ago

I wrote up a little comparison of reST and Pandoc-Markdown, http://www.unexpected-vortices.com/doc-notes/markdown-and-rest-compared.html http://www.unexpected-vortices.com/doc-notes/markdown-and-re... , which might be of interest to some.

riffraff 14y ago

rst is definitely better than markdown. Honestly I also prefer textile to markdown. And I sorta believe wikicreole is better than markdown. I cannot understand for what reason MD has become popular, it has an annoying and confusing syntax for half of the things, supports many less things than others and is not stricly better in any way I can think of.

lmm 14y ago
Supporting many less things is markdown's big advantage. It's a format that makes everything as simple as possible, but no simpler; it's the perfect format for "almost-plain" text like I often want in a readme - mostly plain text, but with headings, bulleted lists and the occasional hyperlink. Compared to rst it's a lot easier to write links. I hadn't even heard of textile, but its link syntax also seems harder to write than markdown's. WikiCreole might be better, but right now figuring out what syntax a given wiki will support is far more of a crapshoot than using an arbitrary markdown implementation.

Ingaz 14y ago

I'm in the same boat as you. I'm using reST for everything: docs for people (converting them to html and doc before sending), doc-comments in every language I use, be python, T-SQL, java or F# I don't think it's ideal but it's just works