erebion/libervia-backend
Watch
1
0
Fork
You've already forked libervia-backend
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

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

Browse source 
ActivityPub to XMPP threads conversion is detailed.

fix 364
This commit is contained in:
Goffi 2022-03-22 17:00:42 +01:00
commit 44906f3bc3
1 changed files with 50 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

50
doc/components.rst
View file

@ -233,6 +233,10 @@ All options are to be set in ``[component ap-gateway]`` section.
**default**: ``_ap`` **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: .. _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. 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) Using the Component (for developers)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~