Page MenuHomePhabricator

Add more Markdown Italics support to Remarkup
Closed, DuplicatePublic

Description

Seems markdown uses _italics_ or *italics* for italics and we don't currently have anything in that slot. Worth possibly supporting for markdown supporters, I don't think we have plans for these?

Event Timeline

It's intentional that we don't support these because they appear frequently in expressions source code, for example:

int *ptr, *next;
__init__.py
y = 60*60*24;
function_with_underscores();

Although there are ways to express these without highlighting, new users won't necessarily know them, and I think it's very frustrating to type:

This computation looks wrong, should just be 60*60*24?

...which is a reasonable sort of thing to type, and have it turn into:

This computation looks wrong, should just be 606024?

...which is confusing (and easy to miss!), and then have to go look up how to escape it properly.

That is, there's product tension here between these concerns:

  1. It's frustrating to accidentally trigger markup rules that you didn't mean to.
  2. It's frustrating to need to look up markup rules.

At least for me, accidentally triggering markup rules is like an 8/10 on the frustration scale and needing to check the help page or click the B or I button to remember how to do something is 0.5/10, so it's an easy call to not have these rules.

(I think we might have had them at one point a very long time ago and removed them after they triggered too often? But I might be misremembering. This would have been a very, very long time ago.)

It's also possible to implement these rules more strictly, so that they must be on a word boundary to start/end, don't match across newlines, etc. This can reduce the false positive rate. For example, in the original Markdown, this input:

a_b_c

...produces this output:

abc

This isn't true in "GitHub Flavored Markdown", presumably because using this rule means that function_with_underscores() becomes functionwithunderscores() which is common and frustrating when discussing code. However, this makes the rules less consistent and predictable. It is not obvious that the * and _ rules in GitHub Flavored Markdown are actually different rules with meaningfully different behavior.

Another case of this is this input:

Yeah that sounds like a *great * plan.

Did you notice I made an error and added an extra space? That makes it render literally:

Yeah that sounds like a *great * plan.

Presumably, that's to prevent int *ptr, *next; from marking up? But these rules don't cover things like this:

char c = *(*x++);

...which renders as:

char c = (x++);

These issues aren't intractable, but the rules are complex and imply product tradeoffs.

epriestley claimed this task.

I'm not completely opposed to ever changing this, but I think there are pretty good reasons for the current behavior.

I believe it's also possible (and fairly easy, even?) to add these rules yourself by extending Remarkup.

chad reopened this task as Open.EditedMar 23 2017, 4:34 PM
chad triaged this task as Wishlist priority.

Just going to reopen this as a wishlist item. Italics/Bold here is probably the biggest requests for cross-functionality Remarkup <-> Markdown I'd personally have. And at least in your test cases, it seems even GitHub fails at them (and CommonMark), though Slack does not, so I think these are workable in the general sense, just will likely come with lost of test cases and regex support. I think correctness of expectation is your main concern (and the maintenance cost), not adhering to a "spec"?

Maybe also I could learn to actually write regexes.

Slack vs GitHub (CommonMark):

pasted_file (516×612 px, 43 KB)

My viewpoint is that Markdown was developed for writing first-party blog posts, not for technical discussions about software.

As a result of this design goal, it chooses many rules which are reasonable when writing English-language blog posts for your own blog, but questionable, poor, or even disastrously terrible when untrusted third parties are using it to write comments in the course of software discussion.

I'd like Remarkup to be good for discussion software first and foremost, and compatible with Markdown only as a secondary goal. I think it is far worse for a markup rule to activate when you don't want it to (above, "8/10 on the frustration scale") than to need to go look up an alternate piece of syntax (above, "0.5 / 10"). Technical users are often familiar with many different language syntaxes, and every implementation of Markdown is different anyway.

All "Markdown-like" engines make compromises because the original Markdown has rules which are completely unsuitable for use in comments. In particular, it has a rule for inline HTML, where you just write whatever HTML you want and it's rendered as-is. That's fine if you're writing a personal blog, but it's an XSS hole if you're using it for comments. So no "comment with markdown" engine supports arbitrary inline HTML, even though original Markdown does.

Many of the other rules have been implemented inconsistently, too. There was no real spec about how *x* and _x_ should behave, and they cause real problems when discussing software, so GitHub and other engines added a lot of rules to try to get them right more often. On the balance, I think this is not terribly worthwhile. The original syntax selections were just bad choices for what the language ended up being used for, and we're better off throwing them away than trying to guess when users do and don't expect them to work.

The CommonMark spec on "emphasis and strong emphasis" http://spec.commonmark.org/0.27/#emphasis-and-strong-emphasis is like 20 pages long, defines 17 rules, and has more than 100 examples to detail the behavior.

If you come to Phabricator for the first time and type *italics* and it doesn't render in italics, I don't think that's really a big deal. Human readers get the point anyway, and you can click B to get a refresher on the rule. Your comment isn't as pretty as you wanted it to be, but it hasn't lost any meaning, and if you want to make it prettier it's easy.

If you come to Phabricator for the first time and type "I think this should be 60*60*24" and it renders some garbage you don't want, I think that suuuuucks and is super frustrating. And it will continue to be super frustrating forever, whenever you copy/paste a snippet and it breaks and you don't notice it or whatever. Your comment has lost meaning because the markup language has a bad rule, and you have no choice to go figure out what the rule is to preserve meaning.

Are you strictly saying both goals here are not attainable?

Maybe a different question is, what percentage of block of Remarkup here include code-related discussions. I'm not saying rendering those well shouldn't be a high-priority, I just see Remarkup used for much much more (task discussions, documents, conpherence, etc).

I think the two goals are sufficiently in conflict and the value of supporting these rules is so low that it probably isn't worth the effort to try to get it right most of the time.

We also can't really revert it: if we ship *x* and _x_ for any amount of time I think we're stuck with them forever, even if they're an intractable mess which made the product worse.

If it's five days from now and we've killed GitHub, would we still want these rules?

I haven't seen any evidence that users discussing code, or tasks, or messaging in Conpherence, or writing documents, or whatever else are having difficulty figuring out how to make stuff bold or italic. And there's also no evidence that they're having stuff they don't want to become italic or bold suddenly becoming italic or bold, which is great.

(There's a sub-problem here which is displaying README.md documents from repositories that are hosted on GitHub, but we can solve that without changing Remarkup.)

My anecdote here is Betamax vs. VHS. Yes, one is superior, the other has 95% of the market. I believe we're both right, but weigh certain issues differently. I see the new user coming from GitHub as the more important customer, as it leads to growth. The more things are different in Phabricator, the steeper the climb. You're right from a technical standpoint, and I do believe Remarkup is superior, so I'm stuck.

Having markdown rendered in documentation as expected probably alleviates 90% of my concerns. At least, having to retype or reformat large chunks of text is un-cool and arduous. Learning some new markup, less so. But it sounds like thats years away.

We could probably ship it (.md in Diffusion rendering as GitHub Flavored Markdown) this week -- it wouldn't be perfect, but we do have total freedom there to iterate as we find cases we're missing there -- it's just a pretty hard sell as a priority for me relative to the development cost. Obviously it would be nice if you bring in your repository to Phabricator and the README.md renders perfectly instead of rendering mostly-okay-but-a-bit-buggy, but it's hard for me to imagine we're losing many users there.

Well we also have a lunch today.