Le 15/06/11 23:09, Willy Tarreau a écrit : > 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.
markdown and asciidoc pretty are similar, and human readable. That said I agree with everything you said. For instance, Mercurial documentation was migrated from standalone text file to simplified reStructuredText version (a popular format in python world) mostly embedded in source code and this has been a huge win. We are now able to generate documentation in different formats (console output, manpages, HTML), display the same documentation from the CLI or web interface and even generate documentation dynamically for features brought by third-parties plugins. -- Patrick Mézard
