On Thu, 2020-05-07 at 14:03 +0100, Daniel P. Berrangé wrote:
On Thu, May 07, 2020 at 02:55:24PM +0200, Peter Krempa wrote:
On Thu, May 07, 2020 at 14:46:38 +0200, Andrea Bolognani wrote:
-+-------------------------------+------------------------------------------------------------+ -| Macro | Meaning | -+===============================+============================================================+ -| ``ATTRIBUTE_NONNULL`` | passing NULL for this parameter is not allowed | -+-------------------------------+------------------------------------------------------------+
+.. list-table:: + :header-rows: 1 + + * - Macro + - Meaning + + * - ``ATTRIBUTE_NONNULL`` + - passing NULL for this parameter is not allowed
Well, the ascii-art version is more readable when looking at the text version.
I don't disagree.
I think there's probably a tradeoff to be had, based on the complexity and size of the table.
For only simple tables where each line is less than 80 chars, and only 1 line high per row, then the ascii-art table is visually nicer.
It's very unlikely that you'll have such a table: either you split the text across multiple lines to keep each under 80 chars, or you stick to a single line per row and end up with very long lines. The exception would probably be very simple two-rows tables, which as you mention below could be replaced with definition lists instead.
For tables where we're likely to exceed 80 chars, the list-table is probably better choice, otherwise things just get too wide.
Another thing to keep in mind is that using list-table makes the diffs when adding/removing rows, or even column, much more sane than they would be otherwise.
In this particular case, I think we didn't need a table at all in the first place. It would be fine as a "definition list".
For this specific case I think you're right. -- Andrea Bolognani / Red Hat / Virtualization