Re: [libvirt] [PATCH 01/11] docs: Tweak PCI controller model documentation
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(a)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