diff doc/libervia-cli/message.rst @ 3806:adebd8036b68

doc (cli/message): `retract` command
author Goffi <goffi@goffi.org>
date Fri, 17 Jun 2022 15:50:15 +0200
parents 267e4987b58b
children d6837db456fd
line wrap: on
line diff
--- a/doc/libervia-cli/message.rst	Fri Jun 17 14:15:23 2022 +0200
+++ b/doc/libervia-cli/message.rst	Fri Jun 17 15:50:15 2022 +0200
@@ -35,10 +35,47 @@
 
   $ echo 'Bonjour, je vous écris avec « Libervia »' | li message send -l fr -t normal -S 'Ceci est un message de test'
 
+retract
+=======
+
+Retract a message, i.e. mark it as retracted in database, and send a retraction request to
+original recipient.
+
+When a message is marked as retracted in database, it won't appear anymore or a hint
+(commonly called *tombstone*) will be displayed instead (the behaviour depend of the
+frontend that you're using). However, there is an option to archive retracted messages:
+``Privacy``/``retract_history``. This option is disabled by default, but if you set it
+(e.g. with ``li param set``), the original message will be kept in metadata and may be
+displayed if the frontend that you're using allows it.
+
+The ``message_id`` positional argument is the internal ID of the message (not an XMPP ID).
+It may be displayed by some frontends.
+
+.. note::
+
+   It is not possible to be sure that a message will be retracted: once something is sent
+   through the network, any recipient can keep it, copy it, share it, etc. This is true for
+   Libervia/XMPP as for any software, decentralized or not.
+
+   Retract send a retractation **request**, i.e. it asks to the recipient(s) client(s) to
+   hide or delete the message, but it's not possible to have a guarantee that nobody kept
+   a request.
+
+   The message is also removed from database, except if the option
+   ``Privacy``/``retract_history`` is set (see above).
+
+example
+-------
+
+Retract message with ID ``1234-5678-9abc-def0``::
+
+  $ li message retract 1234-5678-9abc-def0
+
 mam
 ===
 
 Query archives using MAM.
+
 This command allows you to check message archive kept on the server (i.e. not the local copy).
 You usually want to specify a starting point, and a number of message to retrieve. If too many messages
 are available, you'll have to use RSM commands to navigate through the results.