[gnome-software] Convert the plugin README to markdown

[Richard Hughes <rhughes src gnome org>]

commit 6a614acf0d2fcd71177f442a745f4988c07032d8
Author: Richard Hughes <richard hughsie com>
Date:   Tue Jun 25 09:20:34 2013 +0100

    Convert the plugin README to markdown

 src/plugins/README    |  125 -------------------------------------------
 src/plugins/README.md |  141 +++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 141 insertions(+), 125 deletions(-)
---
diff --git a/src/plugins/README.md b/src/plugins/README.md
new file mode 100644
index 0000000..87eb173
--- /dev/null
+++ b/src/plugins/README.md
@@ -0,0 +1,141 @@
+# Introduction #
+
+Plugins are modules that are loaded at runtime to provide information about
+requests and to service user actions like installing, removing and updating.
+Plugins are disabled by default, and need to be enabled manually before they
+are used.
+This allows different distributions to pick and choose how the application
+installer gathers data just by setting a single GSettings key. For instance:
+
+>  SuSE has AppStream data and also uses
+> PackageKit. The default on SuSE would
+> be  to enable the `appstream` and
+> `packagekit` plugins and leave the
+> rest disabled.
+
+>  Fedora doesn't have AppStream data,
+> so it has to make do with other local
+> data.  On Fedora we would enable the
+> `datadir-apps`, `desktop-db` and all
+> the  `hardcoded` plugins to get some
+> sensible results. For Fedora, it
+> probably also  makes sense to write a
+> plugin that interfaces with FAS or
+> fedora-tagger to get  the extra
+> metadata for uninstalled applications.
+
+Plugins also have a priority system where the largest number gets run first.
+That means if one plugin requires some property or metadata set by another
+plugin then it **must** have a priority value that is greater to ensure the
+property is available.
+
+As we are letting the distribution pick and choose what plugins are run, we need
+a way to 'refine' the results. For instance, the `packagekit` plugin returns
+applications with a kind `PACKAGE` which will not be returned to the
+UI for display as they are not applications.
+The 'packagekit' plugin relies on other plugins like `appstream` or `desktopdb`
+to add the required name, summary and icon data and to convert the `GsApp` to a `NORMAL`.
+Furthermore, the 'hardcoded-kind' plugin may override the NORMAL
+kind to a `SYSTEM` which means the application is core cannot be
+removed by the user. Core apps would be things like nautilus and totem.
+
+As a general rule, try to make plugins as small and self-contained as possible
+and remember to cache as much data as possible for speed. Memory is cheap, time
+less so.
+
+---------------------------------------
+
+## Plugins ##
+
+In this document, application properties are specified as `[id]` meaning the
+property called `id` and metadata (basically, random properites that we don't
+want to export) are specified as `{sekret-property}`.
+Adding and using metadata is quick as it's stored internally in a hash table,
+so don't be afraid to add extra properties where it might make sense for other
+plugins.
+
+### dummy ###
+Provides some dummy data that is useful in self test programs.
+
+Overview:    | <p>
+-------------|---
+Methods:     | Search, AddUpdates, AddInstalled, AddPopular
+Requires:    | `nothing`
+Refines:     | `[id]->[name]`, `[id]->[summary]`
+
+### hardcoded-kind ###
+Provides some hardcoded static core applications that cannot be removed.
+
+Overview:    | <p>
+-------------|---
+Methods:     | `nothing`
+Requires:    | `nothing`
+Refines:     | `[id]->[kind]`
+Note:        | This is based on the gnome jhbuild moduleset
+
+### hardcoded-popular ###
+Provides some hardcoded static favourite applications.
+
+Overview:    | <p>
+-------------|---
+Methods:     | AddPopular
+Requires:    | `nothing`
+Refines:     | `nothing`
+
+### hardcoded-ratings ###
+Provides some hardcoded static ratings for applications.
+
+Overview:    | <p>
+-------------|---
+Methods:     | `nothing`
+Requires:    | `nothing`
+Refines:     | `[id]->[rating]`
+
+### local-ratings ###
+Provides a local SQL database of user-set ratings, useful for testing.
+
+Overview:    | <p>
+-------------|---
+Methods:     | AppSetRating
+Requires:    | `nothing`
+Refines:     | `[id]->[rating]`
+
+### packagekit ###
+Uses the system PackageKit instance to return package data.
+
+Overview:    | <p>
+-------------|---
+Methods:     | Search, AddUpdates, AddInstalled, AppInstall, AppRemove, AppUpdate
+Requires:    | `{package-id}`
+Refines:     | `nothing`
+Refines:     | `{package-id}`, `{package-name}`, `{package-summary}`, `{update-name}`, `{update-details}`
+
+### desktopdb ###
+Uses the PackageKit desktop.db cache to map package names to, desktop names.
+
+Overview:    | <p>
+-------------|---
+Methods:     | `nothing`
+Requires:    | `nothing`
+Refines:     | `{package-name}->{datadir-desktop-filename}`
+
+### datadir-apps ###
+Uses the files in /usr/share/applications to provide icons and, translations for
+installed applications.
+
+Overview:    | <p>
+-------------|---
+Methods:     | `nothing`
+Requires:    | `nothing`
+Refines:     | `{datadir-desktop-filename}->[name]`, `{datadir-desktop-filename}->[summary]`, 
`{datadir-desktop-filename}->[pixbuf]`, `{datadir-desktop-filename}->[id]`, 
`{datadir-desktop-filename}->[kind]`
+
+### datadir-filename ###
+Uses the existance of a files in /usr/share/applications, named $id.desktop to
+set the correct desktop filename., This is useful if we just have a bare `[id]`
+from something like, AddPopular and want to get the details using 'datadir-apps'
+
+Overview:    | <p>
+-------------|---
+Methods:     | `nothing`
+Requires:    | `nothing`
+Refines:     | `[id]->{datadir-desktop-filename}`