[libgdata] [docs] Add note about #defined strings

[Philip Withnall <pwithnall src gnome org>]

commit b926e8e717f309a7d49c57560b4ad4dbf683b215
Author: Philip Withnall <philip tecnocode co uk>
Date:   Thu Apr 1 20:58:00 2010 +0100

    [docs] Add note about #defined strings

 HACKING                           |    3 ++-
 docs/reference/gdata-overview.xml |   10 +++++++++-
 2 files changed, 11 insertions(+), 2 deletions(-)
---
diff --git a/HACKING b/HACKING
index 16676f4..674ecf2 100644
--- a/HACKING
+++ b/HACKING
@@ -109,7 +109,8 @@ Adding public API
    (see the gcc documentation: http://gcc.gnu.org/onlinedocs/gcc/Function-Attributes.html#index-g_t_0040code_007bconst_007d-function-attribute-2207).
 
  - All properties which could be considered to use an enumerated value should almost definitely use a string instead. See the documentation section
-   on "Enumerable Properties" in the "GData Overview" section.
+   on "Enumerable Properties" in the "GData Overview" section. Where appropriate, the values for these string properties should be made available
+   as #defines.
 
  - New services should be implemented in libgdata itself, not by applications which use libgdata. See the documentation section on "New Services" in
    the "GData Overview" section.
diff --git a/docs/reference/gdata-overview.xml b/docs/reference/gdata-overview.xml
index 2b7fb6d..93fdff0 100644
--- a/docs/reference/gdata-overview.xml
+++ b/docs/reference/gdata-overview.xml
@@ -101,7 +101,7 @@
 			remains fairly flexible in how it treats data. The sections below detail some of the ways in which libgdata achieves this,
 			and the reasoning behind them.</para>
 
-		<refsect2>
+		<refsect2 id="enumerable-properties">
 			<title>Enumerable Properties</title>
 			<para>There are many class properties in libgdata which should, at first glance, be implemented as enumerated types. Function
 				calls such as <function><link linkend="gdata-link-get-relation-type">gdata_link_get_relation_type()</link></function>
@@ -125,6 +125,14 @@
 		</refsect2>
 
 		<refsect2>
+			<title>String Constants</title>
+			<para>As the GData protocol is XML-based, it makes extensive use of string constants, typically as
+				<link linkend="enumerable-properties">enumerated types</link> or namespaced URIs. To stop the authors of applications
+				which use libgdata from having to continually look up the correct "magic strings" to use, all such strings should
+				be <code>#define</code>d in libgdata, and referenced in the appropriate function documentation.</para>
+		</refsect2>
+
+		<refsect2>
 			<title>New Services</title>
 			<para>The API required to implement support for a new service using libgdata is not publicly exposed. This is because doing
 				so would clutter the API to a large extent; for example, exposing various properties as writeable which are currently