Improve formatting and add sections links

6 files changed, 31 insertions, 26 deletions

diff --git a/src/ejabberd_options_doc.erl b/src/ejabberd_options_doc.erl
index 8f6ab45b1..ee1cf9add 100644
--- a/src/ejabberd_options_doc.erl
+++ b/src/ejabberd_options_doc.erl
@@ -313,10 +313,12 @@ doc() ->
      {anonymous_protocol,
       #{value => "login_anon | sasl_anon | both",
         desc =>
-            ?T("'login_anon' means that the anonymous login method will be used. "
-               "'sasl_anon' means that the SASL Anonymous method will be used. "
-               "'both' means that SASL Anonymous and login anonymous are both "
-               "enabled. The default value is 'sasl_anon'.")}},
+            [?T("Define what anonymous protocol will be used: "), "",
+            ?T("* 'login_anon' means that the anonymous login method will be used. "), "",
+            ?T("* 'sasl_anon' means that the SASL Anonymous method will be used. "), "",
+            ?T("* 'both' means that SASL Anonymous and login anonymous are both "
+               "enabled."), "",
+            ?T("The default value is 'sasl_anon'."), ""]}},
      {api_permissions,
       #{value => "[Permission, ...]",
         desc =>
@@ -359,26 +361,28 @@ doc() ->
         desc =>
             ?T("This is used by the contributed module "
 	       "'ejabberd_auth_http' that can be installed from the "
-	       "'ejabberd-contrib' Git repository. Please refer to that "
+	       "https://github.com/processone/ejabberd-contrib[ejabberd-contrib] "
+               "Git repository. Please refer to that "
 	       "module's README file for details.")}},
      {auth_password_format,
       #{value => "plain | scram",
         note => "improved in 20.01",
         desc =>
-            ?T("The option defines in what format the users passwords "
-               "are stored. 'plain': The password is stored as plain text "
+            [?T("The option defines in what format the users passwords "
+               "are stored:"), "",
+            ?T("* 'plain': The password is stored as plain text "
                "in the database. This is risky because the passwords "
                "can be read if your database gets compromised. "
                "This is the default value. This format allows clients to "
                "authenticate using: the old Jabber Non-SASL (XEP-0078), "
-               "SASL PLAIN, SASL DIGEST-MD5, and SASL SCRAM-SHA-1. "
-               "'scram': The password is not stored, only some information "
+               "SASL PLAIN, SASL DIGEST-MD5, and SASL SCRAM-SHA-1. "), "",
+            ?T("* 'scram': The password is not stored, only some information "
                "that allows to verify the hash provided by the client. "
                "It is impossible to obtain the original plain password "
                "from the stored information; for this reason, when this "
                "value is configured it cannot be changed to plain anymore. "
                "This format allows clients to authenticate using: "
-               "SASL PLAIN and SASL SCRAM-SHA-1.")}},
+               "SASL PLAIN and SASL SCRAM-SHA-1.")]}},
      {auth_scram_hash,
       #{value => "sha | sha256 | sha512",
         desc =>
@@ -449,13 +453,13 @@ doc() ->
      {captcha_cmd,
       #{value => ?T("Path"),
         desc =>
-            ?T("Full path to a script that generates CAPTCHA images. "
+            ?T("Full path to a script that generates http://../basic/#captcha[CAPTCHA] images. "
                "There is no default value: when this option is not "
                "set, CAPTCHA functionality is completely disabled.")}},
      {captcha_limit,
       #{value => "pos_integer() | infinity",
         desc =>
-            ?T("Maximum number of CAPTCHA generated images per minute for "
+            ?T("Maximum number of http://../basic/#captcha[CAPTCHA] generated images per minute for "
                "any given JID. The option is intended to protect the server "
                "from CAPTCHA DoS. The default value is 'infinity'.")}},
      {captcha_host,
@@ -464,7 +468,7 @@ doc() ->
      {captcha_url,
       #{value => ?T("URL"),
         desc =>
-            ?T("An URL where CAPTCHA requests should be sent. NOTE: you need "
+            ?T("An URL where http://../basic/#captcha[CAPTCHA] requests should be sent. NOTE: you need "
                "to configure 'request_handlers' for 'ejabberd_http' listener "
                "as well. There is no default value.")}},
      {certfiles,
diff --git a/src/mod_admin_update_sql.erl b/src/mod_admin_update_sql.erl
index eae481385..c87849748 100644
--- a/src/mod_admin_update_sql.erl
+++ b/src/mod_admin_update_sql.erl
@@ -364,6 +364,6 @@ mod_doc() ->
     #{desc =>
           ?T("This module can be used to update existing SQL database "
              "from the default to the new schema. Check the section "
-             "http://../database-ldap/#default-and-new-schemas[Default and New Schemas] for details. "
+             "http://../database/#default-and-new-schemas[Default and New Schemas] for details. "
              "Please note that only PostgreSQL is supported. "
              "When the module is loaded use 'update_sql' ejabberdctl command.")}.
diff --git a/src/mod_http_api.erl b/src/mod_http_api.erl
index 0f494bb3a..427833584 100644
--- a/src/mod_http_api.erl
+++ b/src/mod_http_api.erl
@@ -527,8 +527,8 @@ mod_doc() ->
 	  [?T("This module provides a ReST API to call ejabberd commands "
 	      "using JSON data."), "",
 	   ?T("To use this module, in addition to adding it to the 'modules' "
-	      "section, you must also add it to 'request_handlers' of some "
-	      "listener."), "",
+	      "section, you must also enable it in 'listen' -> 'ejabberd_http' -> "
+              "http://../listen-options/#request-handlers[request_handlers]."), "",
 	   ?T("To use a specific API version N, when defining the URL path "
 	      "in the request_handlers, add a 'vN'. "
 	      "For example: '/api/v2: mod_http_api'"), "",
diff --git a/src/mod_http_upload.erl b/src/mod_http_upload.erl
index 0cc8d8488..040cb6085 100644
--- a/src/mod_http_upload.erl
+++ b/src/mod_http_upload.erl
@@ -232,8 +232,9 @@ mod_doc() ->
               "[XEP-0363: HTTP File Upload]. If the request is accepted, "
               "the client receives a URL for uploading the file and "
               "another URL from which that file can later be downloaded."), "",
-           ?T("In order to use this module, it must be configured as "
-              "a 'request_handler' for 'ejabberd_http' listener.")],
+           ?T("In order to use this module, it must be enabled "
+              "in 'listen' -> 'ejabberd_http' -> "
+              "http://../listen-options/#request-handlers[request_handlers].")],
       opts =>
           [{host,
             #{desc => ?T("Deprecated. Use 'hosts' instead.")}},
diff --git a/src/mod_mqtt.erl b/src/mod_mqtt.erl
index 8734c778d..a1621cc01 100644
--- a/src/mod_mqtt.erl
+++ b/src/mod_mqtt.erl
@@ -278,8 +278,9 @@ listen_options() ->
 %%%===================================================================
 mod_doc() ->
     #{desc =>
-          ?T("This module adds support for the MQTT protocol "
-             "version '3.1.1' and '5.0'. Remember to configure "
+          ?T("This module adds "
+             "https://docs.ejabberd.im/admin/guide/mqtt/[support for the MQTT] "
+             "protocol version '3.1.1' and '5.0'. Remember to configure "
 	     "'mod_mqtt' in 'modules' and  'listen' sections."),
       opts =>
           [{access_subscribe,
diff --git a/src/mod_register.erl b/src/mod_register.erl
index a864c0df2..919440b23 100644
--- a/src/mod_register.erl
+++ b/src/mod_register.erl
@@ -638,9 +638,9 @@ mod_doc() ->
            ?T("* Register a new account on the server."), "",
            ?T("* Change the password from an existing account on the server."), "",
            ?T("* Delete an existing account on the server."), "",
-           ?T("This module reads also another option defined globally for the "
-	      "server: 'registration_timeout'. Please check that option "
-	      "documentation in the section with top-level options.")],
+           ?T("This module reads also the top-level _`registration_timeout`_ "
+              "option defined globally for the server, "
+              "so please check that option documentation too.")],
       opts =>
           [{access,
             #{value => ?T("AccessName"),
@@ -664,9 +664,8 @@ mod_doc() ->
            {captcha_protected,
             #{value => "true | false",
               desc =>
-                  ?T("Protect registrations with CAPTCHA (see section "
-                     "https://docs.ejabberd.im/admin/configuration/basic/#captcha[CAPTCHA] "
-                     "of the Configuration Guide). The default is 'false'.")}},
+                  ?T("Protect registrations with http://../basic/#captcha[CAPTCHA]. "
+                     "The default is 'false'.")}},
            {ip_access,
             #{value => ?T("AccessName"),
               desc =>