[libvirt] [PATCH 6/9] docs: add persistent config to snapshot xml description

[Nikolay Shirokovskiy]

On 20.12.2018 23:32, John Ferlan wrote:
> 
> 
> On 12/13/18 3:03 AM, Nikolay Shirokovskiy wrote:
>> Signed-off-by: Nikolay Shirokovskiy <nshirokovskiy at virtuozzo.com>
>> ---
>>  docs/formatsnapshot.html.in | 7 +++++++
>>  1 file changed, 7 insertions(+)
>>
> 
> This probably should be merged with patch5 - nice to separate for review
> though. Although, like patch4 it's not that important to me.
> 
>> diff --git a/docs/formatsnapshot.html.in b/docs/formatsnapshot.html.in
>> index fbbecfd..1357f53 100644
>> --- a/docs/formatsnapshot.html.in
>> +++ b/docs/formatsnapshot.html.in
>> @@ -235,6 +235,13 @@
>>          at the time of the snapshot (<span class="since">since
>>          0.9.5</span>).  Readonly.
>>        </dd>
>> +      <dt><code>persistent/domain</code></dt>
>> +      <dd>Inactive domain configuration for active persistent domain.
> 
> s/for/from an/
> 
>> +        Such a domain have 2 distinct configs and here inactive is
> 
> Tough read grammar wise.
> 
>> +        stored. It is different from <code>domain</code> which more
>> +        presisely keeps "inactive portion" of active config.
> 
> precisely
> 
>> +        (<span class="since">since 5.0.0</span>).
>> +      </dd>
> 
> 
> Hmmm... IIRC... isn't newDef the "next config"? Scour around for
> Domain*Persistent and see what I mean. I think you have this description
> backwards - hey I could be wrong, too...
> 
> An active domain for which configuration specific changes have been made
> will store both the "active" and "next config" in the domain object and
> the <persistent> element will signify that config; whereas, the <domain>
> element signifies the active domain configuration.

Naming is known to be hard. For active domain you can think of this
configs as active/persistent or active/next one(new one). I think
@newDef name is choosen because @persistentDef would be misleading -
inactive domains store its persistent domain in @def and not @newDef
(however I would prefer the opposite - inactive domains storing its
definition in @persistentDef and having @def = NULL).

If done from scratch I would suggest to use:

- <domain> for inactive/transient domains
- <persistent><domain> and <transient><domain> for active persistent domains

or even only last option for all cases. But now for backward compat we
need some name. Well I thought explaining next/new def is more complicated
then stating that persistent is only defined for active persistent domains
and that is keeps the persistent config.

Nikolay

> 
> There is nothing different in the previous patch between the "<domain
> ... </domain>" and the "<persistent> ... </persistent>"; however, I
> would believe that if something changed as "config only" then it
> would/should show up in that persistDom.
> 
> John
> 
>>        <dt><code>cookie</code></dt>
>>        <dd>Save image cookie containing additional data libvirt may need to
>>          properly restore a domain from an active snapshot when such data
>>