[libvirt] [PATCH v3 1/4] docs: formatstorage: Update <permissions> docs

[Cole Robinson]

On 05/24/2015 07:20 AM, John Ferlan wrote:
> 
> 
> On 05/21/2015 04:03 PM, Cole Robinson wrote:
>> - Don't redocument the permissions fields for backingstore, just point to
>>   the volume docs.
>> - Clarify that owner/group are inherited from the parent directory at
>>   volume create/pool build time.
>> - Clarify that <permissions> fields report runtime values too
>> ---
>> v3:
>>     New patch
>>
>>  docs/formatstorage.html.in | 36 ++++++++++++++++++++++--------------
>>  1 file changed, 22 insertions(+), 14 deletions(-)
>>
>> diff --git a/docs/formatstorage.html.in b/docs/formatstorage.html.in
>> index 474abd6..f07bb5d 100644
>> --- a/docs/formatstorage.html.in
>> +++ b/docs/formatstorage.html.in
>> @@ -405,11 +405,17 @@
>>          pools, which are mapped as a directory into the local filesystem
>>          namespace. It provides information about the permissions to use for the
>>          final directory when the pool is built. The
>> -        <code>mode</code> element contains the octal permission set. The
>> -        <code>owner</code> element contains the numeric user ID. The <code>group</code>
>> -        element contains the numeric group ID. The <code>label</code> element
>> -        contains the MAC (eg SELinux) label string.
> 
> s/.$/. There are 4 child elements.

Fixed.

> 
>> +        <code>mode</code> element contains the octal permission set.
>> +        The <code>owner</code> element contains the numeric user ID.
>> +        The <code>group</code> element contains the numeric group ID.
>> +        If <code>owner</code> or <code>group</code> aren't specified when
>> +        creating a directory, the values are inherited from the parent
>> +        directory. The <code>label</code> element contains the MAC (eg SELinux)
>> +        label string.
>>          <span class="since">Since 0.4.1</span>
>> +        For running directory or filesystem based pools, these fields
>> +        will be filled with the values used by the existing directory.
>> +        <span class="since">Since 1.2.16</span>
>>        </dd>
>>        <dt><code>timestamps</code></dt>
>>        <dd>Provides timing information about the volume. Up to four
>> @@ -583,15 +589,20 @@
>>          volume format type value and the default pool format will be used.
>>          <span class="since">Since 0.4.1</span></dd>
>>        <dt><code>permissions</code></dt>
>> -      <dd>Provides information about the default permissions to use
>> +      <dd>Provides information about the permissions to use
>>          when creating volumes. This is currently only useful for directory
>>          or filesystem based pools, where the volumes allocated are simple
>>          files. For pools where the volumes are device nodes, the hotplug
>>          scripts determine permissions. It contains 4 child elements. The
> 
> s/It contains /There are/

Fixed.

> 
>> -        <code>mode</code> element contains the octal permission set. The
>> -        <code>owner</code> element contains the numeric user ID. The <code>group</code>
>> -        element contains the numeric group ID. The <code>label</code> element
>> -        contains the MAC (eg SELinux) label string.
>> +        <code>mode</code> element contains the octal permission set.
>> +        The <code>owner</code> element contains the numeric user ID.
>> +        The <code>group</code> element contains the numeric group ID.
>> +        If <code>owner</code> or <code>group</code> aren't specified when
>> +        creating a supported volume, the values are inherited from the parent
>> +        directory. The <code>label</code> element contains the MAC (eg SELinux)
>> +        label string.
>> +        For existing directory or filesystem based volumes, these fields
>> +        will be filled with the values used by the existing file.
> ^^^
> the <span> used above for 1.2.16
> ^^^
> the <span> used above for 1.2.16
> 

This was intentional, the pool permission syncing pre-dates 1.2.16, my patches
only added it for volumes. I tried a git log grep to try and figure out when
it was added but gave up after a couple minutes. So I left this as is and pushed.

Thanks,
Cole

>>          <span class="since">Since 0.4.1</span>
>>        </dd>
>>        <dt><code>compat</code></dt>
>> @@ -659,11 +670,8 @@
>>          <span class="since">Since 0.6.0</span></dd>
>>        <dt><code>permissions</code></dt>
>>        <dd>Provides information about the permissions of the backing file.
>> -        It contains 4 child elements. The
>> -        <code>mode</code> element contains the octal permission set. The
>> -        <code>owner</code> element contains the numeric user ID. The <code>group</code>
>> -        element contains the numeric group ID. The <code>label</code> element
>> -        contains the MAC (eg SELinux) label string.
>> +          See volume <code>permissions</code> documentation for explanation
>> +          of individual fields.
>>          <span class="since">Since 0.6.0</span>
>>        </dd>
>>      </dl>
>>