On Sat, Aug 10, 2013 at 9:01 PM, Hannes Magnusson < hannes.magnus...@gmail.com> wrote:
> That is pretty much exactly why I didn't want to use it. > It was just to much. I actually need to learn the syntax before I can > write it. > > I don't want the the strong semantics relations anymore. Dirt simple is > the new plan. > > Yes, we do need to introduce some new stuff - like tables for changelogs > (which are already included in the example document I attached). > We also need to introduce magical elements (which are already included in > the example document I attached) which cross link functions, types, > constants, whatever. > These magical elements are all confined in the linking marker [], and I > hope they have obvious meaning: > > [TYPE:FALSE] > [CONSTANT:HTML_SPECIALCHARS] > [SNIPPET:RETURN.FALSEPROBLEM] > > > Python for example also uses rST (or whatever the current acronym for it > is). I know it is a decent format, but I don't want people needing to read > some primer explaining all the details and gotchas before they can do stuff. > > Keep in mind the example was just something I randomly manually cooked up > from the strpos example. > We can bikeshed all we want if a line ending in a space should cause the > next line to be a separate paragraph (wtf?) or if * is a better list token > then -. > > It doesn't matter and I don't really care :) > We can call this format rSTown (rST and markdown hybrid) if we want. > It just needs to be extremely simple and first and foremost: not be in my > way. > First of all: +1 on the general idea :) I always liked to complain about the XML docs. But anyway, I think for writing docs you do need quite a bit of syntax support and if you want to slap all this onto Markdown you'd basically end up with RST-but-doesn't-quite-have-the-syntax-of-RST. I don't see much point in inventing a new language you need to learn if there already is one that has pretty much exactly the features we need. Markdown and rST are very similar when it comes to "basic" editing, only significant difference beeing that Markdown uses `code` while RST uses ``code``. RST just additionally supports all those other things docs need (like crossreferences, tables, custom directives, etc). tl;dr: I think rst would be a good choice for this purpose :) Nikita
