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

[Oguz Bektas]

hi,

'e-mail' is the way it was written in the rest of the files so i opted
for that one.

'on the GUI' vs. 'in the GUI', i feel that 'on' fits better since the
GUI is on the screen. if preferred i can change to 'in'

On Tue, Apr 21, 2020 at 05:14:14PM +0200, Aaron Lauterer wrote:
> 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.
> >