
@c %start of fragment

@node Bookmark file parser
@chapter Bookmark file parser
parses files containing bookmarks

@section Overview
@code{<g-bookmark-file>} 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
@uref{http://www.gnome.org/~ebassi/bookmark-spec,Desktop Bookmark
Specification}.

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 XML Bookmark Exchange Language specification, consisting of valid
UTF-8 encoded XML, under the @samp{xbel} root element; each bookmark is stored
inside a @samp{bookmark} 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 @samp{metadata} element,
with its @samp{owner} attribute set to @samp{http://freedesktop.org}, 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.

@example 


<?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>

@end example

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
@code{g-bookmark-file-add-application} or @code{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 @code{g-bookmark-file-to-data} or
@code{g-bookmark-file-to-file}.

The @code{<g-bookmark-file>} parser was added in GLib 2.12.

@section Usage
@include defuns-bookmarkfile.xml.texi

@c %end of fragment
