Open cholmes opened 11 years ago
Sorry, for clarification, RST itself doesn't generate different outputs, but it can when combined with a tool like Sphinx.
From @rajrsingh
Just spent an hour with RST. Tables were a struggle. The CSV Table type was the only one that felt manageable to me. Better linking options and TOC sounds good, and so does auto-numbering, but we lose good code syntax highlighting. Let's wait on RST.
In response to Raj -
Good to know on tables. I think I was looking at it just because you could do some formatting things that just were not possible in markdown. Specifically cells that span columns, like in http://docutils.sourceforge.net/docs/user/rst/quickref.html#tables
But I guess we could also just have OGC have simpler tables.
For code syntax highlighting, I think you lose that on github, but not on actual sphinx output. See like http://docs.mongodb.org/ecosystem/tutorial/getting-started-with-java-driver/
I guess when I say RST though I really mean RST + Sphinx. The nice output for pdf and html is really the key. I could perhaps see spec development in markdown, and then when it's 1.0 maintain a branch that has a sphinx configuration with rst.
RST will do better tables, and it comes with better tables of contents generation and linking. It will generate a number of different outputs as well, like PDF and html. It shares a number of things in common with markdown, and thus is still quite editable from within github. See https://gist.github.com/dupuy/1855764 for a lot of information. Can help establish best practices for working with rst but still have it displayed well in github.