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

[Tony J Ibbs (Tibs)]

Ka-Ping Yee wrote:
> 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?

Ah - I see what you mean. Yes, as written it *does* make it sound like I
think reST is difficult to remember - but one has to remember that I've
been working on different versions of the "same" thing for some time,
and thus am quite likely to mistype between different versions. In
particular, fingers that are used to typing '..' to mean literal text
must now learn to type ``..``, and my "dearly beloved" #..# has likewise
been replaced. Also, I keep getting the target end of links wrong (e.g.,
whether one needs a colon after [footnote] at the target end) - this
*may* show a slight problem in the format, or just in my fingertips.
*And* I was typing quite a lot of text fairly fast, so I'd have been
making mistakes in any syntax...

So I'm *not* saying that reST is hard (for me) to learn - I'm intimating
that (a) I'm a confused person in this field for historical reasons, and
(b) that I am one of the people who *really* needs a quick reference to
hand for just this purpose.

On the whole, reST has very little markup - there's

    - *..* and **..** (traditional by now)
    - `..`_ or word_ for links (OK - one
      simple thing to learn)
    - ``..`` for literals

and some layout stuff. Doesn't mean I can't get it wrong! I'd be
surprised if I hadn't used `..` to mean an inline literal somewhere.
(and, of course, the XEmacs mode I was using was putting tabs in when I
didn't think it was, which is another matter - looks bad in Outlook at
my end, anyway). The *great* thing is that it leaves 'normal' quote
marks alone.

Tibs

--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
Well we're safe now....thank God we're in a bowling alley.
- Big Bob (J.T. Walsh) in "Pleasantville"
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)