doc (cli/bookmarks): move old bookmarks doc to bookmarks_legacy, and add new bookmarks doc.
This commit is contained in:
Goffi
parent
06a1eef720
commit
33edd87271
2 changed files with 138 additions and 78 deletions
|
|
@ -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.
|
||||
Get and print available bookmarks.
|
||||
|
||||
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::
|
||||
example
|
||||
-------
|
||||
Retrieve all bookmarks::
|
||||
|
||||
$ li bookmarks list
|
||||
|
||||
Retrieve all bookmarked URL stored in PubSub::
|
||||
set
|
||||
===
|
||||
|
||||
$ li bookmarks list -l pubsub -t url
|
||||
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.
|
||||
|
||||
``-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
|
||||
======
|
||||
Remove a bookmark.
|
||||
|
||||
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``
|
||||
example
|
||||
-------
|
||||
Remove a bookmark for a chat room::
|
||||
|
||||
By default a confirmation is requested, use ``-f, --force`` if you don't want it (with
|
||||
usual caution).
|
||||
$ li bookmarks remove lunch@conference.example.net
|
||||
|
||||
examples
|
||||
--------
|
||||
legacy
|
||||
======
|
||||
|
||||
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"
|
||||
Manage legacy bookmarks. Please check :ref:`libervia-cli_bookmarks_legacy`.
|
||||
|
|
|
|||
108
doc/libervia-cli/bookmarks_legacy.rst
Normal file
108
doc/libervia-cli/bookmarks_legacy.rst
Normal file
|
|
@ -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"
|
||||
Loading…
Reference in a new issue