doc (components/AP Gateway): Ad-Hoc and Events:

New Ad-Hoc command is explained, and `Events` section specify how the conversion is done
between the 2 protocols.

fix 372

doc/components.rst

@@ -333,6 +333,18 @@ often required, thus Pierre will look for ``@louise@example.org``).
    The actor endpoint can also be used directly in AP software (in the example above, it
    would be by default ``https://example.org/_ap/actor/louise%40example.org``).
 
+.. _ap-ad-hoc:
+
+Ad-Hoc Commands
+~~~~~~~~~~~~~~~
+
+The gateway supports `XEP-0050 (Ad-Hoc Commands)`_. For now, only the following node is
+provided:
+
+``https://libervia.org/ap_gateway/xmpp_jid_node_2_ap_actor``
+  Convert XMPP JID and Node to corresponding virtual actor. Node is optional.
+
+.. _XEP-0050 (Ad-Hoc Commands): https://xmpp.org/extensions/xep-0050.html
 
 Getting AP Message from XMPP
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -705,6 +717,63 @@ straightforward to add it in the AP gateway.
 .. _Pleroma: https://pleroma.social/
 .. _XEP-0444 (Message Reactions): https://xmpp.org/extensions/xep-0444.html
 
+Events
+~~~~~~
+
+This gateway manages events. On the XMPP side, the ``Events`` protoXEP is used, on AP side
+``Event`` objects are used. `Mobilizon`_ is used as reference implementation here.
+
+.. note::
+
+   The ``Events`` protoXEP has been proposed but not published or reviewed by XMPP council
+   yet. The current version is availale at https://github.com/xsf/xeps/pull/1206 and
+   hopefully it will eventually become an official experimental XEP. The code and this
+   documentation will be updated as the standard evolves.
+
+To retrieve AP events from XMPP, use the corresponding virtual JID as explained in
+:ref:`ap-actor-from-xmpp` with the event node (which is ``urn:xmpp:events:0``).
+
+*example:*
+
+To retrieve events from AP actor with the handle ``somebody@mobilizon.example``, throught
+the ``ap.example.org`` gateway, the ``somebody\40mobilizon.example@ap.example.org`` JID
+can be used with the ``urn:xmpp:events:0`` node.
+
+
+To retrieve XMPP events from AP, you need to the virtual actor corresponding to the JID
+of the pubsub/PEP service with the event node (starting with ``urn:xmpp:events:0``), as
+explained in :ref:`xmpp-node-from-ap`. You can use :ref:`ap-ad-hoc` to easily convert your
+JID/node combination to a virtual AP actor. Note that the resulting virtual actor is
+unaesthetic due to the presence of event node and the constraints explained in
+:ref:`xmpp-node-from-ap`.
+
+To retrieve the link to the XMPP item from AP, you can use the ID from the generated AP
+object. The ID can also be constructed by hand by using the URL
+``https://<ap_gateway_public_domain>/_ap/<virtual_actor>/<event_item_id>``.
+
+*example:*
+
+to retrieve from AP the XMPP event at pubsub service ``pubsub.example.net`` on node
+``urn:xmpp:events:0/party`` with item ID ``picnic_abd1``, and using the AP gateway with
+public url ``https://ap.example.net``, the following link can be used::
+
+  https://ap.example.net/_ap/___urn.3Axmpp.3Aevents.3A0.2Fparty---pubsub.2eexample.2enet@ap.tazar3.int/picnic_abd1
+
+If you paste it in an AP implementation featuring events (e.g. Mobilizon), the event
+should appear and you should be able to comment it and participate to it.
+
+Event comments are supported, the node to use is indicated in the event XMPP item as
+specified in the protoXEP, this should be transparent to end-user.
+
+Participation to an event is supported through the RSVP mechanism on XMPP and with
+``Join`` and ``Leave`` activities on AP. Note that XMPP allows more nuances with its RSVP
+mechanism (it's possible to say if someone will "maybe" attend an event, and to request
+any kind of extra informations) while AP only indicates if one will attend or not an
+event.
+
+
+.. _Mobilizon: https://joinmobilizon.org/
+
 Using the Component (for developers)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~