Previous Entry Share Next Entry
The joy of developing a new programming language...
device
jducoeur wrote in querki_project
... is that you have to build the parser. And the "joy" of building a parser is that you then have to deal with error messages.

My current plan is to begin opening Alpha at the beginning of August. Late last week, I began to think through things that *had* to happen before I could even consider doing that with a straight face, and I realized that one of Querki's weakest spots, at the moment, is the QL Parser. If you made a mistake in a QL Expression in your text field, it would display a horribly cryptic error message: no line numbers, not even an indication of which property was broken (it is typically but not always Display Text), and the message was the raw one from the Scala parser combinator code. Often, even I needed a couple of minutes to figure out what it was talking about, and it was clearly going to drive anybody else insane.

So last Friday's work was mainly to improve this, and I just released that as 0.3.15.1. It is *far* from ideal yet, but it's at least starting to be usable. When you have a syntax error, it now displays not only the error message, but also displays the line that the error is on, and the traditional caret-under-the-line showing the character where the error was registered. Also, I took a few of the most common errors, and replaced their generic "'X' expected but 'Y' found" messages with something a little clearer.

I've put demos up for a few of these, in a new "Public Sandbox" space -- folks who want to see what the errors look like in practice should go take a peek. And just because it's a good practice, I also created a page for How Error Demo Works, which is a nice simple example of a typical Querki model in action.

(There is still one major bug: if the syntax error is in an included Text Property, it displays the wrong Property name. This is on my to-fix list, but is going to require some fairly major enhancements to the parse pipeline, so it'll probably be a few weeks yet.)

Anyway, hopefully this improved error handling will make Querki usage a little less painful to start. I encourage those of you who join the Alpha (and please speak up if you'd like to join in) to tell me when you encounter other cryptic syntax errors -- we can gradually make things clearer and easier to use.

(Fortunately, in the grand scheme of things QL is still an *extremely* simple and lightweight language, and will hopefully stay that way. The parser is well under half a screenful, so there are only so many possible syntax errors...)
Tags:

  • 1
Some thoughts / questions on the "How Error Demo Works" page:

* Are the descriptions of Error Demo's Properties metadata of some form, or just part of the Display Text on the "How Error Demo Works" page? I'm guessing they're the latter, but...
* ...if the former, I'd suggest showing those descriptions on the "Create" page next to the fields in question. (Or beneath them. Probably with a "show/hide Property descriptions" checkbox; I've seen that be very useful in this sort of "display a list of many fields" thing.)
* It would be really nice if the grey box containing the Error Demo's Display Text had a label: Display Text. "Uses them like this" is vague.
* It is weird (and inconvenient) that there is not automatically a link from Error Demo to How Error Demo Works and vice-versa. (GUI-wise, nearly every wiki I've used treats "under-the-hood" info as a different view on the same thing; I can see that you might choose not to do it that way, but linking back and forth seems obviously good/useful.)

Also, I can get to the "Create a [Thing]" page for Things I don't have Create permissions on, which is nice for looking at the UI, but probably wrong longer-term? Especially since the dropdown for adding properties seems to expose the Names of Properties on other Things.

...if the former, I'd suggest showing those descriptions on the "Create" page next to the fields in question. (Or beneath them. Probably with a "show/hide Property descriptions" checkbox; I've seen that be very useful in this sort of "display a list of many fields" thing.)

Good call. One of the items on my list of "really ought to do before opening Alpha" is a rework of the UI for adding/editing Properties -- the workflow currently sucks sharp flinty rocks, and is my pick for worst pain point in the system, so I hope to get to it this month.

At this point, most of the system-level Properties have a Display Text description, but I'm thinking that this should be split into a formal Summary/Details breakdown. (Possibly plus a separate Usage?) The Summary would serve as hover text for the property's name; the Details would be displayed when, eg, you are looking at properties in the editor with an eye to adding one. Possibly clicking on a property's name would produce a popover with the Details as well?

It would be really nice if the grey box containing the Error Demo's Display Text had a label: Display Text. "Uses them like this" is vague.

Makes sense -- done.

It is weird (and inconvenient) that there is not automatically a link from Error Demo to How Error Demo Works and vice-versa.

Interesting point. I'm not going to rush off and deal with this -- too many critical-path items right now -- but I'll put it on the ToDoList to think about, and feel free to remind me of this later.

The "How It Works" concept is evolving, and this is a good example. My original concept had been a single tutorial on a per-Space level, as in the Poker Space; however, this illustrates that we're sometimes going to want something finer-grained.

These pages are, of course, completely manually created, so there's a limit to "automatically". But we might want, eg, a standard system-level property that links a Thing to the tutorial about that Thing, with auto-linking if that property exists and maybe other automatic and/or convention support. Or possibly a system-level How It Works property that can be placed on any Thing to describe it. Or maybe both. Let's talk about this more in the next month or two.

Also, I can get to the "Create a [Thing]" page for Things I don't have Create permissions on, which is nice for looking at the UI, but probably wrong longer-term?

Yep, good point -- bug noted. Since the permissions system was only added last week, there are still *lots* of seams; please point them out when you notice them. I've fixed this for some but not all instances of Edit, but haven't done a principled look for Create yet.

Especially since the dropdown for adding properties seems to expose the Names of Properties on other Things.

Keep in mind, that's intentional. This is Querki's great heresy -- the namespace is Space-global, so any property can be used on any Thing within the Space. That's sometimes extremely useful, but a tad weird from an OO perspective.

(And no, I haven't even begun to think about how the permissions system *should* interact with properties. For now, it focuses on the Thing level, and properties are public-ish. This is going to be an important but complex R&D question.)

but I'm thinking that [Display Text of Properties] should be split into a formal Summary/Details breakdown. (Possibly plus a separate Usage?)

One caution from my experience in FosWiki: if you end up with too many text descriptors for something, people get confused about which should be what and will either misuse them (then get frustrated when the thing they put in didn't show up where expected) or punt by copy-pasting the same thing into all of the fields.

[Automatic linking to/from "How it Works"

Worth noting: I'd been thinking of "How it Works" pages as something designed to *replace* the usual "View Source" on wikipages. It sounds like it's not, in which case the lack of autolinking is less of a big deal. (Basically, what I really want is when looking at a Thing to be able to peek under the hood quickly and easily.)

That being said, cross-linking them is still probably a reasonably good idea.

...the namespace is Space-global

I was seeing email-invitation-ish Properties in the Property dropdown in Sandbox. Is the wedding-invite stuff in that same Space?

[Whoops, this was supposed to be a reply to above.]

One caution from my experience in FosWiki: if you end up with too many text descriptors for something, people get confused about which should be what and will either misuse them (then get frustrated when the thing they put in didn't show up where expected) or punt by copy-pasting the same thing into all of the fields.

Good point. For now, I think I'll split it into two, and hopefully their own documentation will help clarify. One of the interesting aspects of the way Querki tries to "play fair" is that these new Summary and Details Properties will themselves be Properties like any other -- so they will be displayed with the same hover/click documentation.

(Well, mostly. Truth is, I will probably begin to optimize the workflow, which will break some of the automatic-ness of all this. But hopefully I can keep it all Just Working.)

Worth noting: I'd been thinking of "How it Works" pages as something designed to *replace* the usual "View Source" on wikipages. It sounds like it's not, in which case the lack of autolinking is less of a big deal. (Basically, what I really want is when looking at a Thing to be able to peek under the hood quickly and easily.)

Ah -- good reminder. I'd vaguely thought about this before, but haven't done anything about it. Okay, I've put in a to-do for "View Source". (Of course, in Querki's case that's actually a property list. And it probably needs its own permissions. But it's a good idea to have.)

I was seeing email-invitation-ish Properties in the Property dropdown in Sandbox. Is the wedding-invite stuff in that same Space?

For the time being, the Email Module is system-global. There's nothing about it that's specific to the wedding, actually -- the wedding RSVPs are just leveraging a general mechanism to invite someone to join your Space, with a Space-local identity. Indeed, 90% of the Properties in any given Space are typically system-global ones that you can just use.

This will, of course, gradually get more sophisticated, and there will be some problems to wrestle with. The Email Module might get pulled out into a Mixin once those exist, so you can opt into it. (Or not -- the truth is, the Email Module is basically a prototype for a much more general invitation system, which probably *does* have to be system-global.)

The really interesting question is going to be taming the Property list, which is going to do nothing but grow in the long run. I have a variety of ideas for that, including:

-- Being able to search for a Property by name to add it.
-- Property categories/hierarchy, so you can collapse/expand sections.
-- Visually separating the Space-local Properties from the system-global ones.
-- Categorizing properties as Basic/Standard/Advanced, and hiding the Advanced section unless you open it. (This "levels" mechanism is one I am strongly considering as a general system-wide tool.)

I suspect we'll eventually need at least two of those, maybe more. This is going to gradually become an important UI consideration for us.

  • 1
?

Log in

No account? Create an account