Considering switching to restructuredtext (rst)

[cholmes]

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.

[cholmes]

Sorry, for clarification, RST itself doesn't generate different outputs, but it can when combined with a tool like Sphinx.

[cholmes]

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.

[cholmes]

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.