Mercurial > libervia-backend
annotate doc/libervia-cli/blog.rst @ 3606:25d3677701e7
doc: developer documentation explaining storage and pubsub cache
author | Goffi <goffi@goffi.org> |
---|---|
date | Thu, 29 Jul 2021 22:51:01 +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 |