Re: Converting README documentation to Markdown

> I've been thinking about this some more. I think the most value here
> would be to just improve the plain-text formatting, so that there are
> consistent list styles, header styles, indentation, some of the
> ambiguities cleared up -- much of which your 0001 patch does. You
> might as well be targeting markdown-like conventions with this; they
> are mostly reasonable.
>
> I tend to think that actually converting all the README files to
> README.md could be a net negative for maintainability. Because now
> you are requiring everyone who potentially wants to edit those to be
> aware of Markdown syntax and manually check the rendering. With
> things like DocBook, if you make a mess, you get error messages from
> the build step. If you make a mess in Markdown, you have to visually
> find it yourself. There are many READMEs that contain nested lists
> and code snippets and diagrams and such all mixed together. Getting
> that right in Markdown can be quite tricky. I'm also foreseeing
> related messes of trailing whitespace, spaces-vs-tab confusion,
> gitattributes violations, etc. It can be a lot of effort. It's okay
> to do this for prominent files like the top-level one, but I suggest
> that for the rest we can keep it simple and just use plain text.

Agreed.

Best reagards,
--
Tatsuo Ishii
SRA OSS LLC
English: http://www.sraoss.co.jp/index_en/
Japanese:http://www.sraoss.co.jp