[Doc-SIG] Re: Comments on DPS and reStructuredText
David Goodger
dgoodger@bigfoot.com
Sun, 05 Aug 2001 00:38:27 -0400
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