diff --git a/doc-build/md060.md b/doc-build/md060.md index 0cff46bc..aa58e9ac 100644 --- a/doc-build/md060.md +++ b/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: @@ -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 diff --git a/doc/Rules.md b/doc/Rules.md index 8d067e7f..3bc294fc 100644 --- a/doc/Rules.md +++ b/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: @@ -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 @@ -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