Qtext
Each Thing in Querki, pretty much by definition, has one or more display-text properties. There is always a property named Display Text, which is what gets shown when you show this Thing by itself in a browser. There will also be context-specific properties like Mobile Text, as well as any other Text properties that the user wants to add.
These properties are all of type Text or Large Text (which are more or less the same thing); this type is internally referred to as QLText (with an L). That is, they are text that may optionally contain QL expressions. When we render these things, we begin by evaluating all of the QL expressions. But that is only half the process -- once we are done evaluating, the output of that is QText.
QText is a "wikitext" language, semantically similar to HTML but with a highly simplified syntax. The idea is that it should be easier for end users to write and read than HTML is.
To that end, QText is adapted from Markdown, one of the more popular and sensible wikitext languages. Markdown's explicit point is to provide a syntax that makes intuitive sense when you read it. We've tried to continue that approach.
That said, we have an additional goal that Markdown does not. Markdown is intended to supplement HTML -- you can always break out to explicit HTML for the hard stuff. QText, by contrast, is intended to largely replace HTML within the context of Querki.
That isn't so much because of HTML itself as because of Javascript. For security reasons, we are initially forbidding Javascript inside Querki Spaces. We may well soften that line later, using technologies like Caja to insulate the user from the risks, but we expect Javascript to generally not be common. It is rather complex to thoroughly prevent Javascript, though. The safest and easiest way is to neutralize all <'s and &'s, which means no HTML.
That being the case, we will be steadily extending QText, to cover more and more of the interesting functionality of HTML. We will be following two guiding principles there, along the lines of Markdown
- As far as possible, the syntax should be intuitive and obvious.
- The syntax should not conflict with other common ways that folks are likely to type.
We will take our inspirations from various sources, including the extended MultiMarkdown language, which has some useful ideas in it. But we are explicitly thinking of this as a language focused on Querki's requirements, and we aren't going to worry too much about sticking to any one model.
Ordinary Markdown defines syntax for numbered and unnumbered lists, but ignores definition lists. This is unfortunate from our POV, since definition lists are very common in some Querki apps. Indeed, we use them as the default when showing a Thing that has no Display Text.
Ideally, we would like to use MultiMarkdown's syntax for definition lists:
Fruit
: Apple
Color
: Red
However, that will require more surgery to the Actuarius engine that we are using to write QText than I'm prepared for quite yet. So we will instead use a slightly clunkier but easier (and relatively safe) syntax to begin with:
: Fruit : Apple
: Color : Red
Note that the spaces around the colons are mandatory -- that is why this syntax is pretty safe. (Since a space or newline before a colon is unusual in real text.)
My current theory is that this syntax is adequate, if not ideal -- a working option until we have a bit more programming time.
While HTML is largely forbidden in Querki for now, CSS is generally allowed. Indeed, the initial working theory is that most fancy display should be handled using CSS, since modern CSS is extremely powerful as a layout tool.
That being the case, though, it becomes deathly critical that you can declare classes for span and divs. That is, you should be able to surround any text or block with a class declaration, which can then be used in the CSS to describe how to style it.
The syntax for declaring a style in QText will be pretty similar between divs and spans. To declare a div with a style, it should look like this:
{{ class-name :
... div contents go here ...
}}
Note that the class-name is not allowed to have any spaces in it. This will become the following HTML block:
<div class="class-name">
... div contents to here ...
</div>
Similarly, to declare a span with a class, it looks like this:
blah blah {{ class-name : other stuff, that is styled }} blah blah
which turns into:
blah blah <span class="class-name"> other stuff, that is styled </span> blah blah
Note that the spaces around the colon in this syntax are optional, and a space after it will be copied into the resulting HTML.
The key difference in these syntaxes is whether there is anything on this line after the colon. If not, it becomes a div; if there is, it becomes a span.
The span version of this syntax must be contained within the paragraph block; don't try to use it beyond those confines. It is intended for small chunks of code.