Mercurial > libervia-backend

comparison doc/jp/blog.rst @ 2946:ce16847a7b6d

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc: documentation first draft: this patch starts the local documentation, existing documentation will be imported from wiki/other places to this folder and updated. This doc is using reStructuredText format and will be generated with Sphinx.
author Goffi <goffi@goffi.org>
date Fri, 22 Feb 2019 18:58:59 +0100
parents
children 5e72efd2f95d
comparison
equal deleted inserted replaced
2945:6c264c224614 2946:ce16847a7b6d
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