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

[John Ferlan]

On 04/04/2018 04:39 AM, Andrea Bolognani wrote:
> 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 :)
> 

Understood - to the degree of keeping since w/ the possible values is
better than the previous format. I guess I still found it difficult to
read so looked for something else more readable.

>>  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?
> 

Table or list is fine - I guess I just landed on a part of the page with
a table and thought this would be so much nicer than a paragraph of data
where there's multiple since labels. FWIW: The hyperv description of the
power management section uses a table w/ a since column.

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

The information free form is sufficient of course it's easy to miss too,
but at this point baby steps and out of context.

In any case, if you want to not make any extra changes, then I guess
that's fine since your patch is better than the original; however,
taking the extra step for list or table I think would be better.

The R-b can stick with for whatever option you choose.

John