On Sat, Aug 10, 2013 at 2:45 AM, Christian Weiske <cwei...@cweiske.de> wrote: > Hello Hannes, > > >> I however don't think we can do that with XML. >> And I want to make it even easier to contribute - with essentially no >> learning curve. >> >> Looking around the web.. People seem pretty happy with Markdown... >> Now, markdown has its obvious crazy huge drawbacks when it comes to >> writing documentations.. but I think it can be done. Well.. Sortof. >> >> We would need to create our own Markdown flavour, only adding a tick >> here and there, should give us very readable format where people focus >> on content rather then struggling with picking xml elements or fitting >> things into correct containers or limited semantics. > > > At work we chose reStructuredText[1], because it gives you way more > elements than markdown and is only slighter harder to write. Plain > markdown e.g. has no tables, and definition lists, while rST has it out > of the box.
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. -Hannes
