Mercurial > libervia-backend

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

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