Re: Getting more people involved.. bye bye Docbook

On Tue, 13 Aug 2013, Hannes Magnusson wrote: > On Mon, Aug 12, 2013 at 11:48 PM, Stas Malyshev <smalyshev@sugarcrm.com> wrote: > > > >> 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? <snip> > 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. Sorry, but I don't think you can convince me that rST/MD variants of the synopsis and parameters can be more easily parsed than the XML representation that we currently have. Don't get me wrong, I am not a docbook fan, but it is *great* for showing semantics, whereas rST/Markdown can never really give more than just presentation. cheers, Derick