Delete slate-formats.md (#8280)

docs/slate-formats.md

@@ -1,88 +0,0 @@
-Guide to data types used by the Slate-based Rich Text Editor
-------------------------------------------------------------
-
-We always store the Slate editor state in its Value form.
-
-The schema for the Value is the same whether the editor is in MD or rich text mode, and is currently (rather arbitrarily)
-dictated by the schema expected by slate-md-serializer, simply because it was the only bit of the pipeline which
-has opinions on the schema. (slate-html-serializer lets you define how to serialize whatever schema you like).
-
-The BLOCK_TAGS and MARK_TAGS give the mapping from HTML tags to the schema's node types (for blocks, which describe
-block content like divs, and marks, which describe inline formatted sections like spans).
-
-We use <p/> as the parent tag for the message (XXX: although some tags are technically not allowed to be nested within p's)
-
-Various conversions are performed as content is moved between HTML, MD, and plaintext representations of HTML and MD.
-
-The primitives used are:
-
- * Markdown.js - models commonmark-formatted MD strings (as entered by the composer in MD mode)
-   * toHtml() - renders them to HTML suitable for sending on the wire
-   * isPlainText() - checks whether the parsed MD contains anything other than simple text.
-   * toPlainText() - renders MD to plain text in order to remove backslashes.  Only works if the MD is already plaintext (otherwise it just emits HTML)
-
- * slate-html-serializer
-   * converts Values to HTML (serialising) using our schema rules
-   * converts HTML to Values (deserialising) using our schema rules
-
- * slate-md-serializer
-   * converts rich Values to MD strings (serialising) but using a non-commonmark generic MD dialect.
-   * This should use commonmark, but we use the serializer here for expedience rather than writing a commonmark one.
-
- * slate-plain-serializer
-  * converts Values to plain text strings (serialising them) by concatenating the strings together
-  * converts Values from plain text strings (deserialiasing them).
-  * Used to initialise the editor by deserializing "" into a Value. Apparently this is the idiomatic way to initialise a blank editor.
-  * Used (as a bodge) to turn a rich text editor into a MD editor, when deserialising the converted MD string of the editor into a value
-
- * PlainWithPillsSerializer
-  * A fork of slate-plain-serializer which is aware of Pills (hence the name) and Emoji.
-  * It can be configured to output Pills as:
-    * "plain": Pills are rendered via their 'completion' text - e.g. 'Matthew'; used for sending messages)
-    * "md": Pills are rendered as MD, e.g. [Matthew](https://matrix.to/#/@matthew:matrix.org) )
-    * "id": Pills are rendered as IDs, e.g. '@matthew:matrix.org' (used for authoring / commands)
-  * Emoji nodes are converted to inline utf8 emoji.
-
-The actual conversion transitions are:
-
- * Quoting:
-   * The message being quoted is taken as HTML
-   * ...and deserialised into a Value
-   * ...and then serialised into MD via slate-md-serializer if the editor is in MD mode
-
- * Roundtripping between MD and rich text editor mode
-   * From MD to richtext (mdToRichEditorState):
-     * Serialise the MD-format Value to a MD string (converting pills to MD) with PlainWithPillsSerializer in 'md' mode
-     * Convert that MD string to HTML via Markdown.js
-     * Deserialise that Value to HTML via slate-html-serializer
-   * From richtext to MD (richToMdEditorState):
-     * Serialise the richtext-format Value to a MD string with slate-md-serializer (XXX: this should use commonmark)
-     * Deserialise that to a plain text value via slate-plain-serializer
-
- * Loading history in one format into an editor which is in the other format
-   * Uses the same functions as for roundtripping
-
- * Scanning the editor for a slash command
-   * If the editor is a single line node starting with /, then serialize it to a string with PlainWithPillsSerializer in 'id' mode
-     So that pills get converted to IDs suitable for commands being passed around
-
- * Sending messages
-   * In RT mode:
-     * If there is rich content, serialize the RT-format Value to HTML body via slate-html-serializer
-     * Serialize the RT-format Value to the plain text fallback via PlainWithPillsSerializer in 'plain' mode
-   * In MD mode:
-     * Serialize the MD-format Value into an MD string with PlainWithPillsSerializer in 'md' mode
-     * Parse the string with Markdown.js
-     * If it contains no formatting:
-       * Send as plaintext (as taken from Markdown.toPlainText())
-     * Otherwise
-       * Send as HTML (as taken from Markdown.toHtml())
-       * Serialize the RT-format Value to the plain text fallback via PlainWithPillsSerializer in 'plain' mode
-
- * Pasting HTML
-   * Deserialize HTML to a RT Value via slate-html-serializer
-   * In RT mode, insert it straight into the editor as a fragment
-   * In MD mode, serialise it to an MD string via slate-md-serializer and then insert the string into the editor as a fragment.
-
-The various scenarios and transitions could be drawn into a pretty diagram if one felt the urge, but hopefully the above
-gives sufficient detail on how it's all meant to work.