doc/todo/support_multi-row_table_headers.mdwn

   1 [[!template id=gitbranch branch=jon/table_headerblock author="[[Jon]]"]]
   2 [[!tag reviewed]]
   3
   4 It would be great if it were possible to support multi-row table headers in the [[plugins/table]] plugin, so you could do e.g.
   5
   6         \[[!table header="""
   7         Name | Platform ||
   8         | Windows | Mac | Linux
   9         """ data="""
  10         ikiwiki | ‧ | ✓ | ✓
  11         """]]
  12
  13 -- [[Jon]]
  14
  15 [[!tag wishlist patch]]
  16
  17 > This seems like weird overloading of the header parameter - it's
  18 > table data, except when it isn't.
  19
  20 > > My first cut (now rebased out of existence I think) introduced a
  21 > > new "headerblock" parameter, but trying to clearly document the
  22 > > interaction of data/headerblock/header parameters was too awkward. -- [[Jon]]
  23
  24 > Perhaps
  25 > something like this would be easier to use in practice?
  26 > (and also more featureful :-) )
  27 >
  28 >     \[[!table header="2 rows 1 column" data="""
  29 >     Name | Platform ||
  30 >     | Windows | Mac | Linux
  31 >     ikiwiki | no | yes | yes
  32 >     Starcraft | yes | yes | via Wine
  33 >     """]]
  34
  35 > > Thanks for your prompt feedback!
  36 > >
  37 > > This would probably be good, yes, and having mixed row/column headers is
  38 > > definitely a nice-to-have. I don't relish the prospect of writing the parser
  39 > > but I see you've made a stab already...
  40 > >
  41 > > One thing you'd lose, but it's debatable whether this is valuable, would be
  42 > > to have the header defined in the directive, and the remaining table data
  43 > > declared in an external CSV. -- [[Jon]]
  44
  45 > intended to be rendered like
  46 >
  47 > <table>
  48 > <tr><th>Name</th><th colspan=2>Platform</th>
  49 > <tr><th></th><th>Windows</th><th>Mac</th><th>Linux</th></tr>
  50 > <tr><th>ikiwiki</th><td>no</td><td>yes</td><td>yes</td></tr>
  51 > <tr><th>Starcraft</th><td>yes</td><td>yes</td><td>via Wine</td></tr>
  52 > </table>
  53 >
  54 > (Deliberately switching to plain-text to make it more obvious
  55 > what's a `<th>` and what's `<td>`.)
  56 >
  57 > Vague pseudocode for parsing `headers`
  58 > (possibly even valid Perl, I'm not sure):
  59 >
  60 >     my ($header_rows, $header_cols);
  61 >     while ($header =~ s/(\d*)\W*(\w+)//) {
  62 >         my $n = ($1 or 0);
  63 >         my $what = $2;
  64 >         if ($what =~ m/rows?/) {
  65 >             $header_rows = $n;
  66 >         }
  67 >         elif ($what =~ m/col(?:umn)?s?/) {
  68 >             $header_cols = $n;
  69 >         }
  70 >     }
  71 >
  72 > and it would even be fairly easy to extend to support
  73 > `(first|last|)\W*(\d*)\W*(\w+)` later, e.g.
  74 > `header="1 row, first 2 cols, last column"`.
  75 >
  76 > --[[smcv]]
  77
  78 > > To be clear I think your suggestion is a good one, but my hack has
  79 > > addressed my immediate need so it's the one I'm deploying at $ork for the
  80 > > time being. I'm unlikely to have time to implement this solution in the
  81 > > near future. -- [[Jon]]
  82
  83 ----
  84
  85 I'd quite like to revisit this if that's ok. I'm still carrying a fork of
  86 table.pm locally to add this feature as I find it so useful. The main objection
  87 you made back in 2014 seems to be overloading the header= parameter, and I agree
  88 that this is not ideal. So I'm happy to resubmit this with an alternative parameter
  89 name for the new purpose. But I balked at the idea of implementing something like
  90 an NLP processor to define the header range. And I must stress how useful it is in
  91 practise to separate out the header definition from the data: quite often I don't
  92 want headers in my CSV files at all, for example, so I can perform rudimentary analysis
  93 on them with command line tools without having to factor in a header line (how many
  94 records?  = `wc -l`; sorting on fields simply with `sort -k` etc.). Having them
  95 separate means I can have machine-generated or manipulated CSV files of data and then
  96 use ikiwiki to mark them up for human reading, but change or regenerate the data quickly
  97 and easily underneath.
  98
  99 I'd appreciate your take on the above suggestions [[smcv]] before I roll my sleeves up.
 100 Thanks! — [[Jon]] (2018-09-24)
 101
 102 > I continue to think that the `header` parameter shouldn't be sometimes a
 103 > description of which parts of the table are header, and sometimes the header
 104 > data itself; so if you want an inline header, it should indeed have a
 105 > distinct name.
 106 >
 107 > If you can think of a good name for the new parameter, and can document it
 108 > reasonably clearly, then I would be OK with having a separate parameter that
 109 > is the externally-provided header. I don't know what the right name for that
 110 > parameter would be: `headercontent` or `headerblock` is unwieldy but I can't
 111 > think of anything better.
 112 >
 113 > It would maybe simplify things to make it mutually exclusive with `header`,
 114 > but then you wouldn't be able to express things like "the first column of my
 115 > CSV is a header, the first row is just an ordinary row, and please add
 116 > this literal header row to the top".
 117 >
 118 > It might help to write the documentation and/or tests first, and then
 119 > implement it afterwards, when you have an "API" you're happy with.
 120 >
 121 > Corner cases:
 122 >
 123 > How would it work if you want to add a literal header column on the left
 124 > rather than adding a literal header row on the top? If you add both, what
 125 > happens at the top left corner?
 126 >
 127 > Is it necessary to be able to add header columns on the right (for RTL
 128 > languages?), or header rows (footer rows, I suppose) on the bottom?
 129 >
 130 > --[[smcv]]