Commit 189c2c21 authored by Emmanuele Bassi's avatar Emmanuele Bassi Committed by Emmanuele Bassi

Add documentation for GBookmarkFile to GLib's reference guide.

2006-03-27  Emmanuele Bassi  <ebassi@cvs.gnome.org>

	* docs/reference/glib/glib-docs.sgml:
	* docs/reference/glib/glib-sections.txt:
	* docs/reference/glib/tmpl/bookmarkfile.sgml: Add documentation for
	GBookmarkFile to GLib's reference guide.
parent 82702c45
2006-03-27 Emmanuele Bassi <ebassi@cvs.gnome.org>
* docs/reference/glib/glib-docs.sgml:
* docs/reference/glib/glib-sections.txt:
* docs/reference/glib/tmpl/bookmarkfile.sgml: Add documentation for
GBookmarkFile to GLib's reference guide.
2006-03-27 Emmanuele Bassi <ebassi@cvs.gnome.org>
* glib/glib.h:
......
2006-03-27 Emmanuele Bassi <ebassi@cvs.gnome.org>
* docs/reference/glib/glib-docs.sgml:
* docs/reference/glib/glib-sections.txt:
* docs/reference/glib/tmpl/bookmarkfile.sgml: Add documentation for
GBookmarkFile to GLib's reference guide.
2006-03-27 Emmanuele Bassi <ebassi@cvs.gnome.org>
* glib/glib.h:
......
......@@ -57,6 +57,7 @@
<!ENTITY glib-Option SYSTEM "xml/option.xml">
<!ENTITY glib-Markup SYSTEM "xml/markup.xml">
<!ENTITY glib-Keyfile SYSTEM "xml/keyfile.xml">
<!ENTITY glib-Bookmarkfile SYSTEM "xml/bookmarkfile.xml">
<!ENTITY glib-i18n SYSTEM "xml/i18n.xml">
<!ENTITY glib-Version SYSTEM "xml/version.xml">
......@@ -149,6 +150,7 @@ synchronize their operation.
&glib-Pattern-Matching;
&glib-Markup;
&glib-Keyfile;
&glib-Bookmarkfile;
&glib-Windows-Compatibility-Functions;
</chapter>
......
......@@ -1489,6 +1489,60 @@ g_key_file_remove_comment
g_key_file_error_quark
</SECTION>
<SECTION>
<TITLE>Bookmark file parser</TITLE>
<FILE>bookmarkfile</FILE>
GBookmarkFile
G_BOOKMARK_FILE_ERROR
GBookmarkFileError
g_bookmark_file_new
g_bookmark_file_free
g_bookmark_file_load_from_file
g_bookmark_file_load_from_data
g_bookmark_file_load_from_data_dirs
g_bookmark_file_to_data
g_bookmark_file_to_file
g_bookmark_file_has_item
g_bookmark_file_has_group
g_bookmark_file_has_application
g_bookmark_file_get_size
g_bookmark_file_get_uris G_GNUC_MALLOC
<SUBSECTION>
g_bookmark_file_get_title
g_bookmark_file_get_description
g_bookmark_file_get_mime_type
g_bookmark_file_get_is_private
g_bookmark_file_get_icon
g_bookmark_file_get_added
g_bookmark_file_get_modified
g_bookmark_file_get_visited
g_bookmark_file_get_groups
g_bookmark_file_get_applications
g_bookmark_file_get_app_info
<SUBSECTION>
g_bookmark_file_set_title
g_bookmark_file_set_description
g_bookmark_file_set_mime_type
g_bookmark_file_set_is_private
g_bookmark_file_set_icon
g_bookmark_file_set_added
g_bookmark_file_set_groups
g_bookmark_file_set_modified
g_bookmark_file_set_visited
g_bookmark_file_set_app_info
g_bookmark_file_add_group
g_bookmark_file_add_application
g_bookmark_file_remove_group
g_bookmark_file_remove_application
g_bookmark_file_remove_item
g_bookmark_file_move_item
<SUBSECTION Private>
g_bookmark_file_error_quark
</SECTION>
<SECTION>
<TITLE>Dynamic Loading of Modules</TITLE>
<FILE>modules</FILE>
......
<!-- ##### SECTION Title ##### -->
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 ##### -->
<para>
</para>
<!-- ##### SECTION Stability_Level ##### -->
<!-- ##### 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
<!-- ##### FUNCTION g_bookmark_file_new ##### -->
<para>
</para>
@Returns:
<!-- ##### FUNCTION g_bookmark_file_free ##### -->
<para>
</para>
@bookmark:
<!-- ##### FUNCTION g_bookmark_file_load_from_file ##### -->
<para>
</para>
@bookmark:
@filename:
@error:
@Returns:
<!-- ##### FUNCTION g_bookmark_file_load_from_data ##### -->
<para>
</para>
@bookmark:
@data:
@length:
@error:
@Returns:
<!-- ##### FUNCTION g_bookmark_file_load_from_data_dirs ##### -->
<para>
</para>
@bookmark:
@file:
@full_path:
@error:
@Returns:
<!-- ##### FUNCTION g_bookmark_file_to_data ##### -->
<para>
</para>
@bookmark:
@length:
@error:
@Returns:
<!-- ##### FUNCTION g_bookmark_file_to_file ##### -->
<para>
</para>
@bookmark:
@filename:
@error:
@Returns:
<!-- ##### FUNCTION g_bookmark_file_has_item ##### -->
<para>
</para>
@bookmark:
@uri:
@Returns:
<!-- ##### FUNCTION g_bookmark_file_has_group ##### -->
<para>
</para>
@bookmark:
@uri:
@group:
@error:
@Returns:
<!-- ##### FUNCTION g_bookmark_file_has_application ##### -->
<para>
</para>
@bookmark:
@uri:
@name:
@error:
@Returns:
<!-- ##### FUNCTION g_bookmark_file_get_size ##### -->
<para>
</para>
@bookmark:
@Returns:
<!-- ##### FUNCTION g_bookmark_file_get_uris ##### -->
<para>
</para>
@bookmark:
@length:
@Returns:
<!-- ##### FUNCTION g_bookmark_file_get_title ##### -->
<para>
</para>
@bookmark:
@uri:
@error:
@Returns:
<!-- ##### FUNCTION g_bookmark_file_get_description ##### -->
<para>
</para>
@bookmark:
@uri:
@error:
@Returns:
<!-- ##### FUNCTION g_bookmark_file_get_mime_type ##### -->
<para>
</para>
@bookmark:
@uri:
@error:
@Returns:
<!-- ##### FUNCTION g_bookmark_file_get_is_private ##### -->
<para>
</para>
@bookmark:
@uri:
@error:
@Returns:
<!-- ##### FUNCTION g_bookmark_file_get_icon ##### -->
<para>
</para>
@bookmark:
@uri:
@href:
@mime_type:
@error:
@Returns:
<!-- ##### FUNCTION g_bookmark_file_get_added ##### -->
<para>
</para>
@bookmark:
@uri:
@error:
@Returns:
<!-- ##### FUNCTION g_bookmark_file_get_modified ##### -->
<para>
</para>
@bookmark:
@uri:
@error:
@Returns:
<!-- ##### FUNCTION g_bookmark_file_get_visited ##### -->
<para>
</para>
@bookmark:
@uri:
@error:
@Returns:
<!-- ##### FUNCTION g_bookmark_file_get_groups ##### -->
<para>
</para>
@bookmark:
@uri:
@length:
@error:
@Returns:
<!-- ##### FUNCTION g_bookmark_file_get_applications ##### -->
<para>
</para>
@bookmark:
@uri:
@length:
@error:
@Returns:
<!-- ##### FUNCTION g_bookmark_file_get_app_info ##### -->
<para>
</para>
@bookmark:
@uri:
@name:
@exec:
@count:
@stamp:
@error:
@Returns:
<!-- ##### FUNCTION g_bookmark_file_set_title ##### -->
<para>
</para>
@bookmark:
@uri:
@title:
<!-- ##### FUNCTION g_bookmark_file_set_description ##### -->
<para>
</para>
@bookmark:
@uri:
@description:
<!-- ##### FUNCTION g_bookmark_file_set_mime_type ##### -->
<para>
</para>
@bookmark:
@uri:
@mime_type:
<!-- ##### FUNCTION g_bookmark_file_set_is_private ##### -->
<para>
</para>
@bookmark:
@uri:
@is_private:
<!-- ##### FUNCTION g_bookmark_file_set_icon ##### -->
<para>
</para>
@bookmark:
@uri:
@href:
@mime_type:
<!-- ##### FUNCTION g_bookmark_file_set_added ##### -->
<para>
</para>
@bookmark:
@uri:
@added:
<!-- ##### FUNCTION g_bookmark_file_set_groups ##### -->
<para>
</para>
@bookmark:
@uri:
@groups:
@length:
<!-- ##### FUNCTION g_bookmark_file_set_modified ##### -->
<para>
</para>
@bookmark:
@uri:
@modified:
<!-- ##### FUNCTION g_bookmark_file_set_visited ##### -->
<para>
</para>
@bookmark:
@uri:
@visited:
<!-- ##### FUNCTION g_bookmark_file_set_app_info ##### -->
<para>
</para>
@bookmark:
@uri:
@name:
@exec:
@count:
@stamp:
@error:
@Returns:
<!-- ##### FUNCTION g_bookmark_file_add_group ##### -->
<para>
</para>
@bookmark:
@uri:
@group:
<!-- ##### FUNCTION g_bookmark_file_add_application ##### -->
<para>
</para>
@bookmark:
@uri:
@name:
@exec:
<!-- ##### FUNCTION g_bookmark_file_remove_group ##### -->
<para>
</para>
@bookmark:
@uri:
@group:
@error:
@Returns:
<!-- ##### FUNCTION g_bookmark_file_remove_application ##### -->
<para>
</para>
@bookmark:
@uri:
@name:
@error:
@Returns:
<!-- ##### FUNCTION g_bookmark_file_remove_item ##### -->
<para>
</para>
@bookmark:
@uri:
@error:
<!-- ##### FUNCTION g_bookmark_file_move_item ##### -->
<para>
</para>
@bookmark:
@old_uri:
@new_uri:
@error:
@Returns:
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment