Clarify whitespace handling (#46)

* Fix punctuation errors [no substantive changes]

Change single-backticks to double-backticks as required by rst.

* Clarify wording of what lines need to be

- Clarify that leading and trailing whitespace are ignored
  on all lines (so empty lines count as blank, which they technically
  did not before).
- Express the parsing logic imperatively to make it easier to read.
- Add links within the document from line types to relevant sections.

conf.py

@@ -21,8 +21,8 @@
 copyright = '2019--2024, EditorConfig Team'
 author = 'EditorConfig Team'
 
-version = '0.17.1'
-release = '0.17.1'
+version = '0.17.2'
+release = '0.17.2'
 
 # -- General configuration ---------------------------------------------------
 

index.rst

@@ -1,4 +1,4 @@
-..  Copyright (c) 2019--2020 EditorConfig Team
+..  Copyright (c) 2019--2024 EditorConfig Team
     All rights reserved.
 
     Redistribution and use in source and binary forms, with or without
@@ -73,25 +73,35 @@ EditorConfig organization.
 File Format
 ===========
 
-.. versionchanged:: 0.17.0
+.. versionchanged:: 0.17.2
 
 EditorConfig files are in an INI-like file format.
-In an EditorConfig file, all beginning whitespace on each line is considered
-irrelevant. Each line must be one of the following:
+To read an EditorConfig file, take one line at a time, from beginning to end.
+For each line:
+
+#. Remove all leading and trailing whitespace.
+#. Process the remaining text as specified for its type below.
+
+The types of lines are:
+
+- Blank: Contains nothing.  Blank lines are ignored.
+
+- Comment: starts with a ``;`` or a ``#``.  Comment lines are ignored.
 
-- Blank: contains only whitespace characters.
-- Comment: starts with a ``;`` or a ``#``.
 - Section Header: starts with a ``[`` and ends with a ``]``.
-   - May not use any non-whitespace characters outside of the surrounding
-     brackets.
+  These lines define globs; see :ref:`glob-expressions`.
+
    - May contain any characters between the square brackets (e.g.,
      ``[`` and ``]`` and even spaces and tabs are allowed).
    - Forward slashes (``/``) are used as path separators.
    - Backslashes (``\\``) are not allowed as path separators (even on Windows).
-- Key-Value Pair (or Pair): contains a key and a value, separated by an `=`.
-   - Key: The part before the first `=` (trimmed of whitespace, but including
+
+- Key-Value Pair (or Pair): contains a key and a value, separated by an ``=``.
+  See :ref:`supported-pairs`.
+
+   - Key: The part before the first ``=`` (trimmed of whitespace, but including
      any whitespace in the middle).
-   - Value: The part after the first `=` (trimmed of whitespace, but including
+   - Value: The part after the first ``=`` (trimmed of whitespace, but including
      any whitespace in the middle).
 
 Any line that is not one of the above is invalid.
@@ -117,7 +127,7 @@ This specification does not define any "escaping" mechanism for
 
 .. admonition :: Compatibility
 
-  The EditorConfig file format formerly allowed the use of `;` and `#` after the
+  The EditorConfig file format formerly allowed the use of ``;`` and ``#`` after the
   beginning of the line to mark the rest of a line as comment. This led to
   confusion how to parse values containing those characters. Old EditorConfig
   parsers may still allow inline comments.
@@ -133,6 +143,8 @@ The parts of an EditorConfig file are:
 - Section: the lines starting from a Section Header until the beginning of
   the next Section Header or the end of the file.
 
+.. _glob-expressions:
+
 Glob Expressions
 ================
 
@@ -194,6 +206,8 @@ precedence. If multiple EditorConfig files have matching sections, the rules
 from the closer EditorConfig file are read last, so pairs in closer
 files take precedence.
 
+.. _supported-pairs:
+
 Supported Pairs
 ===============