changeset 3909:3c3275a6dc8f

doc (cli/event): update doc following changes: rel 372
author Goffi <goffi@goffi.org>
date Thu, 22 Sep 2022 12:01:44 +0200 (2022-09-22)
parents d43b197735d1
children 199598223f82
files doc/libervia-cli/event.rst doc/libervia-cli/event_invitee.rst
diffstat 2 files changed, 43 insertions(+), 49 deletions(-) [+]
line wrap: on
line diff
--- a/doc/libervia-cli/event.rst	Thu Sep 22 00:01:48 2022 +0200
+++ b/doc/libervia-cli/event.rst	Thu Sep 22 12:01:44 2022 +0200
@@ -5,74 +5,70 @@
 Event commands allows you to create/modify or get data about an event, and to manage your
 invitees.
 
-list
-====
+get
+===
 
-List events available on a service
+Get metadata about one or more event(s).
+
+By default the events are displayed in a format readable, and ``--verbose, -v`` can be
+used one or more times to show more or less data. As usual, :ref:`libervia-cli_output` can
+be used to get the data in a different way.
 
 example
 -------
 
-Retrieve events of profile::
-
-  $ li event list
+Retrieve events from personal agenda::
 
-.. _libervia-cli_event_get:
-
-get
-===
+  $ li event get
 
-Get metadata about a specific event.
+Get details of a next dentist appointment from personal agenda::
 
-example
--------
-
-Retrieve an event metadata::
-
-  $ li event get  -n org.salut-a-toi.event:0__BsyCsXpcrRh44CQhSVTUMi -i 'org.salut-a-toi.event:0'
+  $ li event get -i dentist -vv
 
 .. _libervia-cli_event_create:
 
 create
 ======
 
-Create a new event. You can specify the date of the event with ``-d DATE, --date DATE``,
-and an id with ``-i ID, --id ID`` (default id is used if omitted).
-
-Configuration options are specified using ``-f KEY VALUE, --field KEY VALUE`` where key
-can be a custom data or one of:
+Create a new event. You can specify the starting time of the event with ``-S TIME_PATTERN, --start TIME_PATTERN``, and either its end time with ``-E TIME_PATTERN, --end TIME_PATTERN`` or its duration with ``-D DURATION, --duration DURATION``. ``--start`` and ``--end`` use a full :ref:`time_pattern` when ``--duration`` uses the relative delta part of it. It's mandatory when creating and event to specify starting and ending time (or duration).
 
-name
-  name of the event
-description
-  details of the event
-image
-  URL of the main picture of the event
-background-image
-  URL of image to use as background
-register
-  a boolean value, set to ``true`` if you want to register the event in your local list
+If your organsise an item, the ``--rsvp`` flag should be used: it will use the default
+RSVP form which ask for attendance. If you want to request more information to your guest,
+``--rsvp_json JSON`` can be used: the JSON argument is a data dict as described in
+``dataDict2dataForm`` function where the ``namespace`` key is not necessary (it's set
+automatically):
+
+.. autofunction:: sat.tools.xml_tools.dataDict2dataForm
+
+If the event links to an other one, ``--external JID NODE ITEM`` can be user
 
 example
 -------
 
 Create an event about to celebrate New Year::
 
-  $ li event create -d 2019-12-31 -f name "New Year's Eve" -f description "Party to celebrate new year" -f register true -f image https://example.net/some_image.jpg
+  $ li event create -s some_pubsub@example.net -n urn:xmpp:events:0/party -i new_year_eve_2022 --start 2022-12-31 --end 2023-01-01 -d "Party to celebrate new year" -H https://example.net/some_image.jpg "New Year's Eve"
+
+Add the dentist appointement on coming Tuesday to our personal agenda::
+
+  $ li event create -S tuesday -D "1 hour" Dentist
 
 
 modify
 ======
 
-This command in the same way as libervia-cli_event_create_ but modify an existing event. You need to
-specify the node of the event to modify using ``-n NODE, --node NODE``.
+This command works in the same way as libervia-cli_event_create_ but modify an existing
+event: all arguments are optional, those specified will override the original ones from
+the updated event.
+
+If the ending time or duration must be modified, the starting must be specified again.
 
 example
 -------
 
-Add a background image to the New Year event created above::
+Change the head picture from the New Year event created above::
 
-  $ li event modify -n org.salut-a-toi.event:0__d8QQLJvbcpDXxK66UBXKfT -f background-image https://example.net/some_background_image.jpg
+  $ li event modify -s some_pubsub@example.net -n urn:xmpp:events:0/party -i new_year_eve_2022 -H https://example.net/some_other_image.jpg
 
 
 invitee
--- a/doc/libervia-cli/event_invitee.rst	Thu Sep 22 00:01:48 2022 +0200
+++ b/doc/libervia-cli/event_invitee.rst	Thu Sep 22 12:01:44 2022 +0200
@@ -11,11 +11,10 @@
 get
 ===
 
-Retrieve the RSVP status of one guest. Note that you must the invitees node and not the
-event node. To retrieve invitees node, use :ref:`libervia-cli_event_get` with the event node.
+Retrieve the RSVP status of one or several guest(s).
 
-You may specify the guest bare jid using ``-j JID, --jid JID`` (by default your own bare
-jid will be used).
+You may specify the guest(s) to retrieve by using their bare JIDs with ``-j JIDS, --jid
+JIDS`` as many times as necessary. By default, all guests RSVPs are retrieved.
 
 If no response is known yet, no data is returned.
 
@@ -24,7 +23,7 @@
 
 Get RSVP of Louise::
 
-  $ li event invitee get -u "xmpp:pierre@example.net?;node=generic%2F876a2b99-1c90-41fa-b823-c4a467140770" -j louise@example.org
+  $ li event invitee get -u "xmpp:pubsub.example.net?;node=urn%3Axmpp%3Aevents%3A0%2Fparty;item=picnic_abd1" -j louise@example.org
 
 
 .. _libervia-cli_event_invitee_set:
@@ -32,19 +31,18 @@
 set
 ===
 
-Set your own RSVP data. Note that as for libervia-cli_event_invitee_get_ you must use
-invitees node and not the event node.
+Set your own RSVP data.
 
-Use ``-f KEY VALUE, --field KEY VALUE`` to specify the data to set. ``KEY`` can be one of
-``attend`` (where calue can be ``yes``, ``no``, or ``maybe``) and ``guests`` where value
-must be an integer.
+Use ``-f KEY VALUE, --field KEY VALUE`` to specify the data to set. ``KEY`` can any field
+name used in the RSVP form, where usually ``attending`` is used (with the possible values
+of ``yes``, ``no``, and ``maybe``).
 
 example
 -------
 
-Indicate that you'll come to an event with 3 guests::
+Indicate that you'll come to a picnic::
 
-  $ li event invitee set -u "xmpp:pierre@example.net?;node=generic%2F876a2b99-1c90-41fa-b823-c4a467140770" -f attend yes -f guests 3
+  $ li event invitee set -s pubsub.example.net -n urn:xmpp:events:0/party -i picnic_abd1 -f attending yes
 
 list
 ====