From 30ae66e99e4a7499886436b195311ff012f09fda Mon Sep 17 00:00:00 2001 From: Badlop Date: Mon, 23 Aug 2021 13:40:19 +0200 Subject: [PATCH] Improve formatting and add sections links --- src/ejabberd_options_doc.erl | 30 +++++++++++++++++------------- src/mod_admin_update_sql.erl | 2 +- src/mod_http_api.erl | 4 ++-- src/mod_http_upload.erl | 5 +++-- src/mod_mqtt.erl | 5 +++-- src/mod_register.erl | 11 +++++------ 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 =>