From 189c2c213e89090d21c9f421c8eacfeb1c018bd4 Mon Sep 17 00:00:00 2001 From: Emmanuele Bassi Date: Mon, 27 Mar 2006 18:25:33 +0000 Subject: [PATCH] Add documentation for GBookmarkFile to GLib's reference guide. 2006-03-27 Emmanuele Bassi * 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. --- ChangeLog | 7 + ChangeLog.pre-2-12 | 7 + docs/reference/glib/glib-docs.sgml | 2 + docs/reference/glib/glib-sections.txt | 54 ++ docs/reference/glib/tmpl/bookmarkfile.sgml | 551 +++++++++++++++++++++ 5 files changed, 621 insertions(+) create mode 100644 docs/reference/glib/tmpl/bookmarkfile.sgml diff --git a/ChangeLog b/ChangeLog index 6effaac0..66b330d7 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,10 @@ +2006-03-27 Emmanuele Bassi + + * 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 * glib/glib.h: diff --git a/ChangeLog.pre-2-12 b/ChangeLog.pre-2-12 index 6effaac0..66b330d7 100644 --- a/ChangeLog.pre-2-12 +++ b/ChangeLog.pre-2-12 @@ -1,3 +1,10 @@ +2006-03-27 Emmanuele Bassi + + * 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 * glib/glib.h: diff --git a/docs/reference/glib/glib-docs.sgml b/docs/reference/glib/glib-docs.sgml index d6d50c37..02801d1f 100644 --- a/docs/reference/glib/glib-docs.sgml +++ b/docs/reference/glib/glib-docs.sgml @@ -57,6 +57,7 @@ + @@ -149,6 +150,7 @@ synchronize their operation. &glib-Pattern-Matching; &glib-Markup; &glib-Keyfile; + &glib-Bookmarkfile; &glib-Windows-Compatibility-Functions; diff --git a/docs/reference/glib/glib-sections.txt b/docs/reference/glib/glib-sections.txt index 0def2c67..15b1e5b5 100644 --- a/docs/reference/glib/glib-sections.txt +++ b/docs/reference/glib/glib-sections.txt @@ -1489,6 +1489,60 @@ g_key_file_remove_comment g_key_file_error_quark +
+Bookmark file parser +bookmarkfile +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 + + +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 + + +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 + + +g_bookmark_file_error_quark +
+
Dynamic Loading of Modules modules diff --git a/docs/reference/glib/tmpl/bookmarkfile.sgml b/docs/reference/glib/tmpl/bookmarkfile.sgml new file mode 100644 index 00000000..2f6a987f --- /dev/null +++ b/docs/reference/glib/tmpl/bookmarkfile.sgml @@ -0,0 +1,551 @@ + +Bookmark file parser + + +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 +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 xbel root element; +each bookmark is stored inside a 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 metadata element, with its owner +attribute set to 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. + + + + + + + + Desktop Bookmarks Spec + + + text/xml + + + + + + Editors + + + + + +]]> + + + +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. + + + + + + + + + + + + +The GBookmarkFile struct contains only private data +and should not be used directly. + + + + + +Error domain for bookmark file parsing. Errors in this domain will be +from the #GBookmarkFileError enumeration. See #GError for informations +on error domains. + + + + + + +Error codes returned by bookmark file parsing. + + +@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 + + + + + + +@Returns: + + + + + + + +@bookmark: + + + + + + + +@bookmark: +@filename: +@error: +@Returns: + + + + + + + +@bookmark: +@data: +@length: +@error: +@Returns: + + + + + + + +@bookmark: +@file: +@full_path: +@error: +@Returns: + + + + + + + +@bookmark: +@length: +@error: +@Returns: + + + + + + + +@bookmark: +@filename: +@error: +@Returns: + + + + + + + +@bookmark: +@uri: +@Returns: + + + + + + + +@bookmark: +@uri: +@group: +@error: +@Returns: + + + + + + + +@bookmark: +@uri: +@name: +@error: +@Returns: + + + + + + + +@bookmark: +@Returns: + + + + + + + +@bookmark: +@length: +@Returns: + + + + + + + +@bookmark: +@uri: +@error: +@Returns: + + + + + + + +@bookmark: +@uri: +@error: +@Returns: + + + + + + + +@bookmark: +@uri: +@error: +@Returns: + + + + + + + +@bookmark: +@uri: +@error: +@Returns: + + + + + + + +@bookmark: +@uri: +@href: +@mime_type: +@error: +@Returns: + + + + + + + +@bookmark: +@uri: +@error: +@Returns: + + + + + + + +@bookmark: +@uri: +@error: +@Returns: + + + + + + + +@bookmark: +@uri: +@error: +@Returns: + + + + + + + +@bookmark: +@uri: +@length: +@error: +@Returns: + + + + + + + +@bookmark: +@uri: +@length: +@error: +@Returns: + + + + + + + +@bookmark: +@uri: +@name: +@exec: +@count: +@stamp: +@error: +@Returns: + + + + + + + +@bookmark: +@uri: +@title: + + + + + + + +@bookmark: +@uri: +@description: + + + + + + + +@bookmark: +@uri: +@mime_type: + + + + + + + +@bookmark: +@uri: +@is_private: + + + + + + + +@bookmark: +@uri: +@href: +@mime_type: + + + + + + + +@bookmark: +@uri: +@added: + + + + + + + +@bookmark: +@uri: +@groups: +@length: + + + + + + + +@bookmark: +@uri: +@modified: + + + + + + + +@bookmark: +@uri: +@visited: + + + + + + + +@bookmark: +@uri: +@name: +@exec: +@count: +@stamp: +@error: +@Returns: + + + + + + + +@bookmark: +@uri: +@group: + + + + + + + +@bookmark: +@uri: +@name: +@exec: + + + + + + + +@bookmark: +@uri: +@group: +@error: +@Returns: + + + + + + + +@bookmark: +@uri: +@name: +@error: +@Returns: + + + + + + + +@bookmark: +@uri: +@error: + + + + + + + +@bookmark: +@old_uri: +@new_uri: +@error: +@Returns: + + -- 2.34.1