[libvirt] [PATCH 01/11] docs: Tweak PCI controller model documentation

[Andrea Bolognani]

On Tue, 2018-04-03 at 19:11 -0400, John Ferlan wrote:
> On 03/28/2018 10:06 AM, Andrea Bolognani wrote:
> > Instead of first listing the models on their own, and then
> > listing them again grouped by the libvirt release they were
> > introduced in, have a single list.
> > 
> > Signed-off-by: Andrea Bolognani <abologna at redhat.com>
> > ---
> >  docs/formatdomain.html.in | 20 ++++++++------------
> >  1 file changed, 8 insertions(+), 12 deletions(-)
> 
> Personally I don't find it any easier to read ;-) - it's all a mash of
> letters and dashes... Of course true of other parts on formatdomain too.

The goal was avoiding repeated information, not necessarily making
the whole thing easier to read. But I agree that's a laudable goal
as well :)

>  Still, how about something like this:
> 
>       <table class="top_table">
>         <tr>
>           <th> Value </th>
>           <th> Since </th>
>         </tr>
>         <tr>
>           <td> pci-root </td>
>           <td> <span class="since">since 1.0.5</span> </td>
[...]
>         </tr>
> 
> You could choose different labels if you desired...

Using a table for this seems like a waste of vertical space to me,
and there are no existing examples of anything like that in the
documentation AFAICT. Maybe a <ul> instead?

> Also consider the
> possibilities for expansion w/r/t providing even a *little* bit more
> "Description" details about what each of these things are and
> when/how/why they'd be used (far beyond the scope of this patch though).
> I would think some of that could be drawn from the descriptions that
> exist "just above" the "Device leases" section.  IOW: a relationship
> matrix...

Is the information already present below in free-text format not
enough? I don't think we can compress that information in a format
that would be suitable for a table.

In any case, I agree it would be entirely out of scope here.

-- 
Andrea Bolognani / Red Hat / Virtualization