Textual markup languages (was Re: What YAML engine do you use?)

[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,

-- 
alan kennedy
------------------------------------------------------
email alan:              http://xhaus.com/contact/alan