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
+ − 33 get command retrieves one or move blog post from specified location (by default the
+ − 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
+ − 194 This can be use to activate automatic refreshing of the page.
+ − 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
+ − 232 the first ``markdown`` is the name of the syntax (could an other syntax like ``xhtml`` ),
+ − 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
+ − 239 detected. Configuration is the same as for `edit preview <edit_preview_> `_ . This is can be
+ − 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
