Hacker News Reader

Comment by wreel | Hacker News Reader

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).

View on HN

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

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.

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.

It isn't listed in the Sphinx doc 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/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.

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-restructure...;

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>`__

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...

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.

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.

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

Reply on news.ycombinator.com