[PATCH v2 1/2] docs: refactor mdev_types into new paragraph

[Boris Fiuczynski]

On 11/11/20 10:34 AM, Erik Skultety wrote:
> On Tue, Nov 10, 2020 at 07:09:05PM +0100, Boris Fiuczynski wrote:
>> To prevent copying the mdev_types description multiple times
>> it is refactored into a new paragraph for easy reuse.
>>
>> Signed-off-by: Boris Fiuczynski <fiuczy at linux.ibm.com>
>> ---
>>   docs/formatnode.html.in | 70 ++++++++++++++++++++++++-----------------
>>   1 file changed, 41 insertions(+), 29 deletions(-)
>>
>> diff --git a/docs/formatnode.html.in b/docs/formatnode.html.in
>> index 6928bdd69c..bd3112c5a8 100644
>> --- a/docs/formatnode.html.in
>> +++ b/docs/formatnode.html.in
>> @@ -159,35 +159,10 @@
>>                     </dd>
>>                     <dt><code><a id="MDEVCap">mdev_types</a></code></dt>
>>                     <dd>
>> -                    This device is capable of creating mediated devices, and
>> -                    the capability will contain a list of <code>type</code>
>> -                    elements, which list all mdev types supported on the
>> -                    physical device. <span class="since">Since 3.4.0</span>
>> -                    Each <code>type</code> element has a single <code>id</code>
>> -                    attribute that holds an official vendor-supplied identifier
>> -                    for the type. It supports the following sub-elements:
>> -                      <dl>
>> -                        <dt><code>name</code></dt>
>> -                        <dd>
>> -                          The <code>name</code> element holds a vendor-supplied
>> -                          code name for the given mediated device type. This is
>> -                          an optional element.
>> -                      </dd>
>> -                      <dt><code>deviceAPI</code></dt>
>> -                      <dd>
>> -                        The value of this element describes how an instance of
>> -                        the given type will be presented to the guest by the
>> -                        VFIO framework.
>> -                      </dd>
>> -                      <dt><code>availableInstances</code></dt>
>> -                      <dd>
>> -                        This element reports the current state of resource
>> -                        allocation. In other words, how many instances of the
>> -                        given type can still be successfully created on the
>> -                        physical device.
>> -                    </dd>
>> -                  </dl>
>> -                </dd>
>> +                    This device is capable of creating mediated devices.
>> +                    The sub-elements are summarized in
>> +                    <a href="#MDevTypesCap">mdev_types capability</a>.
>> +                 </dd>
>>                   </dl>
>>                 </dd>
>>   
>> @@ -445,6 +420,43 @@
>>         </dd>
>>       </dl>
>>   
>> +    <h3><a id="MDevTypesCap">mdev_types capability</a></h3>
>> +
>> +    <p>
>> +      <a href="#MDEVCap">PCI</a> devices can be capable of
>> +      creating mediated devices.
>> +      If they are capable the attribute <code>type</code> of the
>> +      element <code>capability</code> is <code>mdev_types</code>.
> 
> I'd slightly adjust the wording because the first I read it I got confused,
> not just the rewrite, also by the original (probably mine) text.
> How about:
> 
> "If the indeed are capable, then the parent <code>capability</code> element

If they indeed...

> for <code>mdev_types</code> type will contain a list of ...."
> 
> Reviewed-by: Erik Skultety <eskultet at redhat.com>

Yes, I agree that it is an easier read.

> 
>> +      This capability will contain a list of <code>type</code>
>> +      elements, which list all mdev types supported on the
>> +      physical device. <span class="since">Since 3.4.0</span>
>> +      Each <code>type</code> element has a single <code>id</code>
>> +      attribute that holds an official vendor-supplied identifier
>> +      for the type. It supports the following sub-elements:
>> +      <dl>
>> +        <dt><code>name</code></dt>
>> +        <dd>
>> +          The <code>name</code> element holds a vendor-supplied
>> +          code name for the given mediated device type. This is
>> +          an optional element.
>> +        </dd>
>> +        <dt><code>deviceAPI</code></dt>
>> +        <dd>
>> +          The value of this element describes how an instance of
>> +          the given type will be presented to the guest by the
>> +          VFIO framework.
>> +        </dd>
>> +        <dt><code>availableInstances</code></dt>
>> +        <dd>
>> +          This element reports the current state of resource
>> +          allocation. In other words, how many instances of the
>> +          given type can still be successfully created on the
>> +          physical device.
>> +        </dd>
>> +      </dl>
>> +    </p>
>> +
>> +
>>       <h2><a id="nodeExample">Examples</a></h2>
>>   
>>       <p>The following are some example node device XML outputs:</p>
>> -- 
>> 2.26.2
>>
> 


-- 
Mit freundlichen Grüßen/Kind regards
    Boris Fiuczynski

IBM Deutschland Research & Development GmbH
Vorsitzender des Aufsichtsrats: Gregor Pillen
Geschäftsführung: Dirk Wittkopp
Sitz der Gesellschaft: Böblingen
Registergericht: Amtsgericht Stuttgart, HRB 243294