Re: [PATCH RFC 2/2] docs: rstfy vfio-ap documentation

[Cornelia Huck <cohuck@redhat.com>]

On Fri, 7 Feb 2020 16:32:18 +0100
Cornelia Huck <cohuck@redhat.com> wrote:

> On Fri, 7 Feb 2020 12:43:03 +0000
> Peter Maydell <peter.maydell@linaro.org> wrote:
> 
> > On Tue, 28 Jan 2020 at 19:39, Cornelia Huck <cohuck@redhat.com> wrote:  
> > >
> > > Move to system/, as this is mostly about configuring vfio-ap.
> > >
> > > Signed-off-by: Cornelia Huck <cohuck@redhat.com>    

> > > -   Example 1: Valid configuration:
> > > -   ------------------------------
> > > -   Guest1: adapters 1,2  domains 5,6
> > > -   Guest2: adapter  1,2  domain 7
> > > +Example 1: Valid configuration
> > > +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> > > +Guest1: adapters 1,2  domains 5,6
> > > +Guest2: adapter  1,2  domain 7    
> > 
> > These don't render correctly -- rST thinks the "Example 1..." line
> > is a subsection heading because of the underlining, and then renders
> > the next two lines as runon-text:
> > "Guest1: adapters 1,2 domains 5,6 Guest2: adapter 1,2 domain 7"
> > 
> > Depending on what you want, you could try one of:
> >  * use a literal block (which gets you fixed-width font, preserved
> >    whitespace and linebreaks)
> >  * use a bulleted list
> >  * use one of rST's table formats  
> 
> Hm... I think this is supposed to be:
> - header ("Example 1: ...")
> - config
> - explanation why this is a valid config
> 
> Maybe a table? Tony, any preferences?
> 
> > 
> > (is it deliberate that line 1 is "adapters" and line 2 is "adapter" ?)  
> 
> I don't think so.
> 
> >   
> > > -   This is valid because both guests have a unique set of APQNs: Guest1 has
> > > -   APQNs (1,5), (1,6), (2,5) and (2,6); Guest2 has APQNs (1,7) and (2,7).
> > > +This is valid because both guests have a unique set of APQNs: Guest1 has
> > > +APQNs (1,5), (1,6), (2,5) and (2,6); Guest2 has APQNs (1,7) and (2,7).

This section now looks like this:

Example 1: Valid configuration                                                  
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~                                                  
                                                                                
+----------+--------+--------+                                                  
|          | Guest1 | Guest2 |                                                  
+==========+========+========+                                                  
| adapters |  1, 2  |  1, 2  |                                                  
+----------+--------+--------+                                                  
| domains  |  5, 6  |  7     |                                                  
+----------+--------+--------+                                                  
                                                                                
This is valid because both guests have a unique set of APQNs:                   
                                                                                
* Guest1 has APQNs (1,5), (1,6), (2,5) and (2,6);                               
* Guest2 has APQNs (1,7) and (2,7).

Seems more readable to me, also in the rendered html. (Not sure if
switching rows/columns would be better.)