Author-attributed text

[cben]

Needed for comments, chat, threaded responses, everything.

An obvious direction is Etherpad-like magic coloring of all text by author. But I'd like to steer cleer of magic text properties and keep the document model be plain text [until proven that it doesn't work]. And there are really 2 scenarious:

1. Collaborative writing, where the end result should be unattributed (though a special history/blame mode is occassionally useful). In Etherpad, you nuke all coloring when it gets annoying.
2. Discussion (including comments on writing), where who wrote what should be part of the text.

Ideas:

• <user> text attributed quotation a-la IRC logs.
• @username and/or email@domain. I'm leaning towards email with compact rendering as a gravatar and autocomplete for fast typing.
  • Potential conflict between @user notification ("to") semantics and attribution ("from") semantics I need here.
  • Conflict between @ and pandoc citations.
  • Email makes more portable documents. [Unless I adopt 1:1 login-with-twitter usernames.]

[cben]

Observation: <email@domain> must just mean an explicitly delimited email.

This makes <user> text IRC-like quote syntax a problematic idea as it's surprising for <user> and <email@domain> to have different semantics... However, it may be acceptable if I just highlight the user without associating the text.

P.S. random idea: consider also user@ over @user? But at this point, going against twitter convention would be silly.

[cben]

For comments on text, I'm increasingly fond of [^B42] footnote syntax with the convention that the letter(s) indicate user (e.g. B = beni). Both footnote site and body get highlighted with user's color. It looks quite well, and is backward-compatible with pandoc.

However, there is no sane way to use it for free-standing discussion, or even replies to comments on text :-(

[cben]

Interesting idea:

https://stackedit.io/#comments

Usually, comments in Markdown are just standard HTML comments. 
<!-- like this -->
**StackEdit** extends HTML comments in order to produce useful, highlighted comments in the preview but not in your exported documents. 
<!--- This is very useful for collecting feedback in a collaborative document. -->

(<!-- is hidden, <!--- stands out in red in preview)

Using HTML comments makes a lot of sense, but the syntax is very ugly...

[cben]

Some people use JR> quoted text style in email to quote text by J. Random. This extension to > quoting also has precedent in Markua's "asides" and "blurbs":

{class: warning}
B> This is a paragraph in the blurb.
B>
B> This is a second paragraph in the blurb
B> which contains newlines.

(plus shorthands like W> implying class: warning.)

This translates to several ideas for my use case.

email1@domain1> Comment by person 1
email1@domain1> is long.

email2@domain2> Comment by person 2.

(like discussed above but without leading <. BTW, space after the > should be required.) The drawback is replies and nesting get very ugly. Also very painful to type without editor help.

It does get better with short document-local user prefixes (A> means Alice, BB> means Bob Baggins) but that's less localized.

A good compromise is the more email-like:

{by: email1@domain1}
> Comment by person 1.
> {by: email2@domain2}
> > Nested comment by person 2.
> Back to person1.

That looks good but I'm afraid this will be fragile. Especially with nesting, it'll be quite easy to accidentally take someone's words out of his mouth into somebody's else. (Was less of problem in email since the original message where you said something was immutable.)

---

It's also time to discuss question "Email-style" vs. "Wave-style" nesting.

Before that I must mention the much simpler option to not support nesting. http://blog.codinghorror.com/discussions-flat-or-threaded/ has excellent arguments in favor of flat discussion (though they are for a each-comment-is-separate-object model, not insert-in-middle-of-doc). I'm not sure yet what I think of that, but I'd like to figure out what a markdown discussion syntax that does support nesting looks like.

What do I mean? In email, if Bob is replying to something Alice said, he writes:

B> A> I'm in wonderland.
B> Where is that?

and when alice has something to add, she wraps this into a new message structured:

A> B> A> I'm in wonderland.
A> B> Where is that?
A> Follow the white rabbit.

(the outermost authorship is implicit in the From: header, but I'm showing it here as quoting.)

This wrapping won't work well with collaborative editing in a single-document [^sd] model. Where it really breaks down is multiple users replying to same message — if Morpheus has something to add he creates a parallel new message:

M> B> A> I'm in wonderland.
M> B> Where is that?
M> Unfortunately no one can be told where it is.  You must see for yourself.

What we need in a single collaboratively-edited doc is reversing the structure: original text remains in place, replies go deeper to the right:

A> I'm in wonderland.
A> B> Where is that?
A> B> A> Follow the white rabbit.
A> B> M> Unfortunately no one can be told where it is.  You must see for yourself.

I call this "Wave-style nesting" because it's precisely what Google Wave did in a real-time-editing system. The structure is also familiar from any forum software.

Unfortunately it clearly violates long established block-quote semantics, so perhaps any >-based syntax is bad? Perhaps it can be mildly fixed by something like:

A> I'm in wonderland.
> B> Where is that?
> > A> Follow the white rabbit.
> > M> Unfortunately no one can be told where it is.  You must see for yourself.

Or even:

A> I'm in wonderland.
B>> Where is that?
A>>> Follow the white rabbit.
M>>> Unfortunately no one can be told where it is.  You must see for yourself.

Hmm, that's weird. Probably the other way around, separating nesting from authorship:

> {A} I'm in wonderland.
>> {B} Where is that?
>>> {A} Follow the white rabbit.
>>> {M} Unfortunately no one can be told where it is.  You must see for yourself.

I'm tempted to use indentation instead.

[^sd]: And I'd rather not go into chain-of-messages model. I may have no choice if I ever bridge mathdown to email and allow commenting by email reply but I think it'll still be more useful to somehow map into onto one-document model. Anyway, let's leave that for much later. There is a more substantial issue though: comment spam. Publicly posting fully editable docs will inevitably lead to vandalism; restricting to read-only, but commentable docs (#91) helps but still should enforce separation between authors.

[cben]

Aha! I've always been aware of ikiwiki doing discussion-in-freely-editable-markdown but for some reason I thought it's indentation-based. That's how it renders: https://ikiwiki.info/ikiwiki/pagespec/discussion/ but the source is >-based, and already invented an authorship syntax for us:

>>>
>>> Then, the requested functionality would be `sibling() or ancestor()`,
>>> or possibly `sibling() or ancestor() or self()`?
>>> --[[smcv]]

>>>> I like that idea! --[[KathrynAndersen]]

This syntax is ikiwiki-specific in that those are links to user pages (e.g. https://ikiwiki.info/users/KathrynAndersen/). And trailing attribution makes it harder to highlight each user's text in a personal color.

Still, I think it's safe to settle on > nesting with separate attribution (TBD syntax).