
On Fri, Feb 22, 2008 at 10:57 AM, Reinier Lamers
[...] Of course, the source code includes comments that specify what functions do, and so provide a bit of API documentation. But such comments should contain as little formatting as possible to keep them readable in a text editor.
Hi Reinier, Do you know about the [Markdown] format and the [Pandoc] processor? [Markdown] is designed for *readability* in text editors and based on common text conventions.
From the [markdown] home page:
The overriding design goal for Markdown's formatting syntax is to make it as readable as possible. The idea is that a Markdown-formatted document should be publishable as-is, as plain text, without looking like it's been marked up with tags or formatting instructions. While Markdown's syntax has been influenced by several existing text-to-HTML filters, the single biggest source of inspiration for Markdown's syntax is the format of plain text email.
Don't take their word for it or mine. You can copy and paste this message into the [Try Pandoc] page. Regards, - Conal [Markdown]: http://daringfireball.net/projects/markdown "The markdown project page" [Pandoc]: http://johnmacfarlane.net/pandoc/try "The Pandoc project page" [Try Pandoc]: http://johnmacfarlane.net/pandoc/try "Try out Pandoc for yourself"