[folks] docs: Add âwikiâ pages to the documentation

[Philip Withnall <pwithnall src gnome org>]

commit 8703f9db92532ba9982a3c75fbe7c6cfd671ba7d
Author: Philip Withnall <philip tecnocode co uk>
Date:   Sun Jul 29 20:04:44 2012 +0200

    docs: Add âwikiâ pages to the documentation
    
    These, aptly enough, contain information moved from the wiki on
    freedesktop.org about folks concepts, debugging and a glossary.

 docs/Makefile.am            |   16 ++++++++++++++--
 docs/wiki/concepts.valadoc  |   28 ++++++++++++++++++++++++++++
 docs/wiki/debugging.valadoc |   34 ++++++++++++++++++++++++++++++++++
 docs/wiki/glossary.valadoc  |   11 +++++++++++
 4 files changed, 87 insertions(+), 2 deletions(-)
---
diff --git a/docs/Makefile.am b/docs/Makefile.am
index 8e222cd..ad3f94e 100644
--- a/docs/Makefile.am
+++ b/docs/Makefile.am
@@ -18,6 +18,14 @@ upload_docs = \
 	upload-docs-vala-folks-telepathy \
 	$(NULL)
 
+folks_wiki_pages = \
+	concepts \
+	glossary \
+	debugging \
+	$(NULL)
+
+EXTRA_DIST = $(folks_wiki_files)
+
 folksdocdir=$(datadir)/devhelp/references/folks
 folksimgdir=$(datadir)/devhelp/references/folks/img
 folkstelepathydocdir=$(datadir)/devhelp/references/folks-telepathy
@@ -71,6 +79,9 @@ folks_doc_files_blacklist = \
 folks_doc_files_all = \
 	$(wildcard $(top_srcdir)/folks/*.vala) \
 	$(NULL)
+folks_wiki_files = \
+	$(addprefix wiki/,$(addsuffix .valadoc,$(folks_wiki_pages))) \
+	$(NULL)
 # FIXME: sort the files manually to work around the native doclet portion of
 # bgo#662784
 folks_doc_files = \
@@ -88,17 +99,18 @@ valadoc_flags_folks = \
 	-X $(top_srcdir)/folks/folks.h \
 	$(addprefix --pkg=,$(folks_doc_deps)) \
 	--vapidir=$(top_srcdir)/folks \
+	--wiki=$(top_srcdir)/docs/wiki \
 	$(folks_doc_files) \
 	$(NULL)
 
-folks-doc: $(folks_doc_files)
+folks-doc: $(folks_doc_files) $(folks_wiki_files)
 	$(AM_V_GEN)$(VALADOC) \
 		-o folks/ \
 		--doclet=devhelp \
 		$(valadoc_flags_folks) \
 		$(NULL)
 
-folks-gtk-doc: $(folks_doc_files)
+folks-gtk-doc: $(folks_doc_files) $(folks_wiki_files)
 	$(AM_V_GEN)$(VALADOC) \
 		-X -l -X $(top_builddir)/folks/.libs/libfolks.so \
 		-o gtk-doc/folks \
diff --git a/docs/wiki/concepts.valadoc b/docs/wiki/concepts.valadoc
new file mode 100644
index 0000000..201db67
--- /dev/null
+++ b/docs/wiki/concepts.valadoc
@@ -0,0 +1,28 @@
+The core of folks is Folks.Individual. An Individual is meant to represent a person, and contains metadata from one or more contact sources (e.g. the Gabble Jabber connection manager, a local address book). Individuals contain one or more Personas, which are a subset of a person's metadata (as exposed by a contact source). These Personas form an ''unordered'' set. The Individual object will expose the sum of all n-ary attributes (e.g. e-mail addresses) from all contained Personas and will expose a single value for the attribute from amongst the Personas (according some some attribute-specific heuristic) for unary attributes (e.g. alias, avatar).
+
+For example, an Individual's alias is chosen from its Personas by preferring aliases which are set (Personas don't necessarily have to implement Folks.Alias, or have a non-null alias set) and are not equal to the Persona's display ID (e.g. set to their IM address as a default). The aliases from writeable PersonaStores are preferred to those from other PersonaStores.
+
+Currently, all backends except the key-file and EDS backends are read-only. The key-file and EDS backends are writeable, which allows for linking of Personas from other backends by creating a Kf.Persona or an Edsf.Persona containing linkable properties which can be matched against the Personas being linked together. There is only ever ''one'' writeable PersonaStore; libfolks does not do synchronisation, since that can only ever go wrong.
+
+Because Individuals are basically just a set of Personas, it is possible to both link and unlink contacts.
+
+Personas are linked using common fields; the single primary writeable PersonaStore returns Personas with fields containing the UIDs of all the other Personas which are linked to that Persona. The IndividualAggregator then assembles Individuals from the Personas whose UIDs are are linked from the primary PersonaStore.
+
+For example, there are two PersonaStores: Telepathy and a primary key file PersonaStore. The key file contains the following, which is exposed as a Persona:
+
+{{{
+[IndividualID]
+    jabber=foo jabber org
+    msn=bla hotmail com
+}}}
+
+The Telepathy backend exposes these two Personas:
+
+{{{
+Persona with uid = jabber:foo jabber org
+Persona with uid = msn:bla hotmail com
+}}}
+
+Since their UIDs are referenced by a Persona in primary key file PersonaStore, the IndividualAggregator links the two Personas to form an Individual.
+
+This linking can work on other fields from other PersonaStores. For example, if a verified e-mail address was provided by a Persona from a Facebook backend, that could be used to link Personas (by setting the "im-addresses" property from the Folks.IMable interface as a ''linkable property''). This is only possible for Personas which come from "trusted" PersonaStores since, for example, a malicious user could otherwise set their Jabber address on Facebook to someoneelse jabber org and hijack people's contact lists; or someone could impersonate someone else's link-local XMPP account by changing their hostname and username (or just using hacked IM software). PersonaStores can either be completely untrusted (e.g. a link-local XMPP PersonaStore); can have their UIDs trusted, but no other properties (e.g. a Jabber PersonaStore); or can have all their properties trusted (e.g. the key-file backend's PersonaStore).
diff --git a/docs/wiki/debugging.valadoc b/docs/wiki/debugging.valadoc
new file mode 100644
index 0000000..c7cf5f0
--- /dev/null
+++ b/docs/wiki/debugging.valadoc
@@ -0,0 +1,34 @@
+The main way to debug libfolks (or applications using it) is using the ''G_MESSAGES_DEBUG'' environment variable. For example, to collect a log file of all libfolks debug data from Empathy, use the command:
+{{{
+FOLKS_DEBUG_NO_COLOUR=1 G_MESSAGES_DEBUG=all empathy &> folks.log
+}}}
+
+Available values for folks for the ''G_MESSAGES_DEBUG'' environment variable are:
+
+ * ''all'' (equivalent to listing all possible values)
+ * ''folks'' (for the core of libfolks)
+ * ''eds'' (for the evolution-data-server backend)
+ * ''key-file'' (for the key file backend)
+ * ''libsocialweb'' (for the libsocialweb backend)
+ * ''telepathy'' (for the Telepathy backend)
+ * ''tracker'' (for the Tracker backend)
+
+Multiple values can be specified using commas, e.g.: ''G_MESSAGES_DEBUG=folks,eds,key-file''.
+
+Another way to debug libfolks itself is to run the //folks-inspect// utility which is bundled with libfolks (possibly in a utils or tools package, depending on your distribution). Its use is beyond the scope of this page, but it has a ''help'' command which should serve as an introduction.
+
+Finally, libfolks has a status printing mechanism. Some libfolks clients may expose this as part of their own debug functionality (for example, folks-inspect uses this for its ''debug'' command), but it can be invoked more generally using gdb:
+
+ * Run the libfolks client you wish to debug under gdb.
+ * Break execution at a suitable (for example, once you've got the client into an erroneous state you wish to examine).
+ * At gdb's command prompt, enter the following commands:
+
+{{{
+set $folks_debug = folks_debug_dup()
+call folks_debug_emit_print_status($folks_debug)
+}}}
+
+This will print out a listing of the state of all the objects relevant to libfolks' linking decisions.
+
+Finally, libfolks outputs debug and status information using terminal colours and formatting by default. If this isn't desired, set the ''FOLKS_DEBUG_NO_COLOUR'' environment variable.
+
diff --git a/docs/wiki/glossary.valadoc b/docs/wiki/glossary.valadoc
new file mode 100644
index 0000000..0b96132
--- /dev/null
+++ b/docs/wiki/glossary.valadoc
@@ -0,0 +1,11 @@
+ * ''aggregation'': the process performed by libfolks which takes all the ''implicit'' and ''explicit link''s between ''persona''s and uses them to form ''individual''s which (should) uniquely represent physical people known by the ''user''.
+ * ''client'': an application (or library) which uses libfolks.
+ * ''explicit link'': a ''link'' between ''persona''s which was explicitly created by the ''user''.
+ * ''implicit link'': a ''link'' between ''persona''s which wasn't explicitly created by the ''user''; it was inferred by libfolks from trusted data which is shared by the ''persona''s in question.
+ * ''individual'': a collection of one or more ''persona''s which relate to the same physical person.
+ * ''link'' (''verb''): to âconnectâ two ''personas'' (which should relate to the same physical person) in a non-destructive manner to form an ''individual''.
+ * ''linked individual'': an ''individual'' which contains more than one ''persona''.
+ * ''persona'': a single âfacetâ of a physical person as seen by the ''user'', such as a contact for them on a particular IM service, their profile on a social networking site or the ''user''âs address book entry for the person.
+ * ''singleton individual'': an ''individual'' which contains only one ''persona'' (i.e. that ''persona'' has no ''implicit'' or ''explicit link''s).
+ * ''unlink'': to break the ''link''s between the ''persona''s forming an ''individual'' so that they are no longer ''aggregated'' into that ''individual''.
+ * ''user'': the physical person who owns the currently logged in user account on the computer.