[PATCH] docs: document handling of metacharacter escape in xl disk format

[PATCH] docs: document handling of metacharacter escape in xl disk format

[Ian Campbell]

Signed-off-by: Ian Campbell <ian.campbell@citrix.com>
Cc: Jim Fehlig <jfehlig@suse.com>
---
 docs/misc/xl-disk-configuration.txt | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/docs/misc/xl-disk-configuration.txt b/docs/misc/xl-disk-configuration.txt
index 6a2118d..a03ad10 100644
--- a/docs/misc/xl-disk-configuration.txt
+++ b/docs/misc/xl-disk-configuration.txt
@@ -48,6 +48,24 @@ positionally or explicitly).
 
 Whitespace may appear before each parameter and will be ignored.
 
+Metacharacters in a <diskspec> may be escaped using a backslash:
+
+    Escape      HEX     Description
+    ------      ---     -----------
+    \a          0x07    Bell
+    \b          0x08    Backspace
+    \t          0x09    Horizontal Tab
+    \n          0x0A    New Line / Line Feed
+    \f          0x0C    Form Feed
+    \r          0x0D    Carriage Return
+    \v          0x0B    Vertical Tab
+    \"          0x22    A literal double quote
+    \'          0x27    A literal single quote
+    \\          0x5C    A literal backslash
+    \xXX                Character XX in hexadecimal
+    \OOO                Character OOO in octal
+
+Any other character following a backslash is an error.
 
 =====================
 POSITIONAL PARAMETERS
-- 
2.1.4

Re: [PATCH] docs: document handling of metacharacter escape in xl disk format

[Jim Fehlig]

Ian Campbell wrote:
> Signed-off-by: Ian Campbell <ian.campbell@citrix.com>
> Cc: Jim Fehlig <jfehlig@suse.com>
> ---
>  docs/misc/xl-disk-configuration.txt | 18 ++++++++++++++++++
>  1 file changed, 18 insertions(+)
> 
> diff --git a/docs/misc/xl-disk-configuration.txt b/docs/misc/xl-disk-configuration.txt
> index 6a2118d..a03ad10 100644
> --- a/docs/misc/xl-disk-configuration.txt
> +++ b/docs/misc/xl-disk-configuration.txt
> @@ -48,6 +48,24 @@ positionally or explicitly).
>  
>  Whitespace may appear before each parameter and will be ignored.
>  
> +Metacharacters in a <diskspec> may be escaped using a backslash:
> +
> +    Escape      HEX     Description
> +    ------      ---     -----------
> +    \a          0x07    Bell
> +    \b          0x08    Backspace
> +    \t          0x09    Horizontal Tab
> +    \n          0x0A    New Line / Line Feed
> +    \f          0x0C    Form Feed
> +    \r          0x0D    Carriage Return
> +    \v          0x0B    Vertical Tab
> +    \"          0x22    A literal double quote
> +    \'          0x27    A literal single quote
> +    \\          0x5C    A literal backslash
> +    \xXX                Character XX in hexadecimal
> +    \OOO                Character OOO in octal

Do you know how any of these would be useful in a diskspec? I guess I'm
struggling to understand when a 'Bell' would be needed :-).

Regards,
Jim

Re: [PATCH] docs: document handling of metacharacter escape in xl disk format

[Ian Campbell]

On Thu, 2016-02-18 at 15:44 -0700, Jim Fehlig wrote:
> Ian Campbell wrote:
> > Signed-off-by: Ian Campbell <ian.campbell@citrix.com>
> > Cc: Jim Fehlig <jfehlig@suse.com>
> > ---
> >  docs/misc/xl-disk-configuration.txt | 18 ++++++++++++++++++
> >  1 file changed, 18 insertions(+)
> > 
> > diff --git a/docs/misc/xl-disk-configuration.txt b/docs/misc/xl-disk-
> > configuration.txt
> > index 6a2118d..a03ad10 100644
> > --- a/docs/misc/xl-disk-configuration.txt
> > +++ b/docs/misc/xl-disk-configuration.txt
> > @@ -48,6 +48,24 @@ positionally or explicitly).
> >  
> >  Whitespace may appear before each parameter and will be ignored.
> >  
> > +Metacharacters in a <diskspec> may be escaped using a backslash:
> > +
> > +    Escape      HEX     Description
> > +    ------      ---     -----------
> > +    \a          0x07    Bell
> > +    \b          0x08    Backspace
> > +    \t          0x09    Horizontal Tab
> > +    \n          0x0A    New Line / Line Feed
> > +    \f          0x0C    Form Feed
> > +    \r          0x0D    Carriage Return
> > +    \v          0x0B    Vertical Tab
> > +    \"          0x22    A literal double quote
> > +    \'          0x27    A literal single quote
> > +    \\          0x5C    A literal backslash
> > +    \xXX                Character XX in hexadecimal
> > +    \OOO                Character OOO in octal
> 
> Do you know how any of these would be useful in a diskspec? I guess I'm
> struggling to understand when a 'Bell' would be needed :-).

I've not got a clue -- these are just all the ones handled by
xlu__cfgl_dequote, perhaps just for completeness?

This is applied to all strings in a cfg file, not just diskspecs, but I
can't think of anything there where Bell would be useful either.

Ian.
_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xen.org
http://lists.xen.org/xen-devel

Re: [PATCH] docs: document handling of metacharacter escape in xl disk format

[Ian Campbell]

On Fri, 2016-02-19 at 10:14 +0000, Ian Campbell wrote:
> On Thu, 2016-02-18 at 15:44 -0700, Jim Fehlig wrote:
> > Ian Campbell wrote:
> > > Signed-off-by: Ian Campbell <ian.campbell@citrix.com>
> > > Cc: Jim Fehlig <jfehlig@suse.com>
> > > ---
> > >  docs/misc/xl-disk-configuration.txt | 18 ++++++++++++++++++
> > >  1 file changed, 18 insertions(+)
> > > 
> > > diff --git a/docs/misc/xl-disk-configuration.txt b/docs/misc/xl-disk-
> > > configuration.txt
> > > index 6a2118d..a03ad10 100644
> > > --- a/docs/misc/xl-disk-configuration.txt
> > > +++ b/docs/misc/xl-disk-configuration.txt
> > > @@ -48,6 +48,24 @@ positionally or explicitly).
> > >  
> > >  Whitespace may appear before each parameter and will be ignored.
> > >  
> > > +Metacharacters in a <diskspec> may be escaped using a backslash:
> > > +
> > > +    Escape      HEX     Description
> > > +    ------      ---     -----------
> > > +    \a          0x07    Bell
> > > +    \b          0x08    Backspace
> > > +    \t          0x09    Horizontal Tab
> > > +    \n          0x0A    New Line / Line Feed
> > > +    \f          0x0C    Form Feed
> > > +    \r          0x0D    Carriage Return
> > > +    \v          0x0B    Vertical Tab
> > > +    \"          0x22    A literal double quote
> > > +    \'          0x27    A literal single quote
> > > +    \\          0x5C    A literal backslash
> > > +    \xXX                Character XX in hexadecimal
> > > +    \OOO                Character OOO in octal
> > 
> > Do you know how any of these would be useful in a diskspec? I guess I'm
> > struggling to understand when a 'Bell' would be needed :-).
> 
> I've not got a clue -- these are just all the ones handled by
> xlu__cfgl_dequote, perhaps just for completeness?
> 
> This is applied to all strings in a cfg file, not just diskspecs,

Having observed this it should have then occurred to me that perhaps this
needs to be documented in xl.cfg(5) instead of in a disk specific location.

Should I move the above to docs/man/xl.cfg.pod.5 and apply pod markup to
it?
_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xen.org
http://lists.xen.org/xen-devel

Re: [PATCH] docs: document handling of metacharacter escape in xl disk format

[Wei Liu]

On Fri, Feb 19, 2016 at 10:23:26AM +0000, Ian Campbell wrote:
> On Fri, 2016-02-19 at 10:14 +0000, Ian Campbell wrote:
> > On Thu, 2016-02-18 at 15:44 -0700, Jim Fehlig wrote:
> > > Ian Campbell wrote:
> > > > Signed-off-by: Ian Campbell <ian.campbell@citrix.com>
> > > > Cc: Jim Fehlig <jfehlig@suse.com>
> > > > ---
> > > >  docs/misc/xl-disk-configuration.txt | 18 ++++++++++++++++++
> > > >  1 file changed, 18 insertions(+)
> > > > 
> > > > diff --git a/docs/misc/xl-disk-configuration.txt b/docs/misc/xl-disk-
> > > > configuration.txt
> > > > index 6a2118d..a03ad10 100644
> > > > --- a/docs/misc/xl-disk-configuration.txt
> > > > +++ b/docs/misc/xl-disk-configuration.txt
> > > > @@ -48,6 +48,24 @@ positionally or explicitly).
> > > >  
> > > >  Whitespace may appear before each parameter and will be ignored.
> > > >  
> > > > +Metacharacters in a <diskspec> may be escaped using a backslash:
> > > > +
> > > > +    Escape      HEX     Description
> > > > +    ------      ---     -----------
> > > > +    \a          0x07    Bell
> > > > +    \b          0x08    Backspace
> > > > +    \t          0x09    Horizontal Tab
> > > > +    \n          0x0A    New Line / Line Feed
> > > > +    \f          0x0C    Form Feed
> > > > +    \r          0x0D    Carriage Return
> > > > +    \v          0x0B    Vertical Tab
> > > > +    \"          0x22    A literal double quote
> > > > +    \'          0x27    A literal single quote
> > > > +    \\          0x5C    A literal backslash
> > > > +    \xXX                Character XX in hexadecimal
> > > > +    \OOO                Character OOO in octal
> > > 
> > > Do you know how any of these would be useful in a diskspec? I guess I'm
> > > struggling to understand when a 'Bell' would be needed :-).
> > 
> > I've not got a clue -- these are just all the ones handled by
> > xlu__cfgl_dequote, perhaps just for completeness?
> > 
> > This is applied to all strings in a cfg file, not just diskspecs,
> 
> Having observed this it should have then occurred to me that perhaps this
> needs to be documented in xl.cfg(5) instead of in a disk specific location.
> 
> Should I move the above to docs/man/xl.cfg.pod.5 and apply pod markup to
> it?

Agreed.

Re: [PATCH] docs: document handling of metacharacter escape in xl disk format

[Jim Fehlig]

On 02/19/2016 03:14 AM, Ian Campbell wrote:
> On Thu, 2016-02-18 at 15:44 -0700, Jim Fehlig wrote:
>> Ian Campbell wrote:
>>> Signed-off-by: Ian Campbell <ian.campbell@citrix.com>
>>> Cc: Jim Fehlig <jfehlig@suse.com>
>>> ---
>>>  docs/misc/xl-disk-configuration.txt | 18 ++++++++++++++++++
>>>  1 file changed, 18 insertions(+)
>>>
>>> diff --git a/docs/misc/xl-disk-configuration.txt b/docs/misc/xl-disk-
>>> configuration.txt
>>> index 6a2118d..a03ad10 100644
>>> --- a/docs/misc/xl-disk-configuration.txt
>>> +++ b/docs/misc/xl-disk-configuration.txt
>>> @@ -48,6 +48,24 @@ positionally or explicitly).
>>>  
>>>  Whitespace may appear before each parameter and will be ignored.
>>>  
>>> +Metacharacters in a <diskspec> may be escaped using a backslash:
>>> +
>>> +    Escape      HEX     Description
>>> +    ------      ---     -----------
>>> +    \a          0x07    Bell
>>> +    \b          0x08    Backspace
>>> +    \t          0x09    Horizontal Tab
>>> +    \n          0x0A    New Line / Line Feed
>>> +    \f          0x0C    Form Feed
>>> +    \r          0x0D    Carriage Return
>>> +    \v          0x0B    Vertical Tab
>>> +    \"          0x22    A literal double quote
>>> +    \'          0x27    A literal single quote
>>> +    \\          0x5C    A literal backslash
>>> +    \xXX                Character XX in hexadecimal
>>> +    \OOO                Character OOO in octal
>> Do you know how any of these would be useful in a diskspec? I guess I'm
>> struggling to understand when a 'Bell' would be needed :-).
> I've not got a clue -- these are just all the ones handled by
> xlu__cfgl_dequote, perhaps just for completeness?

Maybe this code was copied from elsewhere and the unneeded/unused escapes were
not removed. Regardless, it's probably unwise to remove things like bell, form
feed, and vertical tab now.

>
> This is applied to all strings in a cfg file, not just diskspecs, 

Ah, right. And as such, I agree with your follow-up comment that this info
should then be in xl.cfg(5).

Regards,
Jim