2 files changed, 51 insertions, 45 deletions

diff --git a/doc/source/config.rst b/doc/source/config.rst
index 525885f..64d3591 100644
--- a/doc/source/config.rst
+++ b/doc/source/config.rst
@@ -11,15 +11,15 @@ Configuration
   read the present documentation about how to configure them,
   evaluate your threat model and write your configuration file accordingly.
 
-Since PHP *ini-like* configuration model isn't flexible enough,
-Snuffleupagus is using its own format in the file specified by
+Since PHP *ini-like* configuration model isn't flexible enough for our
+usecases, Snuffleupagus is using its own format in the file specified by
 the directive ``sp.configuration_file`` **in** your ``php.ini`` file,
 like ``sp.configuration_file=/etc/php/conf.d/snuffleupagus.rules``.
 
 You can use the ``,`` separator to include multiple configuration files:
 ``sp.configuration_file=/etc/php/conf.d/snuffleupagus.rules,/etc/php/conf.d/sp_wordpress.rules``.
 
-We're also also supporting `glob <https://en.wikipedia.org/wiki/Glob_%28programming%29>`__,
+It also supports `glob <https://en.wikipedia.org/wiki/Glob_%28programming%29>`__,
 so you can write something like:
 ``sp.configuration_file=/etc/php/conf.d/*.rules,/etc/php/conf.d/extra/test.rules``.
 
@@ -32,9 +32,9 @@ To sum up, you should put this in your ``php.ini``:
 
 And the **snuffleupagus rules** into the ``.rules`` files.
 
-Since our configuration format is a bit more complex than php's one,
-we have a ``sp.allow_broken_configuration`` parameter (``false`` by default),
-that you can set to ``true`` if you want PHP to carry on if your Snuffleupagus'
+Since the configuration format is a bit more complex than php's one,
+their is a ``sp.allow_broken_configuration`` parameter (``false`` by default),
+that can be set to ``true`` if you want PHP to carry on if your Snuffleupagus'
 configuration contains syntax errors. You'll still get a big scary message in
 your logs of course. We do **not** recommend to use it of course, but sometimes
 it might be useful to be able to "debug in production" without breaking your
@@ -45,23 +45,23 @@ Configuration file format
 
 Options are chainable by using dots (``.``).
 
-Some options have a string parameter, that **must** be quoted with double quotes, e.g. ``"string"``.
+String parameters **must** be quoted with double quotes, e.g. ``"string"``.
 
 Comments are prefixed either with ``#``, or ``;``.
 
-Some rules apply in a specific ``function`` (context) on a specific ``variable``
+Some rules apply to a specific ``function`` (context) on a specific ``variable``
 (data), like ``disable_function``. Others can only be enabled/disabled, like
 ``harden_random``.
 
 Most of the features can be used in ``simulation`` mode by appending the
 ``.simulation()`` or ``.sim()`` option to them (eg. ``sp.readonly_exec.simulation().enable();``) to see
 whether or not they could break your website. The simulation mode won't block the request,
-but will write a warning in the log.
+and will only log a warning.
 
 The rules are evaluated in the order that they are written, the **first** one
-to match will terminate the evaluation (except for rules in simulation mode).
+to match will terminate the evaluation, except of course for rules in simulation mode.
 
-Rules can be split into lines and contain whitespace for easier readability and maintenance: (This feature is available since version 0.8.0.)
+Since Snuffleupagus 0.8.0, rules can be split into lines and contain whitespace for easier readability and maintenance:
 
 ::
 
@@ -70,8 +70,6 @@ Rules can be split into lines and contain whitespace for easier readability and
     .alias("newline in mail() To:")
     .drop();
 
-The terminating ``;`` is optional for now, but it should be used for future compatibility.
-
 Rules, including comments, needs to be written in ASCII, other encodings aren't
 supported and might cause syntax errors and related issues like making
 all rules after non-ASCII symbols not considered for execution and silently discarded.
diff --git a/doc/source/faq.rst b/doc/source/faq.rst
index 0485f21..df2cdb5 100644
--- a/doc/source/faq.rst
+++ b/doc/source/faq.rst
@@ -54,18 +54,18 @@ Why not Suhosin?
 
 We're huge fans of `Suhosin <https://suhosin.org>`_, unfortunately:
 
-- it doesn't work very well on PHP7
-- it has some oudated features and misses new ones
-- it doesn't cope very well with our various industrialization needs
-- it has some shortcomings by design
+- It doesn't work very well on PHP7+.
+- It has some outdated features and misses modern ones.
+- It doesn't cope very well with some industrialization needs.
+- It has some shortcomings by design.
 
-We're using the `disable_function <https://secure.php.net/manual/en/ini.core.php#ini.disable-functions>`_
-directive, but unfortunately, it doesn't provide enough usable granularity (guess how many CMSs are using
+For example,the `disable_function <https://secure.php.net/manual/en/ini.core.php#ini.disable-functions>`_
+directive doesn't provide enough usable granularity: guess how many CMSs are using
 the `system <https://secure.php.net/manual/en/function.system.php#refsect1-function.system-notes>`_
-function to perform various mandatory maintenance tasks).
+function to perform various mandatory maintenance tasks.
 
 This is why we decided to write our own hardening module, in the spirit of Suhosin,
-with virtual-patching support, as well as other cool new features.
+with virtual-patching support, as well as other fancy new features.
 
 
 What license is Snuffleupagus released under and why?
@@ -75,11 +75,11 @@ Snuffleupagus is licensed under the `LGPL <https://www.gnu.org/copyleft/lesser.h
 was developed by the fine people from `NBS System <https://nbs-system.com/>`__,
 and is maintained by Julien (jvoisin) Voisin.
 
-We chose the LGPL because we don't care that much how you're using Snuffleupagus,
-but we'd like to force people to make their improvements/contributions
-available to everyone.
+The LGPL was chosen because we don't care that much how you're using Snuffleupagus,
+but we'd like to have improvements/contributions made available for everyone to
+benefit from.
 
-The complete license text is shipped with the sources and can be found under ``LICENSE``.
+The complete license text is shipped with the sources and can be found in the ``LICENSE`` file.
 
 For compatibility with older PHP versions, some original PHP source code was copied or ported back to older versions.
 This source code resides in ``src/sp_php_compat.c`` and ``src/sp_php_compat.h`` and retains its original license
@@ -89,12 +89,11 @@ This source code resides in ``src/sp_php_compat.c`` and ``src/sp_php_compat.h``
 What is the different between Snuffleupagus and a (WAF) like ModSecurity?
 """""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 
-`ModSecurity <https://modsecurity.org/>`__ and other `Web Application
-Firewalls (WAF) <https://en.wikipedia.org/wiki/Web_application_firewall>`__ are
-working by inspecting the http traffic. Snuffleupagus being a PHP module, is
-operating directly inside your website's code, with a lesser overhead, as well
-as a better understanding of what is currently happening inside your
-application.
+`ModSecurity <https://modsecurity.org/>`__ and other `Web Application Firewalls
+(WAF) <https://en.wikipedia.org/wiki/Web_application_firewall>`__ are working
+by inspecting the http traffic. Snuffleupagus being a PHP module, operates
+directly inside the website's code, with a smaller overhead, as well as a
+better comprehension of what is currently happening there.
 
 
 Should I use Snuffleupagus?
@@ -103,18 +102,19 @@ Should I use Snuffleupagus?
 Yes.
 
 Even if you're not using the virtual-patching capabilities, Snuffleupagus comes
-with various passive features that won't break your website while killing numerous vulnerabilities.
+with various passive features that won't break your website while killing
+numerous vulnerability classes.
 
 Please keep in mind that you are not only protecting yourself and your users/customers,
-but also other people on the internet that might be attacked by your server if
-it becomes compromised.
+but also other people on the internet that might be attacked by your server
+should it become compromised.
 
 How mature is this project?
 """""""""""""""""""""""""""
 
-This project has been floating around since early 2016 and we did the first commit
-the 28:sup:`th` of December of the same year. It's currently stable,
-and is usable and used in production.
+This project has been floating around since early 2016 and the first commit
+is from the 28th of December of the same year. It's currently stable,
+and is usable and used in production at various scales.
 
 Are you saying that PHP isn't secure?
 """""""""""""""""""""""""""""""""""""
@@ -137,8 +137,8 @@ all your security issues, but we believe that it might definitely help.
 Sounds great, but is it working?
 """"""""""""""""""""""""""""""""
 
-We've been using it in production since a couple of years, and it thwarted
-numerous known and unknown attacks. If you want some evidences, one of the
+It has been used in production since its inception, and thwarted
+numerous known and unknown attacks. Should you want some evidences, one of the
 developer published in June 2019 a `blogpost
 <https://dustri.org/b/snuffleupagus-versus-recent-high-profile-vulnerabilities.html>`__
 showcasing how efficient Snuffleupagus was versus *major* web
@@ -147,13 +147,13 @@ vulnerabilities from 2018/2019.
 
 Why should I send you bugs, security issues and patches?
 """""""""""""""""""""""""""""""""""""""""""""""""""""""""
+
 Snuffleupagus is an open-source security software, by reporting (or fixing)
 bugs, or implementing new features, you are helping others to protect themselves.
 
-We're also firm believers in the *Beerbounty* system:
-we are happy to offer you beers when/if we ever meet if you helped the project in
-any way. If you don't like beer, we're sure that we'll find something else,
-don't worry.
+We're also firm believers in the *Beerbounty* system: we are happy to offer you
+beers when/if we ever meet if you helped the project in any way. If you don't
+like beer, we're sure that we'll find something else, don't worry.
 
 
 Installation and configuration
@@ -161,6 +161,7 @@ Installation and configuration
 
 Can snuffleupagus break my application?
 """""""""""""""""""""""""""""""""""""""
+
 Yes.
 
 Some options won't break anything, like :ref:`harden-rand <harden-rand-feature>`,
@@ -170,7 +171,7 @@ rules might pretty well break your website.
 It's up to you to configure Snuffleupagus accordingly to your needs.
 
 You can also enable the ``simulation`` mode on features that you're not sure about,
-to see what snuffleupagus would do to your application, before activating them for good.
+to see what Snuffleupagus would do to your application, before activating them for good.
 
 How can I find out the problem when my application breaks?
 """"""""""""""""""""""""""""""""""""""""""""""""""""""""""
@@ -180,17 +181,20 @@ By checking the logs; Snuffleupagus systematically prefix them with ``[snuffleup
 
 Does Snuffleupagus run on Windows?
 """"""""""""""""""""""""""""""""""
+
 No idea, feel free to `try <https://github.com/jvoisin/snuffleupagus/issues/2>`_.
 
 
 Does Snuggleupagus run on `HHVM <http://hhvm.com/>`_?
 """""""""""""""""""""""""""""""""""""""""""""""""""""
+
 No it doesn't, since `HHVM's API <https://github.com/facebook/hhvm/wiki/Extension-API>`_
 is really different from PHP7's one. We're not currently planning to rewrite
 Snuffleupagus to support it.
 
 Will Snuffleupagus run on my old PHP 5?
 """""""""""""""""""""""""""""""""""""""
+
 No.
 
 Since PHP5 `is deprecated since the end of 2018 <http://php.net/supported-versions.php>`_,
@@ -202,6 +206,7 @@ Help and support
 
 I found a security issue
 """"""""""""""""""""""""
+
 If you believe you have found a security issue affecting Snuffleupagus,
 then we would be more than happy to hear from you!
 
@@ -219,17 +224,19 @@ you find a security issue.
 
 I found a bug. How can I report it?
 """""""""""""""""""""""""""""""""""
+
 We do have an issue tracker on `Github <https://github.com/jvoisin/snuffleupagus/issues>`_.
 Please make sure to include as much information as possible when reporting your issue,
 such as your operating system, your version of PHP, your version of Snuffleupagus,
 your logs, the problematic PHP code, the request, a brief description, … long story short,
-give us everything that you can.
+give us everything you have.
 
 If you're feeling extra-nice, you can try to :ref:`debug it yourself <debug>`,
 it's not that hard.
 
 Where can I find even more help?
 """"""""""""""""""""""""""""""""
+
 The :doc:`configuration page <config>` might be what you're looking for.
 If you're adventurous, you can also check the `issue tracker <https://github.com/jvoisin/snuffleupagus/issues/?q=is%3Aissue>`_
 (make sure to check the `closed issues <https://github.com/jvoisin/snuffleupagus/issues?q=is%3Aissue+is%3Aclosed>`_ too).
@@ -240,6 +247,7 @@ Unimplemented mitigations and abandoned ideas
 
 Constant time comparisons
 """""""""""""""""""""""""
+
 We didn't manage to perform time-based side-channel attacks on strings 
 against real world PHP application, and the results that we gathered on
 tailored test cases weren't concluding: for simplicity's sake, we chose