Textual markup languages (was Re: What YAML engine do you use?)
alanmk at hotmail.com
Fri Jan 28 23:07:59 CET 2005
>>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.
Thanks, Aahz, that's a key point that I'll continue on below.
>>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
>>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.
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.
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.
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
email alan: http://xhaus.com/contact/alan
More information about the Python-list