doc (components): documentation of comments_max_depth option and threads conversion:

ActivityPub to XMPP threads conversion is detailed.

fix 364

doc/components.rst

@@ -233,6 +233,10 @@ All options are to be set in ``[component ap-gateway]`` section.
 
   **default**: ``_ap``
 
+``comments_max_depth``
+  An integer value indicating the maximum number of comment nodes that can be created. See
+  :ref:`ap-xmpp-threads-conversion`
+
 
 .. _ap-actor-from-xmpp:
 
@@ -361,6 +365,52 @@ handle in AP implementations, e.g.: ``@louise@example.org``).
    before your entity is followed. Other implementations may work differently.
 
 
+.. _ap-xmpp-threads-conversion:
+
+ActivyPub to XMPP Discussion Threads Conversion
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+By default, each (micro)blog publication converted from ActivityPub to XMPP Pubsub is
+associated with a comment node (see `XEP-0277 comments`_) to allow user to post a reply on
+any on them. This result in a "tree-like" comments threading model, which is similar to
+what you can see on popular website such as Reddit, Hacker News, or LinuxFr.
+
+However, some XMPP clients may not play nicely with this kind of threading model. To work
+around this, the ``comments_max_depth`` option allows to limit the maximum number of
+thread. It is an integer value which indicate how many comments nodes may exist for a root
+post. If set to ``1``, only one comment node will be made, and ActivityPub items below
+this level will be moved to this single XMPP pubsub comment node.
+
+The default value of ``0`` means unlimited max depth.
+
+An example can probably make it more clear. Imagine that you have a message ``root
+message``, with a comment to it named ``1``, a comment to ``1`` named ``2`` and so on
+until ``5``. With ``comments_max_depth`` set to ``0``, you'll have one comment node per
+item, resulting in following threads model::
+
+  root message ┑
+               ┕ 1 ┑
+                   ┕ 2 ┑
+                       ┕ 3 ┑
+                           ┕ 4 ┑
+                               ┕ 5
+
+With ``comments_max_depth`` set to ``2``, only 2 nodes will be created, and items below
+depth ``2`` will be put on the same level::
+
+  root message ┑
+               ┕ 1 ┑
+                   ┝ 2
+                   ┝ 3
+                   ┝ 4
+                   ┕ 5
+
+This way, admins can configure the model which suits best the clients which is expected to
+be mainly used on the instance.
+
+.. _XEP-0277 comments: https://xmpp.org/extensions/xep-0277.html#comments
+
+
 Using the Component (for developers)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~