Mercurial > libervia-backend
annotate doc/libervia-cli/blog.rst @ 3652:6e34307319c0
plugin XEP-0353: fix jingle initiation on disco "Service Unavailable" error:
When requesting disco info on a bare jid which is not in our roster, server may return
"Service Unavailable" (to avoid leaking valid JIDs). In this case, the initiation was
failing, this is now fixed by using empty categories in this case.
author | Goffi <goffi@goffi.org> |
---|---|
date | Wed, 08 Sep 2021 11:16:52 +0200 |
parents | 267e4987b58b |
children | 76fb0739cc9c |
rev | line source |
---|---|
2946 | 1 .. highlight:: sh |
2 | |
3 ================================ | |
4 blog: (micro)blogging management | |
5 ================================ | |
6 | |
7 Blog commands are high level tools to handle an XMPP blog. | |
8 They are using the generic pubsub arguments | |
9 | |
10 set | |
11 === | |
12 | |
13 publish a blog item. | |
14 | |
15 :ref:`pubsub_common` commands are used to specify the destination item. | |
16 | |
17 ``stdin`` is used to get the body of the blog post. | |
18 | |
19 examples | |
20 -------- | |
21 | |
22 Create a blog post with a body, a subject, 2 tags, and with comments allowed:: | |
23 | |
3488
c80a0f864b5d
doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents:
3177
diff
changeset
|
24 $ echo "This is post body" | li blog set -T "This is a test message" -t test -t li -C |
2946 | 25 |
26 Create a blog post with rich content using `markdown` syntax, and no subject:: | |
27 | |
3488
c80a0f864b5d
doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents:
3177
diff
changeset
|
28 $ echo "This is a **rich** body" | li blog set -S markdown |
2946 | 29 |
30 get | |
31 === | |
32 | |
2954
5e72efd2f95d
doc: minor fixes + use ".pot" extension instead of ".po" for template in README4TRANSLATORS
Goffi <goffi@goffi.org>
parents:
2946
diff
changeset
|
33 get command retrieves one or more blog post(s) from specified location (by default the |
2946 | 34 personal blog of the profile). |
35 | |
3021
8ec35cf13f66
doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
2999
diff
changeset
|
36 output can be customised to only retrieve some keys, or to use a specific template. For |
8ec35cf13f66
doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
2999
diff
changeset
|
37 instance, the following command retrieves only the title and publication date of the |
8ec35cf13f66
doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
2999
diff
changeset
|
38 personal blog of the profile:: |
8ec35cf13f66
doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
2999
diff
changeset
|
39 |
3488
c80a0f864b5d
doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents:
3177
diff
changeset
|
40 $ li blog get -k title -k published |
2946 | 41 |
42 :ref:`pubsub_common` commands are used to specify the blog location. | |
43 | |
44 examples | |
45 -------- | |
46 | |
47 Retrieve personal blog of the profile using `fancy` output with a verbosity of 1 (to show | |
48 publication date):: | |
49 | |
3488
c80a0f864b5d
doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents:
3177
diff
changeset
|
50 $ li blog get -O fancy -v |
2946 | 51 |
52 Retrieve *title* and *publication date* of last 3 blog posts from the blog at | |
53 https://www.goffi.org:: | |
54 | |
3488
c80a0f864b5d
doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents:
3177
diff
changeset
|
55 $ li blog get -m 3 -u https://www.goffi.org -k title -k published |
2946 | 56 |
57 Retrieve last 2 posts of personal blog, and output them in browser using default | |
58 template:: | |
59 | |
3488
c80a0f864b5d
doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents:
3177
diff
changeset
|
60 $ li blog get -m 2 -O template --oo browser |
2946 | 61 |
3488
c80a0f864b5d
doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents:
3177
diff
changeset
|
62 .. _libervia-cli_blog_edit: |
3041
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
3021
diff
changeset
|
63 |
2946 | 64 edit |
65 ==== | |
66 | |
67 With edit command you can create a new blog post or modify an existing one using your | |
68 local editor (the one set in ``$EDITOR``). You'll edit 2 things: the body of the post, and | |
69 the metadata which contain things like title, comments infos, or tags. | |
70 | |
71 For some common editors (like **vim** or **Emacs**), the editor will be automatially | |
72 opened using a split screen with *body* in one side, and metadata on the other. If the | |
73 editor is not supported or doesn't support split screen, you'll edit first the *body*, then | |
3536
0985c47ffd96
doc: config file is now `libervia.conf` (even if `sat.conf` still works, for now)
Goffi <goffi@goffi.org>
parents:
3488
diff
changeset
|
74 the *metadata*. You can also specify editor and arguments in ``libervia.conf``, see |
2946 | 75 `configuration <edit_conf_>`_ below |
76 | |
77 If you don't change anything or publish an empty blog post, the edition will be cancelled. | |
78 | |
3177
f4914ce9d47d
jp (blog/edit): added `--no-publish` argument.
Goffi <goffi@goffi.org>
parents:
3041
diff
changeset
|
79 In the metadata (see `below <edit_metadata_>`_ for details), you can use ``"publish": |
f4914ce9d47d
jp (blog/edit): added `--no-publish` argument.
Goffi <goffi@goffi.org>
parents:
3041
diff
changeset
|
80 false`` to forbid the publication (or set it with ``--no-publish argument``). In this |
f4914ce9d47d
jp (blog/edit): added `--no-publish` argument.
Goffi <goffi@goffi.org>
parents:
3041
diff
changeset
|
81 case, when you'll save your modification and quit your editor, the blog post will not be |
f4914ce9d47d
jp (blog/edit): added `--no-publish` argument.
Goffi <goffi@goffi.org>
parents:
3041
diff
changeset
|
82 published but saved locally in a draft. To continue your work later, just start your |
f4914ce9d47d
jp (blog/edit): added `--no-publish` argument.
Goffi <goffi@goffi.org>
parents:
3041
diff
changeset
|
83 edition with the ``-D, --current`` option like this:: |
2946 | 84 |
3488
c80a0f864b5d
doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents:
3177
diff
changeset
|
85 $ li blog edit -D |
2946 | 86 |
87 Note that item location must be re-specified if it has been used to create the draft, so | |
88 you'll have to reproduce the arguments to specify service, node or item (or the URL), | |
89 other data like tags will be restored from draft file of metadata. | |
90 | |
91 You can specify the syntax by using ``-S SYNTAX, --syntax SYNTAX``. If not specified, the | |
92 syntax set in your parameters will be used. | |
93 | |
94 When you edit a blog post, it is often useful to activate the ``-P, --preview`` option, | |
95 this will launch a web browser and refresh the page each time you save a modification in | |
96 your editor. By default, the browser registered as default in your system will be used, | |
97 and a new tab will be opened on each modification. This is not ideal, and we recommand to | |
98 set you configuration to activate automatic refreshing of the page instead, see `preview | |
99 configuration <edit_preview_>`_ below to see how to do. | |
100 | |
2999
85d8e9a7284b
doc (jp/blog): added note for --preview
Goffi <goffi@goffi.org>
parents:
2996
diff
changeset
|
101 .. note:: |
85d8e9a7284b
doc (jp/blog): added note for --preview
Goffi <goffi@goffi.org>
parents:
2996
diff
changeset
|
102 |
3488
c80a0f864b5d
doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents:
3177
diff
changeset
|
103 If --preview doesn't work, use ``li blog preview`` (see below) to get error messages. |
2999
85d8e9a7284b
doc (jp/blog): added note for --preview
Goffi <goffi@goffi.org>
parents:
2996
diff
changeset
|
104 On GNU/Linux, Be sure that inotify Python module is installed correctly. |
85d8e9a7284b
doc (jp/blog): added note for --preview
Goffi <goffi@goffi.org>
parents:
2996
diff
changeset
|
105 |
2946 | 106 examples |
107 -------- | |
108 | |
109 Edit a new blog post with comments on your personal blog, using default syntax and preview:: | |
110 | |
3488
c80a0f864b5d
doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents:
3177
diff
changeset
|
111 $ li blog edit -P --comments |
2946 | 112 |
113 Modifiy a draft previously saved using the ``"publish": false`` metadata:: | |
114 | |
3488
c80a0f864b5d
doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents:
3177
diff
changeset
|
115 $ li blog edit -D |
2946 | 116 |
117 Correct a typo in your last published blog post:: | |
118 | |
3488
c80a0f864b5d
doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents:
3177
diff
changeset
|
119 $ li blog edit --last-item |
2946 | 120 |
121 Edit the blog item at an HTTPS URL using XHTML syntax:: | |
122 | |
3488
c80a0f864b5d
doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents:
3177
diff
changeset
|
123 $ li blog edit -u https://www.example.net/some_xmpp_blog_article.html -S xhtml |
2946 | 124 |
125 Create a new blog post on a XMPP blog node using its HTTPS URL (supposing here that | |
126 https://example.net is a XMPP blog node):: | |
127 | |
3488
c80a0f864b5d
doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents:
3177
diff
changeset
|
128 $ li blog edit -u https://www.example.net |
2946 | 129 |
130 .. _edit_metadata: | |
131 | |
132 metadata | |
133 -------- | |
134 | |
135 Metadata is set using a JSON object. The key you can use are: | |
136 | |
137 publish | |
138 boolean indicating if item can be published. Set to ``false`` if you want to work on a | |
139 draft and to avoid accidental publication. | |
140 | |
141 atom_id | |
142 atom entry identifier. This should not be modified manually. | |
143 | |
144 published | |
145 time of initial publication (unix time). This should not be modified manually. | |
146 | |
147 language | |
148 language of the content | |
149 | |
150 comments | |
151 array of URIs to the comments node, if any. | |
152 | |
153 tag | |
154 array of tags, if any | |
155 | |
156 author | |
157 human readable name of the entry author | |
158 | |
159 author_jid | |
160 jid of the author. This should notbe modified manually. | |
161 | |
162 author_jid_verified | |
163 true if the pubsub service confirmed that author_jid is the one of the publisher. It is | |
164 useless to modify this variable. | |
165 | |
166 title | |
167 the title of the message | |
168 | |
169 title_rich | |
170 the rich title of the message, in current text syntax. It will be automatically | |
171 converted to xhtml. | |
172 | |
173 .. _edit_conf: | |
174 | |
175 configuration | |
176 ------------- | |
177 | |
178 editor | |
179 ^^^^^^ | |
180 | |
181 Local editor used is by default the one set in ``$EDITOR`` environment variable, but you | |
3536
0985c47ffd96
doc: config file is now `libervia.conf` (even if `sat.conf` still works, for now)
Goffi <goffi@goffi.org>
parents:
3488
diff
changeset
|
182 can specify one in ``libervia.conf``. To do so, you have to set the name of an editor |
3488
c80a0f864b5d
doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents:
3177
diff
changeset
|
183 executable in the ``editor`` option in ``[li]`` section. |
2946 | 184 |
185 You can specify the args to use by using ``blog_editor_args`` option. Use | |
186 ``{content_file}`` to get the path of the main content file (the body of the blog post), | |
187 and ``{metadata_file}`` to get the path of the json metadata. | |
188 | |
189 .. sourcecode:: cfg | |
190 | |
3488
c80a0f864b5d
doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents:
3177
diff
changeset
|
191 [li] |
2946 | 192 editor = kate |
193 blog_editor_args = {content_file} {metadata_file} | |
194 | |
195 .. _edit_preview: | |
196 | |
197 preview | |
198 ^^^^^^^ | |
199 | |
200 To set the preview, you can use the options ``blog_preview_open_cmd`` and | |
3488
c80a0f864b5d
doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents:
3177
diff
changeset
|
201 ``blog_preview_update_cmd`` in your ``[li]`` section. the former is the command to use to |
2946 | 202 open your browser when edition starts, and the later is the command to use when a |
203 modification is saved. In both cases you may use ``{url}`` to set the location of local HTML file. | |
204 | |
2954
5e72efd2f95d
doc: minor fixes + use ".pot" extension instead of ".po" for template in README4TRANSLATORS
Goffi <goffi@goffi.org>
parents:
2946
diff
changeset
|
205 This can be used to activate automatic refreshing of the page. |
2946 | 206 |
207 For **Konqueror**, you can use its D-Bus API to do refreshing. Ensure that ``qdbus`` is | |
3536
0985c47ffd96
doc: config file is now `libervia.conf` (even if `sat.conf` still works, for now)
Goffi <goffi@goffi.org>
parents:
3488
diff
changeset
|
208 installed on your system, and enter the following lines in your ``libervia.conf``: |
2946 | 209 |
210 .. sourcecode:: cfg | |
211 | |
3488
c80a0f864b5d
doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents:
3177
diff
changeset
|
212 [li] |
2946 | 213 blog_preview_open_cmd = konqueror {url} |
214 blog_preview_update_cmd = /bin/sh -c "qdbus $(qdbus org.kde.konqueror\*) /konqueror/MainWindow_1 reload" | |
215 | |
216 For **Firefox**, you may use ``xdotool`` on X11. Once you have installed this tool, enter the | |
3536
0985c47ffd96
doc: config file is now `libervia.conf` (even if `sat.conf` still works, for now)
Goffi <goffi@goffi.org>
parents:
3488
diff
changeset
|
217 following lines in your ``libervia.conf``: |
2946 | 218 |
219 .. sourcecode:: cfg | |
220 | |
3488
c80a0f864b5d
doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents:
3177
diff
changeset
|
221 [li] |
2946 | 222 blog_preview_open_cmd = firefox -new-tab {url} |
223 blog_preview_update_cmd = /bin/sh -c "WID=$(xdotool search --name 'Mozilla Firefox' | head -1); xdotool windowactivate $WID; xdotool key F5" | |
224 | |
225 This *xdotool* technique can be adapted to other browsers. | |
226 | |
227 syntax extensions | |
228 ^^^^^^^^^^^^^^^^^^ | |
229 | |
230 A dictionary with a mapping from syntax name to file extension can be used. This can be | |
231 useful to activate the right syntax highlighting in your editor. There is a default | |
232 mapping which can be overriden. | |
233 | |
3488
c80a0f864b5d
doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents:
3177
diff
changeset
|
234 The mapping is set in the ``syntax_ext_dict`` option of the ``[li]`` section of your |
3536
0985c47ffd96
doc: config file is now `libervia.conf` (even if `sat.conf` still works, for now)
Goffi <goffi@goffi.org>
parents:
3488
diff
changeset
|
235 ``libervia.conf`` file. For instance, if your prefer do your ``.markdown`` for temp files |
2946 | 236 instead of the default ``.md``, you can use this: |
237 | |
238 .. sourcecode:: cfg | |
239 | |
3488
c80a0f864b5d
doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents:
3177
diff
changeset
|
240 [li] |
2946 | 241 syntax_ext_dict = {"markdown": "markdown"} |
242 | |
2954
5e72efd2f95d
doc: minor fixes + use ".pot" extension instead of ".po" for template in README4TRANSLATORS
Goffi <goffi@goffi.org>
parents:
2946
diff
changeset
|
243 the first ``markdown`` is the name of the syntax (could be an other syntax like ``xhtml``), |
2946 | 244 while the second if the file extension. |
245 | |
3563
267e4987b58b
doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents:
3536
diff
changeset
|
246 rename |
267e4987b58b
doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents:
3536
diff
changeset
|
247 ====== |
267e4987b58b
doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents:
3536
diff
changeset
|
248 |
267e4987b58b
doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents:
3536
diff
changeset
|
249 Move a item to a new ID. This works the same as :ref:`li-pubsub_rename`, the only |
267e4987b58b
doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents:
3536
diff
changeset
|
250 difference is that node defaults to microblog default namespace. |
267e4987b58b
doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents:
3536
diff
changeset
|
251 |
267e4987b58b
doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents:
3536
diff
changeset
|
252 example |
267e4987b58b
doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents:
3536
diff
changeset
|
253 ------- |
267e4987b58b
doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents:
3536
diff
changeset
|
254 |
267e4987b58b
doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents:
3536
diff
changeset
|
255 After a typo, a use want to rename the blog item with ID ``my_great_tittle_123a`` to |
267e4987b58b
doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents:
3536
diff
changeset
|
256 ``my_great_title_123a``:: |
267e4987b58b
doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents:
3536
diff
changeset
|
257 |
267e4987b58b
doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents:
3536
diff
changeset
|
258 $ li blog rename -i my_great_tittle_123a my_great_title_123a |
267e4987b58b
doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents:
3536
diff
changeset
|
259 |
2946 | 260 preview |
261 ======= | |
262 | |
263 This command will show the specified file in browser, and refresh it when changes are | |
2954
5e72efd2f95d
doc: minor fixes + use ".pot" extension instead of ".po" for template in README4TRANSLATORS
Goffi <goffi@goffi.org>
parents:
2946
diff
changeset
|
264 detected. Configuration is the same as for `edit preview <edit_preview_>`_. This can be |
3488
c80a0f864b5d
doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents:
3177
diff
changeset
|
265 used if you have already started an edition with ``li blog edit`` but forgot to use the ``-P, --preview`` arguments. |
2946 | 266 |
3563
267e4987b58b
doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents:
3536
diff
changeset
|
267 example |
267e4987b58b
doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents:
3536
diff
changeset
|
268 ------- |
2946 | 269 |
3563
267e4987b58b
doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents:
3536
diff
changeset
|
270 Preview the draft at ``~/.local/share/libervia/blog/some_name/blog_something.md``:: |
2946 | 271 |
3563
267e4987b58b
doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents:
3536
diff
changeset
|
272 $ li blog preview ~/.local/share/libervia/blog/some_name/blog_something.md |
2946 | 273 |
3488
c80a0f864b5d
doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents:
3177
diff
changeset
|
274 .. _libervia-cli_blog_import: |
3041
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
3021
diff
changeset
|
275 |
2946 | 276 import |
277 ====== | |
278 | |
279 With this command you can import an external blog in a XMPP blog at the specified pubsub | |
280 location. | |
281 | |
282 The import is done using an *importer* name and a *location* which depends of the importer | |
2996 | 283 (it can be a path to a file, an URL to a blog, or something else). Let empty to get list |
284 of importers, and specify only importer name to get its description. | |
2946 | 285 |
286 By default, found images are re-uploaded to XMPP server, if you want to keep original | |
287 URLs, use the ``--no-images-upload`` option. | |
288 | |
289 Alternatively, you can re-upload images except for a specific host with ``--upload-ignore-host UPLOAD_IGNORE_HOST``. The images for the specified host will keep there original URLs while other will be uploaded to XMPP server. | |
290 | |
291 You shoud specify original blog host using ``--host HOST`` argument, this is used notably | |
292 to reconstruct relative URLs of media. | |
293 | |
294 Importers may have specific options, you can set them using the ``-o NAME VALUE, --option NAME VALUE`` argument. Check the importer description for details. | |
295 | |
296 examples: | |
297 --------- | |
298 | |
299 List available importers:: | |
300 | |
3488
c80a0f864b5d
doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents:
3177
diff
changeset
|
301 $ li blog import |
2946 | 302 |
303 Get description of ``dotclear`` importer:: | |
304 | |
3488
c80a0f864b5d
doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents:
3177
diff
changeset
|
305 $ li blog import dotclear |
2946 | 306 |
307 Import a Dotclear blog:: | |
308 | |
3488
c80a0f864b5d
doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents:
3177
diff
changeset
|
309 $ li blog import dotclear /path/to/dotclear.dump |
2946 | 310 |
311 Import a Dotclear blog without uploading images:: | |
312 | |
3488
c80a0f864b5d
doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents:
3177
diff
changeset
|
313 $ li blog import --no-images-upload dotclear /path/to/dotclear.dump |