What YAML engine do you use?

[Aahz]

However, I'm torn on whether to use ReST for textual content. On the one
hand, it's looks pretty comprehensive and solidly implemented. But OTOH,
I'm concerned about complexity: I don't want to commit to ReST if it's
going to become a lot of hard work or highly-inefficient when I really
need to use it "in anger".

From what I've seen, pretty much every textual markup targetted for web
content, e.g. wiki markup, seems to have grown/evolved organically,
meaning that it is either underpowered or overpowered, full of special
cases, doesn't have a meaningful object model, etc.

My perception is that reST is a lot like Python itself: it's easy to hit
the ground running, particularly if you restrict yourself to a specific
subset of featuers. It does give you a fair amount of power, and some
things are difficult or impossible.

Note that reST was/is *not* specifically aimed at web content. Several
people have used it for writing books; some people are using it instead
of PowerPoint.

So, I'm hoping that the learned folks here might be able to give me some
pointers to a markup language that has the following characteristics

1. Is straightforward for non-technical users to use, i.e. can be
(mostly) explained in a two to three page document which is
comprehensible to anyone who has ever used a simple word-processor or
text-editor.

2. Allows a wide variety of content semantics to be represented, e.g.
headings, footnotes, sub/superscript, links, etc, etc.

These two criteria seem to be in opposition. I certainly wouldn't
expect a three-page document to explain all these features, not for
non-technical users. reST fits both these criteria, but only for a
selected subset of featuers.

 

[Alan Kennedy]

[Alan Kennedy]

>>However, I'm torn on whether to use ReST for textual content. On the one
>>hand, it's looks pretty comprehensive and solidly implemented. But OTOH,
>>I'm concerned about complexity: I don't want to commit to ReST if it's
>>going to become a lot of hard work or highly-inefficient when I really
>>need to use it "in anger".
>>
>>From what I've seen, pretty much every textual markup targetted for web
>>content, e.g. wiki markup, seems to have grown/evolved organically,
>>meaning that it is either underpowered or overpowered, full of special
>>cases, doesn't have a meaningful object model, etc.

[Aahz]
> My perception is that reST is a lot like Python itself: it's easy to hit
> the ground running, particularly if you restrict yourself to a specific
> subset of featuers. It does give you a fair amount of power, and some
> things are difficult or impossible.
>
> Note that reST was/is *not* specifically aimed at web content. Several
> people have used it for writing books; some people are using it instead
> of PowerPoint.

Thanks, Aahz, that's a key point that I'll continue on below.

[Alan Kennedy]

>>So, I'm hoping that the learned folks here might be able to give me some
>>pointers to a markup language that has the following characteristics
>>
>>1. Is straightforward for non-technical users to use, i.e. can be
>>(mostly) explained in a two to three page document which is
>>comprehensible to anyone who has ever used a simple word-processor or
>>text-editor.
>>
>>2. Allows a wide variety of content semantics to be represented, e.g.
>>headings, footnotes, sub/superscript, links, etc, etc.

[Aahz]
> These two criteria seem to be in opposition. I certainly wouldn't
> expect a three-page document to explain all these features, not for
> non-technical users. reST fits both these criteria, but only for a
> selected subset of featuers.

The point is well made.

When I wrote my requirements, I did have a specific limited feature set
in mind: basically a print-oriented set of features with which anyone
who reads books would be familiar. I'm trying to capture scientific
abstracts, of the sort that you can see linked off this page.

http://www.paratuberculosis.org/proc7/

But I'm basically only interested in representation of the original
input text. I'll be capturing a lot of metadata as well, but most of
that will be captured outside the markup language, through a series of
form inputs which ask specific metadata questions. So, for example, the
relationships between authors and institutions, seen on the next page,
will not be recorded in the markup.

http://www.paratuberculosis.org/proc7/abst5_p2.htm

I think that is where a lot of markup languages fall down, in that they
end trying to develop a sophisticated metadata model that can capture
that kind of information, and re-engineering the markup to support it.
This co-evolution of the markup and model can go horribly awry, if the
designers are inexperienced or don't know where they're headed.

Since ReST seems to do this stuff fairly well, I think I'll take a
closer look at it. From what I've seen of it, e.g. PEPs, python module
documentation (SQLObject, etc), it seems to be reasonably unobtrusive to
the author.

regards,

 

[Aahz]

I think that is where a lot of markup languages fall down, in that they
end trying to develop a sophisticated metadata model that can capture
that kind of information, and re-engineering the markup to support it.
This co-evolution of the markup and model can go horribly awry, if the
designers are inexperienced or don't know where they're headed.

Ayup. Fortunately, David Goodger (the primary architect of reST) has
plenty of experience in this area; reST was written as a reaction to the,
er, organic nature of some other experiments. Nobody involved with the
reST project claims it's perfect, but most of us do think we've made
good tradeoffs (just like Python ;-). Like Guido, David's also pretty
comfortable saying "no"....

One more thing: reST does make it fairly easy to write "self-documenting"
forms -- give your users boilerplate plus some simple instructions, and
they should find it very easy to write their content. (I'm particularly
referring to using bibliographic fields in reST -- that's easier to do
with boilerplate than explain how to do correctly.)


The one thing I forgot to mention in my first post is that the biggest
downside to reST for non-technical users is that it's possible to write
incorrect documents. With a GUI interface, you can write butt-ugly junk,
but it'll never generate a syntax error. However, given your
requirements, it sounds more like you're using "non-technical" to mean
"not computer experts" -- those people are probably more likely to feel
comfortable with getting error messages.

 

[Aahz]

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.

 

[Tim Parkin]

some of these are amazingly usable. have you asked your users what they
prefer? (or maybe you are your user? ;-)

Most users prefer to write documents in word and then paste them into
textareas. Not surprisingly means no semantic content, little chance of
restyling, horrible encoding problems and far too long spent on the
phone trying to explain why it's not a good idea.

Giving users a wysiwyg textarea creates the problems that users start to
spend time trying to create a 'styled' document, inevitably sacrificing
semantics (many is the user that has applied a header style to make
things bold or a quote sytle to indent a paragraph). Using text based
layouts reinforces the perception that you aren't creating a styled
document and that the semantic structure is important.

People who have used non-wysiwyg editors have found that their initial
reticence has been quickly overtaken by their joy at not having to fight
with 'style' and the reassurance that their content is now 'redesign
proof'.

Tim Parkin
http://www.pollenation.net

 

[richard]

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.

And this is the core of it for me too (if you want simple, use Word).
Roundup's documentation__ (in particular the `Customisation Doc`__ which is
now huge) is entirely written in reST. It uses a fraction of the total pool
of reST constructs, but I believe the end result is perfectly legible. I
also tend to write in reST style when composing emails (a biggie for me is
starting examples with "::").

Anyway, some sample Roundup docs:

__ http://roundup.sourceforge.net/doc-0.8/index.html
__ http://roundup.sourceforge.net/doc-0.8/customizing.html

As you say, reST can/does get messy when you're doing complicated things,
but it stays more readable than XML/DocBook.

Indeed - I chose to use reST for Roundup's documentation for two very
important reasons:

1. lower the barrier for me to write the docs - and I am *really* happy with
how current the Roundup docs stay, because I don't feel like actually
writing them is a pain, as opposed to any sort of Markup Language format,
and
2. the first contributor of docs suggested it, and I've had several
contributors since. It's easier for contributors to write for Roundup's
documentation - even if they don't get the reST markup correct, it's
trivial to fix. This is less the case with a Markup Language.


Richard