On Mon, Aug 12, 2013 at 11:48 PM, Stas Malyshev <smalys...@sugarcrm.com> wrote: > Hi! > >> This means that the users/writers of doc have to learn the syntax >> anyway. So in my opinion it would be easier to teach them >> rST+Less-Extra-Rules than Mardown+More-Extra-Rules. > > From what I see in rST (and please correct me if I am wrong) this is > purely presentational markup, as is markdown of course. While right now > we have docs that we can actually parse with tools and get a lot of > information from it, and how things link to each other - moving to > purely presentational markup will destroy all this information. Is it > what we really want to do?
That is exactly the reason why I started this project. We have _tons_ of information in our docs, yet we don't actually use it. Its really in our way actually, and forces everyone to really understand what they are doing before they can contribute.. And even using the OE stuff is still really easy to break. We have a very fixed organization of the docs, and although not forced semantics in a text format, they should still be easily extracted. In case of changelogs, those tables are the onlything under a header called "changelog" so shouldn't be hard to extract. Similar applies to examples. For our linking, we always need a two-pass system. One to index and another to generate the output with lookups in the indexer. I don't see any complications here - as long as we control the tool. As for using off-the-shelve rST thing.. No clue. -Hannes
