# HG changeset patch
# User Goffi <goffi@goffi.org>
# Date 1652463126 -7200
# Node ID e597dbfbc4c6714a3322c6e6a4768e4faaf5d8e3
# Parent  f31113777881ff06666cb95e9e98bede981101c9
doc (cli/pubsub): document new `--public` flags:

`--public` option is documented for `subscribe`, `subscriptions` and `node subscriptions
get`, with examples. A warning has been added to show explicitely the privacy implication
of using `--public` with `subscribe`.

rel 365

diff -r f31113777881 -r e597dbfbc4c6 doc/libervia-cli/pubsub.rst
--- a/doc/libervia-cli/pubsub.rst	Fri May 13 19:29:17 2022 +0200
+++ b/doc/libervia-cli/pubsub.rst	Fri May 13 19:32:06 2022 +0200
@@ -109,6 +109,31 @@
 Subscription is used to get notifications from the node in case of new/updated item or
 deletion.
 
+If ``--public`` is used, the subscription will be made visible to anybody. For this to
+work, the target pubsub/PEP service must implement `XEP-0465 Public Pubsub
+Subscriptions`_. If your own server also implements XEP-0495 (and thus `XEP-0376 Pubsub
+Account Management`_ wich is a dependency), your subscription will also be visible to
+people requesting pubsub public subscriptions from your account.
+
+.. note::
+
+   Making a subscription public is interesting to show your center of interests and to let
+   other people discover people that you are subscribed to or who are subscribed to you
+   (this correspond the the "following" and "followers" feature that is seen on some
+   software).
+
+   However, it also makes your subscription visible to evil entities such as
+   spammer, bot collectings informations for e.g. marketing or surveillance. In some
+   locations, it may even be life threating as unwisely making public subscription may
+   show your political views, sexual orientation, religion, etc.
+
+   Furthermore, if you make public subscriptions, your JID may be retrieved easily (public
+   subscriptions can be checked to see if a JID exists and is used, or your JID can be
+   simply found from subscribed node, or from your subscribers). This is often desirable
+   in the case of social interactions, but this is to be known if you're willing to keep
+   your identifier secret (in this case, don't use public subscriptions).
+
+
 example
 -------
 
@@ -116,6 +141,11 @@
 
   $ li pubsub subscribe -n informations -s pubsub.example.net
 
+Pierre wants to subscribe to Louise blog, and to make it public, so other people can
+discover it::
+
+  $ li pubsub subscribe -n urn:xmpp:microblog:0 -s louise@example.org --public
+
 unsubscribe
 ===========
 
@@ -131,18 +161,39 @@
 subscriptions
 =============
 
-Retrieve subscriptions for all nodes on a service.
+Retrieve subscriptions from a user, or subscriptions for all nodes on a service.
+
+If no service and no node are specified, and if your server supports `XEP-0376 Pubsub
+Account Management`_, all subscriptions to any server or node of the profile are returned.
 
 ``-n NODE, --node NODE`` can be used to request subscriptions for a specific node (e.g. if
 it has subscription with multiple subIDs).
 
+If ``--public`` is used, only public subscriptions are retrieved. This can be used to find
+public subscriptions from an external user. The PEP/Pubsub service of the target entity
+must implement `XEP-0465 Public Pubsub Subscriptions`_.
+
+.. _XEP-0376 Pubsub Account Management: https://xmpp.org/extensions/xep-0376.html
+.. _XEP-0465 Public Pubsub Subscriptions: https://xmpp.org/extensions/inbox/pubsub-public-subscriptions.html
+
+
 example
 -------
 
-Retrieve all subscriptions on a pubsub service::
+Pierre server supports XEP-0465. To check all the node where he has a subscription, Pierre
+can use this command::
+
+  $ li pubsub subscriptions
+
+Retrieve all subscriptions on a specific pubsub service::
 
   $ li pubsub subscriptions -s pubsub@example.net
 
+Louise wants to checks to which node Pierre is publicly subscribed. She do it with
+following command::
+
+  $ li pubsub subscriptions --public -s pierre@example.net
+
 affiliations
 =============
 
diff -r f31113777881 -r e597dbfbc4c6 doc/libervia-cli/pubsub_node_subscriptions.rst
--- a/doc/libervia-cli/pubsub_node_subscriptions.rst	Fri May 13 19:29:17 2022 +0200
+++ b/doc/libervia-cli/pubsub_node_subscriptions.rst	Fri May 13 19:32:06 2022 +0200
@@ -13,6 +13,13 @@
 
 Retrieve subscriptions to a node.
 
+If ``--public`` is used, only public subscriptions are retrieved (if target service
+supports `XEP-0465 Public Pubsub Subscriptions`). Public subscriptions are accessible to
+anybody, thus you can use this on a node even if you are not an owner of it (and thus
+would not normally be allowed to retrieve subscriptions).
+
+.. _XEP-0465 Public Pubsub Subscriptions: https://xmpp.org/extensions/inbox/pubsub-public-subscriptions.html
+
 example
 -------
 
@@ -20,6 +27,10 @@
 
   $ li pubsub node subscriptions get -n some_node
 
+Retrieve public subscribers to the blog of Louise::
+
+  $ li pubsub node subscriptions get --public -s louise@example.org -n urn:xmpp:microblog:0
+
 set
 ===