Mercurial > libervia-backend
annotate doc/jp/blog.rst @ 2987:8990ed9aad31
quick_frontend (contact list): fixed `nick` use for groupchat:
during the profile connection workflow, joined rooms are retrieved, then presence are
filled, all asynchronously. In some cases, all rooms may not be joined when presence are
filled, resulting in cache being already filled with a `nick` when cache is set for the
room itself. Because of that, a `nick` may be displayed in contact list instead of MUC local
part. This patch fixes it by removing `nick` if it exists when cache a MUC room.
fix 305
| author | Goffi <goffi@goffi.org> |
|---|---|
| date | Fri, 05 Jul 2019 15:58:15 +0200 |
| parents | 5e72efd2f95d |
| children | afad95f257c7 |
| 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 | |
| 95 examples | |
| 96 -------- | |
| 97 | |
| 98 Edit a new blog post with comments on your personal blog, using default syntax and preview:: | |
| 99 | |
| 100 $ jp blog edit -P --comments | |
| 101 | |
| 102 Modifiy a draft previously saved using the ``"publish": false`` metadata:: | |
| 103 | |
| 104 $ jp blog edit -D | |
| 105 | |
| 106 Correct a typo in your last published blog post:: | |
| 107 | |
| 108 $ jp blog edit --last-item | |
| 109 | |
| 110 Edit the blog item at an HTTPS URL using XHTML syntax:: | |
| 111 | |
| 112 $ jp blog edit -u https://www.example.net/some_xmpp_blog_article.html -S xhtml | |
| 113 | |
| 114 Create a new blog post on a XMPP blog node using its HTTPS URL (supposing here that | |
| 115 https://example.net is a XMPP blog node):: | |
| 116 | |
| 117 $ jp blog edit -u https://www.example.net | |
| 118 | |
| 119 .. _edit_metadata: | |
| 120 | |
| 121 metadata | |
| 122 -------- | |
| 123 | |
| 124 Metadata is set using a JSON object. The key you can use are: | |
| 125 | |
| 126 publish | |
| 127 boolean indicating if item can be published. Set to ``false`` if you want to work on a | |
| 128 draft and to avoid accidental publication. | |
| 129 | |
| 130 atom_id | |
| 131 atom entry identifier. This should not be modified manually. | |
| 132 | |
| 133 published | |
| 134 time of initial publication (unix time). This should not be modified manually. | |
| 135 | |
| 136 language | |
| 137 language of the content | |
| 138 | |
| 139 comments | |
| 140 array of URIs to the comments node, if any. | |
| 141 | |
| 142 tag | |
| 143 array of tags, if any | |
| 144 | |
| 145 author | |
| 146 human readable name of the entry author | |
| 147 | |
| 148 author_jid | |
| 149 jid of the author. This should notbe modified manually. | |
| 150 | |
| 151 author_jid_verified | |
| 152 true if the pubsub service confirmed that author_jid is the one of the publisher. It is | |
| 153 useless to modify this variable. | |
| 154 | |
| 155 title | |
| 156 the title of the message | |
| 157 | |
| 158 title_rich | |
| 159 the rich title of the message, in current text syntax. It will be automatically | |
| 160 converted to xhtml. | |
| 161 | |
| 162 .. _edit_conf: | |
| 163 | |
| 164 configuration | |
| 165 ------------- | |
| 166 | |
| 167 editor | |
| 168 ^^^^^^ | |
| 169 | |
| 170 Local editor used is by default the one set in ``$EDITOR`` environment variable, but you | |
| 171 can specify one in ``sat.conf``. To do so, you have to set the name of an editor | |
| 172 executable in the ``editor`` option in ``[jp]`` section. | |
| 173 | |
| 174 You can specify the args to use by using ``blog_editor_args`` option. Use | |
| 175 ``{content_file}`` to get the path of the main content file (the body of the blog post), | |
| 176 and ``{metadata_file}`` to get the path of the json metadata. | |
| 177 | |
| 178 .. sourcecode:: cfg | |
| 179 | |
| 180 [jp] | |
| 181 editor = kate | |
| 182 blog_editor_args = {content_file} {metadata_file} | |
| 183 | |
| 184 .. _edit_preview: | |
| 185 | |
| 186 preview | |
| 187 ^^^^^^^ | |
| 188 | |
| 189 To set the preview, you can use the options ``blog_preview_open_cmd`` and | |
| 190 ``blog_preview_update_cmd`` in your ``[jp]`` section. the former is the command to use to | |
| 191 open your browser when edition starts, and the later is the command to use when a | |
| 192 modification is saved. In both cases you may use ``{url}`` to set the location of local HTML file. | |
| 193 | |
|
2954
5e72efd2f95d
doc: minor fixes + use ".pot" extension instead of ".po" for template in README4TRANSLATORS
Goffi <goffi@goffi.org>
parents:
2946
diff
changeset
|
194 This can be used to activate automatic refreshing of the page. |
| 2946 | 195 |
| 196 For **Konqueror**, you can use its D-Bus API to do refreshing. Ensure that ``qdbus`` is | |
| 197 installed on your system, and enter the following lines in your ``sat.conf``: | |
| 198 | |
| 199 .. sourcecode:: cfg | |
| 200 | |
| 201 [jp] | |
| 202 blog_preview_open_cmd = konqueror {url} | |
| 203 blog_preview_update_cmd = /bin/sh -c "qdbus $(qdbus org.kde.konqueror\*) /konqueror/MainWindow_1 reload" | |
| 204 | |
| 205 For **Firefox**, you may use ``xdotool`` on X11. Once you have installed this tool, enter the | |
| 206 following lines in your ``sat.conf``: | |
| 207 | |
| 208 .. sourcecode:: cfg | |
| 209 | |
| 210 [jp] | |
| 211 blog_preview_open_cmd = firefox -new-tab {url} | |
| 212 blog_preview_update_cmd = /bin/sh -c "WID=$(xdotool search --name 'Mozilla Firefox' | head -1); xdotool windowactivate $WID; xdotool key F5" | |
| 213 | |
| 214 This *xdotool* technique can be adapted to other browsers. | |
| 215 | |
| 216 syntax extensions | |
| 217 ^^^^^^^^^^^^^^^^^^ | |
| 218 | |
| 219 A dictionary with a mapping from syntax name to file extension can be used. This can be | |
| 220 useful to activate the right syntax highlighting in your editor. There is a default | |
| 221 mapping which can be overriden. | |
| 222 | |
| 223 The mapping is set in the ``syntax_ext_dict`` option of the ``[jp]`` section of your | |
| 224 ``sat.conf`` file. For instance, if your prefer do your ``.markdown`` for temp files | |
| 225 instead of the default ``.md``, you can use this: | |
| 226 | |
| 227 .. sourcecode:: cfg | |
| 228 | |
| 229 [jp] | |
| 230 syntax_ext_dict = {"markdown": "markdown"} | |
| 231 | |
|
2954
5e72efd2f95d
doc: minor fixes + use ".pot" extension instead of ".po" for template in README4TRANSLATORS
Goffi <goffi@goffi.org>
parents:
2946
diff
changeset
|
232 the first ``markdown`` is the name of the syntax (could be an other syntax like ``xhtml``), |
| 2946 | 233 while the second if the file extension. |
| 234 | |
| 235 preview | |
| 236 ======= | |
| 237 | |
| 238 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
|
239 detected. Configuration is the same as for `edit preview <edit_preview_>`_. This can be |
| 2946 | 240 used if you have already started an edition with ``jp blog edit`` but forgot to use the ``-P, --preview`` arguments. |
| 241 | |
| 242 example: | |
| 243 -------- | |
| 244 | |
| 245 Preview the draft at ``~/local/sat/blog/some_name/blog_something.md``:: | |
| 246 | |
| 247 $ jp blog preview ~/local/sat/blog/some_name/blog_something.md | |
| 248 | |
| 249 import | |
| 250 ====== | |
| 251 | |
| 252 With this command you can import an external blog in a XMPP blog at the specified pubsub | |
| 253 location. | |
| 254 | |
| 255 The import is done using an *importer* name and a *location* which depends of the importer | |
| 256 (it can be a path to a file, an URL to a blog, or something else). Use empty nothing to | |
| 257 get list of importers, and specify only importer name to get its description. | |
| 258 | |
| 259 By default, found images are re-uploaded to XMPP server, if you want to keep original | |
| 260 URLs, use the ``--no-images-upload`` option. | |
| 261 | |
| 262 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. | |
| 263 | |
| 264 You shoud specify original blog host using ``--host HOST`` argument, this is used notably | |
| 265 to reconstruct relative URLs of media. | |
| 266 | |
| 267 Importers may have specific options, you can set them using the ``-o NAME VALUE, --option NAME VALUE`` argument. Check the importer description for details. | |
| 268 | |
| 269 examples: | |
| 270 --------- | |
| 271 | |
| 272 List available importers:: | |
| 273 | |
| 274 $ jp blog import | |
| 275 | |
| 276 Get description of ``dotclear`` importer:: | |
| 277 | |
| 278 $ jp blog import dotclear | |
| 279 | |
| 280 Import a Dotclear blog:: | |
| 281 | |
| 282 $ jp blog import dotclear /path/to/dotclear.dump | |
| 283 | |
| 284 Import a Dotclear blog without uploading images:: | |
| 285 | |
| 286 $ jp blog import --no-images-upload dotclear /path/to/dotclear.dump |