Previous Entry Share Next Entry
Small but breaking change, open for discussion
jducoeur wrote in querki_project
[Slightly deep dive into QText here. I assume the reader understands HTML spans and divs -- the distinction is important below.]

I just stumbled across this bug, which is illustrated here, and wanted to talk it out before I do anything about it. Input would be appreciated.

Working in Querki is always an interaction of the QL programming language and the QText markup language. These are intentionally combined so that you often don't even think about them being separate levels, but they are, and occasionally the seams show. I just stumbled across one of those.

In the Issue Tracker, I have a Large Text Property called "Discussion". This gets embedded in the display of the Issue Model uncontroversially, like this:
**Discussion:** [[Discussion]]
Makes sense, right? Problem is, it doesn't quite work. I wanted to get fancy in my comments, so I set them off in the "well" style, putting something like this in my Discussion:
... blah, blah, discussion, blah...
To my surprise, what I saw was
Discussion:{{well: ... blah, blah, discussion, blah...
It took a few minutes to realize that this was the system doing exactly what I'd said to do.

The thing is, rendering a page is a two-step process. First, we evaluate the QL -- everything in the square brackets -- and interpolate the results, producing pure QText markup. Then the QText parser goes through and renders that markup. So what got to the QText level was:
**Discussion:** {{well:
... blah, blah, discussion, blah...
That isn't legal QText, or at least it doesn't mean what I want. The "{{" operator is all-or-nothing -- either the whole expression has to be in a single line (in which case it renders as a "span" style), or the beginning and end each has to be on a line of its own (in which case it renders as a "div" style). This is neither, with the beginning in mid-line and the ending on a separate one, so it didn't parse right.


Here's the proposed change -- I think it's correct, but it might cause some formatting problems in some existing Spaces. The implementation change is tiny, but it has significant effects: when rendering a Large Text, the system *always* inserts a blank line at the beginning.

This would fix the above mistake immediately -- what gets to the QText layer would be:
... blah, blah, discussion, blah...
which is exactly what I want.

I *think* the semantics here are correct. Indeed, it's fortuitious that the Types got set up the way they are. I've always had a distinction between "Text" and "Large Text", but heretofore the only real difference has been in the Editor (Text gets a one-line input, where Large Text gets multi-line). This would be a much more important difference, though: it says that Text is *intended* for inline use, whereas Large Text may or may not be. In particular, it recognizes that a Large Text is *potentially* block-level, and allows you to start a block at the beginning of it.

Note that, since QText runs successive lines of body text together, this change does not *necessarily* insert a break in the resulting HTML. Technically speaking, if you use a Large Text in the middle of a line:

-- If the Large Text begins with a blank line, it will start a new paragraph.
-- If the Large Text begins with a QText operator -- "{{", "###", "*", or any of those other beginning-of-line block operators -- it will result in a new HTML block of the indicated kind.
-- Otherwise, the ordinary text at the beginning of the Large Text will flow together with the line it is embedded within.

I *think* that fits nicely with Querki's "It should just work" philosophy, and will usually produce least-surprising results. In particular, it allows me, when writing the content of a Large Text Property, to be able to think of it as I like without having to know about the context of the lines it is being used in. But the logic here is subtle enough that I wouldn't mind a sanity check...


Log in

No account? Create an account