[Doc-SIG] Re: Comments on DPS and reStructuredText

[David Goodger]

on 2001-08-04 5:14 PM, Ka-Ping Yee (ping@lfw.org) wrote:
> I know i have been silent on this list for a long time and i apologize
> for barging in, but something startling just caught my eye:
> 
> On Fri, 3 Aug 2001, Tony J Ibbs (Tibs) wrote:
>> I've attempted to write the comments up *using* reST, but I'm fairly
>> sure I'll have done it wrong because I was typing rather than looking up
>> reST syntax.
> 
> Uh, read that sentence again.  Am i the only one that finds it a bit
> frightening?

Why should you? The reStructuredText spec says it should be "easy to read
without any prior knowledge of the markup language" (goal #1 from
introduction.txt). Nobody said it should be easy to *write* without any
prior knowledge. Reading should be transparent; writing takes a little
training. A very little, I hope.

Kind of like Python. Show a C programmer a Python program, and they will
probably be able to understand it. That doesn't mean that they can write one
without some learning first.

-- 
David Goodger    dgoodger@bigfoot.com    Open-source projects:
 - Python Docstring Processing System: http://docstring.sourceforge.net
 - reStructuredText: http://structuredtext.sourceforge.net
 - The Go Tools Project: http://gotools.sourceforge.net