Marketing reST (was Re: What YAML engine do you use?)

From: Aahz (aahz_at_pythoncraft.com)
Date: 01/29/05 

Date: 29 Jan 2005 06:52:51 -0500

In article <mailman.1039.1106341195.22381.python-list@python.org>,
Fredrik Lundh <fredrik@pythonware.com> wrote:
>
>I've read many specs; YAML (both the spec and the format) is easily
>among the worst ten-or-so specs I've ever seen.
>
>ReST and YAML share the same deep flaw: both formats are marketed as
>simple, readable formats, and at a first glance, they look simple and
>readable -- but in reality, they're messy as hell, and chances are
>that the thing you're looking at doesn't really mean what you think it
>means (unless you're the official ReST/YAML parser implementation).
>experienced designers know how to avoid that; the ReST/YAML designers
>don't even understand why they should.

While I can see how you'd get that impression of reST, it's not true:
like Python, reST is intended to be simpl*er* and readable, but not
simple. The joy of reST is that I can concentrate on writing instead of
formatting, just as I do when writing Usenet posts. ;-) Even after
using reST for a long time, I'm still constantly looking up features that
I use rarely (such as correct formatting of URLs).

But reST is great because it's relatively unobtrusive. Those of us
who've used reST to document code for a long time have gotten into the
habit of using some reST-isms even when not writing reST: have you
noticed the number of Pythonistas who use constructs like ``foo()``?
Even if you didn't know it was from reST, the meaning is obvious.

As you say, reST can/does get messy when you're doing complicated things,
but it stays more readable than XML/DocBook. For the most part, I think
I'd also have to disagree with your assertion that reST formatting
doesn't do what you think it does. In cases where your statement is
correct, it's either labeled as an explicit design decision (to prevent
other ugliness) or it's a bug. 

-- 
Aahz (aahz@pythoncraft.com)           <*>         http://www.pythoncraft.com/
"19. A language that doesn't affect the way you think about programming,
is not worth knowing."  --Alan Perlis

Relevant Pages

  • Re: Pictures in Word document
    ... but writing down thoughts and experiences as they come while I am writing. ... But don't bother formatting until you've finished the ... All of your heading styles ... Publishing is a somewhat different workflow from "document production". ...
    (microsoft.public.mac.office.word)
  • Re: Advice needed: Text editor with tags.
    ... With Docbook, theoretically, you are writing purely the ... > your desired formatting is quite a mammoth undertaking, ... come up with a set of tags for the XML file so I can try out in Tcl. ... All editing functions in the text widget available. ...
    (comp.lang.tcl)
  • Re: Pictures in Word document
    ... I really appreciate your advice and especially for your big chunk of time ... stopped formatting and include the pictures "in line with text", ... Your hint to avoid writing in Page Layout mode is well taken! ... Publishing is a somewhat different workflow from "document production". ...
    (microsoft.public.mac.office.word)
  • Re: Cant Erase/Format CD-RW (WinXP Pro Sp2)
    ... In the CD Writing Tasks pane, click Erase this CD-RW. ... > poor job of formatting the CD-RW. ... > before I installed InCD, WinXP Pro formatted this particular CD with a 650 ...
    (microsoft.public.windowsxp.general)
  • Re: Lecture by Tim Berners-Lee - wow!
    ... is a shame that the WWW specs started out with only a vision of ... Attempts to force browsers to display things in particular ways are ... language, not a formatting language. ... I meant that his vision extended only to markup (which was well ...
    (rec.audio.pro)