[libvirt PATCH 1/2] docs: Convert existing tables to list-table

[Andrea Bolognani]

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