Bookmark file parser
<!-- ##### SECTION Short_Description ##### -->
-parses files containing bookmarks
+
<!-- ##### SECTION Long_Description ##### -->
<para>
-#GBookmarkFile lets you parse, edit or create files containing bookmarks
-to URI, along with some meta-data about the resource pointed by the URI like
-its MIME type, the application that is registering the bookmark and the
-icon that should be used to represent the bookmark. The data is stored using
-the
-<ulink url="http://www.gnome.org/~ebassi/bookmark-spec">Desktop Bookmark
-Specification</ulink>.
-</para>
-
-<para>
-The syntax of the bookmark files is described in detail inside the Desktop
-Bookmark Specification, here is a quick summary: bookmark files use a sub-class
-of the
-<ulink url="">XML Bookmark Exchange Language</ulink> specification, consisting
-of valid UTF-8 encoded XML, under the <literal>xbel</literal> root element;
-each bookmark is stored inside a <literal>bookmark</literal> element, using
-its URI: no relative paths can be used inside a bookmark file. The bookmark
-may have a user defined title and description, to be used instead of the URI.
-Under the <literal>metadata</literal> element, with its <literal>owner</literal>
-attribute set to <literal>http://freedesktop.org</literal>, is stored the
-meta-data about a resource pointed by its URI. The meta-data consists of
-the resource's MIME type; the applications that have registered a bookmark;
-the groups to which a bookmark belongs to; a visibility flag, used to set
-the bookmark as "private" to the applications and groups that has it
-registered; the URI and MIME type of an icon, to be used when displaying the
-bookmark inside a GUI.
-</para>
-
-<informalexample><programlisting>
-<![CDATA[
-<?xml version="1.0"?>
-<!DOCTYPE xbel PUBLIC
- "+//IDN python.org//DTD XML Bookmark Exchange Language 1.0//EN//XML"
- "http://www.python.org/topics/xml/dtds/xbel-1.0.dtd">
-<xbel version="1.0"
- xmlns:mime="http://www.freedesktop.org/standards/shared-mime-info"
- xmlns:bookmark="http://www.freedesktop.org/standards/desktop-bookmarks">
- <bookmark href="file:///home/ebassi/bookmark-spec/bookmark-spec.xml">
- <title>Desktop Bookmarks Spec</title>
- <info>
- <metadata owner="http://freedesktop.org">
- <mime:mime-type>text/xml</mime:mime-type>
- <bookmark:applications>
- <bookmark:application name="GEdit" count="2" exec="gedit %u" timestamp="1115726763"/>
- <bookmark:application name="GViM" count="7" exec="gvim %f" timestamp="1115726812"/>
- </bookmark:applications>
- <bookmark:groups>
- <bookmark:group>Editors</bookmark:group>
- </bookmark:groups>
- </metadata>
- </info>
- </bookmark>
-</xbel>
-]]>
-</programlisting></informalexample>
-
-<para>
-A bookmark file might contain more than one bookmark; each bookmark is accessed
-through its URI.
-</para>
-
-<para>
-The important caveat of bookmark files is that when you add a new bookmark you
-must also add the application that is registering it, using
-g_bookmark_file_add_application() or g_bookmark_file_set_app_info(). If a
-bookmark has no applications then it won't be dumped when creating the
-on disk representation, using g_bookmark_file_to_data() or
-g_bookmark_file_to_file().
-</para>
-
-<para>
-The #GBookmarkFile parser was added in GLib 2.12.
+
</para>
<!-- ##### SECTION See_Also ##### -->
<!-- ##### STRUCT GBookmarkFile ##### -->
<para>
-The <structname>GBookmarkFile</structname> struct contains only private data
-and should not be used directly.
+
</para>
<!-- ##### MACRO G_BOOKMARK_FILE_ERROR ##### -->
<para>
-Error domain for bookmark file parsing. Errors in this domain will be
-from the #GBookmarkFileError enumeration. See #GError for informations
-on error domains.
+
</para>
<!-- ##### ENUM GBookmarkFileError ##### -->
<para>
-Error codes returned by bookmark file parsing.
+
</para>
-@G_BOOKMARK_FILE_ERROR_INVALID_URI: URI was ill-formed
-@G_BOOKMARK_FILE_ERROR_INVALID_VALUE: a requested field was not found
-@G_BOOKMARK_FILE_ERROR_APP_NOT_REGISTERED: a requested application did not
-register a bookmark
-@G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND: a requested URI was not found
-@G_BOOKMARK_FILE_ERROR_READ: document was ill formed
-@G_BOOKMARK_FILE_ERROR_UNKNOWN_ENCODING: the text being parsed was in an
-unknown encoding
-@G_BOOKMARK_FILE_ERROR_WRITE: an error occurred while writing
-@G_BOOKMARK_FILE_ERROR_FILE_NOT_FOUND: requested file was not found
+@G_BOOKMARK_FILE_ERROR_INVALID_URI:
+@G_BOOKMARK_FILE_ERROR_INVALID_VALUE:
+@G_BOOKMARK_FILE_ERROR_APP_NOT_REGISTERED:
+@G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND:
+@G_BOOKMARK_FILE_ERROR_READ:
+@G_BOOKMARK_FILE_ERROR_UNKNOWN_ENCODING:
+@G_BOOKMARK_FILE_ERROR_WRITE:
+@G_BOOKMARK_FILE_ERROR_FILE_NOT_FOUND:
<!-- ##### FUNCTION g_bookmark_file_new ##### -->
<para>
/**
* SECTION:atomic_operations
* @title: Atomic Operations
- * @shot_description: basic atomic integer and pointer operations
+ * @short_description: basic atomic integer and pointer operations
* @see_also: #GMutex
*
* The following functions can be used to atomically access integers and
#include "gutils.h"
+/**
+ * SECTION:bookmarkfile
+ * @title: Bookmark file parser
+ * @short_description: parses files containing bookmarks
+ *
+ * GBookmarkFile lets you parse, edit or create files containing bookmarks
+ * to URI, along with some meta-data about the resource pointed by the URI
+ * like its MIME type, the application that is registering the bookmark and
+ * the icon that should be used to represent the bookmark. The data is stored
+ * using the
+ * <ulink url="http://www.gnome.org/~ebassi/bookmark-spec">Desktop Bookmark
+ * Specification</ulink>.
+ *
+ * The syntax of the bookmark files is described in detail inside the Desktop
+ * Bookmark Specification, here is a quick summary: bookmark files use a
+ * sub-class of the <ulink url="">XML Bookmark Exchange Language</ulink>
+ * specification, consisting of valid UTF-8 encoded XML, under the
+ * <literal>xbel</literal> root element; each bookmark is stored inside a
+ * <literal>bookmark</literal> element, using its URI: no relative paths can
+ * be used inside a bookmark file. The bookmark may have a user defined title
+ * and description, to be used instead of the URI. Under the
+ * <literal>metadata</literal> element, with its <literal>owner</literal>
+ * attribute set to <literal>http://freedesktop.org</literal>, is stored the
+ * meta-data about a resource pointed by its URI. The meta-data consists of
+ * the resource's MIME type; the applications that have registered a bookmark;
+ * the groups to which a bookmark belongs to; a visibility flag, used to set
+ * the bookmark as "private" to the applications and groups that has it
+ * registered; the URI and MIME type of an icon, to be used when displaying
+ * the bookmark inside a GUI.
+ * |[<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../glib/tests/bookmarks.xbel"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include>]|
+ *
+ * A bookmark file might contain more than one bookmark; each bookmark
+ * is accessed through its URI.
+ *
+ * The important caveat of bookmark files is that when you add a new
+ * bookmark you must also add the application that is registering it, using
+ * g_bookmark_file_add_application() or g_bookmark_file_set_app_info().
+ * If a bookmark has no applications then it won't be dumped when creating
+ * the on disk representation, using g_bookmark_file_to_data() or
+ * g_bookmark_file_to_file().
+ *
+ * The #GBookmarkFile parser was added in GLib 2.12.
+ */
+
/* XBEL 1.0 standard entities */
#define XBEL_VERSION "1.0"
#define XBEL_DTD_NICK "xbel"
G_BEGIN_DECLS
-/* GError enumeration
+/**
+ * G_BOOKMARK_FILE_ERROR:
+ *
+ * Error domain for bookmark file parsing.
+ * Errors in this domain will be from the #GBookmarkFileError
+ * enumeration. See #GError for information on error domains.
*/
#define G_BOOKMARK_FILE_ERROR (g_bookmark_file_error_quark ())
+
+/**
+ * GBookmarkFileError:
+ * @G_BOOKMARK_FILE_ERROR_INVALID_URI: URI was ill-formed
+ * @G_BOOKMARK_FILE_ERROR_INVALID_VALUE: a requested field was not found
+ * @G_BOOKMARK_FILE_ERROR_APP_NOT_REGISTERED: a requested application did
+ * not register a bookmark
+ * @G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND: a requested URI was not found
+ * @G_BOOKMARK_FILE_ERROR_READ: document was ill formed
+ * @G_BOOKMARK_FILE_ERROR_UNKNOWN_ENCODING: the text being parsed was
+ * in an unknown encoding
+ * @G_BOOKMARK_FILE_ERROR_WRITE: an error occurred while writing
+ * @G_BOOKMARK_FILE_ERROR_FILE_NOT_FOUND: requested file was not found
+ *
+ * Error codes returned by bookmark file parsing.
+ */
typedef enum
{
G_BOOKMARK_FILE_ERROR_INVALID_URI,
GQuark g_bookmark_file_error_quark (void);
-/*
- * GBookmarkFile
+/**
+ * GBookmarkFile:
+ *
+ * The <structname>GBookmarkFile</structname> struct contains only
+ * private data and should not be directly accessed.
*/
typedef struct _GBookmarkFile GBookmarkFile;
EXTRA_DIST += \
4096-random-bytes \
- keyfiletest.ini
+ keyfiletest.ini \
+ bookmarks.xbel
--- /dev/null
+<?xml version="1.0"?>
+<!DOCTYPE xbel PUBLIC
+ "+//IDN python.org//DTD XML Bookmark Exchange Language 1.0//EN//XML"
+ "http://www.python.org/topics/xml/dtds/xbel-1.0.dtd">
+<xbel version="1.0"
+ xmlns:mime="http://www.freedesktop.org/standards/shared-mime-info"
+ xmlns:bookmark="http://www.freedesktop.org/standards/desktop-bookmarks">
+ <bookmark href="file:///home/ebassi/bookmark-spec/bookmark-spec.xml">
+ <title>Desktop Bookmarks Spec</title>
+ <info>
+ <metadata owner="http://freedesktop.org">
+ <mime:mime-type>text/xml</mime:mime-type>
+ <bookmark:applications>
+ <bookmark:application name="GEdit" count="2" exec="gedit %u" timestamp="1115726763"/>
+ <bookmark:application name="GViM" count="7" exec="gvim %f" timestamp="1115726812"/>
+ </bookmark:applications>
+ <bookmark:groups>
+ <bookmark:group>Editors</bookmark:group>
+ </bookmark:groups>
+ </metadata>
+ </info>
+ </bookmark>
+</xbel