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
