From 3c01578426e5e8a2b9f098aad72100c1d7d95dea Mon Sep 17 00:00:00 2001
From: jedmao <jedmao@outlook.com>
Date: Sun, 10 Nov 2019 00:13:48 +0100
Subject: [PATCH 1/6] Clarify specification

Fixes #8
Fixes #2
---
 README.md |  2 +-
 index.rst | 77 +++++++++++++++++++++++++++----------------------------
 2 files changed, 39 insertions(+), 40 deletions(-)

diff --git a/README.md b/README.md
index 920f1fa..ecae374 100644
--- a/README.md
+++ b/README.md
@@ -9,7 +9,7 @@ To build, first install [Sphinx][], and then, in the same directory as this
 file, run
 
     make html
-    
+
 The built HTML files should be in `_build`.
 
 [Sphinx]: https://www.sphinx-doc.org/en/latest/usage/installation.html
diff --git a/index.rst b/index.rst
index 37fb16f..79e6952 100644
--- a/index.rst
+++ b/index.rst
@@ -41,40 +41,38 @@ with version control systems.
 File Format
 ===========
 
-EditorConfig files use an INI format that is compatible with the format used
-by `Python configparser Library`_. In an EditorConfig file (usually named
-``.editorconfig``), all beginning whitespace in each line is ignored. Each
-line must be one of the following:
-
-- Empty Line: An empty string.
-- Comment: A line starting with a ``;`` or a ``#``.
-- Section Title: A line that starts with a ``[``, and that ends with a ``]``.
-- Assignment: A line separated by an `=` into two parts.
-
-Any line that is not one of the above is invalid. "Inline comment" in
-appearance, i.e., a line that has a ``;`` or a ``#`` in the middle, is
-undefined. For convenience, we also define the following terminologies:
-
-- Section Name: The string between the beginning ``[`` and the ending ``]`` in
-  a Section Title.
-- Section: The lines starting from a Section Title until the beginning of the
-  next Section Title or end of file.
-- Property: The part before the first `=` in an Assignment.
-- Value: The part after the first `=` in an Assignment.
-
-In EditorConfig files, the Section Names are filepath globs, similar to the
-format accepted by gitignore. ``[`` and ``]`` are allowed in the Section
-Names. Forward slashes (``/``) are used as path separators and Backslashes
-(``\\``) are not allowed as path separators (even on Windows). Comments should
-always go on individual lines. EditorConfig files should be UTF-8 encoded, with
-either CRLF or LF line separators.
+EditorConfig uses an INI file format. In an EditorConfig file (usually named
+``.editorconfig``), all beginning whitespace on each line is considered
+irrelevant. Each line must be one of the following:
+
+- Blank: contains only whitespace characters.
+- Comment: starts with a ``;`` or a ``#``.
+   - Inline comments are not supported.
+- Section Header: starts with a ``[`` and ends with a ``]``.
+   - May not use any non-whitespace characters outside of the surrounding
+     brackets.
+   - May contain any characters between the square brackets (e.g.,
+     ``[`` and ``]`` are allowed).
+   - Forward slashes (``/``) are used as path separators.
+   - Backslashes (``\\``) are not allowed as path separators (even on Windows).
+   - Section Name: the string between the beginning ``[`` and the ending ``]``.
+   - Section: the lines starting from a Section Header until the beginning of the
+     next Section Header or the end of the file.
+- Property: contains a key-value pair, separated by an `=`.
+   - Key: the part before the first `=` (trimmed of whitespace).
+   - Value: The part after the first `=` (trimmed of whitespace).
+
+Any line that is not one of the above is invalid.
+
+EditorConfig files should be UTF-8 encoded, with LF or CRLF line separators.
 
 Glob Expressions
 ================
 
-Section names in EditorConfig files are filename globs that support pattern
-matching through Unix shell-style wildcards. These filename globs recognize
-the following as special characters for wildcard matching:
+Section names in EditorConfig files are filepath globs, similar to the format
+accepted by ``.gitignore``. They support pattern matching through Unix
+shell-style wildcards. These filepath globs recognize the following as
+special characters for wildcard matching:
 
 .. list-table::
    :header-rows: 1
@@ -121,8 +119,9 @@ files take precedence.
 Supported Properties
 ====================
 
-EditorConfig file sections contain properties, which are name-value pairs
-separated by an equal sign (``=``). EditorConfig plugins will ignore
+EditorConfig file sections contain properties, which are key-value pairs
+separated by an equal sign (``=``). Any property other than ``root`` MUST be
+located under a section to take effect. EditorConfig plugins will ignore
 unrecognized property names and properties with invalid values.
 
 Here is the list of all property names understood by EditorConfig and all
@@ -152,19 +151,19 @@ valid values for these properties:
      - Set to ``latin1``, ``utf-8``, ``utf-8-bom``, ``utf-16be`` or ``utf-16le`` to
        control the character set. Use of ``utf-8-bom`` is discouraged.
    * - ``trim_trailing_whitespace``
-     - Set to ``true`` to remove any whitespace characters preceeding newline
-       characters and ``false`` to ensure it doesn't.
+     - Set to ``true`` to remove all whitespace characters preceeding newline
+       characters in the file and ``false`` to ensure it doesn't.
    * - ``insert_final_newline``
      - Set to ``true`` ensure file ends with a newline when saving and ``false``
        to ensure it doesn't.
    * - ``root``
-     - Must be specified at the top of the file outside of any sections. Set
-       to ``true`` to stop ``.editorconfig`` files search on current file. The
-       value is case insensitive.
+     - Must be specified in the default (global/root) section of the file. Set
+       to ``true`` to stop the ``.editorconfig`` file search on the current file.
+       The value is case insensitive.
 
-For any property, a value of ``unset`` is to remove the effect of that
+For any property, a value of ``unset`` removes the effect of that
 property, even if it has been set before. For example, add ``indent_size =
-unset`` to undefine indent_size property (and use editor default).
+unset`` to undefine the ``indent_size`` property (and use editor defaults).
 
 Property names are case insensitive and all property names are lowercased when
 parsing. The maximum length of a property name is 50 characters and the

From 7668a3fd19597fccac09a959de2c3322ce5d8d0f Mon Sep 17 00:00:00 2001
From: Jed Mao <jedmao@outlook.com>
Date: Sun, 10 Nov 2019 04:59:58 -0600
Subject: [PATCH 2/6] respond to CR feedback

---
 index.rst | 42 +++++++++++++++++++++++++-----------------
 1 file changed, 25 insertions(+), 17 deletions(-)

diff --git a/index.rst b/index.rst
index 79e6952..f3d98c6 100644
--- a/index.rst
+++ b/index.rst
@@ -5,10 +5,10 @@
     modification, are permitted provided that the following conditions are met:
 
     1. Redistributions of source code must retain the above copyright notice,
-        this list of conditions and the following disclaimer.
-    2. Redistributions in binary form must reproduce the above copyright notice,
-        this list of conditions and the following disclaimer in the documentation
-        and/or other materials provided with the distribution.
+       this list of conditions and the following disclaimer.
+    2. Redistributions in binary form must reproduce the above copyright
+       notice, this list of conditions and the following disclaimer in the
+       documentation and/or other materials provided with the distribution.
 
     THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
     AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
@@ -41,13 +41,16 @@ with version control systems.
 File Format
 ===========
 
-EditorConfig uses an INI file format. In an EditorConfig file (usually named
-``.editorconfig``), all beginning whitespace on each line is considered
-irrelevant. Each line must be one of the following:
+EditorConfig uses a strict EditorConfig-INI file format. In an EditorConfig
+file (usually named ``.editorconfig``), all beginning whitespace on each line
+is considered irrelevant. Each line must be one of the following:
 
 - Blank: contains only whitespace characters.
 - Comment: starts with a ``;`` or a ``#``.
-   - Inline comments are not supported.
+   - Inserting a ``#`` or ``;`` after non-whitespace characters in a line
+     (i.e., inline) will not be parsed as a comment; in fact, it will be
+     considered part of the section name, declaration key or value in which
+     it was inserted.
 - Section Header: starts with a ``[`` and ends with a ``]``.
    - May not use any non-whitespace characters outside of the surrounding
      brackets.
@@ -55,10 +58,7 @@ irrelevant. Each line must be one of the following:
      ``[`` and ``]`` are allowed).
    - Forward slashes (``/``) are used as path separators.
    - Backslashes (``\\``) are not allowed as path separators (even on Windows).
-   - Section Name: the string between the beginning ``[`` and the ending ``]``.
-   - Section: the lines starting from a Section Header until the beginning of the
-     next Section Header or the end of the file.
-- Property: contains a key-value pair, separated by an `=`.
+- Declaration: contains a key-value pair, separated by an `=`.
    - Key: the part before the first `=` (trimmed of whitespace).
    - Value: The part after the first `=` (trimmed of whitespace).
 
@@ -66,6 +66,14 @@ Any line that is not one of the above is invalid.
 
 EditorConfig files should be UTF-8 encoded, with LF or CRLF line separators.
 
+Additionaly, EditorConfig defines the following terms:
+
+- Preamble: the part of the document that precedes the first section. The
+  preamble is optional and may contain declarations, comments or blank lines.
+- Section Name: the string between the beginning ``[`` and the ending ``]``.
+- Section: the lines starting from a Section Header until the beginning of
+  the next Section Header or the end of the file.
+
 Glob Expressions
 ================
 
@@ -108,8 +116,8 @@ When a filename is given to EditorConfig a search is performed in the
 directory of the given file and all parent directories for an EditorConfig
 file (named ".editorconfig" by default).  All found EditorConfig files are
 searched for sections with section names matching the given filename. The
-search will stop if an EditorConfig file is found with the root property set
-to true or when reaching the root filesystem directory.
+search will stop if an EditorConfig file is found with the ``root`` Declaration
+set to ``true`` in the preamble or when reaching the root filesystem directory.
 
 Files are read top to bottom and the most recent rules found take
 precedence. If multiple EditorConfig files have matching sections, the rules
@@ -157,9 +165,9 @@ valid values for these properties:
      - Set to ``true`` ensure file ends with a newline when saving and ``false``
        to ensure it doesn't.
    * - ``root``
-     - Must be specified in the default (global/root) section of the file. Set
-       to ``true`` to stop the ``.editorconfig`` file search on the current file.
-       The value is case insensitive.
+     - Must be specified in the preamble. Set to ``true`` to stop the
+       ``.editorconfig`` file search on the current file. The value is case
+       insensitive.
 
 For any property, a value of ``unset`` removes the effect of that
 property, even if it has been set before. For example, add ``indent_size =

From b6c65819c04e596fb400aff3f917a3f4f22e462f Mon Sep 17 00:00:00 2001
From: Jed Mao <jedmao@outlook.com>
Date: Sun, 10 Nov 2019 05:02:22 -0600
Subject: [PATCH 3/6] and

---
 index.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/index.rst b/index.rst
index f3d98c6..25aa9f0 100644
--- a/index.rst
+++ b/index.rst
@@ -69,7 +69,7 @@ EditorConfig files should be UTF-8 encoded, with LF or CRLF line separators.
 Additionaly, EditorConfig defines the following terms:
 
 - Preamble: the part of the document that precedes the first section. The
-  preamble is optional and may contain declarations, comments or blank lines.
+  preamble is optional and may contain declarations, comments and blank lines.
 - Section Name: the string between the beginning ``[`` and the ending ``]``.
 - Section: the lines starting from a Section Header until the beginning of
   the next Section Header or the end of the file.

From 3d96e629245a53844b1cd64611cfdf054265c9e7 Mon Sep 17 00:00:00 2001
From: Jed Mao <jedmao@outlook.com>
Date: Sun, 10 Nov 2019 23:12:39 -0600
Subject: [PATCH 4/6] more CR updates

---
 index.rst | 22 +++++++++++-----------
 1 file changed, 11 insertions(+), 11 deletions(-)

diff --git a/index.rst b/index.rst
index 25aa9f0..4c035c5 100644
--- a/index.rst
+++ b/index.rst
@@ -48,9 +48,9 @@ is considered irrelevant. Each line must be one of the following:
 - Blank: contains only whitespace characters.
 - Comment: starts with a ``;`` or a ``#``.
    - Inserting a ``#`` or ``;`` after non-whitespace characters in a line
-     (i.e., inline) will not be parsed as a comment; in fact, it will be
-     considered part of the section name, declaration key or value in which
-     it was inserted.
+     (i.e., inline) shall neither be parsed as a comment nor as part of the
+     section name, key or value in which it was inserted. This may change in
+     the future.
 - Section Header: starts with a ``[`` and ends with a ``]``.
    - May not use any non-whitespace characters outside of the surrounding
      brackets.
@@ -116,8 +116,9 @@ When a filename is given to EditorConfig a search is performed in the
 directory of the given file and all parent directories for an EditorConfig
 file (named ".editorconfig" by default).  All found EditorConfig files are
 searched for sections with section names matching the given filename. The
-search will stop if an EditorConfig file is found with the ``root`` Declaration
-set to ``true`` in the preamble or when reaching the root filesystem directory.
+search shall stop if an EditorConfig file is found with the ``root``
+declaration set to ``true`` in the preamble or when reaching the root
+filesystem directory.
 
 Files are read top to bottom and the most recent rules found take
 precedence. If multiple EditorConfig files have matching sections, the rules
@@ -129,7 +130,7 @@ Supported Properties
 
 EditorConfig file sections contain properties, which are key-value pairs
 separated by an equal sign (``=``). Any property other than ``root`` MUST be
-located under a section to take effect. EditorConfig plugins will ignore
+located under a section to take effect. EditorConfig plugins shall ignore
 unrecognized property names and properties with invalid values.
 
 Here is the list of all property names understood by EditorConfig and all
@@ -144,10 +145,9 @@ valid values for these properties:
    * - ``indent_size``
      - Set to a whole number defining the number of columns used for each
        indentation level and the width of soft tabs (when supported). If this
-       equals to ``tab``, the ``indent_size`` will be set to the tab size, which
-       should be ``tab_width`` if ``tab_width`` is specified, or the tab size set
-       by editor if ``tab_width`` is not specified. The values are case
-       insensitive.
+       equals ``tab``, the ``indent_size`` shall be set to the tab size, which
+       should be ``tab_width`` (if specified); else, the tab size set by the
+       editor. The values are case insensitive.
    * - ``tab_width``
      - Set to a whole number defining the number of columns used to represent
        a tab character. This defaults to the value of ``indent_size`` and should
@@ -176,7 +176,7 @@ unset`` to undefine the ``indent_size`` property (and use editor defaults).
 Property names are case insensitive and all property names are lowercased when
 parsing. The maximum length of a property name is 50 characters and the
 maximum length of a property value is 255 characters. Any property beyond
-these limits would be ignored.
+these limits shall be ignored.
 
 Suggestions for Plugin Developers
 =================================

From a8a5168fc74a085fc5286bb4e283dc5fb01b595d Mon Sep 17 00:00:00 2001
From: Jed Mao <jedmao@outlook.com>
Date: Mon, 11 Nov 2019 05:04:12 -0600
Subject: [PATCH 5/6] another one

---
 index.rst | 36 ++++++++++++++++++------------------
 1 file changed, 18 insertions(+), 18 deletions(-)

diff --git a/index.rst b/index.rst
index 4c035c5..9d5e705 100644
--- a/index.rst
+++ b/index.rst
@@ -50,7 +50,7 @@ is considered irrelevant. Each line must be one of the following:
    - Inserting a ``#`` or ``;`` after non-whitespace characters in a line
      (i.e., inline) shall neither be parsed as a comment nor as part of the
      section name, key or value in which it was inserted. This may change in
-     the future.
+     the future; thus, it is not recommended.
 - Section Header: starts with a ``[`` and ends with a ``]``.
    - May not use any non-whitespace characters outside of the surrounding
      brackets.
@@ -68,8 +68,8 @@ EditorConfig files should be UTF-8 encoded, with LF or CRLF line separators.
 
 Additionaly, EditorConfig defines the following terms:
 
-- Preamble: the part of the document that precedes the first section. The
-  preamble is optional and may contain declarations, comments and blank lines.
+- Preamble: the lines that precedes the first section. The preamble is optional
+  and may contain declarations, comments and blank lines.
 - Section Name: the string between the beginning ``[`` and the ending ``]``.
 - Section: the lines starting from a Section Header until the beginning of
   the next Section Header or the end of the file.
@@ -122,19 +122,19 @@ filesystem directory.
 
 Files are read top to bottom and the most recent rules found take
 precedence. If multiple EditorConfig files have matching sections, the rules
-from the closer EditorConfig file are read last, so properties in closer
+from the closer EditorConfig file are read last, so declarations in closer
 files take precedence.
 
-Supported Properties
-====================
+Supported Declarations
+======================
 
-EditorConfig file sections contain properties, which are key-value pairs
-separated by an equal sign (``=``). Any property other than ``root`` MUST be
+EditorConfig file sections contain declarations, which are key-value pairs
+separated by an equal sign (``=``). Any declaration other than ``root`` MUST be
 located under a section to take effect. EditorConfig plugins shall ignore
-unrecognized property names and properties with invalid values.
+unrecognized declaration keys and declarations with invalid values.
 
-Here is the list of all property names understood by EditorConfig and all
-valid values for these properties:
+Here is the list of all declaration keys understood by EditorConfig and all
+valid values for these keys:
 
 .. list-table::
    :header-rows: 0
@@ -169,14 +169,14 @@ valid values for these properties:
        ``.editorconfig`` file search on the current file. The value is case
        insensitive.
 
-For any property, a value of ``unset`` removes the effect of that
-property, even if it has been set before. For example, add ``indent_size =
-unset`` to undefine the ``indent_size`` property (and use editor defaults).
+For any declaration, a value of ``unset`` removes the effect of that
+declaration, even if it has been set before. For example, add ``indent_size =
+unset`` to undefine the ``indent_size`` declaration (and use editor defaults).
 
-Property names are case insensitive and all property names are lowercased when
-parsing. The maximum length of a property name is 50 characters and the
-maximum length of a property value is 255 characters. Any property beyond
-these limits shall be ignored.
+Declaration keys are case insensitive. All keys are lowercased after parsing.
+The maximum length of a declaration key is 50 characters and the maximum length
+of a declaration value is 255 characters. Any key or value beyond these limits
+shall be ignored.
 
 Suggestions for Plugin Developers
 =================================

From 605c0c469855a2b534e44a08a8ca046a2873daf4 Mon Sep 17 00:00:00 2001
From: Jed Mao <jedmao@outlook.com>
Date: Tue, 12 Nov 2019 00:14:28 -0600
Subject: [PATCH 6/6] fixes

---
 index.rst | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/index.rst b/index.rst
index 9d5e705..8d9bb7c 100644
--- a/index.rst
+++ b/index.rst
@@ -41,9 +41,10 @@ with version control systems.
 File Format
 ===========
 
-EditorConfig uses a strict EditorConfig-INI file format. In an EditorConfig
-file (usually named ``.editorconfig``), all beginning whitespace on each line
-is considered irrelevant. Each line must be one of the following:
+EditorConfig uses an [INI file format](https://en.wikipedia.org/wiki/INI_file).
+In an EditorConfig file (usually named ``.editorconfig``), all beginning
+whitespace on each line is considered irrelevant. Each line must be one of the
+following:
 
 - Blank: contains only whitespace characters.
 - Comment: starts with a ``;`` or a ``#``.
@@ -128,7 +129,7 @@ files take precedence.
 Supported Declarations
 ======================
 
-EditorConfig file sections contain declarations, which are key-value pairs
+EditorConfig file sections contain declarations (i.e., key-value pairs)
 separated by an equal sign (``=``). Any declaration other than ``root`` MUST be
 located under a section to take effect. EditorConfig plugins shall ignore
 unrecognized declaration keys and declarations with invalid values.