Mercurial > libervia-backend

comparison doc/components.rst @ 3746:fa3dc4ed7906

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc (components): documentation of `comments_max_depth` option and threads conversion: ActivityPub to XMPP threads conversion is detailed. fix 364
author Goffi <goffi@goffi.org>
date Tue, 22 Mar 2022 17:00:42 +0100
parents 643622ff1492
children 98ba02637436
comparison
equal deleted inserted replaced
3745:a8c7e5cef0cb 3746:fa3dc4ed7906
230 ``ap_path`` 230 ``ap_path``
231 Path prefix to use for ActivityPub request. It's usually not necessary to change the 231 Path prefix to use for ActivityPub request. It's usually not necessary to change the
232 default value. 232 default value.
233 233
234 **default**: ``_ap`` 234 **default**: ``_ap``
235
236 ``comments_max_depth``
237 An integer value indicating the maximum number of comment nodes that can be created. See
238 :ref:`ap-xmpp-threads-conversion`
235 239
236 240
237 .. _ap-actor-from-xmpp: 241 .. _ap-actor-from-xmpp:
238 242
239 How to Address an AP Actor from XMPP 243 How to Address an AP Actor from XMPP
359 Some AP implementations such as Mastodon don't retrieve existing items, but only keep 363 Some AP implementations such as Mastodon don't retrieve existing items, but only keep
360 new ones once an actor is followed. That means that you won't see any message published 364 new ones once an actor is followed. That means that you won't see any message published
361 before your entity is followed. Other implementations may work differently. 365 before your entity is followed. Other implementations may work differently.
362 366
363 367
368 .. _ap-xmpp-threads-conversion:
369
370 ActivyPub to XMPP Discussion Threads Conversion
371 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
372
373 By default, each (micro)blog publication converted from ActivityPub to XMPP Pubsub is
374 associated with a comment node (see `XEP-0277 comments`_) to allow user to post a reply on
375 any on them. This result in a "tree-like" comments threading model, which is similar to
376 what you can see on popular website such as Reddit, Hacker News, or LinuxFr.
377
378 However, some XMPP clients may not play nicely with this kind of threading model. To work
379 around this, the ``comments_max_depth`` option allows to limit the maximum number of
380 thread. It is an integer value which indicate how many comments nodes may exist for a root
381 post. If set to ``1``, only one comment node will be made, and ActivityPub items below
382 this level will be moved to this single XMPP pubsub comment node.
383
384 The default value of ``0`` means unlimited max depth.
385
386 An example can probably make it more clear. Imagine that you have a message ``root
387 message``, with a comment to it named ``1``, a comment to ``1`` named ``2`` and so on
388 until ``5``. With ``comments_max_depth`` set to ``0``, you'll have one comment node per
389 item, resulting in following threads model::
390
391 root message ┑
392 ┕ 1 ┑
393 ┕ 2 ┑
394 ┕ 3 ┑
395 ┕ 4 ┑
396 ┕ 5
397
398 With ``comments_max_depth`` set to ``2``, only 2 nodes will be created, and items below
399 depth ``2`` will be put on the same level::
400
401 root message ┑
402 ┕ 1 ┑
403 ┝ 2
404 ┝ 3
405 ┝ 4
406 ┕ 5
407
408 This way, admins can configure the model which suits best the clients which is expected to
409 be mainly used on the instance.
410
411 .. _XEP-0277 comments: https://xmpp.org/extensions/xep-0277.html#comments
412
413
364 Using the Component (for developers) 414 Using the Component (for developers)
365 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 415 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
366 416
367 Publication of AP items can be tested using the following method (with can be accessed 417 Publication of AP items can be tested using the following method (with can be accessed
368 through the ``APSend`` bridge method, client is then replaced by the ``profile`` name, as 418 through the ``APSend`` bridge method, client is then replaced by the ``profile`` name, as