luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2025-01-12 15:36:17 +01:00
Code Issues Packages Projects Releases Wiki Activity

docs: Move bookmarkfile SECTION

Browse Source 
Move the content to the struct docs.

Helps: #3037
This commit is contained in:
Matthias Clasen 2023-09-25 07:39:37 -04:00 committed by Philip Withnall
parent d028759903
commit 7fd50be9d0
2 changed files with 39 additions and 46 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

45
glib/gbookmarkfile.c
View File

@ -52,51 +52,6 @@
#include "gutils.h"
/**
* SECTION:gbookmarkfile
* @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
* [Desktop Bookmark Specification](http://www.gnome.org/~ebassi/bookmark-spec).
*
* 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.
*
* Here is an example of a bookmark file:
* [bookmarks.xbel](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/glib/tests/bookmarks.xbel)
*
* 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_application_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"

40
glib/gbookmarkfile.h
View File

@ -75,7 +75,45 @@ GQuark g_bookmark_file_error_quark (void);
/**
* GBookmarkFile:
*
* An opaque data structure representing a set of bookmarks.
* `GBookmarkFile` lets you parse, edit or create files containing bookmarks.
*
* Bookmarks refer to a 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](http://www.gnome.org/~ebassi/bookmark-spec).
*
* 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.
*
* Here is an example of a bookmark file:
* [bookmarks.xbel](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/glib/tests/bookmarks.xbel)
*
* 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
* [method@GLib.BookmarkFile.add_application] or [method@GLib.BookmarkFile.set_application_info].
* If a bookmark has no applications then it won't be dumped when creating
* the on disk representation, using [method@GLib.BookmarkFile.to_data] or
* [method@GLib.BookmarkFile.to_file].
*
* Since: 2.12
*/
typedef struct _GBookmarkFile GBookmarkFile;