From 15f9e7bb7c658ab20fb217572e03b7d53faac894 Mon Sep 17 00:00:00 2001
From: Simon McVittie <simon.mcvittie@collabora.co.uk>
Date: Wed, 24 Sep 2014 17:43:35 +0100
Subject: [PATCH] Describe quoting for match rules

I wish I could say "I can't believe this was never documented", but
it wouldn't be true.

Bug: https://bugs.freedesktop.org/show_bug.cgi?id=24307
Reviewed-by: Alban Crequy
---
 doc/dbus-specification.xml | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)

diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml
index a110a08..1830966 100644
--- a/doc/dbus-specification.xml
+++ b/doc/dbus-specification.xml
@@ -4559,6 +4559,32 @@
           "type='signal',sender='org.freedesktop.DBus',interface='org.freedesktop.DBus',member='Foo',path='/bar/foo',destination=':452345.34',arg2='bar'"
         </para>
         <para>
+          Within single quotes (ASCII apostrophe, U+0027), a backslash
+          (U+005C) represents itself, and an apostrophe ends the quoted
+          section. Outside single quotes, \' (backslash, apostrophe)
+          represents an apostrophe, and any backslash not followed by
+          an apostrophe represents itself. For instance, the match rules
+          <literal>arg0=''\''',arg1='\',arg2=',',arg3='\\'</literal> and
+          <literal>arg0=\',arg1=\,arg2=',',arg3=\\</literal>
+          both match messages where the arguments are a 1-character string
+          containing an apostrophe, a 1-character string containing a
+          backslash, a 1-character string containing a comma, and a
+          2-character string containing two backslashes<footnote>
+            <para>
+              This idiosyncratic quoting style is based on the rules for
+              escaping items to appear inside single-quoted strings
+              in POSIX <literal>/bin/sh</literal>, but please
+              note that backslashes that are not inside single quotes have
+              different behaviour. This syntax does not offer any way to
+              represent an apostrophe inside single quotes (it is necessary
+              to leave the single-quoted section, backslash-escape the
+              apostrophe and re-enter single quotes), or to represent a
+              comma outside single quotes (it is necessary to wrap it in
+              a single-quoted section).
+            </para>
+          </footnote>.
+        </para>
+        <para>
           The following table describes the keys that can be used to create 
           a match rule.
           <informaltable>
-- 
2.7.4