# HG changeset patch
# User Goffi <goffi@goffi.org>
# Date 1658502988 -7200
# Node ID 8b76caa89aa0bde64c1fccd4d283b92055915e5c
# Parent  76fb0739cc9cf3c8314b68884f9ca52c2a16198e
doc (cli/pubsub, cli/blog): `attachments` subcommands documentation:

rel 370

diff -r 76fb0739cc9c -r 8b76caa89aa0 doc/libervia-cli/blog.rst
--- a/doc/libervia-cli/blog.rst	Fri Jul 22 17:15:40 2022 +0200
+++ b/doc/libervia-cli/blog.rst	Fri Jul 22 17:16:28 2022 +0200
@@ -328,3 +328,9 @@
 Import a Dotclear blog without uploading images::
 
   $ li blog import --no-images-upload dotclear /path/to/dotclear.dump
+
+attachments
+===========
+
+Subcommands to add or remove data attached to pubsub items. Please check
+:ref:`libervia-cli_blog_attachments`.
diff -r 76fb0739cc9c -r 8b76caa89aa0 doc/libervia-cli/blog_attachments.rst
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/libervia-cli/blog_attachments.rst	Fri Jul 22 17:16:28 2022 +0200
@@ -0,0 +1,10 @@
+.. _libervia-cli_blog_attachments:
+
+===================================================
+blog/attachments: (un)attach Metadata to Blog Items
+===================================================
+
+Blog attachments subcommands are the same as  :ref:`pubsub attachments
+<libervia-cli_pubsub_attachments>` subcommands except that if ``--node`` is not specified,
+default blog node will be used. Please refer to pubsub attachments documentation for
+details.
diff -r 76fb0739cc9c -r 8b76caa89aa0 doc/libervia-cli/pubsub.rst
--- a/doc/libervia-cli/pubsub.rst	Fri Jul 22 17:15:40 2022 +0200
+++ b/doc/libervia-cli/pubsub.rst	Fri Jul 22 17:16:28 2022 +0200
@@ -444,6 +444,12 @@
 
 Subcommands for node management. Please check :ref:`libervia-cli_pubsub_node`.
 
+attachments
+===========
+
+Subcommands to add or remove data attached to pubsub items. Please check
+:ref:`libervia-cli_pubsub_attachments`.
+
 hook
 ====
 
diff -r 76fb0739cc9c -r 8b76caa89aa0 doc/libervia-cli/pubsub_attachments.rst
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/libervia-cli/pubsub_attachments.rst	Fri Jul 22 17:16:28 2022 +0200
@@ -0,0 +1,57 @@
+.. _libervia-cli_pubsub_attachments:
+
+=======================================================
+pubsub/attachments: (Un)Attach Metadata to Pubsub Items
+=======================================================
+
+``attachments`` is a subcommand grouping all pubsub commands related to "pubsub
+attachments" specification.
+
+With them, you can (un)attach data to any pubsub item. This is notably used to handle
+data like saying if an item is (un)noticed, or add emoji reactions.
+
+get
+===
+
+Retrieve a list of all attached data to an item.
+
+By default all attachments of the item are returned, this can be filtered by using ``-j
+JIDS, --jid JIDS``
+
+example
+-------
+
+Louise check all attachments on her last blog post::
+
+  $ li pubsub attachments get -s louise@example.org -n urn:xmpp:microblog:0 -i some-news-acf0
+
+set
+===
+
+Update or replace attachments. By default new attachments are updated, but if the ``-R,
+--replace`` is used, new attachments replace the whole former one where it make sense. For
+instance, ``-R`` doesn't change anything for ``noticed`` attachments, but it will replace
+all reactions (potentially with no reaction at all), where the default behaviour is to
+merge former and new reactions.
+
+Note that only specified attachments are affected, if unknown or unspecified attachments
+exist, they will stay unmodified.
+
+For now, only ``noticed`` (to say that an element has been seen and taken into account)
+and ``reactions`` (emojis to show emotion or other kind of reaction about something) are
+managed.
+
+``-N [BOOLEAN], --noticed [BOOLEAN]`` takes on optional argument to say if the item is
+noticed or not. If the optional argument is not specified, if will be the same as if the
+``true`` value was used.
+
+examples
+--------
+
+Pierre wants to indicate to Louise that is has seen and he took into account her last blog post::
+
+  $ li pubsub attachments set -s louise@example.org -n urn:xmpp:microblog:0 -i some-news-acf0 -N
+
+Louise wants to react to Pierre blog post about night trains::
+
+  $ li pubsub attachments set -s pierre@example.net -n urn:xmpp:microblog:0 -i nigh-train-are-great-f120 -r 🚆🌜💤