Mercurial > libervia-backend
annotate doc/jp/blog.rst @ 3317:83f25da66bec
core (memory): files are now public by default except for those in root directory:
using public permissions by default makes permissions change more easy as we don't have to
recursively change all permissions of sub files when changing directory. Root directories
are private by default.
| author | Goffi <goffi@goffi.org> |
|---|---|
| date | Sat, 01 Aug 2020 16:02:41 +0200 |
| parents | f4914ce9d47d |
| children |
| 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 | |
|
3041
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
3021
diff
changeset
|
62 .. _jp-blog_edit: |
|
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 | |
| 74 the *metadata*. You can also specify editor and arguments in ``sat.conf``, see | |
| 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 |
| 85 $ jp blog edit -D | |
| 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 |
|
85d8e9a7284b
doc (jp/blog): added note for --preview
Goffi <goffi@goffi.org>
parents:
2996
diff
changeset
|
103 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
|
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 | |
| 111 $ jp blog edit -P --comments | |
| 112 | |
| 113 Modifiy a draft previously saved using the ``"publish": false`` metadata:: | |
| 114 | |
| 115 $ jp blog edit -D | |
| 116 | |
| 117 Correct a typo in your last published blog post:: | |
| 118 | |
| 119 $ jp blog edit --last-item | |
| 120 | |
| 121 Edit the blog item at an HTTPS URL using XHTML syntax:: | |
| 122 | |
| 123 $ jp blog edit -u https://www.example.net/some_xmpp_blog_article.html -S xhtml | |
| 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 | |
| 128 $ jp blog edit -u https://www.example.net | |
| 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 | |
| 182 can specify one in ``sat.conf``. To do so, you have to set the name of an editor | |
| 183 executable in the ``editor`` option in ``[jp]`` section. | |
| 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 | |
| 191 [jp] | |
| 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 | |
| 201 ``blog_preview_update_cmd`` in your ``[jp]`` section. the former is the command to use to | |
| 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 | |
| 208 installed on your system, and enter the following lines in your ``sat.conf``: | |
| 209 | |
| 210 .. sourcecode:: cfg | |
| 211 | |
| 212 [jp] | |
| 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 | |
| 217 following lines in your ``sat.conf``: | |
| 218 | |
| 219 .. sourcecode:: cfg | |
| 220 | |
| 221 [jp] | |
| 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 | |
| 234 The mapping is set in the ``syntax_ext_dict`` option of the ``[jp]`` section of your | |
| 235 ``sat.conf`` file. For instance, if your prefer do your ``.markdown`` for temp files | |
| 236 instead of the default ``.md``, you can use this: | |
| 237 | |
| 238 .. sourcecode:: cfg | |
| 239 | |
| 240 [jp] | |
| 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 | |
| 246 preview | |
| 247 ======= | |
| 248 | |
| 249 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
|
250 detected. Configuration is the same as for `edit preview <edit_preview_>`_. This can be |
| 2946 | 251 used if you have already started an edition with ``jp blog edit`` but forgot to use the ``-P, --preview`` arguments. |
| 252 | |
| 253 example: | |
| 254 -------- | |
| 255 | |
| 256 Preview the draft at ``~/local/sat/blog/some_name/blog_something.md``:: | |
| 257 | |
| 258 $ jp blog preview ~/local/sat/blog/some_name/blog_something.md | |
| 259 | |
|
3041
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
3021
diff
changeset
|
260 .. _jp-blog_import: |
|
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
3021
diff
changeset
|
261 |
| 2946 | 262 import |
| 263 ====== | |
| 264 | |
| 265 With this command you can import an external blog in a XMPP blog at the specified pubsub | |
| 266 location. | |
| 267 | |
| 268 The import is done using an *importer* name and a *location* which depends of the importer | |
| 2996 | 269 (it can be a path to a file, an URL to a blog, or something else). Let empty to get list |
| 270 of importers, and specify only importer name to get its description. | |
| 2946 | 271 |
| 272 By default, found images are re-uploaded to XMPP server, if you want to keep original | |
| 273 URLs, use the ``--no-images-upload`` option. | |
| 274 | |
| 275 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. | |
| 276 | |
| 277 You shoud specify original blog host using ``--host HOST`` argument, this is used notably | |
| 278 to reconstruct relative URLs of media. | |
| 279 | |
| 280 Importers may have specific options, you can set them using the ``-o NAME VALUE, --option NAME VALUE`` argument. Check the importer description for details. | |
| 281 | |
| 282 examples: | |
| 283 --------- | |
| 284 | |
| 285 List available importers:: | |
| 286 | |
| 287 $ jp blog import | |
| 288 | |
| 289 Get description of ``dotclear`` importer:: | |
| 290 | |
| 291 $ jp blog import dotclear | |
| 292 | |
| 293 Import a Dotclear blog:: | |
| 294 | |
| 295 $ jp blog import dotclear /path/to/dotclear.dump | |
| 296 | |
| 297 Import a Dotclear blog without uploading images:: | |
| 298 | |
| 299 $ jp blog import --no-images-upload dotclear /path/to/dotclear.dump |