wip

doc-build/md060.md

@@ -3,7 +3,7 @@ This rule is triggered when the column separators of a
 
 This rule recognizes three table column styles based on popular use:
 
-Style `aligned` looks the most like a table:
+Style `aligned` ensures table delimiters are vertically aligned and orderly:
 
 ```markdown
 | Character | Meaning |
@@ -12,7 +12,16 @@ Style `aligned` looks the most like a table:
 | N         | No      |
 ```
 
-Style `compact` uses a single space to pad cell content:
+The `aligned` style ignores cell content, so the following is also valid:
+
+```markdown
+| Character | Meaning |
+|-----------|---------|
+|     Y     |     Yes |
+|     N     |      No |
+```
+
+Style `compact` avoids extra padding with a single space around cell content:
 
 ```markdown
 | Character | Meaning |
@@ -21,7 +30,7 @@ Style `compact` uses a single space to pad cell content:
 | N | No |
 ```
 
-Style `tight` uses no padding for cell content:
+Style `tight` uses no padding at all for cell content:
 
 ```markdown
 |Character|Meaning|
@@ -31,15 +40,18 @@ Style `tight` uses no padding for cell content:
 ```
 
 When this rule's `style` parameter is set to `aligned`, `compact`, or `tight`,
-every table must match the corresponding pattern and errors will be reported for
-any violations. By default, or when the `any` style is used, each table is
-analyzed to see if it satisfies any supported style. If so, no errors are
-reported. If not, errors are be reported for whichever style would produce the
-*fewest* errors (i.e., whichever style is the closest match).
+every table must match the corresponding pattern and any violations will be
+reported for. By default, or when the `any` style is used, each table is
+analyzed to see if it satisfies any supported style. If so, no violations are
+reported. If not, violations are be reported for whichever style would produce
+the *fewest* issues (i.e., whichever style is the closest match).
 
-Note: Pipe alignment for the `aligned` style is based on ...
-The following table is correctly aligned based on character count, though some
-editors render the emoji wider:
+Note: Delimiter placement for the `aligned` style is based on visual appearance
+and not character count. Because editors typically render [emoji][emoji] and
+[CJK characters][cjk-characters] at *twice* the width of
+[Latin characters][latin-script], this rule takes that into account for tables
+using the `aligned` style. The following table is therefore correctly formatted
+and will appear aligned in most editors and monospaced fonts:
 
 <!-- markdownlint-capture -->
 <!-- markdownlint-disable extended-ascii -->
@@ -55,4 +67,7 @@ editors render the emoji wider:
 
 Rationale: Consistent formatting makes it easier to understand a document.
 
+[cjk-characters]: https://en.wikipedia.org/wiki/CJK_characters
+[emoji]: https://en.wikipedia.org/wiki/Emoji
 [gfm-table-060]: https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/organizing-information-with-tables
+[latin-script]: https://en.wikipedia.org/wiki/Latin_script

doc/Rules.md

@@ -2702,7 +2702,7 @@ This rule is triggered when the column separators of a
 
 This rule recognizes three table column styles based on popular use:
 
-Style `aligned` looks the most like a table:
+Style `aligned` ensures table delimiters are vertically aligned and orderly:
 
 ```markdown
 | Character | Meaning |
@@ -2711,7 +2711,16 @@ Style `aligned` looks the most like a table:
 | N         | No      |
 ```
 
-Style `compact` uses a single space to pad cell content:
+The `aligned` style ignores cell content, so the following is also valid:
+
+```markdown
+| Character | Meaning |
+|-----------|---------|
+|     Y     |     Yes |
+|     N     |      No |
+```
+
+Style `compact` avoids extra padding with a single space around cell content:
 
 ```markdown
 | Character | Meaning |
@@ -2720,7 +2729,7 @@ Style `compact` uses a single space to pad cell content:
 | N | No |
 ```
 
-Style `tight` uses no padding for cell content:
+Style `tight` uses no padding at all for cell content:
 
 ```markdown
 |Character|Meaning|
@@ -2730,15 +2739,18 @@ Style `tight` uses no padding for cell content:
 ```
 
 When this rule's `style` parameter is set to `aligned`, `compact`, or `tight`,
-every table must match the corresponding pattern and errors will be reported for
-any violations. By default, or when the `any` style is used, each table is
-analyzed to see if it satisfies any supported style. If so, no errors are
-reported. If not, errors are be reported for whichever style would produce the
-*fewest* errors (i.e., whichever style is the closest match).
+every table must match the corresponding pattern and any violations will be
+reported for. By default, or when the `any` style is used, each table is
+analyzed to see if it satisfies any supported style. If so, no violations are
+reported. If not, violations are be reported for whichever style would produce
+the *fewest* issues (i.e., whichever style is the closest match).
 
-Note: Pipe alignment for the `aligned` style is based on ...
-The following table is correctly aligned based on character count, though some
-editors render the emoji wider:
+Note: Delimiter placement for the `aligned` style is based on visual appearance
+and not character count. Because editors typically render [emoji][emoji] and
+[CJK characters][cjk-characters] at *twice* the width of
+[Latin characters][latin-script], this rule takes that into account for tables
+using the `aligned` style. The following table is therefore correctly formatted
+and will appear aligned in most editors and monospaced fonts:
 
 <!-- markdownlint-capture -->
 <!-- markdownlint-disable extended-ascii -->
@@ -2754,7 +2766,10 @@ editors render the emoji wider:
 
 Rationale: Consistent formatting makes it easier to understand a document.
 
+[cjk-characters]: https://en.wikipedia.org/wiki/CJK_characters
+[emoji]: https://en.wikipedia.org/wiki/Emoji
 [gfm-table-060]: https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/organizing-information-with-tables
+[latin-script]: https://en.wikipedia.org/wiki/Latin_script
 
 <!-- markdownlint-configure-file {
   "no-inline-html": {

doc/md060.md

@@ -14,7 +14,7 @@ This rule is triggered when the column separators of a
 
 This rule recognizes three table column styles based on popular use:
 
-Style `aligned` looks the most like a table:
+Style `aligned` ensures table delimiters are vertically aligned and orderly:
 
 ```markdown
 | Character | Meaning |
@@ -23,7 +23,16 @@ Style `aligned` looks the most like a table:
 | N         | No      |
 ```
 
-Style `compact` uses a single space to pad cell content:
+The `aligned` style ignores cell content, so the following is also valid:
+
+```markdown
+| Character | Meaning |
+|-----------|---------|
+|     Y     |     Yes |
+|     N     |      No |
+```
+
+Style `compact` avoids extra padding with a single space around cell content:
 
 ```markdown
 | Character | Meaning |
@@ -32,7 +41,7 @@ Style `compact` uses a single space to pad cell content:
 | N | No |
 ```
 
-Style `tight` uses no padding for cell content:
+Style `tight` uses no padding at all for cell content:
 
 ```markdown
 |Character|Meaning|
@@ -42,15 +51,18 @@ Style `tight` uses no padding for cell content:
 ```
 
 When this rule's `style` parameter is set to `aligned`, `compact`, or `tight`,
-every table must match the corresponding pattern and errors will be reported for
-any violations. By default, or when the `any` style is used, each table is
-analyzed to see if it satisfies any supported style. If so, no errors are
-reported. If not, errors are be reported for whichever style would produce the
-*fewest* errors (i.e., whichever style is the closest match).
+every table must match the corresponding pattern and any violations will be
+reported for. By default, or when the `any` style is used, each table is
+analyzed to see if it satisfies any supported style. If so, no violations are
+reported. If not, violations are be reported for whichever style would produce
+the *fewest* issues (i.e., whichever style is the closest match).
 
-Note: Pipe alignment for the `aligned` style is based on ...
-The following table is correctly aligned based on character count, though some
-editors render the emoji wider:
+Note: Delimiter placement for the `aligned` style is based on visual appearance
+and not character count. Because editors typically render [emoji][emoji] and
+[CJK characters][cjk-characters] at *twice* the width of
+[Latin characters][latin-script], this rule takes that into account for tables
+using the `aligned` style. The following table is therefore correctly formatted
+and will appear aligned in most editors and monospaced fonts:
 
 <!-- markdownlint-capture -->
 <!-- markdownlint-disable extended-ascii -->
@@ -66,4 +78,7 @@ editors render the emoji wider:
 
 Rationale: Consistent formatting makes it easier to understand a document.
 
+[cjk-characters]: https://en.wikipedia.org/wiki/CJK_characters
+[emoji]: https://en.wikipedia.org/wiki/Emoji
 [gfm-table-060]: https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/organizing-information-with-tables
+[latin-script]: https://en.wikipedia.org/wiki/Latin_script