|
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 |
