document m.room.message formats

[richvdh]

m.text messages have undocumented 'format' and 'formatted_body' fields. #471 includes a lot of hand-wringing about what the ideal should be, but maybe we should document what we have?

[leonerd]

Funnily enough I started doing exactly that :)

See https://docs.google.com/document/d/1QPncBmMkKOo6_B2jyBuy5FFSZJrRsq7WU5wgRSzOMho/edit

[leonerd]

One theme that is slowly emerging from theabove document is that Riot itself has quite a rich support of HTML formatting (using CommonMark to send, and being embedded in an HTML-capable browser for receiving), most of the other client implementations are a lot more limited in what they support.

Prettymuch every client and bridge so far observed at least supports the basic formatting of bold, italics, underline, monospace, and possibly strikethrough. As most of the bridges are talking to 3PNs that consider messages as single-line entities, these bridges almost never support any of the block structuring like numbered headings, pre-formatted blocks, numbered or unnumbered lists, etc. Additionally, none of the terminal-based clients would support things that adjust the font size (either directly, or by numbered headings).

[her001]

@leonerd Thanks for sharing your research! I used it as a reference while adding an initial implementation of formatting incoming HTML messages in the Matrix script for Weechat: torhve/weechat-matrix-protocol-script#75

While documentation is not there, you can use rich html messages with curl be inspired by this template:

token="check your token access in riot general settings"
room_id="vfFxDRtZSSdspfTSEr" #test:matrix.org
room_server="matrix.org"
homeserver="matrix.org"

curl -XPOST -k -d '{"msgtype":"m.text", "body": "", "format": "org.matrix.custom.html", "formatted_body":"<b>test</b> test <font color =\"red\">red test</font> https://docs.google.com/document/d/1QPncBmMkKOo6_B2jyBuy5FFSZJrRsq7WU5wgRSzOMho/edit#heading=h.arjuwv7itr4h <table style=\"width:100%\"><tr><th>Firstname</th><th>Lastname</th><th>Age</th></tr><tr><td>Jill</td><td>Smith</td><td>50</td></tr><tr><td>Eve</td><td>Jackson</td><td>94</td></tr></table> https://www.w3schools.com/html/html_tables.asp"}' "https://matrix.guifi.net:8448/_matrix/client/r0/rooms/%21$room_id:$room_server/send/m.room.message?access_token=$token"