changeset 3041:72583524cfd3

doc (jp): jp commands are now fully documented: rel 232
author Goffi <goffi@goffi.org>
date Tue, 01 Oct 2019 22:49:06 +0200
parents fee60f17ebac
children 964abd07dc03
files doc/configuration.rst doc/jp/account.rst doc/jp/ad-hoc.rst doc/jp/avatar.rst doc/jp/blog.rst doc/jp/bookmarks.rst doc/jp/common_arguments.rst doc/jp/debug.rst doc/jp/encryption.rst doc/jp/event.rst doc/jp/event_invitee.rst doc/jp/file.rst doc/jp/file_share.rst doc/jp/forums.rst doc/jp/identity.rst doc/jp/info.rst doc/jp/input.rst doc/jp/invitation.rst doc/jp/merge-request.rst doc/jp/message.rst doc/jp/param.rst doc/jp/ping.rst doc/jp/pipe.rst doc/jp/profile.rst doc/jp/pubsub.rst doc/jp/pubsub_hook.rst doc/jp/pubsub_node.rst doc/jp/pubsub_node_affiliations.rst doc/jp/pubsub_node_schema.rst doc/jp/pubsub_node_subscriptions.rst doc/jp/roster.rst doc/jp/shell.rst doc/jp/ticket.rst doc/jp/uri.rst doc/overview.rst
diffstat 35 files changed, 2976 insertions(+), 2 deletions(-) [+]
line wrap: on
line diff
--- a/doc/configuration.rst	Wed Sep 25 08:56:41 2019 +0200
+++ b/doc/configuration.rst	Tue Oct 01 22:49:06 2019 +0200
@@ -1,3 +1,5 @@
+.. _configuration:
+
 =============
 Configuration
 =============
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/jp/account.rst	Tue Oct 01 22:49:06 2019 +0200
@@ -0,0 +1,75 @@
+================================
+account: XMPP account management
+================================
+
+``account`` command help you to create or manage the XMPP account of a server, using
+In-Band Registration (`XEP-0077`_).
+
+.. _XEP-0077: https://xmpp.org/extensions/xep-0077.html
+
+create
+======
+
+Create a XMPP account. You have to specify your jid and password as positional arguments.
+By default the registration is done on ``localhost`` with default XMPP Client 2 Server
+port (i.e. 5222), but you can specify other host/port using ``-H HOST, --host HOST`` and
+``-P PORT, --port PORT``. You may also specify an e-mail address using ``-e EMAIL, --email
+EMAIL`` (use of this data depend of the server implementation).
+
+By default, no SàT profile is created and associated to this new XMPP account, but you can
+use ``-p PROFILE, --profile PROFILE`` if you are willing to have one.
+
+example
+-------
+
+Create account for the new user Nestor at ``nestor@example.org`` and associate it with the
+SàT profile ``nestor``::
+
+  $ jp account create nestor@example.org some_password -p nestor
+
+
+modify
+======
+
+Modify an existing XMPP account password. This will modify the XMPP account linked to the
+given profile.
+
+.. note::
+
+   Only the XMPP password on the server is changed, not the one registered in the
+   parameter of SàT. You may have to update the parameter of your profile if the new
+   password doesn't correspond to your parameters one (you can do that with jp param set
+   or with most SàT frontends in parameters).
+
+example
+-------
+
+Change the XMPP password of the XMPP account of the default profile::
+
+  $ jp account modify new_password
+
+
+delete
+======
+
+Delete the XMPP account linked to the given profile from the XMPP server. Before using
+this command, please be sure to understand well that **THIS WILL REMOVE THE WHOLE XMPP
+ACCOUNT AND DATA FROM THE XMPP SERVER**.
+
+By default a confirmation is requested, you can do this without confirmation by using
+``-f, --force``, however this is **NOT RECOMMENDED**, be sure to understand what you're
+doing if you use this option (and be sure to spell correctly the profile, if you forget
+the ``-p PROFILE, --profile`` argument for instance, this would delete entirely the
+default profile).
+
+.. note::
+
+   Be extra careful with this command, as it will remove the whole account from the
+   server, and the associated data.
+
+example
+-------
+
+Delete the XMPP account of Pierre, which is not on the local server anymore::
+
+  $ jp account delete -p pierre
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/jp/ad-hoc.rst	Tue Oct 01 22:49:06 2019 +0200
@@ -0,0 +1,120 @@
+=======================
+ad-hoc: Ad-Hoc commands
+=======================
+
+Ad-Hoc commands is a generic mechanism of XMPP to control an entity. They can be used
+either by humans, or automated. Ad-Hoc commands can be used for administration (e.g. get
+list of connected users, send a service announcement, restart parts of the server), or
+execute about anything (e.g. control a physical robot with XMPP).
+
+run
+===
+
+Run an ad-hoc command. You may specify the node to run as positional argument, or let it
+empty to list available commands.
+
+By default the commands from your server are used, but with ``-j JID, --jid JID`` you can
+specify a different entity.
+
+You can automatically execute commands by using ``-f KEY VALUE, --field KEY VALUE`` and
+``-S, --submit`` as many time as needed.  ``--field`` expect a ``KEY`` which is the name
+of the field to set. If you don't know which name to use, you can run the command to
+automatise a first time manually with ``--verbose, -v`` flag, this will display fields
+names when you have to fill them.
+
+Once all fields of a page are specified, you may use ``-S, --submit`` to validate it, then
+if suitable use again ``--field`` to set fields of next page and ``--submit`` again, and
+so on as many times as you need.
+
+Don't forget that you can use your shell substitution capabilities if necessary, for
+instance if you have a pre-registered announce to send.
+
+examples
+--------
+
+Get a list of available commands on your server to launch a command::
+
+  $ jp ad-hoc run
+
+If your server supports `XEP-0133`_ and you're an admin on it, you can send announcements
+to online users. This can be useful to notify an imminent maintenance of the server. Here
+we notify online users that the server will be shutdown in 30 min, using a shell
+substitution capabilities with a pre-registered message in the file
+``~/announces/maintenance_30.txt``, then we submit it::
+
+  $ jp ad-hoc run "http://jabber.org/protocol/admin#announce" -f subject "Maintenance in 30 min" -f announcement "$(<~/announces/maintenance_30.txt)" -S
+
+Get your server uptime (if supported by your server)::
+
+  $ jp ad-hoc run uptime
+
+Run the commands available at the service with the jid ``someservice.example.org``::
+
+  $ jp ad-hoc run -s someservice.example.org
+
+Run you server commands with verbosity so you get the name of the fields that you can fill
+automatically later::
+
+  $ jp ad-hoc run -v
+
+.. _XEP-0133: https://xmpp.org/extensions/xep-0133.html
+
+list
+====
+
+List ad-hoc commands available at a service.
+
+examples
+--------
+
+List ad-hoc commands available at your server::
+
+  $ jp ad-hoc list
+
+List ad-hoc commands available at a chat service::
+
+  $ jp ad-hoc list -j conference.example.org
+
+remote
+======
+
+Create a remote control from launched media players. Ad-hoc commands to control the media
+player will be added to your device, allowing anybody allowed (including yourself from an
+other device, e.g. a phone) to remotely do action like ``play``, ``pause``, etc.
+
+To add a device, just use the name of the software (e.g. ``vlc``, ``smplayer``). You can
+specify who is allowed to control this media player with the following options:
+
+``-j [JIDS [JIDS ...]], --jids [JIDS [JIDS ...]]``
+  jids of entities allowed to control the media player
+
+``g [GROUPS [GROUPS ...]], --groups [GROUPS [GROUPS ...]]``
+  groups (from your roster) allowed to control you remote
+
+``--forbidden-groups [FORBIDDEN_GROUPS [FORBIDDEN_GROUPS ...]]``
+  groups (from your roster) which are **NOT** allowed to control your media player
+
+``--forbidden-jids [FORBIDDEN_JIDS [FORBIDDEN_JIDS ...]]``
+  jids of entities which are **NOT** allowed to control your media player
+
+If you want the commands to run repeatedly (in opposition of stopping after first action
+is sent), you may use the ``-l, --loop`` option. Most of time you'll want to use it.
+
+.. note::
+
+   SàT already creates automatically a remote control if it finds a media player. This
+   manual way to create a remote control predate the automatic remote control, and is
+   currently more flexible in that you can specify who can access the remote control
+   (automatic remote control is only accessible by the jid of the profile).
+
+examples
+--------
+
+Create a remote control for a running VLC instance::
+
+  $ jp ad-hoc remote vlc -l
+
+Create a remote control for a running SMPlayer instance, and allowing anybody from your
+``housemates`` group to use it::
+
+  $ jp ad-hoc remote smplayer -g housemates -l
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/jp/avatar.rst	Tue Oct 01 22:49:06 2019 +0200
@@ -0,0 +1,44 @@
+===============================
+avatar: retrieve/upload avatars
+===============================
+
+Avatars are images associated to an XMPP entity. Several XMPP extensions are in use, SàT
+tries to hide the technical details so avatar are as easy as possible to manipulate for
+end-user.
+
+get
+===
+
+Retrieve the avatar of the given entity. Entity jid is specified as positional argument.
+
+If an avatar is found, a path to its cached file is printed. Please note that this is the
+cache used by all SàT ecosystem, **do not modify the cached image**. You may use it for
+read-only access, or copy it if you want to modify the image.
+
+You may use the ``-s, --show`` argument to display the found avatar. The software used to
+display the image can be specified in SàT configuration (cf. :ref:`configuration`), in the
+``[jp]`` section: the ``image_cmd`` setting let you specify the path to the software. If
+``image_cmd`` is not used, ``jp`` will try some common software, and if none is found, it
+will try to open the image in a browser (which may sometimes result in using the default
+image software of the platform).
+
+example
+-------
+
+Get the avatar of ``louise@example.org`` and display it::
+
+  $ jp avatar get --show louise@example.org
+
+
+set
+===
+
+Upload and set the given avatar for the profile. The only required argument is the path to
+the image to use as avatar.
+
+example
+-------
+
+Set the avatar of the default profile::
+
+  $ jp avatar set ~/photos/some_photo.jpg
--- a/doc/jp/blog.rst	Wed Sep 25 08:56:41 2019 +0200
+++ b/doc/jp/blog.rst	Tue Oct 01 22:49:06 2019 +0200
@@ -59,6 +59,8 @@
 
   $ jp blog get -m 2 -O template --oo browser
 
+.. _jp-blog_edit:
+
 edit
 ====
 
@@ -255,6 +257,8 @@
 
   $ jp blog preview ~/local/sat/blog/some_name/blog_something.md
 
+.. _jp-blog_import:
+
 import
 ======
 
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/jp/bookmarks.rst	Tue Oct 01 22:49:06 2019 +0200
@@ -0,0 +1,98 @@
+============================
+bookmarks: get/set bookmarks
+============================
+
+Bookmarks are links to MUC rooms or URLs with a few metadata. Due to historical reasons,
+XMPP has several ways to handle bookmarks, and SàT handle them as transparently as
+possible.
+
+With SàT there are 3 places where you can get/store your bookmarks:
+
+local
+  the bookmarks is stored only locally in the database of SàT. It won't be available to
+  other devices.
+private
+  the bookmarks use the old private XML storage (`XEP-0049`_). It is not recommended to
+  use this if PubSub storage is available
+pubsub
+  the bookmarks use PEP storage (`XEP-0223`_), this is the currently recommended way to
+  store bookmarks.
+
+When possible, you can specify ``auto`` to let SàT choose the best location (i.e.
+``pubsub`` if available, then ``private`` then ``local`` if nothing else is possible).
+
+.. _XEP-0049: https://xmpp.org/extensions/xep-0049.html
+.. _XEP-0223: https://xmpp.org/extensions/xep-0223.html
+
+
+list
+====
+
+Get and print available bookmarks. You specify the location of the bookmarks to print
+using ``-l {all,local,private,pubsub}, --location {all,local,private,pubsub``, by default
+all bookmarks from all locations are printed.
+
+Use ``-t {muc,url}, --type {muc,url}`` to indicate if you want to print MUC bookmarks or
+URLs.
+
+After printing the bookmarks location, the bookmarks will show the name and location (jid
+for MUC or URL). For MUC bookmarks you'll also see nickname, and a star (``*``) if
+autojoin is set.
+
+
+examples
+--------
+
+Retrieve all MUC bookmarks::
+
+  $ jp bookmarks list
+
+Retrieve all bookmarked URL stored in PubSub::
+
+  $ jp bookmarks list -l pubsub -t url
+
+
+remove
+======
+
+Delete a bookmark. You need to specify the jid of the MUC room or the URL to remove as
+positional argument. If you are deleting an URL, you need to specify it with ``-t url``
+
+By default a confirmation is requested, use ``-f, --force`` if you don't want it (with
+usual caution).
+
+examples
+--------
+
+Delete the bookmark of a MUC room that you are not following anymore::
+
+  $ jp bookmarks remove some_old_room@conference.example.net
+
+Delete the bookmark of a URL without requesting confirmation::
+
+  $ jp bookmarks remove -t url https://unused_url.example.net
+
+
+add
+===
+
+Create or update a bookmark. The bookmark itself (URL or JID of the MUC) is specified as
+positional argument. If you are bookmarking an URL, you need to specify it with ``-t
+url``. A name is often helpful, use ``-n NAME, --name NAME`` to specify it.
+
+For MUC only, you can specify the nick to use on the room with ``-N NICK, --nick NICK``,
+and the flag ``-a, --autojoin`` indicates if you want to join the chat room automatically
+when you're connecting.
+
+If you're using add on a jid/URL which already exists, the metadata will be updated.
+
+examples
+--------
+
+Add a bookmark to Salut à Toi official chat room::
+
+  $ jp bookmarks add sat@chat.jabberfr.org -a
+
+Add a link to Salut à Toi official website::
+
+  $ jp bookmarks add -t url https://www.salut-a-toi.org -n "SàT officiel"
--- a/doc/jp/common_arguments.rst	Wed Sep 25 08:56:41 2019 +0200
+++ b/doc/jp/common_arguments.rst	Tue Oct 01 22:49:06 2019 +0200
@@ -4,6 +4,8 @@
 
 Some arguments are used in many commands. This page describe them.
 
+.. _jp-common_profile:
+
 profile
 =======
 
@@ -156,6 +158,8 @@
   Add a verbosity level (can be used multiple times). Use to have more concise output by
   default when it makes sense.
 
+.. _draft_common:
+
 draft
 =====
 
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/jp/debug.rst	Tue Oct 01 22:49:06 2019 +0200
@@ -0,0 +1,79 @@
+=====================================================
+debug: tools to help debugging/monitoring Salut à Toi
+=====================================================
+
+``debug`` groups commands to monitor or manipulate SàT and XMPP stream.
+
+.. _jp-debug_bridge_method:
+
+bridge method
+=============
+
+Call a method of the bridge. You have to provide the name of the method and the arguments
+as positional arguments. Arguments are evaluated as Python code (using ``eval``), so you
+need to properly escape them (for your shell **and** Python). You can either split your
+Python arguments as many shell arguments, or put them in a single shell argument.
+
+You profile is automatically set if the method requires it (using the value of ``-p
+PROFILE, --profile PROFILE``), so you must not specify it as an extra argument.
+
+You can refer to `Bridge API documentation`_ to get core methods signatures
+
+.. _Bridge API documentation: https://wiki.goffi.org/wiki/Bridge_API
+
+
+examples
+--------
+
+Send a message using a single shell arguments for all Python arguments. We
+use first the method name (``messageSend``), then the required arguments (see `Bridge
+API documentation`_ for details), without the profile as it is automatically set. We
+specify them as Python in one shell argument, so we use single quote (``\```)first for
+s hell string, and inside it we use double quote (``"``) for Python strings::
+
+  $ jp debug bridge method messageSend '"louise@example.org", {"": "test message"}, {}, "auto", {}'
+
+.. note::
+
+  This is for debugging only, if you want to send message with jp, use :ref:`jp-message_send`.
+
+Get version string of SàT::
+
+  $ jp debug bridge method getVersion
+
+
+bridge signal
+=============
+
+Send a fake signal. This is specially useful to test behaviour of a frontend when a
+specific event happens. To use is you just need to specify the name of the signal and the
+arguments to use (using Python eval in the same way as for jp-debug_bridge_method_).
+
+example
+-------
+
+Send a note with ``info`` level and hand written XMLUI. Here me use a shell variable to
+store the level, so we can easily change it if we want to use an other level for tests.
+Note the use of quotes (to escape both for shell and Python)::
+
+  $ LEVEL='info'; jp debug bridge signal -c actionNew '{"xmlui": '"'"'<?xml version="1.0" ?><sat_xmlui title="test title" type="dialog"><dialog level="'$LEVEL'" type="note"><message>test message\non\nseveral\nlines</message></dialog></sat_xmlui>'"'"'}' '""' -1
+
+
+monitor
+=======
+
+Show raw XML stream. By default, output is pretty formatted/highlighted and you get all
+streams in both direction. You can filter the direction using ``-d {in,out,both},
+--direction {in,out,both}``.
+
+For this to work, you need to set the option ``Activate XML log`` in the ``Debug`` section
+of your parameters.
+
+Verbosity is used, to print details on the direction of a stanza, use ``--verbose, -v``
+
+example
+-------
+
+Monitor raw XML stream::
+
+  $ jp debug monitor -v
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/jp/encryption.rst	Tue Oct 01 22:49:06 2019 +0200
@@ -0,0 +1,126 @@
+========================================
+encryption: encryption sessions handling
+========================================
+
+Salut à Toi being an XMPP client does encryption by default between client and server. In
+addition, SàT is also capable of doing end-to-end (e2e) encryption, meaning that the
+payload of messages are encrypted to be hidden from the servers (and their
+administrators).  The ``encryption`` commands are here to handle those e2e encryption
+sessions and algorithms.
+
+.. note::
+
+   For the moment, only one 2 one chat messages can be e2e encrypted
+
+algorithms
+==========
+
+Display e2e encryption algorithms available in this instance of Salut à Toi.
+
+example
+-------
+
+Show available e2e algorithms::
+
+  $ jp encryption algorithms
+
+get
+===
+
+Display which encryption session is currently active with the given entity.
+
+The only required argument is the JID of the entity.
+
+If not e2e encryption session exist, a message will be displayed and jp will exit with a
+non zero code: this means that the messages are in clear in the XMPP servers, but normal
+XMPP encryption is not affected (message should still be encrypted between client and
+server and between servers).
+
+If an e2e encryption session exist, you'll see the algorithm name and its namespace. In
+case of e2e encryption which only works from device to device (e.g. it's the case with
+``OTR`` which doesn't support multiple devices), you'll also see the resources of the
+devices where the encryption is active in ``directed_devices``
+
+example
+-------
+
+Check if session is encrypted with Louise::
+
+  $ jp encryption get louise@example.org
+
+start
+=====
+
+Start e2e session with an entity.
+
+You need to specify the JID of the entity you want to start a session with as a positional
+argument.
+
+By default, SàT will select itself the algorithm to use among those available, but you can
+specify one using either its name with ``-n NAME, --name NAME`` or its namespace using
+``-N NAMESPACE, --namespace``. ``NAME`` is the short name of the algorithm, e.g. ``omemo``
+while the namespace is the longer (e.g. ``urn:xmpp:otr:0``).
+
+If an encryption session is started but one with an other algorithm was already there, the
+original session will be stopped and replaced by one with the new requested algorithm. You
+can change this behaviour by using ``--encrypt-noreplace``: in this case the command will
+fail in case of conflict (e2e encryption is requested with a new algorithm while an e2e
+encryption session was already started with an other algorithm), and return a non-zero
+code. If an e2e encryption session was already started with the requested algorithm, the
+command will succeed in all cases an nothing will be changed.
+
+examples
+--------
+
+Start e2e encryption with Pierre, using the algorithm selected by SàT::
+
+  $ jp encryption start louise@example.net
+
+Start an OMEMO session with Louise::
+
+  $ jp encryption start -n omemo louise@example.org
+
+stop
+====
+
+Terminate an e2e session with given entity. The entity must be specified as positional
+argument.
+
+After this command is run, the messages with specified entity will not be e2e encrypted
+anymore (but this won't affect encryption between SàT and XMPP server and between XMPP
+servers).
+
+example
+-------
+
+Stop the e2e encryption session with Pierre::
+
+  $ jp encryption stop pierre@example.net
+
+trust ui
+========
+
+Run the user interface to handle trust with given entity and given algorithm. The user
+interface depends of the algorithm used, but it generally shows you the fingerprints
+associated with your contact or contact devices, and asks you if you trust them or not.
+
+The only mandatory argument is the jid of your contact.
+
+By default the currently active encryption session algorithm is used, but you may manage
+trust for an other algorithm by using ``-n NAME, --name NAME`` or ``-N NAMESPACE,
+--namespace NAMESPACE``.
+
+.. note::
+
+   Trusting a contact or a device means that you certify that this contact or device is
+   the one you want to talk too. You should not trust a device if you have not verified by
+   an external channel (i.e. not XMPP) the fingerprint. The best way is to verify the
+   fingerprint physically if possible (i.e. in front of your contact, not with computer
+   networks in the middle).
+
+example
+-------
+
+Manage ``OMEMO`` trust with Louise devices::
+
+  $ jp encryption trust ui -n omemo louise@example.org
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/jp/event.rst	Tue Oct 01 22:49:06 2019 +0200
@@ -0,0 +1,69 @@
+========================
+event: events management
+========================
+
+Event commands allows you to create/modify or get data about an event, and to manage your
+invitees.
+
+.. _jp-event_get:
+
+get
+===
+
+Get metadata about a specific event.
+
+example
+-------
+
+Retrieve an event metadata::
+
+  $ jp event get  -n org.salut-a-toi.event:0__BsyCsXpcrRh44CQhSVTUMi -i 'org.salut-a-toi.event:0'
+
+.. _jp-event_create:
+
+create
+======
+
+Create a new event. You can specify the date of the event with ``-d DATE, --date DATE``,
+and an id with ``-i ID, --id ID`` (default id is used if omitted).
+
+Configuration options are specified using ``-f KEY VALUE, --field KEY VALUE`` where key
+can be a custom data or one of:
+
+name
+  name of the event
+description
+  details of the event
+image
+  URL of the main picture of the event
+background-image
+  URL of image to use as background
+register
+  a boolean value, set to ``true`` if you want to register the event in your local list
+
+example
+-------
+
+Create an event about to celebrate New Year::
+
+  $ jp event create -d 2019-12-31 -f name "New Year's Eve" -f description "Party to celebrate new year" -f register true -f image https://example.net/some_image.jpg
+
+
+modify
+======
+
+This command in the same way as jp-event_create_ but modify an existing event. You need to
+specify the node of the event to modify using ``-n NODE, --node NODE``.
+
+example
+-------
+
+Add a background image to the New Year event created above::
+
+  $ jp event modify -n org.salut-a-toi.event:0__d8QQLJvbcpDXxK66UBXKfT -f background-image https://example.net/some_background_image.jpg
+
+
+invitee
+=======
+
+Subcommands to handle guests. Please check :ref:`jp-event_invitee`.
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/jp/event_invitee.rst	Tue Oct 01 22:49:06 2019 +0200
@@ -0,0 +1,94 @@
+.. _jp-event_invitee:
+
+========================================
+event/invitee: event invitees management
+========================================
+
+``invitee`` groups commands to invite somebody to an event, get or set data about an invitee, and list all invitees. You can send an invitation by e-mail to people without XMPP account.
+
+.. _jp-event_invitee_get:
+
+get
+===
+
+Retrieve the RSVP status of one guest. Note that you must the invitees node and not the
+event node. To retrieve invitees node, use :ref:`jp-event_get` with the event node.
+
+You may specify the guest bare jid using ``-j JID, --jid JID`` (by default your own bare
+jid will be used).
+
+If no response is known yet, no data is returned.
+
+example
+-------
+
+Get RSVP of Louise::
+
+  $ jp event invitee get -u "xmpp:pierre@example.net?;node=generic%2F876a2b99-1c90-41fa-b823-c4a467140770" -j louise@example.org
+
+
+.. _jp-event_invitee_set:
+
+set
+===
+
+Set your own RSVP data. Note that as for jp-event_invitee_get_ you must use
+invitees node and not the event node.
+
+Use ``-f KEY VALUE, --field KEY VALUE`` to specify the data to set. ``KEY`` can be one of
+``attend`` (where calue can be ``yes``, ``no``, or ``maybe``) and ``guests`` where value
+must be an integer.
+
+example
+-------
+
+Indicate that you'll come to an event with 3 guests::
+
+  $ jp event invitee set -u "xmpp:pierre@example.net?;node=generic%2F876a2b99-1c90-41fa-b823-c4a467140770" -f attend yes -f guests 3
+
+list
+====
+
+Get and format the RSVP of your invitees. Note that as for jp-event_invitee_get_ and
+jp-event_invitee_set_ you must use invitees node and not the event node.
+
+By default, only people who have answered are shown. You may use ``-m, --missing`` to show
+other people which were invited, but have not answered yet. When using this option, you
+can also use ``-R, --no-rsvp`` to only show people which have not answered yet.
+
+You'll also have a small summary indicating how many people who can expect at your event.
+
+example
+-------
+
+Get the full list of invitees (including those who didn't answered yet) with the RSVP formatted::
+
+  $ jp event invitee list -u "xmpp:pierre@example.net?;node=generic%2F876a2b99-1c90-41fa-b823-c4a467140770" -m
+
+invite
+------
+
+Invite somebody to an event. The invitation is done by e-mail, a guest account will be
+created. Contrary to other ``invitee`` commands, in this one you'll use the event node
+directly.
+
+This command is really similar to :ref:`jp-invitation_create`
+
+E-mail address is specified using ``-e EMAIL, --email EMAIL`` and you'll need to give an
+URL template (using ``-U URL_TEMPLATE, --url-template URL_TEMPLATE``)leading to your
+website page handling the invitation (for Libervia default invitation page is
+``<your_server>/g/<uuid>``). You can use ``{uuid}`` as a placeholder which will be
+replaced by event's id.
+
+You'll probably want to specify the name of the invitee, using ``-N NAME, --name NAME``
+and your own name (as the host inviting), using ``-H HOST_NAME, --host-name HOST_NAME``.
+The language spoken by your guest can be specified using ``-l LANG, --lang LANG``, it is
+mainly useful if you have many invitee speaking different languages.
+
+example
+-------
+
+Pierre is inviting Louise (whose e-mail address is ``louise_email@example.net``) to an
+event he's organising::
+
+  $ jp event invitee invite -e louise_email@example.et -N "Louise" -H "Pierre" -l fr -U "https://www.example.org/g/{uuid}" -u "xmpp:pierre@example.org?;node=generic%2F61400ea7-a2a2-4ce0-9b68-3735b602f671"
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/jp/file.rst	Tue Oct 01 22:49:06 2019 +0200
@@ -0,0 +1,147 @@
+========================================
+file: files sending/receiving/management
+========================================
+
+``file`` group all commands related to file management, and allows you to send easily a
+file to a contact or device from the command line.
+
+send
+====
+
+Send a file to a contact.
+
+The file will be sent using best available method (which is Jingle File Transfer when
+available), and will try to send the file in P2P when possible.  If P2P is possible, the
+signal is sent through the server (metadata, negotiation, etc.), while the file itself
+goes directly from the source device to the target device. When P2P is not possible, the
+file may go through the server or an other one (if a proxy is used for instance).
+
+When sending a file, you specify one or more file(s) to send, and the either the bare jid
+or the full jid of the target device. If bare jid is specified, the main resource will be
+used.
+
+You'll usually want to see the progression of the transfer, use ``-P, --progress`` for
+that.
+
+If you send several files at once, you may want to use ``-b, --bz2`` to group them in a
+single compressed ``tar.bz2`` archive (the client receiving the files will then receive a
+single file, than the user can then decompress).
+
+By default the name of the source file is used, but you use ``-n NAME, --name NAME`` to
+specify another one.
+
+The path and namespace (set with ``-d PATH, --path PATH`` and ``-N NAMESPACE, --namespace
+NAMESPACE``) are non-standard metadata used by SàT to organise files (``PATH`` being like
+a file path on locale file system, and ``NAMESPACE`` being a name to associate to a group
+of files, for instance for a photo album).
+
+examples
+--------
+
+Send a file to Louise, with a progress bar::
+
+  $ jp file send -P some_file.ext louise@example.org
+
+Send a picture to a file sharing component, putting it in the ``holidays`` namespace, in
+the ``/some/path`` path::
+
+  $ jp file send -P -N holidays -d /some/path some_photo.jpg files.example.org
+
+.. _jp-file_request:
+
+request
+=======
+
+Ask to get a file from a device/sharing service. A file is requested using one or more
+metadata, which can be the file name (with ``-n NAME, --name NAME``), its hash (with ``-H
+HASH, --hash HASH`` and the algorithm may be specified with ``-a HASH_ALGO, --hash-algo
+HASH_ALGO``), its path (with ``-d PATH, --path PATH``) and its namespace (with ``-N
+NAMESPACE, --namespace NAMESPACE``). Note that ``PATH`` and ``NAMESPACE`` are SàT specific
+and not (yet?) XMPP standards.
+
+If you already know the hash, it's the most efficient and recommended way to retrieve a
+file.
+
+You need to specify the full jid of the device or the sharing service as a positional
+argument.
+
+By default the file is downloaded in current directory, but you can specify an other one
+(and an other filename) with ``-D DEST, --dest DEST``.
+
+If you want to see progression of the transfer, use ``-P, --progress``.
+
+examples
+--------
+
+Request a file names ``some_file.jpg`` in path ``/photos/demo_album`` at service
+``files.example.org``, with a progress bar::
+
+  $ jp file request -P -d photos/demo_album -n some_file.jpg files.example.org
+
+Request file with given ``sha-256`` hash (which is default hash algorithm, so we don't
+specify it), and save it to file ``dest_file.txt``::
+
+  $ jp file request -H f2ca1bb6c7e907d06dafe4687e579fce76b37e4e93b7605022da52e6ccc26fd2 -D dest_file.txt files.example.org
+
+receive
+=======
+
+Wait for a file (or several ones) to be received, and accept it if it match criteria.
+
+You should specify which jid you are expecting a file from, using the positional
+arguments. If you don't, all files will be accepted, which can be dangerous if some
+malicious user send you a file at this moment.
+
+To see progression (this is recommended), you can use the ``-P, --progress`` options.
+
+By default, if a file with the same name as the proposed one exists, the transfer will be
+denied. You can override this behaviour with ``-f, --force``, but be sure to absolutely
+trust the sender in this case, as the name is chosen by her, and could be malicious, or it
+could override an important file.
+
+If you expect several files, you can use the ``-m, --multiple``, in this case the command
+won't stop after the file received file, and you'll have to manually stop it with
+``Ctrl-C`` or by sending a ``SIGTERM``.
+
+File(s) will be written in the current directory, but you may specify an other destination
+with ``--path DIR``.
+
+examples
+--------
+
+Accept and receive the next file, save it to local directory and show a progress bar::
+
+  $ jp file receive --progress
+
+Several files are expected from Louise, accept them and store them do
+``~/Downloads/Louise``::
+
+  $ jp file receive --multiple --path ~/Downloads/Louise louise@example.org
+
+
+upload
+======
+
+Upload a file to your XMPP server (or an other entity if specified). The upload will be
+done using `XEP-0363 (HTTP File Upload)`_, and the public URL to retrieve the file will be
+printed. Note that anybody knowing this URL can download the file you've uploaded.
+
+The path to the file to upload is expected as first argument, then optionally the entity
+of the service to upload too (by default, this is autodetected if your server offers this
+feature).
+
+As usual, you can use ``-P, --progress`` to see a progress bar.
+
+.. _XEP-0363 (HTTP File Upload): XEP-0363: HTTP File Upload
+
+example
+-------
+
+Upload a document to a server::
+
+  $ jp file upload -P ~/Documents/something_interesting.odt
+
+share
+=====
+
+Subcommands for advanced file sharing. Please check :ref:`jp-file_share`.
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/jp/file_share.rst	Tue Oct 01 22:49:06 2019 +0200
@@ -0,0 +1,98 @@
+.. _jp-file_share:
+
+==================================
+file/share: advances files sharing
+==================================
+
+``share`` groups commands for listing file available on a device/service, sharing a file
+or directory, and inviting people to retrieve files.
+
+.. _jp-file_share_list:
+
+list
+====
+
+List files available on a device or sharing service. You mainly have to specify the jid of
+the device/service where the files are stored (if jid is omitted, your own jid will be
+used, so you can check what you are sharing).
+
+.. note::
+
+   you have to use the full jid of the device if you want to list files available on a
+   device.
+
+You may specify a path using ``-d PATH, --path PATH``.
+
+File and directories are printed with a different colour if you use default output.
+
+examples
+--------
+
+List files shared from a device (note that we use a full jid here)::
+
+  $ jp file share list louise@example.org/some_resource
+
+List files available on a sharing service at the path ``/photos``::
+
+  $ jp file share list -d photos files.example.org
+
+Louise wants to list the file shared by Pierre::
+
+  $ jp file share list pierre@files.example.org
+
+path
+====
+
+Share a local file or directory with a list of entities, or publicly. The files can then
+be listed or requested using jp-file_share_list_ or :ref:`jp-file_request`.
+
+You specify the file or directory the positional ``path`` argument. By default the name of
+the file/directory is used, but you can give a different one using ``-n NAME, --name
+NAME``.
+
+You can specify entities allowed to see your files using ``-j JID, --jid JID`` as many
+time as necessary. If you don't specify any entity, the file will only be accessible by
+your own devices. If you want to make your file accessible to everybody, use ``--public``
+(note that this means that your file is accessible to the world, i.e. also to people you
+don't know, so use this option carefully).
+
+examples
+--------
+
+Share the file ``interesting_doc.odt`` with Pierre and Louise::
+
+  $ jp file share path -j pierre@example.net -j louise@example.org interesting_doc.odt
+
+Imagine that you have built a weather station and want to make its data public. You can
+share the directory ``~/weather_station_data`` with the world, using the name ``public
+weather data``::
+
+  $ jp file share path --public --name "public weather data" ~/weather_station_data
+
+invite
+======
+
+This command send an invitation for a file sharing repository to an XMPP entity.
+
+The invitation is a non standard (yet?) way to notify somebody of the existence of a files
+repository.
+
+Beside the positional arguments ``service`` and ``jid``, which are respectively the
+service where is the files repository and the jid of the entity to invite, you mainly have
+to indicate the path and namespace of your repository, using ``-P PATH, --path PATH`` and
+``N NAMESPACE, --namespace NAMESPACE``.
+
+Use the ``-t {files,photos}, --type {files,photos}`` to specify if you repository is a
+generic files repository or a photo album.
+
+Optionally, you can associate a thumbnail to the repository ``with -T THUMBNAIL,
+--thumbnail THUMBNAIL``. This is recommended to have more user friendly representation of
+the album in e.g. Libervia.
+
+example
+-------
+
+Pierre wants to invite Louise to view his ``summer holidays`` photo album::
+
+  $ jp file share invite -P "photos/summer holidays" -t photos pierre@files.example.net
+  louise@example.org
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/jp/forums.rst	Tue Oct 01 22:49:06 2019 +0200
@@ -0,0 +1,102 @@
+==============================
+forums: forums topics handling
+==============================
+
+Forums are internally a way to organise blog nodes open to many publishers. The ``forums``
+commands let you manage the structure of topics. You may have several different structures
+in one PubSub forums node, this can be useful if you have multi-lingual forums.
+
+.. _jp-forums_get:
+
+get
+===
+
+Get and print the structure of forums. Beside the classic PubSub node arguments, you may
+specify the ``KEY`` of the forum with ``-k KEY, --key KEY``. This can be used to have
+several structures of forums, for instance one per language.
+
+If you use the default output, the verbosity is used to retrieve details of topics.
+
+examples
+--------
+
+Get structure of default forum with details::
+
+  $ jp forums get -v
+
+Get structure of French forums in JSON::
+
+  $ jp forums get -k fr -O json
+
+
+edit
+====
+
+Edit the structure of XMPP forums. As for jp-forums_get_ you may specify the key beside
+the classic PubSub node arguments. The edition works the same as for :ref:`jp-blog_edit`.
+
+To edit the structure you'll get a JSON file which is a list of object where the topic
+metadata are set. You can use the following metadata:
+
+``main-language``
+  a language code, using `ISO 639`_
+``name``
+  short name of the forum
+``title``
+  title of the topic/category in the given language
+``short-desc``
+  small description of the topic/category
+``desc``
+  long description of the topic/category
+``uri``
+  URI to the PubSub node containing the messages of the topic (it's actually a blog node
+  with suitable permissions). URI must only be set for topic, not for categories.
+``sub-forums``
+  list of object with the same metadata (i.e. other topics or categories)
+
+Here is a small example of a forum structure:
+
+.. sourcecode:: json
+
+   [
+       {
+           "main-language": "en",
+           "name": "short-name",
+           "title": "This is a category",
+           "short-desc": "short description about the category",
+           "desc": "this is a an example of a long description"
+           "sub-forums": [
+               {
+                   "uri": "xmpp:pubsub.example.org?;node=org.salut-a-toi.forums%3A0_L5SaR5WYafXmUyD46R2avf",
+                   "title": "some intereting topic",
+                   "short-desc": "This is a description explaining what the topic is about"
+               },
+               {
+                   "uri": "xmpp:pubsub.example.org?;node=org.salut-a-toi.forums%3A0_L5SaR5WYafXmUyD46R2avf",
+                   "title": "a second topic",
+                   "short-desc": "This topic is about bla bla bla"
+               },
+           ],
+       },
+       {
+           "main-language": "en",
+           "title": "An other category",
+           "sub-forums": [
+               {
+                   "uri": "xmpp:pubsub.example.org?;node=org.salut-a-toi.forums%3A0_L5SaR5WYafXmUyD46R2avf",
+                   "title": "yet another topic",
+                   "short-desc": "This is a demo topic, made for an example"
+               },
+           ]
+       }
+   ]
+
+
+.. _ISO 639: https://www.iso.org/iso-639-language-codes.html
+
+example
+-------
+
+Edit structure of forums on a PubSub service::
+
+  $ jp forums edit -s pubsub.example.org
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/jp/identity.rst	Tue Oct 01 22:49:06 2019 +0200
@@ -0,0 +1,34 @@
+=============================
+identity: identity management
+=============================
+
+Identity use several XMPP extensions (like vcards) to retrieve or set informations about
+an entity. For now it's really basic and only nickname and avatar are managed.
+
+get
+===
+
+Retrieve informations about the identity behind an XMPP entity. You only have to specify
+the jid of the entity, and you'll get (if set) his/her/its nickname and a link to the
+cached avatar.
+
+example
+--------
+
+Get identity information about an entity::
+
+  $ jp identity get somebody@example.org
+
+set
+===
+
+Set identity data to the server, using various XMPP extensions. You set the data to change
+using ``-f KEY VALUE, --field KEY VALUE``, where ``KEY`` can only be ``nick`` at the
+moment.
+
+example
+-------
+
+Set the nickname of default profile::
+
+  $ jp identity set -f nick toto
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/jp/info.rst	Tue Oct 01 22:49:06 2019 +0200
@@ -0,0 +1,58 @@
+
+==================================
+info: retrieve various information
+==================================
+
+``info`` groups subcommands used to retrieve read-only informations.
+
+disco
+=====
+
+Display discovery information (see `XEP-0030`_ for details). This can be used to check
+which features you server or a service is offering, and which items are available (items
+can be services like chat room, gateways, etc).
+
+You only have to specify the jid of the entity to check, and optionally a node.
+
+By default both infos and items are requested, but you can restrict what to request by
+using ``-t {infos,items,both}, --type {infos,items,both}``
+
+.. _XEP-0030: https://xmpp.org/extensions/xep-0030.html
+
+
+example
+-------
+
+Request infos and items from a server::
+
+  $ jp info disco example.org
+
+version
+=======
+
+Request software version of an entity. You only need to specify the jid of the entity as
+positional argument.
+
+Depending of the software and its configuration, you have software version, software name,
+and the operating system on which the software is running.
+
+example
+-------
+
+Check version of a server::
+
+  $ jp info version example.org
+
+session
+-------
+
+Give information about the session of the given profile. You'll the full jid currently
+used on the server, and the time when the session was started (which may not be the same
+time as when the connection with the XMPP server was started).
+
+example
+-------
+
+Get session informations::
+
+  $ jp info session
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/jp/input.rst	Tue Oct 01 22:49:06 2019 +0200
@@ -0,0 +1,119 @@
+================================================
+input: automatise commands using external inputs
+================================================
+
+``input`` is a way to use external data (like file in a specific format) as input
+arguments. It may be seen as a something similar to ``--output`` but for inputs.
+
+
+csv
+===
+
+CSV (for Comma-Separated Values) is a common format for tabular data. It is widely used in
+spreadsheet software (at least at en export format). With ``csv`` command, you can use
+columns a CSV file as arguments to jp commands.
+
+To set the command, you'll write in sequence what to do with each column of your data.
+For each column you can:
+
+- specify a short option name using ``-s ARGUMENTS, --short ARGUMENTS`` (short options are
+  the ones with a single ``-``)
+- specify a long option name using ``-l ARGUMENTS, --long ARGUMENTS`` (long options are
+  the ones with two ``-``)
+- specify a positional argument using ``-p ARGUMENTS, --positional ARGUMENTS``
+- indicate to use the column data with ``stdin`` using ``-i, --stdin``
+- ignore the column if it's not used in the jp command, using ``-x, --ignore``
+
+After each column specification, you may use a filter to manage the value. So far the
+following filters are available:
+
+``-S, --split``
+  This will split the value (on any whitespace character, discarding empty values) and
+  repeat the option which each item. This is useful when you are using an option which can
+  be repeated (like ``-t TAG, --tag TAG`` with ``jp blog set``).
+
+``-E ARGUMENTS, --empty ARGUMENTS``
+  Indicate what to do if the column value is empty (by default en empty string is used).
+  You can use either ``skip`` to skip the whole row, or ``ignore`` so the option will not
+  be set at all (which is different from the default which will still set the option but
+  with an empty string).
+
+CSV file is read from stdin, and by default unicode is expected. You may force an encoding
+by using ``--encoding ENCODING``.
+
+By default all the rows are read, but you may want to ignore first rows (if they are used
+for columns title, or if you have already handled part of the list). To do that, use the
+``-r ROW, --row ROW`` option.
+
+When you test your command, it is better to do a dry run to see what will happen. The
+``-D, --debug`` option is here for that: if you set it, the commands won't be actually
+run, but the exact command which would be executed will be printed on screen. You should
+always use this option first until you're sure that what you want will be executed.
+
+You may add verbosity level to help debugging. With a verbosity level of 2 (i.e. ``-vv``)
+the value read from CSV will be printed.
+
+By default stdout and stderr of each launched command is ignored, but you can log them to
+files using respectively ``--log LOG`` and ``--log-err LOG_ERR`` where ``LOG`` and
+``LOG_ERR`` are paths to a log file to create.
+
+Once all the sequence and options are set, you write the jp command that you want to use,
+with all the needed static option (i.e. options which must be used each time).
+
+
+example
+-------
+
+Louise as a spreadsheet with a table like this:
+
+============================  ============  =============  ===============
+title                         body          internal data  tags
+============================  ============  =============  ===============
+Some title                    a body        ABC            jp demo
+Something else                another body  XYZ            jp demo
+Third one                     third body    VWZ            special_tag jp
+This one doesn't have a body                123            jp demo numbers
+last one                      last body     456            jp demo numbers
+============================  ============  =============  ===============
+
+She wants to use it as input data to create blog posts.
+
+She first saves the file using CSV format, let's say to ``~/blog_input.csv``.
+
+Then she checks ``jp blog set --help`` to get name of options to use. She'll need to use
+``--title`` for title, ``stdin`` for the body and ``-t`` for tags. Louise wants to
+activate comments, so she also wants to use ``-C`` for all posts, and a tag to says it's
+coming from the spreadsheet (using ``-t spreadsheet``) .
+
+The first row of the table is used for columns headers, so she'll start at row 1 with ``-r
+1``.
+
+There is one row without body, Louise want to skip any row without body so she'll use the
+``-E skip`` filter, just after specifying the body row.
+
+Reading column by column, the sequence is like this:
+
+``-l title``
+  a title which goes to the ``--title`` long option of ``jp blog``
+``-i -E skip``
+  a body which goes to the stdin of ``jp blog``. If the body is empty, the ``-E skip``
+  filter tells to skip the whole row.
+``-x``
+  the ``internal data`` column is not used, so it is ignored
+``-s t -S``
+  the last column are the tags, so the ``-t`` short option is used. There are several of
+  them separated by spaces, so the ``-S`` filter is used to split the values.
+
+First she'll use the ``-D, --debug`` to check that the commands which will be executed are
+the expected one::
+
+  $ jp input csv -D -r 1 -l title -i -E skip -x -s t -S blog set -C -t spreadsheet < ~/blog_input.csv
+
+Everything seems fine, so she'll actually launch the command by running the same command
+line but without the ``-D`` option::
+
+  $ jp input csv -r 1 -l title -i -E skip -x -s t -S blog set -C -t spreadsheet < ~/blog_input.csv
+
+She could also have used ``--log`` and ``--log-err`` to check the logs of each command::
+
+  $ jp input csv -r 1 -l title -i -E skip -x -s t -S --log /tmp/jp_blog_stdout.log --log-err /tmp/jp_blog_stderr.log blog set -C -t spreadsheet < ~/blog_input.csv
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/jp/invitation.rst	Tue Oct 01 22:49:06 2019 +0200
@@ -0,0 +1,96 @@
+==============================================
+invitation: invite people without XMPP account
+==============================================
+
+Invitations allows you to invite people without XMPP account, so they can participate e.g.
+to a discussion by using a specially generated link. This is a Salut à Toi specific
+feature and those commands are rather low lever.
+
+.. _jp-invitation_create:
+
+create
+======
+
+Invite somebody to participate. This will create a guest account and a link with an
+identifier to access this account, and send an invitation to the given email.
+
+The email is specified using ``-e EMAIL, --email EMAIL``, which can be used multiple times
+to send the invitation to more than one address.
+
+You'll usually want to specify the name of the person you're inviting, using ``-n NAME,
+--name NAME``, it may later be used in email sent or in the web page where your guest will
+land.
+
+``-N HOST_NAME, --host-name HOST_NAME`` is used to specify the name of yourself (i.e. the
+person which is inviting), it may be used in invitation message.
+
+You'll most of time have to specify the URL template using ``-u URL, --url URL``. This
+will be used in the invitation email to construct the URL where your invitee will click.
+You may use the string ``{{uuid}}`` in this template which will be replaced by the id
+associated to the invitation. With Libervia, default invitation page is
+``<your_server>/g/<uuid>``.
+
+The language of your guest can be specified using ``-l LANG, --lang LANG``, this is
+notably useful if you have multilingual blog posts (e.g. for an event where people
+speaking different languages are invited).
+
+The ``-x KEY VALUE, --extra KEY VALUE`` is used for extra data which depend on what you
+are inviting your guests for.
+
+
+example
+-------
+
+Invite Louise, which is speaking French, to an event. The invitation is sent to her email
+address ``louise_email@example.net``, is sent by Piotr, and must link to the Libervia
+instance at ``https://www.example.org/g/<id>``. We use here the ``event_uri`` extra key::
+
+  $ jp invitation create -n Louise -N Pierre -e louise_email@example.net -l fr -u "https://www.example.org/g/{uuid}" -x event_uri xmpp:pierre@example.org?;node=MnXe4ic2X8RUz6JAJuw4f9;item=org.salut-a-toi.event%3A0
+
+
+get
+===
+
+Get metadata for one specific invitation. You only have to specify the invitation id, and
+you may use the option ``-j, --with-jid`` to also get the jid used for the invitation
+(this will start the session of the invitee).
+
+example
+-------
+
+Get invitation data for invitation with id ``okFec4gDz75My7iQAVTmsc``::
+
+  $ jp invitation get okFec4gDz75My7iQAVTmsc -j
+
+
+modify
+======
+
+This work the same way as  jp-invitation_create_, you only have to specify the ``id`` of the
+invitation.
+
+If you use the ``--replace`` argument, all the invitation data will be replaced by the
+ones you're specifying.
+
+example
+-------
+
+Change the language of the invitee for the invitation ``okFec4gDz75My7iQAVTmsc`` for
+Slovak::
+
+  $ jp invitation modify -l sk okFec4gDz75My7iQAVTmsc
+
+
+list
+====
+
+List registered invitations. You may filter by the profile who made the invitation using
+``-p PROFILE, --profile PROFILE``.
+The invitations are shown by default using id as main data, and metadata below.
+
+example
+-------
+
+List invitations::
+
+  $ jp invitation list
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/jp/merge-request.rst	Tue Oct 01 22:49:06 2019 +0200
@@ -0,0 +1,81 @@
+===============================================
+merge-request: create and manage merge requests
+===============================================
+
+Merge-request are used to propose some modifications to a project. They are generic and
+are made to be used with several backends, but only Mercurial is implemented so far.
+
+To prepare a merge request with Mercurial, you just need to have a clone of the project,
+and do your modifications (either directly, or in a bookmark, a branch, or a MQ patch).
+
+set
+===
+
+Create and publish a merge request. Once the modification on the project are done, simply
+run the command from the repository (or specify its path with ``-r PATH, --repository
+PATH``). If the project has set metadata (it can be done with a magic string in README),
+you don't have to specify any service or node, it will be set automatically (but you still
+can specify them if needed).
+
+You may associate one or more labels to your request using ``-l LABELS, --label LABELS``.
+
+By default, a confirmation is requested before publishing the request, you can publish
+without confirmation by using the ``-f, --force`` flag.
+
+If you have already done a merge request and you just want to update it, check its id and
+specify it with ``-i ITEM, --item ITEM``, this will override the previous request with the
+new updated one.
+
+examples
+--------
+
+Publish a merge request (to be executed from the repository of the project you have
+modified)::
+
+  $ jp merge-request set
+
+Update an existing merge request, which has the id ``123`` (to be executed from the
+reposiroty of the project you have modified)::
+
+  $ jp merge-request set -i 123
+
+Do a merge request for repository at path ``~/some_project``, specifying a label
+indicating it's work in progress (WIP)::
+
+  $ jp merge-request set -r ~/some_project --label WIP
+
+
+get
+===
+
+Get and print one or more merge requests. By default only some metadata are shown (without
+the patches), but you can use ``--verbose, -v`` to show details.
+
+examples
+--------
+
+Show some metadata of last 5 merge requests::
+
+  $ jp merge-request get -M 5
+
+Display details for merge request with id 456::
+
+  $ jp merge-request get -v -i 456
+
+
+import
+======
+
+Import a merge request into your project. You mainly have to be in the project repository
+(or specify it using ``-r PATH, --repository PATH``) and to specify the id of the patch to
+import (using ``-i ITEM, --item ITEM``). The behaviour depends of the type of the patch,
+for Mercurial, the patch will be imported as `MQ`_ patch.
+
+.. _MQ: https://www.mercurial-scm.org/wiki/MqExtension
+
+example
+-------
+
+Import the merge request with id 321::
+
+  $ jp merge-request import -i 321
--- a/doc/jp/message.rst	Wed Sep 25 08:56:41 2019 +0200
+++ b/doc/jp/message.rst	Tue Oct 01 22:49:06 2019 +0200
@@ -6,10 +6,12 @@
 
 Message commands let you send chat messages or manage your server message archives.
 
+.. _jp-message_send:
+
 send
 ====
 
-send a message to a contact or a chat room.
+Send a message to a contact or a chat room.
 ``stdin`` is used as message source.
 You can encrypt your message using ``--encrypt [ALGORITHM]`` argument, this will create an encrypted session and replace existing one if needed.
 You can manage your encrypted session using ``encryption`` command.
@@ -36,7 +38,7 @@
 mam
 ===
 
-query archives using 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.
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/jp/param.rst	Tue Oct 01 22:49:06 2019 +0200
@@ -0,0 +1,124 @@
+============================
+param: manage SàT parameters
+============================
+
+``param`` commands allows to retrieve or set parameters as well as to export/import them
+to a XML file.
+
+Parameters are retrieve using a ``category`` and a ``name``, they are both case sensitive.
+
+``category`` is the name of the tabs that you see when you set parameters in a frontend
+like Cagou or Libervia.
+
+.. note::
+
+   You need to have your session started to retrieve of modify parameters. If you can't
+   or are not willing to connect for any reason (e.g. no internet connection), you can
+   use the ``--start-session`` option to start the profile session without connecting it
+   to the XMPP server.
+
+get
+===
+
+Retrieve list of categories, parameters or a specific parameter value:
+
+- without argument, you'll get the list of categories
+- with only a category specified, you'll get a list of parameters and their values
+- with a category and a name, you'll get the value or requested attribute of the specified
+  parameters
+
+By default you'll get the value of the parameters, but you can request an other attribute
+(for instance its ``type`` or ``constraint``) using the ``-a ATTRIBUTE, --attribute
+ATTRIBUTE`` argument.
+
+You can set a security limit to retrieve only parameters allowed with this limit.
+Security limit is an integer used in some frontends (like Libervia), to restrict
+parameters modifiable by non privileged users. You can set it using ``--security-limit
+SECURITY_LIMIT``, by default it is disabled (i.e. all parameters are returned).
+
+examples
+--------
+
+Get list of categories::
+
+  $ jp param get
+
+Get list of parameters in ``General`` category::
+
+  $ jp param get General
+
+Get JID set for default profile. It is set in ``Connection`` category, with the parameters
+named ``JabberID`` (be careful with the case)::
+
+  $ jp param get Connection JabberID
+
+Get the type of the ``check_certificate`` parameters in ``Connection`` category::
+
+  $ jp param get Connection check_certificate -a type
+
+Get the constraint of the ``Priority`` parameters in ``Connection`` category::
+
+  $ jp param get Connection Priority -a constraint
+
+set
+===
+
+As expected, this command set a SàT parameter. The ``category``, ``name`` and ``value``
+are needed as positional arguments.
+
+``--security-limit SECURITY_LIMIT`` can be used if you want an update to be rejected if
+the parameter is not modifiable with this limit. This can be useful if you use ``jp`` from
+an external tool and you want to limit damage risks, or for testing purpose.
+
+examples
+--------
+
+Use Markdown_ syntax for composition (e.g. for editing blog posts)::
+
+  $ jp param set Composition Syntax markdown
+
+Try to change jid of the profile with a low security limit, this command should fail::
+
+  $ jp param set --security-limit 0 Connection JabberID some_random_jid@example.org
+
+.. _Markdown: https://daringfireball.net/projects/markdown/
+
+.. _jp-param_save:
+
+save
+====
+
+Save the parameters structure to an external files. The parameters are saved as XML. The only
+expected argument is the path to the destination file.
+
+.. note::
+
+   it's the parameters structure and not the parameters values which are saved. This is
+   low level method and most end users won't probably need it
+
+example
+-------
+
+Save parameters structure to ``~/parameters.xml``::
+
+  $ jp param save ~/parameters.xml
+
+.. _jp-param_load:
+
+load
+====
+
+Load and merge the parameters structure from external XML files. The only expected
+argument is the path to the source file.
+
+.. note::
+
+   it's the parameters structure and not the parameters values which is loaded and merged.
+   This is low level method and most end users won't probably need it
+
+example
+-------
+
+Load and merge parameters structure from ``~/parameters.xml``::
+
+  $ jp param load ~/parameters.xml
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/jp/ping.rst	Tue Oct 01 22:49:06 2019 +0200
@@ -0,0 +1,20 @@
+=========================================
+ping: get response time of an XMPP entity
+=========================================
+
+``ping`` is more or less the equivalent of the command of the same name on most OSes, but
+for XMPP. It send a `XEP-0199`_ PING and wait for the answer. When (and if) received, the
+time to receive the answer is shown, else the time to receive the error message is shown.
+This can be helpful to quickly test the connection with the server or a device.
+
+If you need to get only the response time (without text around), you may use ``-d,
+--delay-only``.
+
+.. _XEP-0199: https://xmpp.org/extensions/xep-0199.html
+
+example
+-------
+
+Get reponse time of a server::
+
+  $ jp ping example.org
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/jp/pipe.rst	Tue Oct 01 22:49:06 2019 +0200
@@ -0,0 +1,43 @@
+==================================================
+pipe: send/receive data stream through shell pipes
+==================================================
+
+``pipe`` commands allow you to send or receive data stream through a Unix shell pipe.
+Salut à Toi will create a network connection (using XMPP and Jingle) between you an your
+contact.
+
+in
+==
+
+Receive data stream. Data will be send to stdout, so it can be piped out or simply print
+to the screen. You can specify bare jids of entities to accept stream for, by default all
+streams are accepted.
+
+example
+-------
+
+Receive a video stream, and redirect it to mpv_ so show the video::
+
+  $ jp pipe in | mpv -
+
+.. _mpv: https://mpv.io/
+
+out
+===
+
+Send data stream. Data comes from stdin, so you may use pipe in something or just write
+some text.
+
+The only expected argument is the full jid of the device where the stream must be piped
+out.
+
+example
+-------
+
+Send a video to louise::
+
+ $ jp pipe out louise@example.org/sat < some_video.webm
+
+Send output from ``cal`` command to louise::
+
+ $ cal | jp pipe out louise@example.org/sat
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/jp/profile.rst	Tue Oct 01 22:49:06 2019 +0200
@@ -0,0 +1,191 @@
+=============================
+profile: SàT profile handling
+=============================
+
+Profiles are the names associated with accounts in SàT, for more informations you can
+check :ref:`glossary`. The `profile` commands help you create/delete/modify and manage
+profiles.
+
+
+connect
+=======
+
+Unsurprisingly this command connects your profile, i.e. log-in your XMPP account. This
+command uses :ref:`jp-common_profile` common commands, so you can use either ``-c,
+--connect`` to connect to XMPP server, or ``--start-session`` if you want to start SàT
+profile session without connecting to XMPP server (for instance if you want to modify
+parameters without connecting to XMPP server).
+
+Note that :ref:`jp-common_profile` common commands are available in commands needing a
+connected profile, ``jp profile connect`` is interesting if you only want to connect your
+profile/start a session.
+
+example
+-------
+
+Connect the default profile::
+
+  $ jp profile connect -c
+
+
+disconnect
+==========
+
+Disconnect your profile from XMPP server. There is no option beside the
+:ref:`jp-common_profile` common options.
+
+example
+-------
+
+Disconnect the profile ``pierre``::
+
+  $ jp profile disconnect -p pierre
+
+
+create
+======
+
+Create a new SàT profile. The only mandatory argument is the profile name, but you'll
+probably want to associate an XMPP jid with ``-j JID, --jid JID`` and a profile password
+with ``-p PASSWORD, --password PASSWORD``. By default, profile password will be used for
+XMPP password (see note below), but you may specify XMPP password with ``-x PASSWORD,
+--xmpp-password PASSWORD``.
+
+SàT is also capable to manage components, which can be seen as XMPP server independent
+plugins. To create a component profile, you'll have to use ``-C COMPONENT, --component
+COMPONENT`` where ``COMPONENT`` is the component entry point (check the documentation of
+the component that you want to use to get its entry point).
+
+.. note::
+
+   profile password and XMPP password are not the same: the profile password is the
+   password of your SàT profile, while the XMPP password is the one checked by your XMPP
+   server. If specify a jid with ``--jid`` and you don't specify an XMPP password, the
+   profile password will be used by default.
+
+   The reason to have distinct password is that you may use a different password for
+   profile, including an empty one if you want SàT to connect your profile without
+   having to enter a password. Also the XMPP password is encrypted in database using the
+   profile password (which is not stored in database, only a hash is kept).
+
+
+.. note::
+
+   passwords in jp are currently specified directly on the command-line and not prompted,
+   this is not safe from a security point of view as people can see it on the screen, it
+   may stay in your shell history, or visible on process list. Keep that in mind if you're
+   in a public environment or on a public machine. This will be improved for SàT 0.8.
+
+examples
+--------
+
+Nestor wants to create a profile for its account on ``example.org``, he specifies a
+profile password only, so it will also be used as the XMPP password::
+
+  $ jp profile create nestor -j nestor@example.org -p some_password
+
+Create a component profile for the file sharing component (whose entry point is
+``file_sharing``). The jid of the service is specified with ``--jid`` (note that we don't
+use a node as it is a jid of a component) and the ``--xmpp-password`` is the shared
+secret. Here the profile password is kept empty to not have to enter manually the XMPP
+password each time we connect the service::
+
+  $ jp profile create file_sharing -j files.example.org -p "" --xmpp-password
+  some_shared_secret -C file_sharing
+
+
+default
+=======
+
+This command simply prints the default profile (i.e. the profile used when none is
+specified with ``-p PROFILE, --profile PROFILE``). The default profile is either the first
+one that you've created, or the one you have explicitly set as default.
+
+example
+-------
+
+Print default profile::
+
+  $ jp profile default
+
+
+delete
+======
+
+Delete a profile and all its associated data. This delete the SàT profile and associated
+data (i.e. local data), but doesn't request the XMPP server to delete anything.
+
+By default a confirmation is requested, use ``-f, --force`` to avoid it (be cautious with
+this option).
+
+example
+-------
+
+Delete the profile of Pierre::
+
+  $ jp profile delete pierre
+
+
+info
+====
+
+Display information on a profile. For now, only the registered jid is shown, and
+optionally the XMPP password. To display the XMPP password, use ``--show-password`` but be
+careful that nobody can see your screen, as **this password will be shown in clear text**.
+
+example
+-------
+
+Show jid and XMPP password for default profile::
+
+  $ jp profile info --show-password
+
+
+list
+====
+
+Show all profiles. You can use ``-c, --clients`` to show only client profiles, and ``-C,
+--components`` to show only component profiles.
+
+example
+-------
+
+Show all profiles::
+
+  $ jp profile list
+
+
+modify
+======
+
+Update an existing profile. You can use this command to change profile password (with ``-w
+PASSWORD, --password PASSWORD``) or even disable it (with ``--disable-password``, this is
+equivalent to using an empty profile password ; be cautious with this option, see the note
+below).
+
+With ``-j JID, --jid JID`` and ``-x PASSWORD, --xmpp-password PASSWORD`` you can change
+XMPP jid and password.
+
+This command can also be used to select the default password, use the ``-D, --default``
+flag for that.
+
+.. note::
+
+   Be cautious with ``--disable-password`` that means that no password will be needed with
+   any frontend of SàT to use this profile, and that XMPP password will be easy to
+   retrieve for anybody having an access to the machine where SàT is installed
+
+examples
+--------
+
+Pierre has changed server, he can update his jid and password like this::
+
+  $ jp profile modify -p pierre -j pierre@example.org -x new_password
+
+Use ``louise`` as default profile::
+
+  $ jp profile modify -p louise -D
+
+Disable profile password for default profile (be cautious, see the note above)::
+
+  $ jp profile modify --disable-password
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/jp/pubsub.rst	Tue Oct 01 22:49:06 2019 +0200
@@ -0,0 +1,352 @@
+.. _jp-pubsub:
+
+=========================
+pubsub: PubSub management
+=========================
+
+PubSub commands are low level command to handle a PubSub Service.
+They are using the generic pubsub arguments
+
+For most of those commands, :ref:`pubsub_common` commands are used to specify the
+destination item.
+
+set
+===
+
+Publish a pubsub item.
+
+``stdin`` is used to get the raw XML of the payload of the item to publish.
+
+example
+-------
+
+Create an item with a custom note XML::
+
+  $ echo '<note xmlns="http://example.net/mynotes">this is a note</note>' | jp pubsub set -n "notes"
+
+get
+===
+
+Retrieve items from specified node. Default output is prettified and highlighted XML.
+
+example
+-------
+
+Retrieve the last 5 notes from our custom notes node::
+
+  $ jp pubsub get -n notes -m 5
+
+delete
+======
+
+Delete an item from a node. If ``-N, --notify`` is specified, subscribers will be notified
+of the item retraction.
+
+By default a confirmation is requested before deletion is requested to the PubSub service,
+but you can override this behaviour by using ``-f, --force`` option.
+
+example
+-------
+
+Delete item with id ``123456`` from a node::
+
+  $ jp pubsub delete -n test_node -i 123456
+
+edit
+====
+
+Edit the raw XML of an item payload using your local editor (the one set in ``$EDITOR``).
+
+If you don't change anything or publish an empty blog post, the edition will be cancelled.
+
+:ref:`draft_common` commands can be used.
+
+example
+-------
+
+Edit the last note in our custom node::
+
+  $ jp pubsub edit -n notes -L
+
+subscribe
+=========
+
+Subscribe to a node.
+
+Subscription is used to get notifications from the node in case of new/updated item or
+deletion.
+
+example
+-------
+
+Subscribe to an information blog::
+
+  $ jp pubsub subscribe -n informations -s pubsub.example.net
+
+unsubscribe
+===========
+
+Unsubscribe from a node.
+
+example
+-------
+
+Unsubscribe from an information blog::
+
+  $ jp pubsub unsubscribe -n informations -s pubsub.example.net
+
+subscriptions
+=============
+
+Retrieve subscriptions for all nodes on a service.
+
+``-n NODE, --node NODE`` can be used to request subscriptions for a specific node (e.g. if
+it has subscription with multiple subIDs).
+
+example
+-------
+
+Retrieve all subscriptions on a pubsub service::
+
+  $ jp pubsub subscriptions -s pubsub@example.net
+
+affiliations
+=============
+
+Retrieve affiliations for all nodes at a service.
+
+``-n NODE, --node NODE`` can be used to request affiliation for a specific node.
+
+examples
+--------
+
+Retrieve all affiliations at a pubsub service::
+
+  $ jp pubsub affiliations -s pubsub@example.net
+
+Retrieve affiliation for the ``notes`` node::
+
+  $ jp pubsub affiliations -s pubsub@example.net -n notes
+
+search
+======
+
+Search items corresponding to one or more filter(s).
+
+``search`` will check all items (or some of them according to options used) from one or
+several nodes (several nodes can be checked if recursion is used, see below). For each
+item the given filters will be checked, and all corresponding items will be returned.
+
+This is a resource intensive method (both for server and client), use with caution, and
+use MAM to do searching when suitable.
+
+filters
+-------
+
+To do a search you one or more filters. Filters are checked in the order in which they are
+specified. You can use 4 kinds of filters:
+
+``-t TEXT, --text TEXT``
+  do a full-text search. If *TEXT* is appearing anywhere in the item (including in XML
+  tags or arguments), the item is selected
+
+``-r EXPRESSION, --regex EXPRESSION``
+  do a regular expression search. `Python standard re module`_ is used internally, so you
+  can use its syntax.
+
+``-x XPATH, --xpath XPATH``
+  use an `XPath version 1.0`_ expression to filter the query. You can have a look at
+  `Wikipedia XPath page`_ for a user friendly introduction.
+
+``-P PYTHON_CODE, --python PYTHON_CODE``
+  use a Python expression to do a test. The expression must return a boolean (``True`` to
+  keep item, ``False`` otherwise). From within the Python expression 3 variables are
+  defined: ``item`` which contain the raw item as a string, and ``item_xml`` which is the
+  parsed XML as an lxml ``etree.Element`` and ``etree`` which is the ``lxml.etree`` module.
+
+.. _Python standard re module: https://docs.python.org/3.7/library/re.html
+.. _XPath version 1.0: https://www.w3.org/TR/1999/REC-xpath-19991116/
+.. _Wikipedia XPath page: https://en.wikipedia.org/wiki/XPath
+
+filter modifiers
+----------------
+
+Before each filter you can specify one or more filter modifiers. A modifier will change
+filter behaviour, it's a flag which can be used either without argument (then it will
+activate the flag), or with an explicit boolean value (i.e. ``true`` or ``false``).
+
+The available filters are:
+
+``-C [BOOLEAN], --ignore-case [BOOLEAN]``
+  (don't) ignore case. Filters are normally case sensitive, this modifier change this
+  behaviour.
+
+``-I [BOOLEAN], --invert [BOOLEAN]``
+  (don't) invert effect of following filters. This is applying a logical ``NOT`` to the
+  filter. This means that instead of keeping item matching the filter, it will keep the
+  items which are **not** matching the filter.
+
+``-A [BOOLEAN], --dot-all [BOOLEAN]``
+  (don't) use `DOTALL`_ option for regex. This filter only makes sense before a
+  ``--regex`` expression.
+
+``-k [BOOLEAN], --only-matching [BOOLEAN]``
+  (don't) keep only the matching part of the item. Normally the whole item is returned,
+  with this flag, only the part matching the filters are kept.
+
+.. _DOTALL: https://docs.python.org/3.7/library/re.html#re.DOTALL
+
+actions
+-------
+
+Once filters are set, you may indicate what do to with the found items. By default they
+are printed, but you can also use an other jp command, or even an external tool.
+
+The following actions are available:
+
+``print`` (default)
+  pretty print the found items.
+
+``exec``
+  use the given jp command on each found item. Everything after the ``exec`` is used to
+  indicate the command and arguments to use (you must not specify ``jp``, use the command
+  directly). The service, node and item will be set to match the found item.
+
+``external``
+  pipe the raw XML of each item to the given command. Everything after the ``external``
+  action is used to indicate the command and arguments to use.
+
+recursive search
+----------------
+
+By default, only items in the given node will be filtered, but if you specify a recursion
+depth > 0 (using ``-D MAX_DEPTH, --max-depth MAX_DEPTH``), every node linked in item will
+be checked too, then node linked in linked item and so on until depth level is reached.
+
+For instance, if you want to find all comments of a blog node containing an http(s) link,
+you can do that::
+
+  $ jp pubsub search -n urn:xmpp:microblog:0 -s user@example.net -D 1 -r 'https?://'
+
+examples
+--------
+
+Finding all items containing the text "something interesting" in personal blog::
+
+  $ jp pubsub search -n urn:xmpp:microblog:0 -M -1 -t "something interesting"
+
+Find which blog items in the last 20 have a body with less than 200 characters (note that
+body can be either ``<title>`` or ``<content>``, see `XEP-0277`_ for details). Here we use
+a python expression on the text of the body to count the number of characters::
+
+  $ jp pubsub search -n urn:xmpp:microblog:0 -M 20 --python "len((item_xml.find('.//{http://www.w3.org/2005/Atom}content[@type=\"text\"]') or item_xml.find('.//{http://www.w3.org/2005/Atom}title[@type=\"text\"]')).text) < 200"
+
+Find items published by ``toto@example.net`` among last 30 on a blog node, and use
+``pubsub blog`` command to retrieve id and title. We use ``-N`` to specify the ``pubsub``
+namespace which is used in the XPath expression, then we use ``exec`` to run ``blog get -k
+title -k id`` on found items::
+
+  $ jp pubsub search -n some_blog_node -s pubsub.example.net -M 30 -N pubsub http://jabber.org/protocol/pubsub -x '/pubsub:item[starts-with(@publisher, "toto@example.net")]' exec blog get -k title -k id
+
+Find items which have **NOT** a title among last 30 items in our personal blog. As
+explained in `XEP-0277`_ Atom's ``<title>`` is always used (even if there is only a body
+and no title), so we actually look for items without ``<content>``. We do that with an
+XPath looking for this ``atom:content`` element, then we use the ``-I [BOOLEAN], --invert
+[BOOLEAN]`` to filter out elements which match.::
+
+  $ jp pubsub search -n urn:xmpp:microblog:0 -M 30 -I -x //atom:content -N atom http://www.w3.org/2005/Atom
+
+Display authors names from last 10 items and their comments, using the ``-k [BOOLEAN],
+--only-matching [BOOLEAN]`` modifier to only display the data we need. We use ``-D 1`` to
+do a recursive search of level 1, which will also look into comments nodes (using last 10
+items there too)::
+
+  $ jp pubsub search -n urn:xmpp:microblog:0 -M 10 --only-matching -x //atom:author/atom:name -N atom http://www.w3.org/2005/Atom -D 1
+
+.. _XEP-0277: https://xmpp.org/extensions/xep-0277.html
+
+transform
+=========
+
+Modify items using an external command.
+
+``transform`` will retrieve requested items, and will send each of them to the standard
+input (stdin) of the specified command. The output of the command will be used, it can be
+3 things:
+
+- a raw XML of the modified item, in which case the item will be republished
+- the string ``SKIP``, in which case the item will be ignored
+- the string ``DELETE``, in which case the item will be retracted
+
+By default a dry run is done, which means that no item is modified or deleted. To actually
+do the transformation, you have to use ``--apply`` argument.
+
+If you have to modify the ``publisher`` of an item, you need specific privileges. The
+``--admin`` allows you do to that, but it must be supported by your PubSub service
+(currently only ``SàT PubSub`` supports this non standard feature).
+
+To modify all items of a node, use the ``-A, --all`` option. This will use `RSM`_
+repetitively until all items are treated. Of course that means that your PubSub service
+must support RSM. The items being republished, they will reappear on top of your node,
+that's why it is recommended to use ``--order-by creation`` option when supported by the
+service, to keep consistent order and avoid transforming the same items several times.
+
+If the command you're using exit with a non zero code, the process will stop. Use ``-I,
+--ignore_errors`` if you want to continue transformation even if an non zero code is
+returned.
+
+.. _RSM: https://xmpp.org/extensions/xep-0059.html
+
+example
+-------
+
+Imagine that you want to replace all occurrences of "sàt" by "Salut à Toi" in your personal blog. You first create a Python script like this:
+
+.. sourcecode:: python
+
+   #!/usr/bin/env python3
+
+   import sys
+   item_raw = sys.stdin.read()
+   if not "sàt" in item_raw:
+       print("SKIP")
+   else:
+       print(item_raw.replace("sàt", "Salut à Toi"))
+
+And save it a some location, e.g. ``~/expand_sat.py`` (don't forget to make is executable
+with ``chmod +x ~/expand_sat.py``).
+
+To be sure it's safe, you can first do a dry-run and check the result::
+
+  $ jp pubsub transform -n urn:xmpp:microblog:0 -A -o creation ~/expand_sat.py
+
+Once you have checked that you have the expected behaviour, you can apply the
+transformations::
+
+  $ jp pubsub transform -n urn:xmpp:microblog:0 -A -o creation --apply ~/expand_sat.py
+
+And that's it. You can use the same technique for more complex transformations, including
+modifying the XML (with Python, you can easily do that with standard
+``xml.etree.ElementTree`` module or with ``lxml.etree``).
+
+uri
+===
+
+Build an XMPP URI linking to a PubSub node or item.
+
+example
+-------
+
+Build a link to personal blog::
+
+  $ jp pubsub uri -n urn:xmpp:microblog:0
+
+node
+====
+
+Subcommands for node management. Please check :ref:`jp-pubsub_node`.
+
+hook
+====
+
+Subcommands for hooks management. Please check :ref:`jp-pubsub_hook`.
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/jp/pubsub_hook.rst	Tue Oct 01 22:49:06 2019 +0200
@@ -0,0 +1,96 @@
+.. _jp-pubsub_hook:
+
+====================================
+pubsub/hook: PubSub hooks management
+====================================
+
+``hook`` is a subcommands grouping all PubSub commands related to hooks management. Hooks
+are user actions launched on specific events.
+
+3 types of hooks can be used:
+
+``python``
+  A Python module is expected as argument. The module must be available in Python path,
+  and it must have a ``hook`` function.
+
+``python_file``
+  A path to a Python script is expected as argument. The script must contain a ``hook``
+  function.
+
+``python_code``
+  Python code which will be directly executed. 3 variables will be set: ``host`` which
+  contain the main SàT instance, ``client`` which contain the session attached to the
+  profile, and ``item`` which contain the item attached to the event.
+
+.. note::
+
+   Hooks are executed in SàT context, and must be asynchronous. If they block, the whole
+   SàT execution will be blocked. They have access to everything, so don't run a code that
+   you don't absolutely trust.
+
+.. note::
+
+   Only ``python_file`` type is currently implemented
+
+.. note::
+   Hook is an experimental feature, the way to use it may change in the future.
+
+create
+======
+
+Create a hook of given type. Type is specified with ``-t {python,python_file,python_code},
+--type {python,python_file,python_code}`` and a positional arguments is expected, which
+depends on the chosen type.
+
+By default the hook is temporary (it will be lost if the profile is disconnected), but you
+can make is persistent accross reconnexions if you use the ``-P, --persistent`` argument.
+
+example
+-------
+
+Install a persistent hook on blog node, using the Python script named
+``do_something_neat.py`` in ``$HOME`` directory::
+
+  $ jp pubsub node hook create -n urn:xmpp:microblog:0 -t python_file --persistent ~/do_something_neat.py
+
+delete
+======
+
+Delete one hook or all of them. To delete a hook, specify its type and argument (the that
+you have used with ``create``). If you use empty ``--type`` and ``--arg`` all hooks will
+be removed.
+
+example
+-------
+
+Delete the ``do_something_neat.py`` hook::
+
+  $ jp pubsub node hook delete -n urn:xmpp:microblog:0 -t python_file --arg ~/do_something_neat.py
+
+list
+====
+
+List registered hooks. The output will give the following informations:
+
+service
+  PubSub service on which the hook is attached.
+
+node
+  PubSub node on which the hook is attached.
+
+type
+  hook type
+
+arg
+  hook arguments (dependant of hook type)
+
+persistent
+  boolean indicating is the hook persist accross sessions.
+
+example
+-------
+
+Get PubSub hooks registered for this profile in JSON::
+
+  $ jp pubsub hook list -O json
+
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/jp/pubsub_node.rst	Tue Oct 01 22:49:06 2019 +0200
@@ -0,0 +1,124 @@
+.. _jp-pubsub_node:
+
+====================================
+pubsub/node: PubSub nodes management
+====================================
+
+``node`` is a subcommands grouping all PubSub commands related to node management. For
+details on ``pubsub`` command itself, refer to :ref:`jp-pubsub`.
+
+info
+====
+
+Get settings of the node. Use ``-k KEYS, --key KEYS`` to select data to print.
+
+examples
+--------
+
+Get informations on our personal microblog node::
+
+  $ jp pubsub node info -n urn:xmpp:microblog:0
+
+Only print ``access_model`` and ``publish_model``::
+
+  $ jp pubsub node info -n urn:xmpp:microblog:0 -k access_model -k publish_model
+
+create
+======
+
+Create a node. Node configuration can be specified using ``-f KEY VALUE, --field KEY
+VALUE`` where ``KEY`` is a pubsub option. By default the ``pubsub#`` prefix will be
+appended, as it is used with standard options (see `XEP-0060`_ for more details); to
+change this behaviour, use the ``-F, --full-prefix`` flag.
+
+.. _XEP-0060: https://xmpp.org/extensions/xep-0060.html
+
+example
+--------
+
+Create a node called ``notes`` with a ``whitelist`` access model (so only you and people
+you may authorize later can access it)::
+
+  $ jp pubsub node create -n notes
+
+purge
+=====
+
+Remove all items from a node (but don't delete the node).
+
+A confirmation is requested by default, you can override this behaviour by using ``-f, --force`` option.
+
+example
+-------
+
+Remove all items from a blog comments node (in other words, removing all comments while
+letting the node so people can add new comments)::
+
+  $ jp pubsub node purge -n "urn:xmpp:microblog:0:comments/123-456-789"
+
+delete
+======
+
+Delete a node (note that this will delete definitively all items that where published to
+this node).
+
+A confirmation is requested by default, you can override this behaviour by using ``-f, --force`` option.
+
+example
+-------
+
+Delete the ``temporary_notes`` node::
+
+  $ jp pubsub node delete -n temporary_notes
+
+set
+===
+
+Update a node configuration.
+
+Configuration options are specified using ``-f KEY VALUE, --field KEY VALUE`` argument
+where ``KEY`` is a PubSub option. If ``KEY`` doesn't start with ``pubsub#`` prefix, it is
+added automatically, except if ``-F, --full-prefix`` argument is used (in which case the
+``KEY`` is used as specified.
+
+example
+-------
+
+Make the ``public_notes`` node accessible to the world::
+
+  $ jp pubsub node set -n public_notes -f access_model open
+
+import
+======
+
+Import a raw XML containing items to create in the node. The path to the XML file is used
+as positional argument.
+
+The XML file must contain full `<item>` element for each item to import. The output of ``pubsub get`` can be used directly.
+
+If you want to change publisher of one or more items (i.e. if you want to use an other ``jid`` than the jid of the profile as publisher), you must use the ``--admin`` arguments. This needs a PubSub service supporting this feature (and you must of course be an administrator of this service). The new publisher must be allowed to publish to the node.
+
+example
+-------
+
+Import a node backup which has previously been saved using ``jp blog get -M -1 -n
+some_node > some_node_backup.xml``::
+
+  $ jp pubsub node import -n some_node ~/some_node_backup.xml
+
+.. note::
+
+   If your node is big, -M 1 option is not adapted as it will get all items at once and
+   may be blocked by your server stanza size limit. The possibility to use RSM to
+   retrieve all items by pages is planned in a future version.
+
+affiliations
+============
+
+Subcommands for node affiliations management. Please check :ref:`jp-pubsub_node_affiliations`.
+
+subscriptions
+=============
+
+Subcommands for node subscriptions management. Please check
+:ref:`jp-pubsub_node_subscriptions`.
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/jp/pubsub_node_affiliations.rst	Tue Oct 01 22:49:06 2019 +0200
@@ -0,0 +1,40 @@
+.. _jp-pubsub_node_affiliations:
+
+=======================================================
+pubsub/node/affiliations: nodes affiliations management
+=======================================================
+
+``affiliations`` is a subcommand handling the affiliations of a node (not to be confused
+with ``pubsub affiliations`` which handle the affiliations of a PubSub service).
+
+get
+===
+
+Retrieve entities affiliated to this node and their role.
+
+example
+-------
+
+Get affiliations of a node::
+
+  $ jp pubsub node affiliations get -n some_node
+
+set
+===
+
+Set affiliation of an entity on a node. Affiliations are specified with ``-a JID
+AFFILIATION`` argument. Check `XEP-0060 affiliations`_ for allowed values for
+``AFFILIATION``. Use ``none`` to remove an affiliation.
+
+.. _XEP-0060 affiliations: https://xmpp.org/extensions/xep-0060.html#affiliations
+
+example
+-------
+
+If we have a whitelisted node ``some_whitelisted_node``, we can allow
+``louise@example.net`` to publish on it (by setting her role as ``publisher``), and
+``pierre@example.net`` to access it (by setting his role as ``member``) using the
+following command::
+
+  $ jp pubsub node affiliations set -n some_whitelisted_node -a louise@example.net
+  publisher -a pierre@example.net member
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/jp/pubsub_node_schema.rst	Tue Oct 01 22:49:06 2019 +0200
@@ -0,0 +1,59 @@
+.. _jp-pubsub_node_schema:
+
+=========================================
+pubsub/node/schema: nodes schema handling
+=========================================
+
+``node schema`` is an experimental feature to associate a data form with a PubSub node, and
+reject items not following this form. This feature is currently only available with SàT
+PubSub.
+
+Those commands can only be used by an owner of the node.
+
+set
+===
+
+Set the schema of a node. The raw schema is written directly as positional argument.
+
+example
+-------
+
+Set the schema for tickets node using the file ``tickets_schema.xml`` from ``$HOME``
+directory. Shell substition is used here to put the content of the file in the positional
+argument::
+
+  $ jp pubsub node schema set -n org.salut-a-toi.tickets:0 -s pubsub.example.org "$(<~/test_schema.xml)"
+
+
+edit
+====
+
+Edit the schema of a node using your local editor (the one set in ``$EDITOR``).
+
+If you don't change anything or publish an empty schema, the edition will be cancelled.
+
+:ref:`draft_common` commands can be used.
+
+example
+-------
+
+Edit the tickets node schema::
+
+  $ jp pubsub node schema edit -n org.salut-a-toi.tickets:0 -s pubsub.example.org
+
+
+example
+-------
+
+get
+===
+
+Retrieve schema of a node.
+
+example
+-------
+
+Get schema of tickets and save it to a file named ``tickets_schema.xml`` in ``$HOME``
+directory::
+
+  $ jp pubsub node schema get -n org.salut-a-toi.tickets:0 -s pubsub.example.org > ~/tickets_schema.xml
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/jp/pubsub_node_subscriptions.rst	Tue Oct 01 22:49:06 2019 +0200
@@ -0,0 +1,43 @@
+.. _jp-pubsub_node_subscriptions:
+
+========================================================
+pubsub/node/affiliations: nodes subscriptions management
+========================================================
+
+``subscriptions`` is a subcommand handling the subscription to a node.
+
+Those commands can only be used by an owner of the node.
+
+get
+===
+
+Retrieve subscriptions to a node.
+
+example
+-------
+
+Get subscription from ``some_node``::
+
+  $ jp pubsub node subscriptions get -n some_node
+
+set
+===
+
+Set subscriptions to a node. Subscriptions are specified with ``-S JID [SUSBSCRIPTION]
+[JID [SUSBSCRIPTION] ...], --subscription JID [SUSBSCRIPTION] [JID [SUSBSCRIPTION] ...]``
+where ``JID`` is the jid of the entity to change subscription state, and ``SUBSCRIPTION``
+is a subscription state (on of ``subscribed``, ``pending``, ``none``) as specified in
+`XEP-0060 Subscription State`_. If ``SUBSCRIPTION`` is not specified, it default to
+``subscribed``.
+
+.. _XEP-0060 Subscription State: https://xmpp.org/extensions/xep-0060.html#substates
+
+example
+-------
+
+Subscribe Louise with her new address at ``louise@example.org`` and remove her
+subscription from old ``louise@example.com``::
+
+  $ jp pubsub node subscriptions set -n some_node -S louise@example.org subscribed louise@example.com none
+
+
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/jp/roster.rst	Tue Oct 01 22:49:06 2019 +0200
@@ -0,0 +1,110 @@
+================================
+roster: manager an entity roster
+================================
+
+"Roster" is the name used in XMPP for the contact list. In addition to list of contacts,
+you have also data like subscription information or groups associated to a contact.
+
+Groups are simple strings associated to one or more contacts (e.g. "friends" or "family").
+
+Subscription is the mechanism to get presence information of an entity. When you add a
+contact to your roster, most XMPP clients also do a presence subscription request, than
+the entity may accept or deny. If a presence subscription is accepted, the subscribed user
+can see when the other entity is online, and its presence status.
+
+get
+===
+
+Show the current roster. By default only a display name and JIDs are displayed, but you
+can increase verbosity to also display groups, or all other metadata.
+
+The short name shown next to jid is either the ``name`` specified in roster, or the node
+part of the jid. If none of them exist, only the entity JID is shown.
+
+The following metadata may be displayed:
+
+groups
+  group the entity belong too
+ask
+  true if a presence subscription request has been sent (but not answered yet)
+from
+  the contact has a subscription to user presence (i.e. your contact can see when you're
+  online and your presence status)
+to
+  the user has a subscription to the contact presence (i.e. you can see when you're
+  contact is online and his/her presence status)
+
+examples
+--------
+
+Get roster of default profile and display groups::
+
+  $ jp roster get -v
+
+Get roster of default profile and display all metadata::
+
+  $ jp roster get -vv
+
+Get roster or default profile and show the result in JSON::
+
+  $ jp roster get -O json
+
+stats
+=====
+
+Show some statistics about the profile roster. The number of contacts per server is shown,
+with a percentage of contacts on this server compared to the total number of contacts.
+This can notably be helpful to see if there is a concentration of your contacts in a
+specific server or gateway.
+
+Other more or less useful numbers are shown, they are self explaining.
+
+example
+-------
+
+Get statistic for the default profile::
+
+  $ jp roster stats
+
+purge
+=====
+
+This command is used to remove from the roster all contacts which have no subscription or
+only partial subscription.
+
+By default, only contacts without subscription at all are removed. With ``--no_from`` you
+also remove contacts which have no subscription to you (but you have a subscription to
+them), and with ``--no_to`` you also remove contacts that you are not subscribed to (but
+who are subscribed to you).
+
+example
+-------
+
+Remove all contacts from default profile which have no subscription at all or from which
+the default profile is not subscribed to::
+
+  $ jp roster purge --no_to
+
+resync
+======
+
+SàT uses `roster versioning`_ to optimize the synchronisation of roster with server on
+client connection. This means that once the roster has been retrieved, on each following
+connection, only the difference of contacts (i.e. which new or removed contacts) is
+received.
+
+This command does a full resynchronisation of the roster, or in other words it requests
+the whole roster and save it, replacing the list built with versioning. ``resync`` is
+mostly useful for developers and end-user should not need this command, as roster
+versioning is supposed to work fine and the roster should be synchronised correctly on
+startup. But if for any reason you suspect that your current roster list is corrupted, you
+may use it to be sure that a full resynchronisation is done.
+
+.. _roster versioning: https://tools.ietf.org/html/rfc6121#section-2.6
+
+exemple
+-------
+
+Do a full resynchronisation of default profile's roster::
+
+  $ jp roster resync
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/jp/shell.rst	Tue Oct 01 22:49:06 2019 +0200
@@ -0,0 +1,208 @@
+========================
+shell: use SàT with REPL
+========================
+
+``shell`` launch a read–eval–print loop (REPL) with some helpers to launch jp commands.
+This is useful if you are willing to a session when you'll use several commands in a row
+(for e.g. to inspect something on a PubSub service).
+
+start the shell
+===============
+
+To start the shell, you just have to enter ``jp shell``. You can eventually specify a
+profile to use an other one than the default one by entering ``jp shell -p
+<some_profile>``.
+
+
+.. _jp-shell_use:
+
+use the shell
+=============
+
+Once in the shell, you can launch a command by entering it as usual (without having to
+specify ``jp``). For instance to get last 2 blog posts from your personal blog, you just
+have to enter::
+
+  > blog get -m 2
+
+There are 2 kinds of commands in the shell:
+
+- **shell commands** which are command to manipulate the shell itself
+- **jp commands** which are the classic commands that you use with jp
+
+The most important thing to remember is that you can use ``?`` (or ``help`` which is
+equivalent) to get the list of commands (shell + jp), and ``?<command>`` (or ``help
+<command>``) to get information on a shell command. For jp commands, you can use the usual
+``--help`` argument.
+
+You may move in the commands hierarchy using ``cmd`` which can be seen as something
+roughly equivalent to ``cd`` for the filesystem. for instance if you know you'll work with
+XMPP blogs, you can enter::
+
+  > cmd blog
+
+Then you'll be in the blog hierarchy, you can check that by entering ``?``. From there you
+can use blog commands directly, like in this example to retrieve last 2 blog posts::
+
+  blog> get -m 2
+
+You can even go further, e.g. if you know that you'll do several ``get`` command (in this
+can you'll only have to specify the arguments of ``get``)::
+
+  blob> cmd get
+  blog/get> -m 2
+
+You can use ``/`` with ``cmd``, including as first character to indicate that you want to
+start from root::
+
+  blog/get> cmd /pubsub
+  pubsub> cmd node/info
+
+Similarly, you can use ``..`` to move to parent command::
+
+  pubsub/node/info> cmd ..
+
+On of the interesting feature of shell is that you can fix an argument, i.e. indicate
+the value to use in the next commands. For instance if you're willing to work on a
+specific node, you can set its value with ``use``::
+
+  blog> use node some_interesting_node
+
+Then you won't have to specify it anymore for each command. The name of the argument to
+fix must be the long form. To check which arguments are fixed, just enter ``use`` without
+argument. If an argument is fixed but not used in a command, it will be ignored.
+
+To clear a fixed argument, you have the ``use_clear`` command. To clear the ``node``
+argument set above, just enter::
+
+  blog> use_clear node
+
+Without argument, all fixed arguments will be cleared.
+
+
+Shell commands
+==============
+
+Below is a description of shell commands.
+
+
+cmd
+---
+
+Move in the command hierarchy, this avoid to type again a command if you know you'll use
+it several times. See jp-shell_use_ for explanation and examples
+
+do
+--
+
+Launch a jp command. By default the command is launched if you enter directly its name and
+arguments, but if a command or argument conflict with a shell command, the shell command
+will be launcher instead. The ``do`` command avoid such a situation by always launching a
+jp command::
+
+  > do blog get -m 2
+
+exit
+----
+
+Quit the shell (alias of ``quit``).
+
+help (alias ``?``)
+------------------
+
+Give information on available commands or on a specific command, see jp-shell_use_ for
+more explanations.
+
+examples
+^^^^^^^^
+
+Get general help::
+
+  > ?
+
+Get help on ``do`` command::
+
+  > ?do
+
+quit
+----
+
+Quit the shell
+
+shell (alias ``!``)
+-------------------
+
+Launch an external command.
+
+example
+^^^^^^^
+
+Print a calendar with ``cal``::
+
+  > !cal
+
+use
+---
+
+Fix the value of an argument, which will then be set for all following commands, see
+jp-shell_use_ for more explanations.
+
+Without argument, show all fixed arguments
+
+examples
+^^^^^^^^
+
+Fix the PubSub node (the long name of the argument is used, so it will go to ``--node``)::
+
+  pubsub> use node some_intersting_node
+
+Show all fixed arguments::
+
+  > use
+
+use_clear
+---------
+
+Unfix the value of an argument (i.e. use the normal default value). Without argument,
+it unfixes all arguments.
+
+examples
+^^^^^^^^
+Clear the node::
+
+  pubsub> use_clear node
+
+Clear all arguments::
+
+  > use_clear
+
+verbose
+-------
+
+Without argument, show if verbose mode is activated. With an argument evaluating to a
+boolean, activate or deactivate this mode.
+
+In verbose mode, the fixed arguments and the command launched are printed before launching
+a jp command.
+
+examples
+^^^^^^^^
+
+Show if verbose mode is activated::
+
+  > verbose
+
+Activate verbose mode::
+
+  > verbose on
+
+version
+-------
+
+Print current version of jp/Salut à Toi.
+
+whoami
+------
+
+Show the name of the connected profile (the one set with ``--profile`` when launching the
+shell). This profile will be used as default profile.
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/jp/ticket.rst	Tue Oct 01 22:49:06 2019 +0200
@@ -0,0 +1,72 @@
+=================================
+ticket: create and manage tickets
+=================================
+
+Ticket is a generic tools to create items with metadata and states (where state can be
+``queued``, ``done``, etc). This can be used for many things, from TODO list to bugs
+management.
+
+get
+===
+
+Retrieve one or more tickets and display them. A project may use magic string in README to
+indicate PubSub service and node to use, in which case use just need to be in the
+directory of the project.
+
+examples
+--------
+
+Retrieve last 5 tickets (ordered by creation) from a project using magic string in README::
+
+  $ jp ticket get -m 5 -o creation
+
+Retrieve the ticket with id ``123`` on service ``pubsub.example.org``::
+
+  $ jp ticket get -s pubsub.example.org -i 123
+
+
+
+import
+======
+
+Import tickets from an external source. This works in the same way as
+:ref:`jp-blog_import`: you need to specify an importer and a data location. If you let
+both positional argument empty, you'll get list of importers, if you specify importer but
+not data location, you'll get a description on how the importer works.
+
+If you want to see a progress bar for the import, use the ``-P, --progress`` option, this
+is recommended for most imports.
+
+Some importers may have specific option (check description for details), you can specify
+them with ``o NAME VALUE, --option NAME VALUE``
+
+When you import a ticket, the ticket will be created according to the schema of the PubSub
+node. By default, the metadata of the original ticket will be put to the one of the same
+name in the dest PubSub item. But of course the schema of your destination PubSub node may
+differ from the original metadata. In this case, you can use ``-m IMPORTED_FIELD
+DEST_FIELD, --map IMPORTED_FIELD DEST_FIELD`` to specify how the mapping mus be done
+(``IMPORTED_FIELD is the name of the field in the original ticket, while ``DEST_FIELD`` if
+the name of the field in your node schema).
+
+
+examples
+--------
+
+Get list of ticket importers::
+
+  $ jp ticket import
+
+Get description of ticket importer for Bugzilla::
+
+  $ jp ticket import bugzilla
+
+Import tickets from a Bugzilla XML export file at ``~/bugzilla_export.xml`` to the
+``pubsub.example.org`` PubSub service. We use default tickets node and want a progression
+bar::
+
+  $ jp ticket import -P -s pubsub.example.org ~/bugzilla_export.xml
+
+Same import, but this time we want to map the field ``assigned_to_name`` from Bugzilla to
+the field ``assigned_to`` in our schema::
+
+  $ jp ticket import -P -s pubsub.example.org -m assigned_to_name assigned_to ~/bugzilla_export.xml
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/jp/uri.rst	Tue Oct 01 22:49:06 2019 +0200
@@ -0,0 +1,39 @@
+================================
+uri: XMPP URI parsing/generation
+================================
+
+URI commands are helper to easily parse/build XMPP URIs.
+
+parse
+=====
+
+Parse an XMPP URI, and print different parts.
+
+When possible, the ``type`` of URI is shown (e.g. ``pubsub``) and the ``sub_type`` (e.g.
+``microblog``).
+
+The ``path`` is always displayed (see `RFC 5122 Path section`_ for details).
+
+If suitable, you'll also get data like ``node`` (for a PubSub URI).
+
+.. _RFC 5122 Path section: https://tools.ietf.org/html/rfc5122#section-2.4
+
+examples
+--------
+
+Parse a blog URI::
+
+  $ jp uri parse "xmpp:somebody@example.org?;node=urn%3Axmpp%3Amicroblog%3A0"
+
+build
+======
+
+Build an XMPP URI according to arguments. 2 positional arguments are expected: ``type``
+and ``path``. For now, only ``pubsub`` type is supported.
+
+examples
+--------
+
+Build XMPP URI for a blog::
+
+  $ jp uri build pubsub somebody@example.org -f node urn:xmpp:microblog:0
--- a/doc/overview.rst	Wed Sep 25 08:56:41 2019 +0200
+++ b/doc/overview.rst	Tue Oct 01 22:49:06 2019 +0200
@@ -132,6 +132,7 @@
 
 You can check :doc:`jp documentation <jp/index>` documentation for more details.
 
+.. _glossary:
 
 Glossary
 ========