Previous Entry Share Next Entry
QText Reference
querki
jducoeur wrote in querki_project
For months now, I've been telling people, "oh, QText is basically just like Markdown, only, y'know, kind of not". I finally decided today that things have diverged enough that it really needs some documentation.

So -- there is now a Reference Page for QText. This tells you what works. In particular, it describes the enhancements that QText has made to Markdown (such as style tags), and the Markdown features that will probably *not* be supported in Querki in the long run. (Mostly, we're going to be trimming down a lot of the places where Markdown gives you three different ways to do something, in favor of one preferred mechanism.)

Those who are working in Querki will probably want to give this a quick read, since it tells you how to make your Text and Large Text values pretty. And opinions about what else we should be adding to it would be welcomed...
Tags:

  • 1
"...the thing about having to put two spaces at the end of the line to get a line break is, in my opinion, one of Markdown's weaknesses -- it's hard to remember, and tends to lead to surprises.
So opinions would be welcomed -- should we change things so that a line break in the original text becomes one in the results? I'm seriously considering this, and would love user input."

I'm in favor of DWIM. Random extra spaces at the end of a line is completely counter-intuitive to me.

"You can have multiple lines in a given item by indenting each successive line with four spaces,"

In the example you show, the text is rendered with line breaks between the paragraphs of each item (good), but there is *no* line break *between* the two items. This seems wrong.

"To create a line across the page, just show a line of three or more dashes by itself."

Um, I see no line in the sample output...

"You can have multiple lines in a given item by indenting each successive line with four spaces,"

In the example you show, the text is rendered with line breaks between the paragraphs of each item (good), but there is *no* line break *between* the two items. This seems wrong.


Agreed. Though I can imagine sometimes wanting it to work that way, it looks weird / probably isn't a sensible default?

See my reply to Alexx -- now fixed. (It was just a problem with my CSS style.)

Um, I see no line in the sample output...

It's there, but hard to see against the "example" style I'm using for output. I've removed that style in this case, so the hr is now visible. (The default hr *is* subtle, and I've left it that way. You can change that in your Space using Styles, if you like.)

In the example you show, the text is rendered with line breaks between the paragraphs of each item (good), but there is *no* line break *between* the two items. This seems wrong.

Subtler example of the same thing, and mostly illustrates that I'm still a CSS neophyte. The "example" style (which is basically a quick and dirty copy of Bootstrap's "well well-small") sets the para:last-child's margin-bottom to 0, so that the size of the surrounding well looks right. But that interacts poorly with the internal para's in the bullet list.

So for now, I've just removed the example style from there. I'm honestly not sure of the correct fix for this...

I favor the idea that line breaks in the editor lead to line breaks in the product. Adding two spaces is very counterintuitive.

The double-invisible-space thing is a little hackish. It's also invisible, which I think violates one of your design principles of trying to keep things as visible as possible.

While it can be a little surprising, I've come to respect Markdown's "two newlines equal a paragraph" standard. Removing it makes it quite difficult to understand what should happen in cases where you wrap in the presence of other markup, like indenting or lists:

> This is an attempt to have one big
> section of blockquote, but without
> double-newline, it's four separate
> sections.

* This is a bulleted item that got a
  bit long and I'd like to continue;
  but without double-newline this is
  now one list item plus four pieces
  of code.


I also really have come to rely on having the option of repeating the > character at the start of every line. It's useful especially when you have a long indent section and you want to rearrange bits of it. And most of my editors automatically add in the >'s anyway.

I guess it boils down to how arrow keys move you around your editor. In an editor like vi/m, where going "up" doesn't necessarily take you to the letter displayed directly above where you are (if the long line has soft-wrapped), it's nicer to have the option to break up long lines without losing semantic meaning. If you've got complete control over the editor used to specify QText, you can provide some structure there.

Spans vs divs--where must the linebreak go? before the {{s, after, both, neither? Clarity would be helpful here. And what should this do:
Some text, and then {{wacky_style:
I start a bit}} and don't know whether it'll be a span or a div.


(This is also a place where single-newlines would make it confusing--while html spans *can* have newlines in them, it sometimes doesn't do what users want.)


If you're disallowing HTML, does that mean you'll be escaping the angle brackets, or does it fail a validation check and you don't let it get saved in the first place?

"I also really have come to rely on having the option of repeating the > character at the start of every line. It's useful especially when you have a long indent section and you want to rearrange bits of it. And most of my editors automatically add in the >'s anyway.

I guess it boils down to how arrow keys move you around your editor. In an editor like vi/m, where going "up" doesn't necessarily take you to the letter displayed directly above where you are (if the long line has soft-wrapped), it's nicer to have the option to break up long lines without losing semantic meaning."

While those are valid accounts of how you, personally, are reacting, are they reflective of a (desired) typical Querki user? Will the typical Querki user be using an editor that auto-adds >'s, or have even heard of vi/m?

I guess my exploratory ramblings should have been labeled as such.

I don't particularly think Querki users will be coming from vim, though I also don't really want to generalize too much. Despite conversations with jducoeur trying to figure out who his users _are_, it's not something I feel confident going one way or another on. (Also, typical user is a dangerous concept, but that's another topic.)

That's why I included my thinking. Our host had mentioned that he didn't want to change this unreasoningly, i.e., that there might be unintended consequences. So I worked through why it _had_ worked for me, to see if that was still applicable.

The sentence after the ones you quoted was the conclusion, namely, if Querki provides an editor where this reason is irrelevant, then it may well be that hard-breaking on single newlines is okay--provided the other cases I point out are also okay.

The double-invisible-space thing is a little hackish. It's also invisible, which I think violates one of your design principles of trying to keep things as visible as possible.

Yeah, I was actually surprised that Bootstrap does it that way.

If you've got complete control over the editor used to specify QText, you can provide some structure there.

Interesting food for thought, and part of why I'm not going to make this decision casually.

The thing is, I expect the 99% case to be that people edit their Text blocks in-browser (or possibly in-app, in the case of the future hypothetical Querki App), so it seems to make sense to optimize the UX for that. And in the presence of word-wrapping (which I *think* every browser does), it seems like simply declaring that one line == one paragraph is most sensible and intuitive.

That said, I am mildly concerned about, eg, people writing in another edit and copy/pasting into Querki. I'd rather not provide a *bad* experience for that. And I agree that the interaction with the run-on formats in Markdown needs to be taken into account. So I'm going to mull on this for now.

Spans vs divs--where must the linebreak go? before the {{s, after, both, neither? Clarity would be helpful here. And what should this do:
Some text, and then {{wacky_style:
I start a bit}} and don't know whether it'll be a span or a div.


Good question. The answer is that the above isn't legal, and won't be parsed, intentionally. For now, I'm taking a hard line about spans vs. divs -- spans can only happen in *one* line, and divs must be formal blocks, surrounding other blocks. This sort of inline-to-inline use has never been regarded as good style in HTML, and is the sign of an error more often than not.

We'll see if I hold that hard line. I'm pretty sure that it's correct for the 99% case, and I'm curious to see whether folks come up with good, real-world arguments for changing it.

(This is also a place where single-newlines would make it confusing--while html spans *can* have newlines in them, it sometimes doesn't do what users want.)

Not sure I'm understanding you. Can you explain further?

If you're disallowing HTML, does that mean you'll be escaping the angle brackets, or does it fail a validation check and you don't let it get saved in the first place?

Well, keep in mind that I'm only disallowing HTML in the short term -- as it says, we'll be whitelisting it in eventually.

As it stands, Markdown already escapes angle brackets (unless they are wrapped around a URL). I don't plan to change that -- Markdown's auto-escaping of HTML entities seems generally sensible.

I had not realized the two-spaces thing was inherited from Markdown!

That being said, since I started writing CoffeeScript, I've made spaces-at-end-of-line something my editor syntax-highlights, because it is more likely indicative of something wrong in an off-side language. Your editor could provide some similar sort of feedback, which would make things less invisible.

The span thing--when you're writing CSS, you have to remember that span (or rather, any "display:inline" content) doesn't honor vertical spacing; they inherit vertical spacing from the surrounding block. Now that you're letting people add CSS, they need to know which things are display:inline vs display:block or their formatting might end up weird and they won't know why.

One link that goes into this a bit:
http://esbueno.noahstokes.com/post/1004527039/css-wheres-my-vertical-margin

It's an edge case, but a frustrating one when it occurs.

The rest of your points make perfect sense. ;) I suppose I could have just made an account and played around to find out some of those answers.

That being said, since I started writing CoffeeScript, I've made spaces-at-end-of-line something my editor syntax-highlights, because it is more likely indicative of something wrong in an off-side language. Your editor could provide some similar sort of feedback, which would make things less invisible.

Plausible, but out of scope for the time being. The "editor" is simply a plain browser textarea at the moment. That'll eventually evolve into something more interesting, but that's an *enormous* project, not least because it has to work in all browsers, including mobile. For now, I'm necessarily following KISS, and don't expect that to change for at least six months.

It's an edge case, but a frustrating one when it occurs.

Yeah, I'll have to chew on that. I'm not going to borrow trouble -- let's see what happens in practice -- but it may call for enhancements down the road. (In the very long run it'll be a non-issue -- the "editor" mentioned above is going to be essentially an IDE -- but that's a goodly way off.)

For now, the party line is basically that CSS is an "if you know what you're doing" feature, with very little hand-holding -- it's aimed at power users. I don't expect more than 10% of users, long-term, to use the style-tag feature, and I don't expect more than 2% to actually *write* anything in CSS. Hence, I have to keep this sort of thing in perspective...

That said, I am mildly concerned about, eg, people writing in another edit and copy/pasting into Querki.

This is my standard modus operandi for doing any sort of large-scale composition on wikis or forums. I've lost too many comments / messages / pages to accidental tab closings and browser crashes to be sanguine about editing for more than a minute or two in an HTML textbox.

Keeping a "dirty" flag and forcing a confirmation via javascript before tabclosing if there's unsaved edits would help, but I wouldn't feel fully comfortable abandoning outside editing unless there were some sort of autosave / autorestore happening in the background.

[Even for this quick comment, before posting it I've reflexively hit "Command-A Command-C" so that it's on my clipboard if the submit doesn't work. Browsers are not the world's most reliable editors.]

Yep, agreed. I'm not going to be able to deal with this in the very short run (too much on my plate), but my medium-term plan is that Ctrl-S will save the Text that you are in the middle of editing (since I often do that reflexively), and the longer-term plan is proper autosave.

I've just added an Issue for the former, so we don't lose track of it. (It was already on the formal project to-do list, but the Issue Tracker is beginning to subsume that...)

In re tabs and accordions, this feels like it could be handled using your section (divs/spans) notation. Ship with a few pre-built styles that people can simply include, and you've got something akin to how Bootstrap works.

{{tabs:
1. Tab 1 Title
2. Tab 2 Title
3. Tab 3 Title

  {{tab1:
  Everything in here will be shown in tab 1.
  }}
  {{tab2:
  And here's the content for tab 2.
  }}
}}


And then automatically do the right thing.

Yeah, I've contemplated that approach, and might yet go for it. (Probably with underscores at the front -- _tabs -- which is my usual way of avoiding namespace collisions with userspace names.)

Indeed, if I go this route, of using the "style" mechanism as the catch-all for UI functionality like this, I'll probably add parameterization, to get better locality and reasoning:
{{tabs:
  {{tab(Tab 1 Title):
  Everything in here will be shown in tab 1.
  }}

  {{tab(Tab 2 Title):
  And here's the content for tab 2.
  }}
}}
Or something like that, anyway. I'm already expecting that mid-level Querki use is going to require coping with the concept of using parameters on the QL side, anyway, so I don't see a lot of reason to shy away from them in QText...

Ooh, yeah, if you're willing to do parameters, then sure. You could even do named parameters, and you've got something starting to resemble HAML..
{{tabs:
  {{tab(title="Tab 1 Title",default):
  Content
  }}
}}

vs.

.tabs
  .tab(title="Tab 1 Title" default)
    %p Content

Named parameters are possible (they will be showing up in QL in the not-too-distant future), but I'm going to let that feature fight for its life. We'll see how much we care...

  • 1
?

Log in

No account? Create an account