Add embed entity

[SuperTux88]

Fixes #93

I did a few changes to the proposal:

• I renamed link to url.
• I added a nothing property for when nothing should be embedded and nothing should be scanned. I think this is better to be explicit in this case. When this is true the url property is optional, otherwise it is required.

cc @annando

[SuperTux88]

Oh yes, I forget to change the descriptions m( fixed that now.

Markdown is not allowed, it also wouldn't make any sense, because this is provided by websites for all sorts of use-cases and not only diaspora, so I don't think any website would provide markdown there.

The embed is in the optional section of the status_message entity, I think that is enough to show that it is optional.

[annando]

I would prefer having some "Markdown is not allowed" in the documentation, just to clarify this. And yes, if that hadn't been cleared, I had put it through our HTML to Markdown interpreter, since the fetched description sometimes contain HTML elements. BTW: Is only plaintext allowed or HTML elements?

With "optional" I meant that the "embed" could point to an address that doesn't exist in the status message at all. So you could include the links A, B and C in your post, but the "embed" points to the link "D". This is a little bit nitpicking to mention this, but one does never know how people are interpreting specifications.

[SuperTux88]

Is only plaintext allowed or HTML elements?

Everything is "allowed" (websites can put what they want in that field), but only plaintext is rendered. It has the type String which allows just everything. We have many things that "doesn't allow" markdown, but we don't mention when something doesn't allow markdown, we mention when something explicitly allows Markdown.

With "optional" I meant that the "embed" could point to an address that doesn't exist in the status message at all.

While this is theoretically possible, I wouldn't recommend this so I don't think it is a good idea to mention that. When you link to a url that isn't in the status message at all, not everybody can see it (when not every software supports this entity, or old versions), so maybe people talk about a link in the comments, that not everybody can see. While when you include the link in the message too, some softwares maybe embed the wrong url or embed nothing at all (if they don't support embedding at all), but at least everybody can see all links. So I would always include the link in the message for accessibility reasons.

[SuperTux88]

@annando I added a little paragraph about the second part now, I hope that it's clear know that the link should also be included in the text but doesn't need to match 1:1.

[annando]

I still am confused by:

Everything is "allowed" (websites can put what they want in that field), but only plaintext is rendered.

So how do I force a linefeed in the description? By doing some CR or with
?

[SuperTux88]

So how do I force a linefeed in the description?

The description is only plain text (see spec), there are no newlines or other formatting.

[SuperTux88]

@annando are there any open points here or can you approve this PR?