--- a/doc/libervia-cli/bookmarks.rst	Wed Nov 20 11:43:27 2024 +0100
+++ b/doc/libervia-cli/bookmarks.rst	Wed Nov 20 11:49:46 2024 +0100
@@ -1,98 +1,50 @@
-============================
-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 Libervia handle them as transparently as
-possible.
-
-With Libervia there are 3 places where you can get/store your bookmarks:
-
-local
-  the bookmarks is stored only locally in the database of Libervia. 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 Libervia 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
-
+===========================
+bookmarks: Manage bookmarks
+===========================
+Bookmarks are used to store a list of group chat rooms and indicate which ones are
+currently joined. Libervia offers commands to list, set, and remove bookmarks.
 
 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.
+Get and print available bookmarks.
 
-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::
+example
+-------
+Retrieve all bookmarks::
 
   $ li bookmarks list
 
-Retrieve all bookmarked URL stored in PubSub::
+set
+===
+
+Add or update a bookmark.
+
+You can use ``-n NAME, --name NAME`` to specify a name for the bookmark. This option
+allows you to provide a human-readable name for the bookmark, making it easier to
+identify.
 
-  $ li bookmarks list -l pubsub -t url
+``-N NICK, --nick NICK`` set the nickname to use in the room.
+
+``-j [BOOL], --join [BOOL]`` indicates whether you want to join the room. If the value is not set or ``true``, the room will be joined; otherwise, it will be left if the user is currently in it.
 
+example
+-------
+Add a bookmark to a chat room with a name and join it::
+
+  $ li bookmarks set lunch@conference.example.net -n "Lunch Organization" -j
 
 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).
+Remove a bookmark.
 
-examples
---------
-
-Delete the bookmark of a MUC room that you are not following anymore::
-
-  $ li bookmarks remove some_old_room@conference.example.net
-
-Delete the bookmark of a URL without requesting confirmation::
-
-  $ li bookmarks remove -t url https://unused_url.example.net
-
+example
+-------
+Remove a bookmark for a chat room::
 
-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.
+  $ li bookmarks remove lunch@conference.example.net
 
-If you're using add on a jid/URL which already exists, the metadata will be updated.
-
-examples
---------
+legacy
+======
 
-Add a bookmark to Libervia official chat room::
-
-  $ li bookmarks add libervia@chat.jabberfr.org -a
-
-Add a link to Libervia official website::
-
-  $ li bookmarks add -t url https://www.salut-a-toi.org -n "Libervia officiel"
+Manage legacy bookmarks. Please check :ref:`libervia-cli_bookmarks_legacy`.

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/libervia-cli/bookmarks_legacy.rst	Wed Nov 20 11:49:46 2024 +0100
@@ -0,0 +1,108 @@
+.. _libervia-cli_bookmarks_legacy:
+
+==========================================
+bookmarks legacy: legacy bookmark commands
+==========================================
+
+.. note::
+
+   These are the legacy commands, used for older ways to handle bookmarks (notably via
+   `XEP-0048`_). These are kept to deal with legacy data. New ``bookmarks`` commands
+   automatically handle legacy bookmarks using `XEP-0049`_, so ``bookmarks legacy``
+   commands should not be used in the vast majority of cases.
+
+Bookmarks are links to MUC rooms or URLs with a few metadata. Due to historical reasons,
+XMPP has several ways to handle bookmarks, and Libervia handle them as transparently as
+possible.
+
+With Libervia there are 3 places where you can get/store your bookmarks:
+
+local
+  the bookmarks is stored only locally in the database of Libervia. 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 Libervia choose the best location (i.e.
+``pubsub`` if available, then ``private`` then ``local`` if nothing else is possible).
+
+.. _XEP-0048: https://xmpp.org/extensions/xep-0048.html
+.. _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::
+
+  $ li bookmarks list
+
+Retrieve all bookmarked URL stored in PubSub::
+
+  $ li 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::
+
+  $ li bookmarks remove some_old_room@conference.example.net
+
+Delete the bookmark of a URL without requesting confirmation::
+
+  $ li 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 Libervia official chat room::
+
+  $ li bookmarks add libervia@chat.jabberfr.org -a
+
+Add a link to Libervia official website::
+
+  $ li bookmarks add -t url https://www.salut-a-toi.org -n "Libervia officiel"