Mercurial > libervia-backend
annotate doc/jp/blog.rst @ 3013:860c550028d6
memory (sqlite): properly wait for messages to be writen in database:
the deferreds of the queries writing message to databases where not gathered and returned,
so the caller was not waiting for them to continue its workflow. This was resulting in
messages not always written when database was read just after the write (a case common
with MUC implementation), and message was appearing empty when sent to bridge.
fix 328
| author | Goffi <goffi@goffi.org> |
|---|---|
| date | Thu, 18 Jul 2019 21:58:34 +0200 |
| parents | 85d8e9a7284b |
| children | 8ec35cf13f66 |
| 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 | |
| 24 $ echo "This is post body" | jp blog set -T "This is a test message" -t test -t jp -C | |
| 25 | |
| 26 Create a blog post with rich content using `markdown` syntax, and no subject:: | |
| 27 | |
| 28 $ echo "This is a **rich** body" | jp blog set -S markdown | |
| 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 | |
| 36 output can be customised to only retrieve some keys, or to use a specific template. | |
| 37 | |
| 38 :ref:`pubsub_common` commands are used to specify the blog location. | |
| 39 | |
| 40 examples | |
| 41 -------- | |
| 42 | |
| 43 Retrieve personal blog of the profile using `fancy` output with a verbosity of 1 (to show | |
| 44 publication date):: | |
| 45 | |
| 46 $ jp blog get -O fancy -v | |
| 47 | |
| 48 Retrieve *title* and *publication date* of last 3 blog posts from the blog at | |
| 49 https://www.goffi.org:: | |
| 50 | |
| 51 $ jp blog get -m 3 -u https://www.goffi.org -k title -k published | |
| 52 | |
| 53 Retrieve last 2 posts of personal blog, and output them in browser using default | |
| 54 template:: | |
| 55 | |
| 56 $ jp blog get -m 2 -O template --oo browser | |
| 57 | |
| 58 edit | |
| 59 ==== | |
| 60 | |
| 61 With edit command you can create a new blog post or modify an existing one using your | |
| 62 local editor (the one set in ``$EDITOR``). You'll edit 2 things: the body of the post, and | |
| 63 the metadata which contain things like title, comments infos, or tags. | |
| 64 | |
| 65 For some common editors (like **vim** or **Emacs**), the editor will be automatially | |
| 66 opened using a split screen with *body* in one side, and metadata on the other. If the | |
| 67 editor is not supported or doesn't support split screen, you'll edit first the *body*, then | |
| 68 the *metadata*. You can also specify editor and arguments in ``sat.conf``, see | |
| 69 `configuration <edit_conf_>`_ below | |
| 70 | |
| 71 If you don't change anything or publish an empty blog post, the edition will be cancelled. | |
| 72 | |
| 73 In the metadata (see `below <edit_metadata_>`_ for details), you can use | |
| 74 ``"publish": false`` to forbid the publication. In this case, when you'll save | |
| 75 your modification and quit your editor, the blog post will not be published but | |
| 76 saved locally in a draft. To continue your work later, just start your edition with the | |
| 77 ``-D, --current`` option like this:: | |
| 78 | |
| 79 $ jp blog edit -D | |
| 80 | |
| 81 Note that item location must be re-specified if it has been used to create the draft, so | |
| 82 you'll have to reproduce the arguments to specify service, node or item (or the URL), | |
| 83 other data like tags will be restored from draft file of metadata. | |
| 84 | |
| 85 You can specify the syntax by using ``-S SYNTAX, --syntax SYNTAX``. If not specified, the | |
| 86 syntax set in your parameters will be used. | |
| 87 | |
| 88 When you edit a blog post, it is often useful to activate the ``-P, --preview`` option, | |
| 89 this will launch a web browser and refresh the page each time you save a modification in | |
| 90 your editor. By default, the browser registered as default in your system will be used, | |
| 91 and a new tab will be opened on each modification. This is not ideal, and we recommand to | |
| 92 set you configuration to activate automatic refreshing of the page instead, see `preview | |
| 93 configuration <edit_preview_>`_ below to see how to do. | |
| 94 | |
|
2999
85d8e9a7284b
doc (jp/blog): added note for --preview
Goffi <goffi@goffi.org>
parents:
2996
diff
changeset
|
95 .. note:: |
|
85d8e9a7284b
doc (jp/blog): added note for --preview
Goffi <goffi@goffi.org>
parents:
2996
diff
changeset
|
96 |
|
85d8e9a7284b
doc (jp/blog): added note for --preview
Goffi <goffi@goffi.org>
parents:
2996
diff
changeset
|
97 If --preview doesn't work, use ``jp blog preview`` (see below) to get error messages. |
|
85d8e9a7284b
doc (jp/blog): added note for --preview
Goffi <goffi@goffi.org>
parents:
2996
diff
changeset
|
98 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
|
99 |
| 2946 | 100 examples |
| 101 -------- | |
| 102 | |
| 103 Edit a new blog post with comments on your personal blog, using default syntax and preview:: | |
| 104 | |
| 105 $ jp blog edit -P --comments | |
| 106 | |
| 107 Modifiy a draft previously saved using the ``"publish": false`` metadata:: | |
| 108 | |
| 109 $ jp blog edit -D | |
| 110 | |
| 111 Correct a typo in your last published blog post:: | |
| 112 | |
| 113 $ jp blog edit --last-item | |
| 114 | |
| 115 Edit the blog item at an HTTPS URL using XHTML syntax:: | |
| 116 | |
| 117 $ jp blog edit -u https://www.example.net/some_xmpp_blog_article.html -S xhtml | |
| 118 | |
| 119 Create a new blog post on a XMPP blog node using its HTTPS URL (supposing here that | |
| 120 https://example.net is a XMPP blog node):: | |
| 121 | |
| 122 $ jp blog edit -u https://www.example.net | |
| 123 | |
| 124 .. _edit_metadata: | |
| 125 | |
| 126 metadata | |
| 127 -------- | |
| 128 | |
| 129 Metadata is set using a JSON object. The key you can use are: | |
| 130 | |
| 131 publish | |
| 132 boolean indicating if item can be published. Set to ``false`` if you want to work on a | |
| 133 draft and to avoid accidental publication. | |
| 134 | |
| 135 atom_id | |
| 136 atom entry identifier. This should not be modified manually. | |
| 137 | |
| 138 published | |
| 139 time of initial publication (unix time). This should not be modified manually. | |
| 140 | |
| 141 language | |
| 142 language of the content | |
| 143 | |
| 144 comments | |
| 145 array of URIs to the comments node, if any. | |
| 146 | |
| 147 tag | |
| 148 array of tags, if any | |
| 149 | |
| 150 author | |
| 151 human readable name of the entry author | |
| 152 | |
| 153 author_jid | |
| 154 jid of the author. This should notbe modified manually. | |
| 155 | |
| 156 author_jid_verified | |
| 157 true if the pubsub service confirmed that author_jid is the one of the publisher. It is | |
| 158 useless to modify this variable. | |
| 159 | |
| 160 title | |
| 161 the title of the message | |
| 162 | |
| 163 title_rich | |
| 164 the rich title of the message, in current text syntax. It will be automatically | |
| 165 converted to xhtml. | |
| 166 | |
| 167 .. _edit_conf: | |
| 168 | |
| 169 configuration | |
| 170 ------------- | |
| 171 | |
| 172 editor | |
| 173 ^^^^^^ | |
| 174 | |
| 175 Local editor used is by default the one set in ``$EDITOR`` environment variable, but you | |
| 176 can specify one in ``sat.conf``. To do so, you have to set the name of an editor | |
| 177 executable in the ``editor`` option in ``[jp]`` section. | |
| 178 | |
| 179 You can specify the args to use by using ``blog_editor_args`` option. Use | |
| 180 ``{content_file}`` to get the path of the main content file (the body of the blog post), | |
| 181 and ``{metadata_file}`` to get the path of the json metadata. | |
| 182 | |
| 183 .. sourcecode:: cfg | |
| 184 | |
| 185 [jp] | |
| 186 editor = kate | |
| 187 blog_editor_args = {content_file} {metadata_file} | |
| 188 | |
| 189 .. _edit_preview: | |
| 190 | |
| 191 preview | |
| 192 ^^^^^^^ | |
| 193 | |
| 194 To set the preview, you can use the options ``blog_preview_open_cmd`` and | |
| 195 ``blog_preview_update_cmd`` in your ``[jp]`` section. the former is the command to use to | |
| 196 open your browser when edition starts, and the later is the command to use when a | |
| 197 modification is saved. In both cases you may use ``{url}`` to set the location of local HTML file. | |
| 198 | |
|
2954
5e72efd2f95d
doc: minor fixes + use ".pot" extension instead of ".po" for template in README4TRANSLATORS
Goffi <goffi@goffi.org>
parents:
2946
diff
changeset
|
199 This can be used to activate automatic refreshing of the page. |
| 2946 | 200 |
| 201 For **Konqueror**, you can use its D-Bus API to do refreshing. Ensure that ``qdbus`` is | |
| 202 installed on your system, and enter the following lines in your ``sat.conf``: | |
| 203 | |
| 204 .. sourcecode:: cfg | |
| 205 | |
| 206 [jp] | |
| 207 blog_preview_open_cmd = konqueror {url} | |
| 208 blog_preview_update_cmd = /bin/sh -c "qdbus $(qdbus org.kde.konqueror\*) /konqueror/MainWindow_1 reload" | |
| 209 | |
| 210 For **Firefox**, you may use ``xdotool`` on X11. Once you have installed this tool, enter the | |
| 211 following lines in your ``sat.conf``: | |
| 212 | |
| 213 .. sourcecode:: cfg | |
| 214 | |
| 215 [jp] | |
| 216 blog_preview_open_cmd = firefox -new-tab {url} | |
| 217 blog_preview_update_cmd = /bin/sh -c "WID=$(xdotool search --name 'Mozilla Firefox' | head -1); xdotool windowactivate $WID; xdotool key F5" | |
| 218 | |
| 219 This *xdotool* technique can be adapted to other browsers. | |
| 220 | |
| 221 syntax extensions | |
| 222 ^^^^^^^^^^^^^^^^^^ | |
| 223 | |
| 224 A dictionary with a mapping from syntax name to file extension can be used. This can be | |
| 225 useful to activate the right syntax highlighting in your editor. There is a default | |
| 226 mapping which can be overriden. | |
| 227 | |
| 228 The mapping is set in the ``syntax_ext_dict`` option of the ``[jp]`` section of your | |
| 229 ``sat.conf`` file. For instance, if your prefer do your ``.markdown`` for temp files | |
| 230 instead of the default ``.md``, you can use this: | |
| 231 | |
| 232 .. sourcecode:: cfg | |
| 233 | |
| 234 [jp] | |
| 235 syntax_ext_dict = {"markdown": "markdown"} | |
| 236 | |
|
2954
5e72efd2f95d
doc: minor fixes + use ".pot" extension instead of ".po" for template in README4TRANSLATORS
Goffi <goffi@goffi.org>
parents:
2946
diff
changeset
|
237 the first ``markdown`` is the name of the syntax (could be an other syntax like ``xhtml``), |
| 2946 | 238 while the second if the file extension. |
| 239 | |
| 240 preview | |
| 241 ======= | |
| 242 | |
| 243 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
|
244 detected. Configuration is the same as for `edit preview <edit_preview_>`_. This can be |
| 2946 | 245 used if you have already started an edition with ``jp blog edit`` but forgot to use the ``-P, --preview`` arguments. |
| 246 | |
| 247 example: | |
| 248 -------- | |
| 249 | |
| 250 Preview the draft at ``~/local/sat/blog/some_name/blog_something.md``:: | |
| 251 | |
| 252 $ jp blog preview ~/local/sat/blog/some_name/blog_something.md | |
| 253 | |
| 254 import | |
| 255 ====== | |
| 256 | |
| 257 With this command you can import an external blog in a XMPP blog at the specified pubsub | |
| 258 location. | |
| 259 | |
| 260 The import is done using an *importer* name and a *location* which depends of the importer | |
| 2996 | 261 (it can be a path to a file, an URL to a blog, or something else). Let empty to get list |
| 262 of importers, and specify only importer name to get its description. | |
| 2946 | 263 |
| 264 By default, found images are re-uploaded to XMPP server, if you want to keep original | |
| 265 URLs, use the ``--no-images-upload`` option. | |
| 266 | |
| 267 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. | |
| 268 | |
| 269 You shoud specify original blog host using ``--host HOST`` argument, this is used notably | |
| 270 to reconstruct relative URLs of media. | |
| 271 | |
| 272 Importers may have specific options, you can set them using the ``-o NAME VALUE, --option NAME VALUE`` argument. Check the importer description for details. | |
| 273 | |
| 274 examples: | |
| 275 --------- | |
| 276 | |
| 277 List available importers:: | |
| 278 | |
| 279 $ jp blog import | |
| 280 | |
| 281 Get description of ``dotclear`` importer:: | |
| 282 | |
| 283 $ jp blog import dotclear | |
| 284 | |
| 285 Import a Dotclear blog:: | |
| 286 | |
| 287 $ jp blog import dotclear /path/to/dotclear.dump | |
| 288 | |
| 289 Import a Dotclear blog without uploading images:: | |
| 290 | |
| 291 $ jp blog import --no-images-upload dotclear /path/to/dotclear.dump |