docs: Give advice on dealing with quoting special characters

The man page mentions passing config snippets key=val in xl create.
Unfortunately, the config syntax contain characters which are
interpreted (and often discarded) by the shell before getting passed
in, resulting in a parsing error.

For example:

xl create hvm.cfg cpus="0-3"

The shell will eat the quotes and pass 'cpus=0-3' to xl, which won't
parse properly without the quotes.

Mention this in the man page, and recommend the use of single quotes, as well
as separating multiple arguments with a semicolon, thus:

xl create hvm.cfg 'cpus="0-3"; pci=["1.0","1.1"]'

Signed-off-by: George Dunlap <george.dunlap@eu.citrix.com>
Acked-by: Ian Jackson <ian.jackson@eu.citrix.com>

diff --git a/docs/man/xl.pod.1 b/docs/man/xl.pod.1
index 7c03de6df16b62ba61b58c0fe9505b771ea3b524..30bd4bfc4474a22b234fb8f8c6c6db6837ff3f87 100644 (file)
--- a/docs/man/xl.pod.1
+++ b/docs/man/xl.pod.1
@@ -152,6 +152,12 @@ It is possible to pass I<key=value> pairs on the command line to provide
 options as if they were written in the configuration file; these override
 whatever is in the I<configfile>.
 
+NB: Many config options require characters such as quotes or brackets
+which are interpreted by the shell (and often discarded) before being
+passed to xl, resulting in xl being unable to parse the value
+correctly.  A simple work-around is to put all extra options within a
+single set of quotes, separated by semicolons.  (See below for an example.)
+
 =back
 
 B<EXAMPLES>
@@ -165,6 +171,13 @@ B<EXAMPLES>
 This creates a domain with the file /etc/xen/DebianLenny, and returns as
 soon as it is run.
 
+=item I<with extra parameters>
+
+  xl create hvm.cfg 'cpus="0-3"; pci=["01:05.1","01:05.2"]'
+
+This creates a domain with the file hvm.cfg, but additionally pins it to
+cpus 0-3, and passes through two PCI devices.
+
 =back
 
 =item B<config-update> B<domid> [I<configfile>] [I<OPTIONS>]
@@ -186,9 +199,11 @@ Use the given configuration file.
 
 =item B<key=value>
 
-It is possible to pass I<key=value> pairs on the command line to provide
-options as if they were written in the configuration file; these override
-whatever is in the I<configfile>.
+It is possible to pass I<key=value> pairs on the command line to
+provide options as if they were written in the configuration file;
+these override whatever is in the I<configfile>.  Please see the note
+under I<create> on handling special characters when passing
+I<key=value> pairs on the command line.
 
 =back