Mercurial > libervia-backend

comparison doc/jp/common_arguments.rst @ 2946:ce16847a7b6d

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc: documentation first draft: this patch starts the local documentation, existing documentation will be imported from wiki/other places to this folder and updated. This doc is using reStructuredText format and will be generated with Sphinx.
author Goffi <goffi@goffi.org>
date Fri, 22 Feb 2019 18:58:59 +0100
parents
children 8fd8c9f548cd
comparison
equal deleted inserted replaced
2945:6c264c224614 2946:ce16847a7b6d
1 ================
2 common arguments
3 ================
4
5 Some arguments are used in many commands. This page describe them.
6
7 profile
8 =======
9
10 profile arguments are really common, they allow you to select your profile.
11 If you don't select any, the default profile is used, which is the first
12 profile created or the one you have explicitly set. You can check which profile
13 is used by default with ``jp profile default``.
14
15 The common arguments for profile are:
16
17 ``-p PROFILE, --profile PROFILE``
18 to select the name of your profile. It can be a profile key like ``@DEFAULT@``
19
20 ``-c, --connect``
21 connect the profile to the XMPP server before doing anything else. If your
22 profile is already connected, nothing happen. This is specially useful in scripts.
23
24 ``--start-session``
25 starts a session without connecting, this can be needed if you can't connect but
26 you need to access your session e.g. to change parameters.
27 This is advanced used and is not need in most common cases.
28
29 ``--pwd PASSWORD``
30 the password of your profile, needed if the session is not started yet.
31
32 .. note::
33
34 jp does not yet prompt for password when needed, this mean that using the ``--pwd``
35 option is not secure if you are not the only user of your machine: the password will
36 appear **IN CLEAR** in the list of launched process, or in the history of your shell.
37 If you are on a shared machine or if anybody can access your shell history at some
38 point, you should connect first your profile with an other frontend (Primitivus for
39 instance). This will be fixed in a future version of jp.
40
41 .. _pubsub_common:
42
43 pubsub
44 ======
45
46 pubsub arguments are used in many commands, they allow you to select a service, node and
47 items. Depending on the command, you may only not be able to select an item, or you may
48 select one or multiple items.
49
50 The common arguments for pubsub are:
51
52 ``-u PUBSUB_URL, --pubsub-url PUBSUB_URL``
53 retrieve pubsub information from an URL. You can use either and ``xmpp:`` scheme or an
54 ``https:`` (or ``http:``) scheme. In the later case, the HTML page will be downloaded to
55 retrieve the location of the XMPP node/item, if available.
56 Note that you can override parts of the location in the URL if you specify service, node
57 or item.
58
59 e.g.::
60
61 $ jp blog get -u https://www.goffi.org
62
63 ``-s SERVICE, --service``
64 used to specifiy the JID of the pubsub service
65
66 ``-n NODE, --node NODE``
67 used to specifiy the pubsub node
68
69 ``-i ITEM, --item ITEM``
70 for commands where an item can be specified, you do it with this option. In some
71 commands, multiple items can be specified, in this case just use this arguments several
72 times.
73
74 ``-L, --last-item``
75 when an item id is needed, you can use this option to retrieve the last published item.
76 e.g.::
77
78 $ jp blog edit --last-item
79
80 ``-M, --max-items``
81 use to specify a maxium number of items to retrieve, when it makes sense.
82 Note that this is using the pubsub max (i.e. defined in
83 `XEP-0060 <https://xmpp.org/extensions/xep-0060.html>`_). Modern pubsub services should
84 implement `Result Set Management <https://xmpp.org/extensions/xep-0059.html>`_ (RSM) and in
85 this case the ``-m, --max`` argument should be prefered. See below for RSM common
86 arguments.
87
88 result set management
89 =====================
90
91 Result Set Management (RSM) common arguments are used to navigate into pages of results
92 when lot of elements may be expected. Given a result with a large number of arguments, a
93 *page* is set of elements which correspond to an *index* (a page number). For instance if
94 you have 123 elements, you can ask them 10 by 10, and *index 1* match elements from 11 to
95 20 included.
96
97
98 ``-a ITEM_ID, --after ITEM_ID``
99 find page after this item. You usually use the last item id of the latest page you got.
100
101 ``-b ITEM_ID, --before ITEM_ID``
102 find page before this item. This this usually used when you check items backwards
103
104 ``--index RSM_INDEX``
105 index of the page to retrieve. Note that first page has index **0**.
106
107 ``-m RSM_MAX, --max RSM_MAX``
108 used to specify a maxium number of items to retrieve per page. Note that the actual
109 maximum number of items per page used may be lower if the service used consider that
110 your request is too big.
111
112 message archive management
113 ==========================
114
115 Message Archive Management (MAM) argument is used by some commands (related to instant message or
116 pubsub) to filter results.
117
118 There is currently only one argument in this group:
119
120 ``-f FILTER_NAME VALUE, --filter FILTER_NAME VALUE``
121 specify a MAM filter to use. Depending on the service supporting MAM, some filters can
122 be used to do things like full text search. The available filters depend on the service
123 you use, please check documentation of your service.
124
125 order-by
126 ========
127
128 Order-By argument specify or the returned elements are sorted.
129
130 There is currently only one argument in this group:
131
132 ``-o {creation,modification}, --order-by {creation,modification}``
133 specify how result is sorted. with ``creation``, first created element is returned
134 first. There is no notion of *creation* of *modification* in original
135 `pubsub XEP <https://xmpp.org/extensions/xep-0060.html>`_, as publishing an item with an
136 existing id will overwrite the older one, creating a new item. With this option, we use
137 the terms defined in `XEP-0413 <https://xmpp.org/extensions/xep-0413.html>`_, and
138 *creation* time is the time when the first item has been published, before being
139 overwritten.
140
141 In the case of ``modification``, if an item is overwritten, it reappears on top, this is
142 the default pubsub sorting order.
143
144 progress
145 ========
146
147 This single option may be used when a long operation is happening, like a file transfer.
148
149 ``-P, --progress``
150 Show progress bar.
151
152 verbose
153 =======
154
155 ``--verbose, -v``
156 Add a verbosity level (can be used multiple times). Use to have more concise output by
157 default when it makes sense.
158
159 draft
160 =====
161
162 Common arguments used when an edition is potentially long to do, and a file may be kept
163 until publication.
164
165
166 ``-D, --current``
167 Used when you have started to edit something (e.g. a blog post), which is not yet
168 published, and you want to continue your work.
169
170 e.g.::
171
172 $ jp blog edit -D
173
174 ``-F DRAFT_PATH, --draft-path DRAFT_PATH``
175 Used when you have started to edit something and want to continue your work from this
176 file. In other words, it's similar to ``-D, --current`` except that you specify the file
177 to use instead of using the last available draft.
178
179 output
180 ======
181
182 Output is used when you want to get the result of the command in a specific way. It may be
183 used, for instance, to retrieve the result formatted in JSON so the data can be easily
184 manipulated by a script, or if you want only a specific element of the result.
185
186 ``-O {…}, --output {…}``
187 specifiy the output to use. Available options depends of the command you are using,
188 check ``jp [your command] --help`` to know them.
189
190 e.g.::
191
192 $ jp blog get -O json
193
194 ``--output-option OUTPUT_OPTS, --oo OUTPUT_OPTS``
195 depending of the output selected, you may have options to customise the output.
196 For instance, if you use the ``template`` output, you may use an option to display the
197 result in a browser.
198
199 e.g.::
200
201 $ jp blog
202
203 Some options expect parameters, in this case they can be specified using ``=``.
204
205 e.g. specifiying a template to use::
206
207 $ jp blog get -O template --oo browser --oo template=/tmp/my_template.html