Re: [PATCH 10/14] docs: update xl-disk-configuration.txt to describe new syntax

[Ian Jackson <Ian.Jackson@eu.citrix.com>]

Ian Campbell writes ("Re: [Xen-devel] [PATCH 10/14] docs: update xl-disk-configuration.txt to describe new syntax"):
> Since this is a bit of a total rewrite I've attached the patched up
> version of the file too for other people's convenience since the diff
> itself is almost unusable, hence I have snipped most of the - lines in
> the diff before commenting on the + bits.

Right.

> > +where each diskspec is in this form:
> > +
> > +   [<key>=<value>|flag]*,
> > +     [<target>, [<format>, [<vdev>, [<access>]]]],
> > +     [<key>=<value>]*,
> > +     [target=<target>]
> 
> The actual meaning of this is pretty opaque. The paragraphs following
> "More formally" does a pretty good job of describing it but I still have
> a few questions/misunderstandings.

Do you think I should get rid of this template ?

> It's not obvious that the "[<target>, [<format>, [<vdev>,
> [<access>]]]]," bit specifies the "positional parameters" (I'm assuming
> they do) nor is it mentioned in the text whether or not the positional
> parameters must be contiguous if used.
> 
> Are you using "*" to mean "0 or 1 of the preceding element" as opposed
> to "0 or more of the preceding element", I initially read it as the
> second which confused me because it suggests that a valid syntax could
> be
>         [<key>=<value>|flag][<key>=<value>|flag][<key>=<value>|flag],
> whereas I expected it would need to be
>         [<key>=<value>|flag],[<key>=<value>|flag],[<key>=<value>|flag],
> is the placement of either the "," or the "*" wrong and/or did you mean
> "?" rather than "*"?

No, it's just that the placement of the "," is wrong.

> > +Description:           Block device or image file path.  For a
> > +                       physical block device a /dev will be prepended
> >                         when not specified and when the path doesn't
> > +                       start with a '/'.
> 
> Won't we prepend a /dev/ for any path, regardless of whether it is a
> physical block device or an image file? Granted it's not likely to be
> all that useful in the second case but we can't really distinguish the
> two until too late.

Yes, this is a good point.

> > +Deprecated values are acceptable and are intended work compatibly with
> > +xend and xl from xen 4.1.  In future they may print a warning.
> > +Support for deprecated parameters and syntaxes are likely to be
> > +dropped in future versions of xl.
> > 
> > +There is also support for a deprecated old syntax for <diskspec>:
> > 
> > +  [<format>:][<target>],<vdev>[:<devtype>],<access>   (deprecated)
> > 
> > +This syntax also supports deprecated prefixes, described below.  These
> > +are found prepended to the format parameter - eg "tap:aio:qcow:".
> 
> Are valid <format>s a fixed list of existing formats which will not be
> extended as list of supported formats grows in the future, IOW new
> formats will only be available via the format positional paramter?

That is correct.

> > +<block-dev-type>:
> > +-----------------
> 
> That tag doesn't appear anywhere in the syntax description, so it's not
> clear where it is allowable. I'd assume it was <devtype> above if I
> didn't know any better...
> 
> > +Description:           Specifies the block device type.
> > +Supported values:      phy,file, tap, tap2
>                               ^ whitespace

I think this is a leftover which should be deleted.

> > +<access-type>:
> > +--------------
> 
> Spelled <access> above?

No.  It should be backend-type.

I will send out a fixed version.

Ian.