Pipe table should clarify that one separator row is conventional

[MarkLodato]

The spec does not explicitly say that the convention is for a single separator row. The very first example shows a separator between every row:

| a  |  b |
|----|:--:|
| 1  | 2  |
|:---|---:|
| 3  | 4  |

This implies that a separator is required between each row. Nothing explicitly states that separators are not required, and no examples shows multiple rows without separators between.

I think it would be helpful to start with a more conventional example, something like:

| decimal | alpha |
| --- | --- |
| 1 | a |
| 2 | b |
| 3 | c |

[jgm]

Actually, that example is meant to show a case with two heading rows. A row with a separator under it is a heading. But perhaps you're right that a simpler example up front is a good idea.

[waldyrious]

A row with a separator under it is a heading.

A little off-topic here, but would you consider a simpler syntax for heading rows? Instead of

| decimal | alpha |
| --- | --- |
| 1 | a |
| 2 | b |
| 3 | c |

...it could be:

|# decimal | alpha |
| 1 | a |
| 2 | b |
| 3 | c |

This would be more compact, it would still be usable in multiple rows, and it reuses the heading marker #, which is more consistent (the existing convention resembles setext-style headings, which Djot departs from).

I can open a separate issue if that's something you would consider.

[jgm]

@waldyrious no, I prefer the current approach.