Mercurial > libervia-backend

comparison doc/jp/forums.rst @ 3041:72583524cfd3

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc (jp): jp commands are now fully documented: rel 232
author Goffi <goffi@goffi.org>
date Tue, 01 Oct 2019 22:49:06 +0200
parents
children
comparison
equal deleted inserted replaced
3040:fee60f17ebac 3041:72583524cfd3
1 ==============================
2 forums: forums topics handling
3 ==============================
4
5 Forums are internally a way to organise blog nodes open to many publishers. The ``forums``
6 commands let you manage the structure of topics. You may have several different structures
7 in one PubSub forums node, this can be useful if you have multi-lingual forums.
8
9 .. _jp-forums_get:
10
11 get
12 ===
13
14 Get and print the structure of forums. Beside the classic PubSub node arguments, you may
15 specify the ``KEY`` of the forum with ``-k KEY, --key KEY``. This can be used to have
16 several structures of forums, for instance one per language.
17
18 If you use the default output, the verbosity is used to retrieve details of topics.
19
20 examples
21 --------
22
23 Get structure of default forum with details::
24
25 $ jp forums get -v
26
27 Get structure of French forums in JSON::
28
29 $ jp forums get -k fr -O json
30
31
32 edit
33 ====
34
35 Edit the structure of XMPP forums. As for jp-forums_get_ you may specify the key beside
36 the classic PubSub node arguments. The edition works the same as for :ref:`jp-blog_edit`.
37
38 To edit the structure you'll get a JSON file which is a list of object where the topic
39 metadata are set. You can use the following metadata:
40
41 ``main-language``
42 a language code, using `ISO 639`_
43 ``name``
44 short name of the forum
45 ``title``
46 title of the topic/category in the given language
47 ``short-desc``
48 small description of the topic/category
49 ``desc``
50 long description of the topic/category
51 ``uri``
52 URI to the PubSub node containing the messages of the topic (it's actually a blog node
53 with suitable permissions). URI must only be set for topic, not for categories.
54 ``sub-forums``
55 list of object with the same metadata (i.e. other topics or categories)
56
57 Here is a small example of a forum structure:
58
59 .. sourcecode:: json
60
61 [
62 {
63 "main-language": "en",
64 "name": "short-name",
65 "title": "This is a category",
66 "short-desc": "short description about the category",
67 "desc": "this is a an example of a long description"
68 "sub-forums": [
69 {
70 "uri": "xmpp:pubsub.example.org?;node=org.salut-a-toi.forums%3A0_L5SaR5WYafXmUyD46R2avf",
71 "title": "some intereting topic",
72 "short-desc": "This is a description explaining what the topic is about"
73 },
74 {
75 "uri": "xmpp:pubsub.example.org?;node=org.salut-a-toi.forums%3A0_L5SaR5WYafXmUyD46R2avf",
76 "title": "a second topic",
77 "short-desc": "This topic is about bla bla bla"
78 },
79 ],
80 },
81 {
82 "main-language": "en",
83 "title": "An other category",
84 "sub-forums": [
85 {
86 "uri": "xmpp:pubsub.example.org?;node=org.salut-a-toi.forums%3A0_L5SaR5WYafXmUyD46R2avf",
87 "title": "yet another topic",
88 "short-desc": "This is a demo topic, made for an example"
89 },
90 ]
91 }
92 ]
93
94
95 .. _ISO 639: https://www.iso.org/iso-639-language-codes.html
96
97 example
98 -------
99
100 Edit structure of forums on a PubSub service::
101
102 $ jp forums edit -s pubsub.example.org