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

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 60a63723ecea
comparison
equal deleted inserted replaced
3040:fee60f17ebac 3041:72583524cfd3
1 .. _jp-file_share:
2
3 ==================================
4 file/share: advances files sharing
5 ==================================
6
7 ``share`` groups commands for listing file available on a device/service, sharing a file
8 or directory, and inviting people to retrieve files.
9
10 .. _jp-file_share_list:
11
12 list
13 ====
14
15 List files available on a device or sharing service. You mainly have to specify the jid of
16 the device/service where the files are stored (if jid is omitted, your own jid will be
17 used, so you can check what you are sharing).
18
19 .. note::
20
21 you have to use the full jid of the device if you want to list files available on a
22 device.
23
24 You may specify a path using ``-d PATH, --path PATH``.
25
26 File and directories are printed with a different colour if you use default output.
27
28 examples
29 --------
30
31 List files shared from a device (note that we use a full jid here)::
32
33 $ jp file share list louise@example.org/some_resource
34
35 List files available on a sharing service at the path ``/photos``::
36
37 $ jp file share list -d photos files.example.org
38
39 Louise wants to list the file shared by Pierre::
40
41 $ jp file share list pierre@files.example.org
42
43 path
44 ====
45
46 Share a local file or directory with a list of entities, or publicly. The files can then
47 be listed or requested using jp-file_share_list_ or :ref:`jp-file_request`.
48
49 You specify the file or directory the positional ``path`` argument. By default the name of
50 the file/directory is used, but you can give a different one using ``-n NAME, --name
51 NAME``.
52
53 You can specify entities allowed to see your files using ``-j JID, --jid JID`` as many
54 time as necessary. If you don't specify any entity, the file will only be accessible by
55 your own devices. If you want to make your file accessible to everybody, use ``--public``
56 (note that this means that your file is accessible to the world, i.e. also to people you
57 don't know, so use this option carefully).
58
59 examples
60 --------
61
62 Share the file ``interesting_doc.odt`` with Pierre and Louise::
63
64 $ jp file share path -j pierre@example.net -j louise@example.org interesting_doc.odt
65
66 Imagine that you have built a weather station and want to make its data public. You can
67 share the directory ``~/weather_station_data`` with the world, using the name ``public
68 weather data``::
69
70 $ jp file share path --public --name "public weather data" ~/weather_station_data
71
72 invite
73 ======
74
75 This command send an invitation for a file sharing repository to an XMPP entity.
76
77 The invitation is a non standard (yet?) way to notify somebody of the existence of a files
78 repository.
79
80 Beside the positional arguments ``service`` and ``jid``, which are respectively the
81 service where is the files repository and the jid of the entity to invite, you mainly have
82 to indicate the path and namespace of your repository, using ``-P PATH, --path PATH`` and
83 ``N NAMESPACE, --namespace NAMESPACE``.
84
85 Use the ``-t {files,photos}, --type {files,photos}`` to specify if you repository is a
86 generic files repository or a photo album.
87
88 Optionally, you can associate a thumbnail to the repository ``with -T THUMBNAIL,
89 --thumbnail THUMBNAIL``. This is recommended to have more user friendly representation of
90 the album in e.g. Libervia.
91
92 example
93 -------
94
95 Pierre wants to invite Louise to view his ``summer holidays`` photo album::
96
97 $ jp file share invite -P "photos/summer holidays" -t photos pierre@files.example.net
98 louise@example.org