On Sat, Aug 10, 2013 at 12:12 PM, Nikita Popov <nikita....@gmail.com> wrote: > 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).
I'm unsure if either of you actually opened the example file.. Please have a look at it. If you think you can do better, please reply back with a modified file. -Hannes
