From 854f4c38777ebb2527757d1a585774b0c856efa3 Mon Sep 17 00:00:00 2001
From: Richard Jones <rjones@trick.home.annexia.org>
Date: Thu, 24 Sep 2009 11:29:39 +0100
Subject: [PATCH] Add a warning about CSV format.

---
 tools/virt-ifconfig.pl | 29 +++++++++++++++++++++++++++--
 1 file changed, 27 insertions(+), 2 deletions(-)

diff --git a/tools/virt-ifconfig.pl b/tools/virt-ifconfig.pl
index 6b77ae6..4197153 100755
--- a/tools/virt-ifconfig.pl
+++ b/tools/virt-ifconfig.pl
@@ -83,8 +83,9 @@ my $csv;
 
 =item B<--csv>
 
-Write out the results in CSV format (comma-separated values).
-This format can be imported easily into databases and spreadsheets.
+Write out the results in CSV format (comma-separated values).  This
+format can be imported easily into databases and spreadsheets, but
+read L</NOTE ABOUT CSV FORMAT> below.
 
 =back
 
@@ -221,6 +222,30 @@ sub do_ifconfig
 
 exit 0;
 
+=head1 NOTE ABOUT CSV FORMAT
+
+Comma-separated values (CSV) is a deceptive format.  It I<seems> like
+it should be easy to parse, but it is definitely not easy to parse.
+
+Myth: Just split fields at commas.  Reality: This does I<not> work
+reliably.  This example has two columns:
+
+ "foo,bar",baz
+
+Myth: Read the file one line at a time.  Reality: This does I<not>
+work reliably.  This example has one row:
+
+ "foo
+ bar",baz
+
+For shell scripts, use C<csvtool> (L<http://merjis.com/developers/csv>
+also packaged in major Linux distributions).
+
+For other languages, use a CSV processing library (eg. C<Text::CSV>
+for Perl or Python's built-in csv library).
+
+Most spreadsheets and databases can import CSV directly.
+
 =head1 SEE ALSO
 
 L<guestfs(3)>,
-- 
1.8.3.1