# HG changeset patch # User Goffi # Date 1732099786 -3600 # Node ID f72d6b86f8dce7d4778f98338b0e6b1477c70acb # Parent 554a87ae17a6090c315c070019bd6ee2d470b2c0 doc (cli/bookmarks): move old bookmarks doc to bookmarks_legacy, and add new bookmarks doc. diff -r 554a87ae17a6 -r f72d6b86f8dc doc/libervia-cli/bookmarks.rst --- 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`. diff -r 554a87ae17a6 -r f72d6b86f8dc doc/libervia-cli/bookmarks_legacy.rst --- /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"