Mercurial > libervia-backend

comparison doc/jp/bookmarks.rst @ 3041:72583524cfd3

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc (jp): jp commands are now fully documented: rel 232
author Goffi <goffi@goffi.org>
date Tue, 01 Oct 2019 22:49:06 +0200
parents
children
comparison
equal deleted inserted replaced
3040:fee60f17ebac 3041:72583524cfd3
1 ============================
2 bookmarks: get/set bookmarks
3 ============================
4
5 Bookmarks are links to MUC rooms or URLs with a few metadata. Due to historical reasons,
6 XMPP has several ways to handle bookmarks, and SàT handle them as transparently as
7 possible.
8
9 With SàT there are 3 places where you can get/store your bookmarks:
10
11 local
12 the bookmarks is stored only locally in the database of SàT. It won't be available to
13 other devices.
14 private
15 the bookmarks use the old private XML storage (`XEP-0049`_). It is not recommended to
16 use this if PubSub storage is available
17 pubsub
18 the bookmarks use PEP storage (`XEP-0223`_), this is the currently recommended way to
19 store bookmarks.
20
21 When possible, you can specify ``auto`` to let SàT choose the best location (i.e.
22 ``pubsub`` if available, then ``private`` then ``local`` if nothing else is possible).
23
24 .. _XEP-0049: https://xmpp.org/extensions/xep-0049.html
25 .. _XEP-0223: https://xmpp.org/extensions/xep-0223.html
26
27
28 list
29 ====
30
31 Get and print available bookmarks. You specify the location of the bookmarks to print
32 using ``-l {all,local,private,pubsub}, --location {all,local,private,pubsub``, by default
33 all bookmarks from all locations are printed.
34
35 Use ``-t {muc,url}, --type {muc,url}`` to indicate if you want to print MUC bookmarks or
36 URLs.
37
38 After printing the bookmarks location, the bookmarks will show the name and location (jid
39 for MUC or URL). For MUC bookmarks you'll also see nickname, and a star (``*``) if
40 autojoin is set.
41
42
43 examples
44 --------
45
46 Retrieve all MUC bookmarks::
47
48 $ jp bookmarks list
49
50 Retrieve all bookmarked URL stored in PubSub::
51
52 $ jp bookmarks list -l pubsub -t url
53
54
55 remove
56 ======
57
58 Delete a bookmark. You need to specify the jid of the MUC room or the URL to remove as
59 positional argument. If you are deleting an URL, you need to specify it with ``-t url``
60
61 By default a confirmation is requested, use ``-f, --force`` if you don't want it (with
62 usual caution).
63
64 examples
65 --------
66
67 Delete the bookmark of a MUC room that you are not following anymore::
68
69 $ jp bookmarks remove some_old_room@conference.example.net
70
71 Delete the bookmark of a URL without requesting confirmation::
72
73 $ jp bookmarks remove -t url https://unused_url.example.net
74
75
76 add
77 ===
78
79 Create or update a bookmark. The bookmark itself (URL or JID of the MUC) is specified as
80 positional argument. If you are bookmarking an URL, you need to specify it with ``-t
81 url``. A name is often helpful, use ``-n NAME, --name NAME`` to specify it.
82
83 For MUC only, you can specify the nick to use on the room with ``-N NICK, --nick NICK``,
84 and the flag ``-a, --autojoin`` indicates if you want to join the chat room automatically
85 when you're connecting.
86
87 If you're using add on a jid/URL which already exists, the metadata will be updated.
88
89 examples
90 --------
91
92 Add a bookmark to Salut à Toi official chat room::
93
94 $ jp bookmarks add sat@chat.jabberfr.org -a
95
96 Add a link to Salut à Toi official website::
97
98 $ jp bookmarks add -t url https://www.salut-a-toi.org -n "SàT officiel"