[libvirt] [PATCH v2] docs: formatdomain: Document the CPU feature 'name' attribute

[John Ferlan]

On 01/24/2018 10:25 AM, Kashyap Chamarthy wrote:
> Currently, the CPU feature 'name' XML attribute, as in:
> 
>     [...]
>     <cpu match='exact'>
>       <model fallback='forbid'>IvyBridge</model>
>       <vendor>Intel</vendor>
>       <feature policy='require' name='pcid'/>
>     </cpu>
>     [...]
> 
> isn't explicitly documented in formatdomain.html.
> 
> Document it now.
> 
> Signed-off-by: Kashyap Chamarthy <kchamart at redhat.com>
> ---
> v2:
>  - Remove redundant line [Eduardo Habkost]
> 
>  docs/formatdomain.html.in | 14 ++++++++++++++
>  1 file changed, 14 insertions(+)
> 

When built, formatted, rendered, and read in a browser one gets in one
long line:

Since 0.8.5 the policy attribute can be omitted and will default to
require. Individual CPU feature names should be specified as part of the
name attribute. For example, to explicitly specify the 'pcid' feature
with Intel IvyBridge CPU model:
...

So I think wrapping your change with <p> ... </p> will at least make it
look like a separate paragraph within the <feature> element description.

> diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in
> index d272cc1ba..a6d40411c 100644
> --- a/docs/formatdomain.html.in
> +++ b/docs/formatdomain.html.in
> @@ -1454,6 +1454,20 @@
>  
>          <span class="since">Since 0.8.5</span> the <code>policy</code>
>          attribute can be omitted and will default to <code>require</code>.
> +
> +        Individual CPU feature names can be specified as part of the

Since the name attribute is required, rather than "can be" or "should
be" (as Eduardo suggested), I think perhaps "features names are
specified using the required <code>name</name> attribute."

or

"The required <code>name</code> attribute is used specify each desired
CPU feature."

(because we state initially "The cpu element can contain zero or more
elements...").

> +        <code>name</code> attribute. For example, to explicitly specify

s/specify/require


Thoughts?  I can make the adjustment before pushing if desired.

John



> +        the 'pcid' feature with Intel IvyBridge CPU model:
> +
> +<pre>
> +...
> +<cpu match='exact'>
> +  <model fallback='forbid'>IvyBridge</model>
> +  <vendor>Intel</vendor>
> +  <feature policy='require' name='pcid'/>
> +</cpu>
> +...</pre>
> +
>        </dd>
>  
>        <dt><code>cache</code></dt>
>