On Wed, Jun 15, 2011 at 04:37:16PM -0400, James Bardin wrote: > Just throwing my $.02; how about converting the documentation to > something more easily parse-able, like markdown?
You mean the mainline doc ? If so, it's been discussed to great length in the past, and the short answer is "no". The documentation is always what lags behind code. Whatever barrier you put in front of doc contribs will simply slow them down. I've experienced this a lot in the past with the french doc version which was never updated in contribs. Here I already see what will happen : "I've updated the doc but I'm not sure about the end results as I don't have the tool to regenerate it". The current format leaves no excuse for this. I want a human to be able to parse it and to have to conform to very few rules. What I want is a *smart* converter which understands the doc format. Once we spot the real issues (ambiguous situations where we cannot guess), then we'll fix the format and add a few rules. Also, I regularly receive support from people who work on production systems where they have no choice but reading the doc in the 80x25 text console with vi or less. I absolutely want the doc to be optimally usable there. This means no tags, no long lines, etc... Just plain text formatted right and convertible to other formats for a nicer experience when it's possible. BTW, a "man" output would be nice too ;-) I remember about asciidoc and such which were able to produce various formats, and which could serve as an intermediary format later when we're able to parse what we have. Regards, Willy
