On Fri, Aug 16, 2013 at 2:59 AM, Derick Rethans <der...@php.net> wrote:
> On Tue, 13 Aug 2013, Hannes Magnusson wrote: > > > On Mon, Aug 12, 2013 at 11:48 PM, Stas Malyshev <smalys...@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. > > Getting the synopsis from our current functions has a lot of dependencies, and you cannot extract them with a xml parser per-file basis. You'd have to kill-off the magic entities and hope the rest looks like as xml that the parser won't choke on. The semantics you get from docbook are of course much more detailed then anything else.. But for what use, and at what cost? There are handful of tools out there that use our docbook sources, vast majority written by us and "easily" ported for our usecases. Most other tools screen scrape the rendered html versions anyway. -Hannes
