Re: [PATCH] xl: Special case tap/aio for disk validation

[Kamala Narasimhan <kamala.narasimhan@gmail.com>]

> Several elements of the 'format:path,vdev:type,attrib' string are
> optional. Can we delineate those in some non-confusing way? Often man
> pages and the like use [], which would end up as (I think):
> 	[format:]path,vdev[:type],attrib
>
Believe it or not I tried that!  It ended up looking very confusing which is why
I switched to explicit verbal description of whether or not a particular
attribute is mandatory.

> I don't know if that meets the non-confusing criterion though. I didn't
> initially notice the "Mandatory" tag (see comments on line-wrapping
> below). The thing the tag doesn't cover is how the punctuation binds to
> the mandatory vs. optional elements. Perhaps insert
>         The "format:" and ":type" elements are optional
> alongside the comment about not all attributes being required?
> 
Sure, if that helps.

> IanJ wrote a existing spec for vdev at one point. I thought it had been
> committed somewhere but I can't see it. I think the most recent version
> was
> http://lists.xensource.com/archives/html/xen-devel/2010-09/msg01329.html
> but perhaps IanJ can confirm. We should incorporate it, either by
> reference or as a separate chapter in the same document or something
> similar.
> 
Sure.

> The discussion of which backend corresponds to each option is useful
> from an implementation detail point of view but I'm not sure it is
> necessary as part of the documentation of the configuration syntax. It's
> liable get out of date IMHO. Perhaps those bits would be better as a
> comment alongside the implementation?
> 
I do agree this is an information a pure end user won't care about.  The
question then gets to who is the target audience for this document.  If it is
mostly developers, it might help for them to have this information.

> It's not clear where the deprecated block-dev-type and access-type
> attributes are acceptable. I think we can just say that multiple
> deprecated attributes are accepted before the first valid "format" type
> is discovered, with the last one taking precedence, or something along
> those lines.
>
Sure.

> Lastly, I think the doc should be line-wrapped to 80 columns, otherwise
> the autowrapping of the table like elements ends up quite hard to
> follow. e.g. it currently comes out looking like:
>         
>         Description:         Specifies the format of image file.
>         Supported values:    raw, qcow, qcow2, vhd 
>         Deprecated values:   None
>         Mandatory:           No. When not specified raw format is
>         assumed.  For a physical block device the format must be raw and
>         need not be explicitly specified.  For an image file the format
>         could be one of the supported values and when not specified
>         assumed to be raw.
>         Backend used:        For qcow/qcow2 qemu backend is u[...]
>
> should be (subject to my guessing where 80 columns actually is in this
> case):
> 
>         Description:         Specifies the format of image file.
>         Supported values:    raw, qcow, qcow2, vhd 
>         Deprecated values:   None
>         Mandatory:           No. When not specified raw format is assumed.  For a physical block device the format
>                              must be raw and need not be explicitly specified.  For an image file the format could
>                              be one of the supported values and when not specified assumed to be raw.
>         Backend used:        For qcow/qcow2 qemu backend is u[...]
>                              [...] etc 
> 
Yep, I will do that and send out a revised version.

Kamala