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