Fix and improve documentation

This change, long overdue, fixes dozens of typos and grammar mistakes,
and improves the overall quality of the documentation of the project.  A
spell checker has detected some mistakes, but a lot of sentences were
grammatically wrong, so a lot of them have been simply rewritten.

On top of the grammar and the typos, I have also changed the table
layouts to ignore the indentation, which was kind of hard to cope with
and each table has only up to three columns.  Markdown does not care
about that, as well.

All of these have been spotted by me, though some of them may have been
mentioned in other reports in the past.  The SQL query layouts are
simplified, being now much easier to copy-paste from the docs if one
wishes to test them.

Backpatch-through: 14

docs/description.md

@@ -2,24 +2,24 @@
 
 ## Basic Usage
 
-`pg_hint_plan` reads hinting phrases in a comment of special form given with
-the target SQL statement. The special form is beginning by the character
-sequence `"/\*+"` and ends with `"\*/"`. Hint phrases are consists of hint name
-and following parameters enclosed by parentheses and delimited by spaces. Each
-hinting phrases can be delimited by new lines for readability.
+`pg_hint_plan` reads hinting phrases in a comment of special form given
+a SQL statement.  A hint can be specified by prefixing it with the sequence
+`"/\*+"` and ending it with `"\*/"`.  Hint phrases consist of hint names
+and parameters enclosed by parentheses and delimited by whitespaces.  Hint
+phrases can use newlines for readability.
 
-In the example below, hash join is selected as the joining method and scanning
-`pgbench_accounts` by sequential scan method.
+In the example below, a hash join is selected as the join method while
+doing a sequential scan on `pgbench_accounts`:
 
 ```sql
-postgres=# /*+
-postgres*#    <b>HashJoin(a b)</b>
-postgres*#    <b>SeqScan(a)</b>
-postgres*#  */
-postgres-# EXPLAIN SELECT *
-postgres-#    FROM pgbench_branches b
-postgres-#    JOIN pgbench_accounts a ON b.bid = a.bid
-postgres-#   ORDER BY a.aid;
+=# /*+
+     <b>HashJoin(a b)</b>
+     <b>SeqScan(a)</b>
+    */
+   EXPLAIN SELECT *
+     FROM pgbench_branches b
+     JOIN pgbench_accounts a ON b.bid = a.bid
+     ORDER BY a.aid;
                                         QUERY PLAN
 ---------------------------------------------------------------------------------------
     Sort  (cost=31465.84..31715.84 rows=100000 width=197)
@@ -30,6 +30,4 @@ postgres-#   ORDER BY a.aid;
             ->  Hash  (cost=1.01..1.01 rows=1 width=100)
                 ->  Seq Scan on pgbench_branches b  (cost=0.00..1.01 rows=1 width=100)
 (7 rows)
-
-postgres=#
 ```

docs/errors.md

@@ -1,29 +1,27 @@
 # Errors
 
-`pg_hint_plan` stops parsing on any error and uses hints already parsed on the
-most cases. Following are the typical errors.
+`pg_hint_plan` stops hint parsing on any error and will uses the hints
+already parsed.  Here are some typical errors.
 
 ## Syntax errors
 
 Any syntactical errors or wrong hint names are reported as a syntax error.
-These errors are reported in the server log with the message level specified by
-`pg_hint_plan.message_level` if `pg_hint_plan.debug_print` is on and above.
+These errors are reported in the server log with the message level specified
+by `pg_hint_plan.message_level` if `pg_hint_plan.debug_print` is on and
+above.
 
-## Object misspecifications
+## Incorrect Object definitions
 
-Object misspecifications result in silent ignorance of the hints. This kind of
-error is reported as "not used hints" in the server log by the same condition
-as syntax errors.
+Incorrect object definitions result in silently ignoring the hints. This kind
+of error is reported as a "Not Used Hint" in the server logs.
 
 ## Redundant or conflicting hints
 
-The last hint will be active when redundant hints or hints conflicting with
-each other. This kind of error is reported as "duplication hints" in the server
-log by the same condition to syntax errors.
+The last hint is considered when redundant hints are defined or hints
+conflict with each other.  This kind of error is reported as a duplicated
+hints.
 
 ## Nested comments
 
-Hint comment cannot include another block comment within. If `pg_hint_plan`
-finds it, differently from other erros, it stops parsing and abandans all hints
-already parsed. This kind of error is reported in the same manner as other
-errors.
+Hint comments cannot be recursive.   If detected, hint parsing is immediately
+stopped and all the hints already parsed are ignored.

docs/functional_limitations.md

@@ -1,26 +1,28 @@
 # Functional limitations
 
-## Influences of some of planner GUC parameters
+## Influence of planner GUC parameters
 
-The planner does not try to consider joining order for FROM clause entries more
-than `from_collapse_limit`. `pg_hint_plan` cannot affect joining order as
-expected for the case.
+The planner does not try to consider joining order for FROM clause entries
+more than `from_collapse_limit`. `pg_hint_plan` cannot affect the joining
+order in this case.
 
-## Hints trying to enforce unexecutable plans
+## Hints trying to enforce non-executable plans
 
-Planner chooses any executable plans when the enforced plan cannot be executed.
+Planner chooses any executable plans when the enforced plan cannot be
+executed:
 
--   `FULL OUTER JOIN` to use nested loop
--   To use indexes that does not have columns used in quals
--   To do TID scans for queries without ctid conditions
+-   `FULL OUTER JOIN` to use nested loop.
+-   Use of indexes that do not have columns used in quals.
+-   TID scans for queries without ctid conditions.
 
 ## Queries in ECPG
 
-ECPG removes comments in queries written as embedded SQLs so hints cannot be
-passed form those queries. The only exception is that `EXECUTE` command passes
-given string unmodifed. Please consider using the hint table in the case.
+ECPG removes comments in queries written as embedded SQLs so hints cannot
+be passed to it.  The only exception `EXECUTE`, that passes the query string
+to the server as-is.  The hint table can be used in the case.
 
-## Work with `pg_stat_statements`
+## `pg_stat_statements`
 
-`pg_stat_statements` generates a query id ignoring comments. As the result, the
-identical queries with different hints are summarized as the same query.
+`pg_stat_statements` generates a query ID, ignoring comments.  Hence,
+queries with different hints, still written the same way, may compute the
+same query ID.