Rephrase and update intro and syntax sections of setupcfg

Doc/packaging/setupcfg.rst

@@ -9,8 +9,10 @@ Specification of the :file:`setup.cfg` file
 :version: 0.9
 
 This document describes the :file:`setup.cfg`, an ini-style configuration file
-(compatible with :class:`configparser.RawConfigParser`) used by Packaging to
+used by Packaging to replace the :file:`setup.py` file used by Distutils.
-replace the :file:`setup.py` file.
+This specification is language-agnostic, and will therefore repeat some
+information that's already documented for Python in the
+:class:`configparser.RawConfigParser` documentation.
 
 .. contents::
    :depth: 3
@@ -20,11 +22,10 @@ replace the :file:`setup.py` file.
 Syntax
 ======
 
-The configuration file is an ini-based file. Variables name can be
+The ini-style format used in the configuration file is a simple collection of
-assigned values, and grouped into sections. A line that starts with "#" is
+sections that group sets of key-value fields separated by ``=`` or ``:`` and
-commented out. Empty lines are also removed.
+optional whitespace.  Lines starting with ``#`` or ``;`` are comments and will
-
+be ignored.  Empty lines are also ignored.  Example::
-Example::
 
    [section1]
    # comment
@@ -35,22 +36,24 @@ Example::
    foo = bar
 
 
-Values conversion
+Parsing values
------------------
+---------------
 
-Here are a set of rules for converting values:
+Here are a set of rules to parse values:
 
-- If value is quoted with " chars, it's a string. This notation is useful to
+- If a value is quoted with ``"`` chars, it's a string.  If a quote character is
-  include "=" characters in the value. In case the value contains a "
+  present in the quoted value, it can be escaped as ``\"`` or left as-is.
-  character, it must be escaped with a "\" character.
+
-- If the value is "true" or "false" --no matter what the case is--, it's
+- If the value is ``true``, ``t``, ``yes``, ``y`` (case-insensitive) or ``1``,
-  converted to a boolean, or 0 and 1 when the language does not have a
+  it's converted to the language equivalent of a ``True`` value; if it's
-  boolean type.
+  ``false``, ``f``, ``no``, ``n`` (case-insensitive) or ``0``, it's converted to
-- A value can contains multiple lines. When read, lines are converted into a
+  the equivalent of ``False``.
-  sequence of values. Each new line for a multiple lines value must start with
+
-  a least one space or tab character. These indentation characters will be
+- A value can contain multiple lines.  When read, lines are converted into a
-  stripped.
+  sequence of values.  Each line after the first must start with a least one
-- all other values are considered as strings
+  space or tab character; this leading indentation will be stripped.
+
+- All other values are considered strings.
 
 Examples::
 
@@ -68,12 +71,12 @@ Examples::
 Extending files
 ---------------
 
-An INI file can extend another file. For this, a "DEFAULT" section must contain
+A configuration file can be extended (i.e. included) by other files.  For this,
-an "extends" variable that can point to one or several INI files which will be
+a ``DEFAULT`` section must contain an ``extends`` key which value points to one
-merged to the current file by adding new sections and values.
+or more files which will be merged into the current files by adding new sections
+and fields.  If a file loaded by ``extends`` contains sections or keys that
+already exist in the original file, they will not override the previous values.
 
-If the file pointed in "extends" contains section/variable names that already
-exist in the original file, they will not override existing ones.
 
 file_one.ini::
 
@@ -107,13 +110,12 @@ To point several files, the multi-line notation can be used::
     extends = file_one.ini
               file_two.ini
 
-When several files are provided, they are processed sequentially. So if the
+When several files are provided, they are processed sequentially, following the
-first one has a value that is also present in the second, the second one will
+precedence rules explained above.  This means that the list of files should go
-be ignored. This means that the configuration goes from the most specialized to
+from most specialized to most common.
-the most common.
 
-**Tools will need to provide a way to produce a canonical version of the
+**Tools will need to provide a way to produce a merged version of the
-file**. This will be useful to publish a single file.
+file**.  This will be useful to let users publish a single file.
 
 
 Description of sections and fields