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

[Daniel P. Berrangé]

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:
> > Signed-off-by: Andrea Bolognani <abologna at redhat.com>
> > ---
> >  docs/coding-style.rst  |  53 +++++++++++-------
> >  docs/glib-adoption.rst | 123 +++++++++++++++++++++++++++--------------
> >  2 files changed, 114 insertions(+), 62 deletions(-)
> > 
> > diff --git a/docs/coding-style.rst b/docs/coding-style.rst
> > index 151ea87b6a..15c3a0b22d 100644
> > --- a/docs/coding-style.rst
> > +++ b/docs/coding-style.rst
> > @@ -547,27 +547,38 @@ Attribute annotations
> >  Use the following annotations to help the compiler and/or static
> >  analysis tools understand the code better:
> >  
> > -+-------------------------------+------------------------------------------------------------+
> > -| Macro                         | Meaning                                                    |
> > -+===============================+============================================================+
> > -| ``ATTRIBUTE_NONNULL``         | passing NULL for this parameter is not allowed             |
> > -+-------------------------------+------------------------------------------------------------+
> > -| ``ATTRIBUTE_PACKED``          | force a structure to be packed                             |
> > -+-------------------------------+------------------------------------------------------------+
> > -| ``G_GNUC_FALLTHROUGH``        | allow code reuse by multiple switch cases                  |
> > -+-------------------------------+------------------------------------------------------------+
> > -| ``G_GNUC_NO_INLINE``          | the function is mocked in the test suite                   |
> > -+-------------------------------+------------------------------------------------------------+
> > -| ``G_GNUC_NORETURN``           | the function never returns                                 |
> > -+-------------------------------+------------------------------------------------------------+
> > -| ``G_GNUC_NULL_TERMINATED``    | last parameter must be NULL                                |
> > -+-------------------------------+------------------------------------------------------------+
> > -| ``G_GNUC_PRINTF``             | validate that the formatting string matches parameters     |
> > -+-------------------------------+------------------------------------------------------------+
> > -| ``G_GNUC_UNUSED``             | parameter is unused in this implementation of the function |
> > -+-------------------------------+------------------------------------------------------------+
> > -| ``G_GNUC_WARN_UNUSED_RESULT`` | the return value must be checked                           |
> > -+-------------------------------+------------------------------------------------------------+
> > +.. 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 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.

For tables where we're likely to exceed 80 chars, the list-table is
probably better choice, otherwise things just get too wide.


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".


Regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|