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, 50 insertions, 1 deletions

diff --git a/src/mod_vcard_xupdate.erl b/src/mod_vcard_xupdate.erl
index 927ea959..1c0114fa 100644
--- a/src/mod_vcard_xupdate.erl
+++ b/src/mod_vcard_xupdate.erl
@@ -31,13 +31,14 @@
 %% gen_mod callbacks
 -export([start/2, stop/1, reload/3]).
 
--export([update_presence/1, vcard_set/1, remove_user/2,
+-export([update_presence/1, vcard_set/1, remove_user/2, mod_doc/0,
 	 user_send_packet/1, mod_opt_type/1, mod_options/1, depends/2]).
 %% API
 -export([compute_hash/1]).
 
 -include("logger.hrl").
 -include("xmpp.hrl").
+-include("translate.hrl").
 
 -define(VCARD_XUPDATE_CACHE, vcard_xupdate_cache).
 
@@ -202,3 +203,51 @@ mod_options(Host) ->
      {cache_size, ejabberd_option:cache_size(Host)},
      {cache_missed, ejabberd_option:cache_missed(Host)},
      {cache_life_time, ejabberd_option:cache_life_time(Host)}].
+
+mod_doc() ->
+    #{desc =>
+          [?T("The user's client can store an avatar in the "
+              "user vCard. The vCard-Based Avatars protocol "
+              "(https://xmpp.org/extensions/xep-0153.html[XEP-0153]) "
+              "provides a method for clients to inform the contacts "
+              "what is the avatar hash value. However, simple or small "
+              "clients may not implement that protocol."), "",
+           ?T("If this module is enabled, all the outgoing client presence "
+              "stanzas get automatically the avatar hash on behalf of the "
+              "client. So, the contacts receive the presence stanzas with "
+              "the 'Update Data' described in "
+              "https://xmpp.org/extensions/xep-0153.html[XEP-0153] as if the "
+              "client would had inserted it itself. If the client had already "
+              "included such element in the presence stanza, it is replaced "
+              "with the element generated by ejabberd."), "",
+           ?T("By enabling this module, each vCard modification produces "
+              "a hash recalculation, and each presence sent by a client "
+              "produces hash retrieval and a presence stanza rewrite. "
+              "For this reason, enabling this module will introduce a "
+              "computational overhead in servers with clients that change "
+              "frequently their presence. However, the overhead is significantly "
+              "reduced by the use of caching, so you probably don't want "
+              "to set 'use_cache' to 'false'."), "",
+           ?T("The module depends on 'mod_vcard'."), "",
+           ?T("NOTE: Nowadays https://xmpp.org/extensions/xep-0153.html"
+              "[XEP-0153] is used mostly as \"read-only\", i.e. modern "
+              "clients don't publish their avatars inside vCards. Thus "
+              "in the majority of cases the module is only used along "
+              "with 'mod_avatar' module for providing backward compatibility.")],
+      opts =>
+          [{use_cache,
+            #{value => "true | false",
+              desc =>
+                  ?T("Same as top-level 'use_cache' option, but applied to this module only.")}},
+           {cache_size,
+            #{value => "pos_integer() | infinity",
+              desc =>
+                  ?T("Same as top-level 'cache_size' option, but applied to this module only.")}},
+           {cache_missed,
+            #{value => "true | false",
+              desc =>
+                  ?T("Same as top-level 'cache_missed' option, but applied to this module only.")}},
+           {cache_life_time,
+            #{value => "timeout()",
+              desc =>
+                  ?T("Same as top-level 'cache_life_time' option, but applied to this module only.")}}]}.