7:46 a.m.
It's easier to modify than the ASCII-art alternative.
Andrea Bolognani (2):
docs: Convert existing tables to list-table
docs: Document list-tables as recommended
docs/coding-style.rst | 53 +++++++++++-------
docs/glib-adoption.rst | 123 +++++++++++++++++++++++++++--------------
docs/styleguide.rst | 20 +++++++
3 files changed, 134 insertions(+), 62 deletions(-)
--
2.25.4
7:46 a.m.
New subject: [libvirt PATCH 1/2] docs: Convert existing tables to list-table
Signed-off-by: Andrea Bolognani <abologna(a)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
+
+ * - ``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
File handling
-------------
diff --git a/docs/glib-adoption.rst b/docs/glib-adoption.rst
index 62ddd7c61d..a5dca47f5e 100644
--- a/docs/glib-adoption.rst
+++ b/docs/glib-adoption.rst
@@ -53,44 +53,85 @@ The following libvirt APIs have been deleted already:
``VIR_STRDUP``, ``VIR_STRNDUP``
Prefer the GLib APIs ``g_strdup`` and ``g_strndup``.
-+-------------------------------+--------------------------------------+-------------------------------------------+
-| deleted version | GLib version | Notes
|
-+===============================+======================================+===========================================+
-| ``VIR_AUTOPTR`` | ``g_autoptr`` |
|
-+-------------------------------+--------------------------------------+-------------------------------------------+
-| ``VIR_AUTOCLEAN`` | ``g_auto`` |
|
-+-------------------------------+--------------------------------------+-------------------------------------------+
-| ``VIR_AUTOFREE`` | ``g_autofree`` | The GLib version
does not use parentheses |
-+-------------------------------+--------------------------------------+-------------------------------------------+
-| ``VIR_AUTOUNREF`` | ``g_autoptr`` | The cleanup
function needs to be defined |
-+-------------------------------+--------------------------------------+-------------------------------------------+
-| ``VIR_DEFINE_AUTOPTR_FUNC`` | ``G_DEFINE_AUTOPTR_CLEANUP_FUNC`` |
|
-+-------------------------------+--------------------------------------+-------------------------------------------+
-| ``VIR_DEFINE_AUTOCLEAN_FUNC`` | ``G_DEFINE_AUTO_CLEANUP_CLEAR_FUNC`` |
|
-+-------------------------------+--------------------------------------+-------------------------------------------+
-| ``VIR_STEAL_PTR`` | ``g_steal_pointer`` | ``a =
f(&b)`` instead of ``f(a, b)`` |
-+-------------------------------+--------------------------------------+-------------------------------------------+
-| ``VIR_RETURN_PTR`` | ``return g_steal_pointer`` |
|
-+-------------------------------+--------------------------------------+-------------------------------------------+
-| ``ARRAY_CARDINALITY`` | ``G_N_ELEMENTS`` |
|
-+-------------------------------+--------------------------------------+-------------------------------------------+
-| ``ATTRIBUTE_FALLTHROUGH`` | ``G_GNUC_FALLTHROUGH`` |
|
-+-------------------------------+--------------------------------------+-------------------------------------------+
-| ``ATTRIBUTE_FMT_PRINTF`` | ``G_GNUC_PRINTF`` |
|
-+-------------------------------+--------------------------------------+-------------------------------------------+
-| ``ATTRIBUTE_NOINLINE`` | ``G_GNUC_NO_INLINE`` |
|
-+-------------------------------+--------------------------------------+-------------------------------------------+
-| ``ATTRIBUTE_NORETURN`` | ``G_GNUC_NORETURN`` |
|
-+-------------------------------+--------------------------------------+-------------------------------------------+
-| ``ATTRIBUTE_RETURN_CHECK`` | ``G_GNUC_WARN_UNUSED_RESULT`` |
|
-+-------------------------------+--------------------------------------+-------------------------------------------+
-| ``ATTRIBUTE_SENTINEL`` | ``G_GNUC_NULL_TERMINATED`` |
|
-+-------------------------------+--------------------------------------+-------------------------------------------+
-| ``ATTRIBUTE_UNUSED`` | ``G_GNUC_UNUSED`` |
|
-+-------------------------------+--------------------------------------+-------------------------------------------+
-| ``VIR_STRDUP`` | ``g_strdup`` |
|
-+-------------------------------+--------------------------------------+-------------------------------------------+
-| ``VIR_STRNDUP`` | ``g_strndup`` |
|
-+-------------------------------+--------------------------------------+-------------------------------------------+
-| ``virStrerror`` | ``g_strerror`` |
|
-+-------------------------------+--------------------------------------+-------------------------------------------+
+.. list-table::
+ :header-rows: 1
+
+ * - deleted version
+ - GLib version
+ - Notes
+
+ * - ``VIR_AUTOPTR``
+ - ``g_autoptr``
+ -
+
+ * - ``VIR_AUTOCLEAN``
+ - ``g_auto``
+ -
+
+ * - ``VIR_AUTOFREE``
+ - ``g_autofree``
+ - The GLib version does not use parentheses
+
+ * - ``VIR_AUTOUNREF``
+ - ``g_autoptr``
+ - The cleanup function needs to be defined
+
+ * - ``VIR_DEFINE_AUTOPTR_FUNC``
+ - ``G_DEFINE_AUTOPTR_CLEANUP_FUNC``
+ -
+
+ * - ``VIR_DEFINE_AUTOCLEAN_FUNC``
+ - ``G_DEFINE_AUTO_CLEANUP_CLEAR_FUNC``
+ -
+
+ * - ``VIR_STEAL_PTR``
+ - ``g_steal_pointer``
+ - ``a = f(&b)`` instead of ``f(a, b)``
+
+ * - ``VIR_RETURN_PTR``
+ - ``return g_steal_pointer``
+ -
+
+ * - ``ARRAY_CARDINALITY``
+ - ``G_N_ELEMENTS``
+ -
+
+ * - ``ATTRIBUTE_FALLTHROUGH``
+ - ``G_GNUC_FALLTHROUGH``
+ -
+
+ * - ``ATTRIBUTE_FMT_PRINTF``
+ - ``G_GNUC_PRINTF``
+ -
+
+ * - ``ATTRIBUTE_NOINLINE``
+ - ``G_GNUC_NO_INLINE``
+ -
+
+ * - ``ATTRIBUTE_NORETURN``
+ - ``G_GNUC_NORETURN``
+ -
+
+ * - ``ATTRIBUTE_RETURN_CHECK``
+ - ``G_GNUC_WARN_UNUSED_RESULT``
+ -
+
+ * - ``ATTRIBUTE_SENTINEL``
+ - ``G_GNUC_NULL_TERMINATED``
+ -
+
+ * - ``ATTRIBUTE_UNUSED``
+ - ``G_GNUC_UNUSED``
+ -
+
+ * - ``VIR_STRDUP``
+ - ``g_strdup``
+ -
+
+ * - ``VIR_STRNDUP``
+ - ``g_strndup``
+ -
+
+ * - ``virStrerror``
+ - ``g_strerror``
+ -
--
2.25.4
7:55 a.m.
New subject: [libvirt PATCH 1/2] docs: Convert existing tables to list-table
On Thu, May 07, 2020 at 14:46:38 +0200, Andrea Bolognani wrote:
Signed-off-by: Andrea Bolognani <abologna(a)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.
8:03 a.m.
New subject: [libvirt PATCH 1/2] docs: Convert existing tables to list-table
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(a)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 :|
8:34 a.m.
New subject: [libvirt PATCH 1/2] docs: Convert existing tables to list-table
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
8:04 a.m.
New subject: [libvirt PATCH 1/2] docs: Convert existing tables to list-table
On Thu, May 07, 2020 at 02:46:38PM +0200, Andrea Bolognani wrote:
Signed-off-by: Andrea Bolognani <abologna(a)redhat.com>
---
docs/coding-style.rst | 53 +++++++++++-------
docs/glib-adoption.rst | 123 +++++++++++++++++++++++++++--------------
2 files changed, 114 insertions(+), 62 deletions(-)
diff --git a/docs/glib-adoption.rst b/docs/glib-adoption.rst
index 62ddd7c61d..a5dca47f5e 100644
--- a/docs/glib-adoption.rst
+++ b/docs/glib-adoption.rst
@@ -53,44 +53,85 @@ The following libvirt APIs have been deleted already:
``VIR_STRDUP``, ``VIR_STRNDUP``
Prefer the GLib APIs ``g_strdup`` and ``g_strndup``.
-+-------------------------------+--------------------------------------+-------------------------------------------+
-| deleted version | GLib version | Notes
|
-+===============================+======================================+===========================================+
-| ``VIR_AUTOPTR`` | ``g_autoptr`` |
|
-+-------------------------------+--------------------------------------+-------------------------------------------+
-| ``VIR_AUTOCLEAN`` | ``g_auto`` |
|
-+-------------------------------+--------------------------------------+-------------------------------------------+
-| ``VIR_AUTOFREE`` | ``g_autofree`` | The GLib
version does not use parentheses |
-+-------------------------------+--------------------------------------+-------------------------------------------+
-| ``VIR_AUTOUNREF`` | ``g_autoptr`` | The cleanup
function needs to be defined |
-+-------------------------------+--------------------------------------+-------------------------------------------+
-| ``VIR_DEFINE_AUTOPTR_FUNC`` | ``G_DEFINE_AUTOPTR_CLEANUP_FUNC`` |
|
-+-------------------------------+--------------------------------------+-------------------------------------------+
-| ``VIR_DEFINE_AUTOCLEAN_FUNC`` | ``G_DEFINE_AUTO_CLEANUP_CLEAR_FUNC`` |
|
-+-------------------------------+--------------------------------------+-------------------------------------------+
-| ``VIR_STEAL_PTR`` | ``g_steal_pointer`` | ``a =
f(&b)`` instead of ``f(a, b)`` |
-+-------------------------------+--------------------------------------+-------------------------------------------+
-| ``VIR_RETURN_PTR`` | ``return g_steal_pointer`` |
|
-+-------------------------------+--------------------------------------+-------------------------------------------+
-| ``ARRAY_CARDINALITY`` | ``G_N_ELEMENTS`` |
|
-+-------------------------------+--------------------------------------+-------------------------------------------+
-| ``ATTRIBUTE_FALLTHROUGH`` | ``G_GNUC_FALLTHROUGH`` |
|
-+-------------------------------+--------------------------------------+-------------------------------------------+
-| ``ATTRIBUTE_FMT_PRINTF`` | ``G_GNUC_PRINTF`` |
|
-+-------------------------------+--------------------------------------+-------------------------------------------+
-| ``ATTRIBUTE_NOINLINE`` | ``G_GNUC_NO_INLINE`` |
|
-+-------------------------------+--------------------------------------+-------------------------------------------+
-| ``ATTRIBUTE_NORETURN`` | ``G_GNUC_NORETURN`` |
|
-+-------------------------------+--------------------------------------+-------------------------------------------+
-| ``ATTRIBUTE_RETURN_CHECK`` | ``G_GNUC_WARN_UNUSED_RESULT`` |
|
-+-------------------------------+--------------------------------------+-------------------------------------------+
-| ``ATTRIBUTE_SENTINEL`` | ``G_GNUC_NULL_TERMINATED`` |
|
-+-------------------------------+--------------------------------------+-------------------------------------------+
-| ``ATTRIBUTE_UNUSED`` | ``G_GNUC_UNUSED`` |
|
-+-------------------------------+--------------------------------------+-------------------------------------------+
-| ``VIR_STRDUP`` | ``g_strdup`` |
|
-+-------------------------------+--------------------------------------+-------------------------------------------+
-| ``VIR_STRNDUP`` | ``g_strndup`` |
|
-+-------------------------------+--------------------------------------+-------------------------------------------+
-| ``virStrerror`` | ``g_strerror`` |
|
-+-------------------------------+--------------------------------------+-------------------------------------------+
+.. list-table::
+ :header-rows: 1
+
+ * - deleted version
+ - GLib version
+ - Notes
+
+ * - ``VIR_AUTOPTR``
+ - ``g_autoptr``
+ -
+
+ * - ``VIR_AUTOCLEAN``
+ - ``g_auto``
+ -
+
+ * - ``VIR_AUTOFREE``
+ - ``g_autofree``
+ - The GLib version does not use parentheses
+
+ * - ``VIR_AUTOUNREF``
+ - ``g_autoptr``
+ - The cleanup function needs to be defined
+
+ * - ``VIR_DEFINE_AUTOPTR_FUNC``
+ - ``G_DEFINE_AUTOPTR_CLEANUP_FUNC``
+ -
+
+ * - ``VIR_DEFINE_AUTOCLEAN_FUNC``
+ - ``G_DEFINE_AUTO_CLEANUP_CLEAR_FUNC``
+ -
+
+ * - ``VIR_STEAL_PTR``
+ - ``g_steal_pointer``
+ - ``a = f(&b)`` instead of ``f(a, b)``
+
+ * - ``VIR_RETURN_PTR``
+ - ``return g_steal_pointer``
+ -
+
+ * - ``ARRAY_CARDINALITY``
+ - ``G_N_ELEMENTS``
+ -
+
+ * - ``ATTRIBUTE_FALLTHROUGH``
+ - ``G_GNUC_FALLTHROUGH``
+ -
+
+ * - ``ATTRIBUTE_FMT_PRINTF``
+ - ``G_GNUC_PRINTF``
+ -
+
+ * - ``ATTRIBUTE_NOINLINE``
+ - ``G_GNUC_NO_INLINE``
+ -
+
+ * - ``ATTRIBUTE_NORETURN``
+ - ``G_GNUC_NORETURN``
+ -
+
+ * - ``ATTRIBUTE_RETURN_CHECK``
+ - ``G_GNUC_WARN_UNUSED_RESULT``
+ -
+
+ * - ``ATTRIBUTE_SENTINEL``
+ - ``G_GNUC_NULL_TERMINATED``
+ -
+
+ * - ``ATTRIBUTE_UNUSED``
+ - ``G_GNUC_UNUSED``
+ -
+
+ * - ``VIR_STRDUP``
+ - ``g_strdup``
+ -
+
+ * - ``VIR_STRNDUP``
+ - ``g_strndup``
+ -
+
+ * - ``virStrerror``
+ - ``g_strerror``
+ -
I'm wondering how long we actually need to bother keeping this text,
given that it is talking about stuff we've already deleted.
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 :|
8:30 a.m.
New subject: [libvirt PATCH 1/2] docs: Convert existing tables to list-table
On Thu, May 07, 2020 at 14:04:44 +0100, Daniel Berrange wrote:
On Thu, May 07, 2020 at 02:46:38PM +0200, Andrea Bolognani wrote:
> Signed-off-by: Andrea Bolognani <abologna(a)redhat.com>
> ---
> docs/coding-style.rst | 53 +++++++++++-------
> docs/glib-adoption.rst | 123 +++++++++++++++++++++++++++--------------
> 2 files changed, 114 insertions(+), 62 deletions(-)
>
> diff --git a/docs/glib-adoption.rst b/docs/glib-adoption.rst
> index 62ddd7c61d..a5dca47f5e 100644
> --- a/docs/glib-adoption.rst
> +++ b/docs/glib-adoption.rst
> @@ -53,44 +53,85 @@ The following libvirt APIs have been deleted already:
> ``VIR_STRDUP``, ``VIR_STRNDUP``
> Prefer the GLib APIs ``g_strdup`` and ``g_strndup``.
[...]
I'm wondering how long we actually need to bother keeping this text,
given that it is talking about stuff we've already deleted.
IMO we can purge those which don't have the definition present, which
looks like it's all of them.
Also when grepping random entries I've found that we mention VIR_STRDUP
in a syntax check.
8:36 a.m.
New subject: [libvirt PATCH 1/2] docs: Convert existing tables to list-table
On Thu, 2020-05-07 at 14:04 +0100, Daniel P. Berrangé wrote:
I'm wondering how long we actually need to bother keeping this
text,
given that it is talking about stuff we've already deleted.
We've started using GLib six months ago. Do you think that's long
enough to drop this page completely? I wouldn't mind.
--
Andrea Bolognani / Red Hat / Virtualization
8:43 a.m.
New subject: [libvirt PATCH 1/2] docs: Convert existing tables to list-table
On Thu, May 07, 2020 at 03:36:55PM +0200, Andrea Bolognani wrote:
On Thu, 2020-05-07 at 14:04 +0100, Daniel P. Berrangé wrote:
> I'm wondering how long we actually need to bother keeping this text,
> given that it is talking about stuff we've already deleted.
We've started using GLib six months ago. Do you think that's long
enough to drop this page completely? I wouldn't mind.
Yeah, I think that'd be ok. For any other ideas of things we want to
convert, we can create issues and tag them "bitesizedtask"
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 :|
7:46 a.m.
New subject: [libvirt PATCH 2/2] docs: Document list-tables as recommended
Signed-off-by: Andrea Bolognani <abologna(a)redhat.com>
---
docs/styleguide.rst | 20 ++++++++++++++++++++
1 file changed, 20 insertions(+)
diff --git a/docs/styleguide.rst b/docs/styleguide.rst
index 3162868fb7..34c5b1573a 100644
--- a/docs/styleguide.rst
+++ b/docs/styleguide.rst
@@ -77,6 +77,26 @@ which allows for 6 levels of headings
Heading 6
^^^^^^^^^
+Tables
+======
+
+Tables should be created using the ``list-table`` directive whenever
+possible, as in
+
+::
+
+ .. list-table::
+ :header-rows: 1
+
+ * - Option
+ - Description
+
+ * - ``foo_enabled``
+ - Whether or not ``foo`` should be enabled
+
+ * - ``bar_user``
+ - Which user to run ``bar`` as
+
Manual pages
============
--
2.25.4
1660
days inactive
1660
days old
9 comments
3 participants
participants (3)
-
Andrea Bolognani -
Daniel P. Berrangé -
Peter Krempa