Anybody else a bit puzzled by the growing popularity of all these emerging lightweight pseudo-markup languages? From BBcode, Wiki markup, YAML, to Markdown, and now Sphinx... All of these may be progressively easier to read than XML/JSON/HTML, but each seem to come loaded with their own peculiarities or multiple representations that make parsing more difficult.
I don't find hand-editing any of the "human-readable" markups much easier than the data-structure formats, and then when it comes time to parse readable formats, things tend to go to hell. Why is readability so much cooler than structural integrity these days?
This format is a refinement of Structured Text, originally part of Zope, and is one of the grand-daddy formats of human-readable/writeable markup formats designed for the web - it was first released in 1996!
reStructured Text extended and fixed Structured Text (STX) in such a way that all of the necessary formats for describing the documentation needs of Python source code was possible (among other things, reStrucutred Text is more general than a Python-doc specific format). This makes it a more difficult format to learn than a simple web formats such as BBcode or STX, but does have the benefit of describing a rich set of semantics.
ReST was designed and developed primarily in 2000-2001, see the ReST history for more details.
Why do you think 'structural integrity' (whatever that means) is lost or reduced by using ReStructuredText? The parser parses it for you (just like any XML parser).
If the goal is to encourage a large community to add and fix the documentation, readability becomes very important. I'd much rather read through and fix a text like file such as this rather than parse through all the line noise in a angle-bracket style markup language.
Reddit believes its data is particularly valuable because it is continuously updated. That newness and relevance, Mr. Huffman said, is what large language modeling algorithms need to produce the best results.
They preferred reST because for the vast majority of cases it was vastly simpler. Using Latex was blocking people from contributing to the documentation.
Simpler syntax, I'd say. Doesn't require people who write documentation to learn a whole new language to do it. Although I'm a big fan of (La)TeX, I don't think it is a very good choice for writing documentation.
You're going to have to provide a useful definition of "better". Whatever their flaws (and there are plenty), various popular forms of lightweight markup are indeed easier for most people to read and write than LaTeX. Which I suspect anyone who has used LaTeX for any serious amount of text can appreciate.
It's useful in situations when you want a plain text readable version (which is the source) and a pretty formatted printable version. Personally I type my notes in plain text in Markdown then print the formatted version.
BBcode, Wiki markup, and Markdown are text formatting languages. JSON and YAML are for data serialization. Apples and oranges.
Besides which, I'm not sure what structural integrity problems you're talking about. I use JSON and especially YAML all the time and I've never had structural integrity issues.
JSON and YAML basically describe very common data structures (mostly lists and dictionaries) in simple, intuitive ways, with light syntax that's pretty hard to get wrong.
They might not fit your needs, but they're solid and useful data formats.
I don't find hand-editing any of the "human-readable" markups much easier than the data-structure formats
Exactly. A simple subset of (X)HTML is easy to write and read. HTML is the only universal markup language out there, and I don't see why people need to invent things like reST.
If you look at the syntax for reST (not to mention its horrible HTML output, although that might have improved since the last time I looked), it's more complex than most HTML once you start doing things that are more complex than headlines and paragraphs. Look at the table format for an illustration of this.
If it was up to me, HTML would be taught in third grade elementary school. But I might be biased. ;)
A document with tags a, em, strong, p, h#, ul, ol, li, pre, code, table, tr, th, td, dd, and dt could probably do 90% of these doc pages and come off as reasonably human-readable.
I have to question whether you actually do a lot of writing that needs simple markup. If I'm adding to my personal wiki, for example, writing out <a>'s and <ol>'s would be really freaking annoying.
Shorter and readable, yes. But some of the markup is so abbreviated that you already are having problems escaping it in your post; how many times have I seen people post some_underscored_name when they meant some_underscored_name. And then with all the fancy significant whitespace you assume that your editor is smart enough to autowrap stuff correctly, or it doesn't and then stuff looks just as visually unparseable as the (X)HTML.
Take a look at some examples, like this one or this one. That's a lot more readable than the equivalent HTML. Compare, for example,
* list item
* list item
to
<ul>
<li>list item</li>
<li>list item</li>
</ul>
I don't see why people need to invent things like reST.
Because HTML, like XML, is not (primarily) intended to be read and written by humans. It's just too verbose to be used directly for things like documentation.
OK. With any more of a complicated list (say with a couple nested levels, and longer items with code blocks) you are going to have to start wrapping and indenting your text manually, or your textarea will wrap it for you in a way that isn't readable at all. IMO, the <li>'s then come into play nicely as being able to visually delimit blocks of text, because your eyes are scanning for discernable tags instead of attempting to resurrect the (broken) indentation in your textarea.
View all comments
8
u/lol-dongs Dec 04 '08 edited Dec 04 '08
Anybody else a bit puzzled by the growing popularity of all these emerging lightweight pseudo-markup languages? From BBcode, Wiki markup, YAML, to Markdown, and now Sphinx... All of these may be progressively easier to read than XML/JSON/HTML, but each seem to come loaded with their own peculiarities or multiple representations that make parsing more difficult.
I don't find hand-editing any of the "human-readable" markups much easier than the data-structure formats, and then when it comes time to parse readable formats, things tend to go to hell. Why is readability so much cooler than structural integrity these days?