From fe3aa7658584d7e6c7e0e1486ddae52fefcade87 Mon Sep 17 00:00:00 2001
From: Dmitri Bogomolov <4glitch@gmail.com>
Date: Sun, 31 Jan 2021 20:42:35 +0200
Subject: [PATCH] Message Encodings section and extended_encoding doc

---
 docs/extended_encoding.rst | 55 ++++++++++++++++++++++++++++++++++++++
 docs/protocol.rst          | 28 +++++++++++++++++++
 2 files changed, 83 insertions(+)
 create mode 100644 docs/extended_encoding.rst

diff --git a/docs/extended_encoding.rst b/docs/extended_encoding.rst
new file mode 100644
index 00000000..25539ad4
--- /dev/null
+++ b/docs/extended_encoding.rst
@@ -0,0 +1,55 @@
+Extended encoding
+=================
+
+Extended encoding is an attempt to create a standard for transmitting structured
+data. The goals are flexibility, wide platform support and extensibility. It is
+currently available in the v0.6 branch and can be enabled by holding "Shift"
+while clicking on Send. It is planned that v5 addresses will have to support
+this. It's a work in progress, the basic plain text message works but don't
+expect anthing else at this time.
+
+The data structure is in msgpack, then compressed with zlib. The top level is
+a key/value store, and the "" key (empty string) contains the value of the type
+of object, which can then have its individual format and standards.
+
+Text fields are encoded using UTF-8.
+
+Types
+-----
+
+You can find the implementations in the ``src/messagetypes`` directory of
+PyBitmessage. Each type has its own file which includes one class, and they are
+dynamically loaded on startup. It's planned that this will also contain
+initialisation, rendering and so on, so that developers can simply add a new
+object type by adding a single file in the messagetypes directory and not have
+to change any other part of the code.
+
+message
+^^^^^^^
+
+The replacement for the old messages. Mandatory keys are ``body`` and
+``subject``, others are currently not implemented and not mandatory. Proposed
+other keys:
+
+``parents``:
+   array of msgids referring to messages that logically precede it in a
+   conversation. Allows to create a threaded conversation view
+
+``files``:
+   array of files (which is a key/value pair):
+
+   ``name``:
+      file name, mandatory
+   ``data``:
+      the binary data of the file
+   ``type``:
+      MIME content type
+   ``disposition``:
+      MIME content disposition, possible values are "inline" and "attachment"
+
+vote
+^^^^
+
+Dummy code available in the repository. Supposed to serve voting in a chan
+(thumbs up/down) for decentralised moderation. Does not actually do anything at
+the moment and specification can change.
diff --git a/docs/protocol.rst b/docs/protocol.rst
index 2dc4c1bc..a9134325 100644
--- a/docs/protocol.rst
+++ b/docs/protocol.rst
@@ -210,6 +210,34 @@ Unencrypted Message Data
 Message Encodings
 """""""""""""""""
 
+.. list-table::
+   :header-rows: 1
+   :widths: auto
+
+   * - Value
+     - Name
+     - Description
+   * - 0
+     - IGNORE
+     - Any data with this number may be ignored. The sending node might simply
+       be sharing its public key with you.
+   * - 1
+     - TRIVIAL
+     - UTF-8. No 'Subject' or 'Body' sections. Useful for simple strings
+       of data, like URIs or magnet links.
+   * - 2
+     - SIMPLE
+     - UTF-8. Uses 'Subject' and 'Body' sections. No MIME is used.
+       ::
+	  messageToTransmit = 'Subject:' + subject + '\n' + 'Body:' + message
+   * - 3
+     - EXTENDED
+     - See :doc:`extended_encoding`
+
+Further values for the message encodings can be decided upon by the community.
+Any MIME or MIME-like encoding format, should they be used, should make use of
+Bitmessage's 8-bit bytes. 
+
 Pubkey bitfield features
 """"""""""""""""""""""""