[pmg-devel] [PATCH docs] pmgconfig: grammar, phrasing and typo fixes

[Aaron Lauterer]

LGTM

some comments inline but nothing that would prevent this patch to be applied

Reviewed-By: Aaron Lauterer <a.lauterer at proxmox.com>

On 4/21/20 4:48 PM, Oguz Bektas wrote:
> Signed-off-by: Oguz Bektas <o.bektas at proxmox.com>
> ---
>   pmgconfig.adoc | 76 +++++++++++++++++++++++++-------------------------
>   1 file changed, 38 insertions(+), 38 deletions(-)
> 
> diff --git a/pmgconfig.adoc b/pmgconfig.adoc
> index 7b2d1f7..0f47260 100644
> --- a/pmgconfig.adoc
> +++ b/pmgconfig.adoc
> @@ -44,9 +44,9 @@ Configuration files overview
>   
>   `/etc/network/interfaces`::
>   
> -Network setup. We never modify this files directly. Instead, we write
> +Network setup. We never modify this file directly. Instead, we write
>   changes to `/etc/network/interfaces.new`. When you reboot, we rename
> -the file to `/etc/network/interfaces`, so any changes gets activated
> +the file to `/etc/network/interfaces`, so the changes are applied
>   on the next reboot.
>   
>   `/etc/resolv.conf`::
> @@ -147,7 +147,7 @@ Service Configuration Templates
>   
>   {pmg} uses various services to implement mail filtering, for example
>   the {postfix} Mail Transport Agent (MTA), the {clamav} antivirus
> -engine and the Apache {spamassassin} project. Those services use
> +engine and the Apache {spamassassin} project. These services use
>   separate configuration files, so we need to rewrite those files when
>   configuration is changed.
>   
> @@ -224,11 +224,11 @@ iface ens18 inet static
>   .DNS recommendations
>   
>   Many tests to detect SPAM mails use DNS queries, so it is important to
> -have a fast and reliable DNS server. We also query some public
> +have a fast and reliable DNS server. We also query some publicly
>   available DNS Blacklists. Most of them apply rate limits for clients,
>   so they simply will not work if you use a public DNS server (because
>   they are usually blocked). We recommend to use your own DNS server,
> -which need to be configured in 'recursive' mode.
> +which needs to be configured in 'recursive' mode.
>   
>   
>   Options
> @@ -306,12 +306,12 @@ include::pmg.mail-options-conf-opts.adoc[]
>   Before and After Queue scanning
>   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>   
> -Scanning email can happen at two different stages of mail-processing:
> +Scanning e-mail can happen at two different stages of mail-processing:

in english both works, e-mail as well as email. Maybe we should decide 
which one we want to use and be consistent.

https://grammarist.com/style/e-mail-email/

>   
>   * During the SMTP Session after the complete message has been received (after
>     the 'DATA' command), known as 'before queue filtering'.
>   
> -* After intially accepting the mail and putting it on a queue for further
> +* After initially accepting the mail and putting it on a queue for further
>     processing, known as 'after queue filtering'.
>   
>   The former has the advantage that the system can reject a mail (by sending a
> @@ -320,14 +320,14 @@ sender to the other mailserver. This is of particular advantage if the
>   processed mail is a spam message or contains a virus and has a forged
>   sender-address. Sending out a notification in this situation leads so-called
>   'backscatter' mail, which might cause your server to get listed as spamming on
> -RBLs.
> +RBLs (Real-time Blackhole List).
>   
>   The latter has the advantage of providing faster delivery of mails for the
>   sending servers, since queueing mails is much faster than analyzing it for
>   spam and viruses.
>   
>   If a mail is addressed to multiple recipients (e.g. when multiple addresses are
> -subscribed to the same mailinglist) the situation is more complicated: Your
> +subscribed to the same mailing list) the situation is more complicated: Your
>   mailserver can only reject or accept the mail for all recipients, after having
>   received the complete message, while your rule setup might accept the mail for
>   part of the recipients and reject it for others. This can be due to a
> @@ -337,7 +337,7 @@ feature.
>   If the resulting action of the rule system is the same for all recipients {pmg}
>   responds accordingly if configured for before queue filtering (sending '554'
>   for a blocked mail and '250' for an accepted or quarantined mail). If some
> -mailboxes accept the mail and some reject it the system has to accept the mail.
> +mailboxes accept the mail and some reject it, the system has to accept the mail.
>   
>   Whether {pmg} notifies the sender that delivery failed for some recipients by
>   sending a non-delivery report, depends on the 'ndr_on_block' setting in
> @@ -372,7 +372,7 @@ domain.com to your first e-mail server, and e-mails addressed to
>   subdomain.domain.com to a second one.
>   
>   You can add the IP addresses, hostname, transport protocol (smtp/lmtp),
> -transport ports and mail domains (or just single email addresses)
> +transport ports and mail domains (or just single e-mail addresses)
>   of your additional e-mail servers. When transport protocol is set to `lmtp`,
>   the option 'Use MX' is useless and will be automatically set to 'No'.
>   
> @@ -408,11 +408,11 @@ certificate for you (`/etc/pmg/pmg-tls.pem`).
>   
>   {pmg} uses opportunistic TLS encryption by default. The SMTP transaction is
>   encrypted if the 'STARTTLS' ESMTP feature is supported by the remote
> -server.  Otherwise, messages are sent in the clear.
> +server. Otherwise, messages are sent in the clear.
>   
>   You can set a different TLS policy per destination. A destination is either a
>   remote domain or a next-hop destination as specified in `/etc/pmg/transport`.
> -This can be used, should you need to prevent e-mail delivery without
> +This can be used if you need to prevent e-mail delivery without
>   encryption, or to work around a broken 'STARTTLS' ESMTP implementation. See
>   {postfix_tls_readme} for details on the supported policies.
>   
> @@ -420,7 +420,7 @@ Enable TLS logging::
>   
>   To get additional information about SMTP TLS activity you can enable
>   TLS logging. That way information about TLS sessions and used
> -certificate’s is logged via syslog.
> +certificates is logged via syslog.
>   
>   Add TLS received header::
>   
> @@ -453,7 +453,7 @@ which system and private key were used for signing) is also included in the
>   The verification is done by the receiver: The public key is fetched
>   via DNS TXT lookup for `yourselector._domainkey.yourdomain.example` and used
>   for verifying the hash. You can publish multiple selectors for your domain,
> -each use by a system which sends e-mail from your domain, without the need to
> +each used by a system which sends e-mail from your domain, without the need to
>   share the private key.
>   
>   {pmg} verifies DKIM Signatures for inbound mail in the Spam Filter by default.
> @@ -501,7 +501,7 @@ ifndef::manvolnum[]
>   [thumbnail="pmg-gui-mailproxy-whitelist.png", big=1]
>   endif::manvolnum[]
>   
> -All SMTP checks are disabled for those entries (e. g. Greylisting,
> +All SMTP checks are disabled for those entries (e.g. Greylisting,
>   SPF, RBL, ...)
>   
>   NOTE: If you use a backup MX server (e.g. your ISP offers this service
> @@ -539,16 +539,16 @@ ifndef::manvolnum[]
>   [thumbnail="pmg-gui-spamquar-options.png", big=1]
>   endif::manvolnum[]
>   
> -Proxmox analyses all incoming e-mail messages and decides for each
> -e-mail if its ham or spam (or virus). Good e-mails are delivered to
> -the inbox and spam messages can be moved into the spam quarantine.
> +{pmg} analyses all incoming e-mail messages and decides for each
> +e-mail if it is ham or spam (or virus). Good e-mails are delivered to
> +the inbox and spam messages are moved into the spam quarantine.
>   
>   The system can be configured to send daily reports to inform users
> -about the personal spam messages received the last day. That report is
> +about the personal spam messages received the last day. The report is
>   only sent if there are new messages in the quarantine.
>   
>   Some options are only available in the config file `/etc/pmg/pmg.conf`,
> -and not in the webinterface.
> +and not in the web interface.
>   
>   include::pmg.spamquar-conf-opts.adoc[]
>   
> @@ -577,11 +577,11 @@ slightly adjusting the score of a particular rule. Two examples:
>     'DEAR_SOMETHING'). By setting the score of this rule to 0 you can disable
>     it completely.
>   
> -The system logs all rules which particular mail hits. Analyzing the logs can
> +The system logs all the rules which a particular mail hits. Analyzing the logs can
>   lead to finding such a pattern in your environment.
>   
>   You can adjust the score of a rule by creating a new 'Custom Rule Score' entry
> -in the GUI.
> +on the GUI.

I would opt for "in the GUI". In the interface, not on the interface :/

couldn't find much online but 
https://forum.wordreference.com/threads/in-the-gui-or-on-the-gui.3332406/

>   
>   NOTE: In general it is strongly recommended to not make large changes to the
>   default scores.
> @@ -600,7 +600,7 @@ ifndef::manvolnum[]
>   endif::manvolnum[]
>   
>   All mails are automatically passed to the included virus detector
> -({clamav}). The default setting are considered safe, so it is usually
> +({clamav}). The default settings are considered safe, so it is usually
>   not required to change them.
>   
>   {clamav} related settings are saved to subsection 'clamav' in `/etc/pmg/pmg.conf`,
> @@ -612,8 +612,8 @@ ifndef::manvolnum[]
>   [thumbnail="pmg-gui-clamav-database.png", big=1]
>   endif::manvolnum[]
>   
> -Please note that the virus signature database it automatically
> -updated. But you can see the database status on the GUI, and you can
> +Please note that the virus signature database is automatically
> +updated. You can see the database status on the GUI, and also

s/on/in/  but only a maybe as I think its better

>   trigger manual updates there.
>   
>   
> @@ -626,8 +626,8 @@ ifndef::manvolnum[]
>   endif::manvolnum[]
>   
>   Indentified virus mails are automatically moved to the virus
> -quarantine. The administartor can view those mails using the GUI, or
> -deliver them in case of false positives. {pmg} does not notify
> +quarantine. The administrator can view these mails using the GUI, and
> +choose to deliver them in case of false positives. {pmg} does not notify
>   individual users about received virus mails.
>   
>   Virus quarantine related settings are saved to subsection 'virusquar'
> @@ -654,9 +654,9 @@ them, as `init.pre`, `v310.pre`, `v320.pre`, `local.cf` will be overwritten by
>   the xref:pmgconfig_template_engine[template engine], while the others can
>   get updated by any {spamassassin} package upgrade.
>   
> -To add your special configuration, you have to create a new file and name it
> +To add your custom configuration, you have to create a new file and name it
>   `custom.cf` (in this directory), then add your configuration there. Make sure
> -to use the correct {spamassassin} syntax, and test with
> +to use the correct {spamassassin} syntax, and test it with:
>   
>   ----
>   # spamassassin -D --lint
> @@ -665,16 +665,16 @@ to use the correct {spamassassin} syntax, and test with
>   If you run a cluster, the `custom.cf` file is synchronized from the
>   master node to all cluster members automatically.
>   
> -Should you only wish to adjust the score assigned to a particular rule you
> +To adjust the score assigned to a particular rule you
>   can also use the xref:pmgconfig_spamdetector_customscores[Custom Rule Score]
> -settings in the GUI.
> +settings on the GUI.

same, I would prefer in

>   
>   
>   [[pmgconfig_custom_check]]
>   Custom Check Interface
>   ----------------------
>   
> -For use cases which are not handled by the {pmg} Virus Detector and
> +For use-cases which are not handled by the {pmg} Virus Detector and
>   {spamassassin} configuration, advanced users can create a custom check
>   executable which, if enabled will be called before the Virus Detector and before
>   passing an e-mail through the Rule System. The custom check API is kept as
> @@ -694,7 +694,7 @@ The expected output need to be printed on STDOUT and consists of two lines:
>   * one of the following 3 results:
>   ** 'OK' - e-mail is ok
>   ** 'VIRUS: <virusdescription>' - e-mail is treated as if it contained a virus
> -    (the virusdescription is logged and added to the e-mail's headers)
> +    (the virus description is logged and added to the e-mail's headers)
>   ** 'SCORE: <number>' - <number> is added (negative numbers are also possible)
>       to the e-mail's spamscore
>   
> @@ -775,7 +775,7 @@ Local Users
>   
>   [thumbnail="pmg-gui-local-user-config.png", big=1]
>   
> -Local users are used to manage and audit {pmg}. Those users can login on the
> +Local users can manage and audit {pmg}. They can login on the
>   management web interface.
>   
>   There are three roles:
> @@ -796,7 +796,7 @@ With this role, the user is only allowed to view data and configuration, but
>   not to edit it.
>   
>   In addition there is always the 'root' user, which is used to perform special
> -system administrator tasks, such as updgrading a host or changing the
> +system administrator tasks, such as upgrading a host or changing the
>   network configuration.
>   
>   NOTE: Only pam users are able to login via the webconsole and ssh, which the
> @@ -843,10 +843,10 @@ Sync
>   ^^^^
>   
>   {pmg} synchronizes the relevant user and group info periodically, so that
> -that information is available in a fast manner, even when the LDAP/AD server
> +the information is available in a fast manner, even when the LDAP/AD server
>   is temporarily not accessible.
>   
> -After a successfull sync, the groups and users should be visible on the web
> +After a successful sync, the groups and users should be visible on the web
>   interface. After that, you can create rules targeting LDAP users and groups.
>   
>   
>