neithere

Python, Music, Laziness

Raindrop

what

when

url
http://bitbucket.org/neithere//
code
http://bitbucket.org/neithere//src/
technologies
Python

Goals

Syntax
Develop a minimalistic wikish syntax that would be clean, readable and easy to learn, type and maintain. Support for complex layouts is not required; just plain document structure.
Implementation
Develop an implementation in Python. Should be pluggable into a Django application as template filter. Should be modular. Output must be valid XHTML.

Status

The syntax is mature at this moment.

A working model (parser) had been created to test and improve the syntax on live projects (mostly private ones).

Code may be published after refactoring.

ToDo

Study alternatives
Try incorporate their best features but preserve the balance between simplicity and flexibility.
Refactoring
Remove hacks; simplify and optimize the core.
Rewrite
Try to use an external grammar parser (see ru_python: parser generators?)
Cute Headings’ IDs (?)
Headers should get a-z0-9\- ids. If h2 is «Contact Information», its id is «contact-information». If a h3 with text «Telephone» is defined below, it gets this id: contact-information-telephone (i.e. inherits text from the outer heading).

Similar projects

Below is given a superficial overview of alternatives to Raindrop. To study them well is an important task.

Markdown
I think it’s among the best alternatives. I even tried once to abandon Raindrop in favour of it. But I couldn’t because of lack of definition lists in Markdown, noisy link markup, possibility to accidentally place a h1 within the document (where only h2+ should be allowed) and so on. But I really like the way how lists (ol and ul) can be written; I think it would be a good idea to either import that to Raindrop or to enrich Markdown with some Raindrop features.
Textile
Rather light. But, for example, each table row requires 2 extra “|” characters if compared with Raindrop; lists look ugly; headings are barely visible in source text; links are ugly as anywhere except for MediaWiki and Raindrop.
ReStructuredText
Nice lists, perfect definition lists (ReST DL ToDo), also ReST field lists is a good idea; ugly headings (eye-candy OR easy to type) and awful tables (of two flavours) and much more pros and cons; there are, however, some ReST problems.

See also Lightweight markup languages article on Wikipedia.

The most common issues with markups are:

emphasis
most markups make it easy to emphasize a substring: _foo_, *bar*, etc. But other ones introduce surprisingly moronic approaches like typing a variable number of chars on each side of the substring (''em'', '''s.em''', ''''v.s.em'''') to define a certain grade of emphasis; this makes the text less readable, and also the chances are high to break the markup by typing a wrong number of these chars (which is not easy to catch when you look at the text).
links
only Mediawiki is known to have a neat syntax for links: [http://foo.bar link text]
headings
  • invalid: everywhere the first available level of a heading is h1, but it should occur once in the entire document; moreover, it should be even taken out from the document body. AFAIK, this behaviour is supported only by Raindrop. Some markups allow you to just type ==, ## or h2., but some don’t even ask you and interpret the first level as h1!
  • ugly: either you have to write extra chars at the both sides of the text, or the heading takes two lines and, to look well, the second one must contain as many dummy chars as there are in the first line — that’s dumb
tables
cumbersome everywhere! I’m afraid, Raindrop has no alternatives in this case. That’s bad, by the way.