comparison doc/libervia-cli/bookmarks_legacy.rst @ 4328:f72d6b86f8dc

doc (cli/bookmarks): move old bookmarks doc to bookmarks_legacy, and add new bookmarks doc.
author Goffi <goffi@goffi.org>
date Wed, 20 Nov 2024 11:49:46 +0100
parents doc/libervia-cli/bookmarks.rst@d6837db456fd
children
comparison
equal deleted inserted replaced
4327:554a87ae17a6 4328:f72d6b86f8dc
1 .. _libervia-cli_bookmarks_legacy:
2
3 ==========================================
4 bookmarks legacy: legacy bookmark commands
5 ==========================================
6
7 .. note::
8
9 These are the legacy commands, used for older ways to handle bookmarks (notably via
10 `XEP-0048`_). These are kept to deal with legacy data. New ``bookmarks`` commands
11 automatically handle legacy bookmarks using `XEP-0049`_, so ``bookmarks legacy``
12 commands should not be used in the vast majority of cases.
13
14 Bookmarks are links to MUC rooms or URLs with a few metadata. Due to historical reasons,
15 XMPP has several ways to handle bookmarks, and Libervia handle them as transparently as
16 possible.
17
18 With Libervia there are 3 places where you can get/store your bookmarks:
19
20 local
21 the bookmarks is stored only locally in the database of Libervia. It won't be available to
22 other devices.
23 private
24 the bookmarks use the old private XML storage (`XEP-0049`_). It is not recommended to
25 use this if PubSub storage is available
26 pubsub
27 the bookmarks use PEP storage (`XEP-0223`_), this is the currently recommended way to
28 store bookmarks.
29
30 When possible, you can specify ``auto`` to let Libervia choose the best location (i.e.
31 ``pubsub`` if available, then ``private`` then ``local`` if nothing else is possible).
32
33 .. _XEP-0048: https://xmpp.org/extensions/xep-0048.html
34 .. _XEP-0049: https://xmpp.org/extensions/xep-0049.html
35 .. _XEP-0223: https://xmpp.org/extensions/xep-0223.html
36
37
38 list
39 ====
40
41 Get and print available bookmarks. You specify the location of the bookmarks to print
42 using ``-l {all,local,private,pubsub}, --location {all,local,private,pubsub``, by default
43 all bookmarks from all locations are printed.
44
45 Use ``-t {muc,url}, --type {muc,url}`` to indicate if you want to print MUC bookmarks or
46 URLs.
47
48 After printing the bookmarks location, the bookmarks will show the name and location (jid
49 for MUC or URL). For MUC bookmarks you'll also see nickname, and a star (``*``) if
50 autojoin is set.
51
52
53 examples
54 --------
55
56 Retrieve all MUC bookmarks::
57
58 $ li bookmarks list
59
60 Retrieve all bookmarked URL stored in PubSub::
61
62 $ li bookmarks list -l pubsub -t url
63
64
65 remove
66 ======
67
68 Delete a bookmark. You need to specify the jid of the MUC room or the URL to remove as
69 positional argument. If you are deleting an URL, you need to specify it with ``-t url``
70
71 By default a confirmation is requested, use ``-f, --force`` if you don't want it (with
72 usual caution).
73
74 examples
75 --------
76
77 Delete the bookmark of a MUC room that you are not following anymore::
78
79 $ li bookmarks remove some_old_room@conference.example.net
80
81 Delete the bookmark of a URL without requesting confirmation::
82
83 $ li bookmarks remove -t url https://unused_url.example.net
84
85
86 add
87 ===
88
89 Create or update a bookmark. The bookmark itself (URL or JID of the MUC) is specified as
90 positional argument. If you are bookmarking an URL, you need to specify it with ``-t
91 url``. A name is often helpful, use ``-n NAME, --name NAME`` to specify it.
92
93 For MUC only, you can specify the nick to use on the room with ``-N NICK, --nick NICK``,
94 and the flag ``-a, --autojoin`` indicates if you want to join the chat room automatically
95 when you're connecting.
96
97 If you're using add on a jid/URL which already exists, the metadata will be updated.
98
99 examples
100 --------
101
102 Add a bookmark to Libervia official chat room::
103
104 $ li bookmarks add libervia@chat.jabberfr.org -a
105
106 Add a link to Libervia official website::
107
108 $ li bookmarks add -t url https://www.salut-a-toi.org -n "Libervia officiel"