Generate ejabberd.yml.5 man page from source code directly

Several documentation callbacks (doc/0 and mod_doc/0) are implemented
and `ejabberdctl man` command is added to generate a man page. Note
that the command requires a2x to be installed (which is a part of
asciidoc package).

1 files changed, 85 insertions, 0 deletions

diff --git a/src/mod_privilege.erl b/src/mod_privilege.erl
index 9c05c60b..097df393 100644
--- a/src/mod_privilege.erl
+++ b/src/mod_privilege.erl
@@ -32,6 +32,7 @@
 
 %% API
 -export([start/2, stop/1, reload/3, mod_opt_type/1, mod_options/1, depends/2]).
+-export([mod_doc/0]).
 %% gen_server callbacks
 -export([init/1, handle_call/3, handle_cast/2, handle_info/2,
 	 terminate/2, code_change/3]).
@@ -82,6 +83,90 @@ mod_options(_) ->
      {presence, [{managed_entity, none}, {roster, none}]},
      {message, [{outgoing,none}]}].
 
+mod_doc() ->
+    #{desc =>
+          [?T("This module is an implementation of "
+              "https://xmpp.org/extensions/xep-0356.html"
+              "[XEP-0356: Privileged Entity]. This extension "
+              "allows components to have privileged access to "
+              "other entity data (send messages on behalf of the "
+              "server or on behalf of a user, get/set user roster, "
+              "access presence information, etc.). This may be used "
+              "to write powerful external components, for example "
+              "implementing an external "
+              "https://xmpp.org/extensions/xep-0163.html[PEP] or "
+              "https://xmpp.org/extensions/xep-0313.html[MAM] service."), "",
+           ?T("By default a component does not have any privileged access. "
+              "It is worth noting that the permissions grant access to "
+              "the component to a specific data type for all users of "
+              "the virtual host on which 'mod_privilege' is loaded."), "",
+           ?T("NOTE: This module is complementary to 'mod_delegation', "
+              "but can also be used separately.")],
+      opts =>
+          [{roster,
+            #{value => ?T("Options"),
+              desc =>
+                  ?T("This option defines roster permissions. "
+                     "By default no permissions are given. "
+                     "The 'Options' are:")},
+            [{both,
+              #{value => ?T("AccessName"),
+                desc =>
+                    ?T("Sets read/write access to a user's roster. "
+                       "The default value is 'none'.")}},
+             {get,
+              #{value => ?T("AccessName"),
+                desc =>
+                    ?T("Sets read access to a user's roster. "
+                       "The default value is 'none'.")}},
+             {set,
+              #{value => ?T("AccessName"),
+                desc =>
+                    ?T("Sets write access to a user's roster. "
+                       "The default value is 'none'.")}}]},
+           {message,
+            #{value => ?T("Options"),
+              desc =>
+                  ?T("This option defines permissions for messages. "
+                     "By default no permissions are given. "
+                     "The 'Options' are:")},
+            [{outgoing,
+              #{value => ?T("AccessName"),
+                desc =>
+                    ?T("The option defines an access rule for sending "
+                       "outgoing messages by the component. "
+                       "The default value is 'none'.")}}]},
+           {presence,
+            #{value => ?T("Options"),
+              desc =>
+                  ?T("This option defines permissions for presences. "
+                     "By default no permissions are given. "
+                     "The 'Options' are:")},
+            [{managed_entity,
+              #{value => ?T("AccessName"),
+                desc =>
+                    ?T("An access rule that gives permissions to "
+                       "the component to receive server presences. "
+                       "The default value is 'none'.")}},
+             {roster,
+              #{value => ?T("AccessName"),
+                desc =>
+                    ?T("An access rule that gives permissions to "
+                       "the component to receive the presence of both "
+                       "the users and the contacts in their roster. "
+                       "The default value is 'none'.")}}]}],
+      example =>
+          ["modules:",
+           "  ...",
+           "  mod_privilege:",
+           "    roster:",
+           "      get: all",
+           "    presence:",
+           "      managed_entity: all",
+           "    message:",
+           "      outgoing: all",
+           "  ..."]}.
+
 depends(_, _) ->
     [].