document a limitation in the original Pod tables

[finanalyst]

• parsing and processing of Pod Table assumed only one header row
• changing this behaviour turns out to be more complex.
• since the extra flexibility is in procedural tables, it seems a case of diminishing returns to get multiple lines in a text-table header.

@thoughtstream @lizmat thoughts?

[lizmat]

Take this visual table:

hello   |  world
foo     | bar
========|======
this    | that

The legacy implementation of pod6 will consider the header to consist of: "hello foo" and "world bar" as single cells.

The Raku grammar follows this, but doesn't get rid of the extra whitespace, so you would get "hello \nfoo " and "world\nbar".

Fixing this in the Raku grammar would basically mean removing a lot of logic to create this result, but in the process break the generation of legacy $=pod. So it would mean moving that logic to the "generate legacy Pod objects out of the RakuAST tree. Which is a twisty maze of hacks to mimic the twisty maze of hacks in the legacy grammar.

I'd rather not have to go there again.

And since there is a workaround for creating double line headers (namely use the procedural form of a table), I thought allowing the current behaviour wouldn't be a big issue.

[finanalyst]

@thoughtstream I agree that my 'clarification' is confusing. @lizmat has stated the problem better.

Perhaps something along the lines of '... renderers are expected to treat multi-line header rows as a single row ...'

Alternatively, we take out all the examples of multiple line in the header section of tables, pointing out that more control over headers is possible with procedural tables.

[thoughtstream]

Thank you both for clarifying the issue here, @lizmat and @finanalyst.

My preference for addressing this issue in the spec would be something like this:

Visual-style tables can only have a single header row (namely: everything before the first ===== line). That single header may, however, span one or more initial lines of the visual table specification, as some of the preceding examples illustrate. However, regardless of how many lines a visual-style header spans, it is always treated as a single header row. Individual renderers are free to choose how they represent visual header contents that have line breaks in them: they may treat them as a single string to be reflowed and wrapped, or they may elect to preserve the original line breaks within each header cell. The only requirement is that the entire header of a visual-style table must be rendered as a single row of cells. If two or more header rows are required, use a procedural table instead.