Table of Contents
Bookmarks are widely-used part of the World Wide Web browsers. They are a mechanism through which a user can return to specific sites already visited, much like their book counterparts.
Recently, bookmarks have become a feature for user with regards to browsing their file system, as a way to access recently used, or often used, places.
Even the list of recently used files can be seen as being composed of short-lived bookmarks.
This specification aims to do the following things:
Provide a standard mechanism for storing and accessing a list of bookmarks (in form of URI)
Provide per-application and per-task bookmarks
Replace the Recent Files Storage Specification, providing a single specification for both bookmarks and recent files
Applications implementing the following specification will have the ability to access all, or just a part of, the bookmarks, which will be stored in a system-wide fashion instead of re-implementing their bookmark system. This way, all the bookmarks associated to an application will be available to each instance of said application, and to other applications performing the same tasks. Also, a notification mechanism should be implemented so that every change inside the bookmarks should be propagated to each application using the bookmarks.
For different desktops and applications to have access to the same information, a protocol for storing the bookmarks list has to be determined.
A valid, UTF-8 encoded XML document will be used for storing the
desktop bookmarks. The storage format will conform to the
XBEL DTD
with custom meta-data; see the XBEL specification [XBEL] for the
contents of the bookmark, title,
desc and info elements used in
this specification.
A valid desktop bookmark stream must conform to the 1.0 version of
the XBEL Specification. The root element must be xbel,
with its attribute version set to "1.0". No
folder element should be used, as well as no
alias and separator elements; if
any of those elements are found, they should be ignored.
Each bookmark must have the bookmark element as root
node. The target URI of the bookmark must be stored in the
href attribute of the bookmark
element.
Each bookmark should have its attributes added,
modified and visited set with date
and time specified as a string conformant to the ISO 8601
specification [ISO8601] [DateTime]. The time should be relative to UTC
time; local time should be converted to UTC before encoding, and
converted back after reading the attribute payload.
The owner for all the meta-data elements defined in this specification
must be Freedesktop.Org. Thus, the owner attribute
of the meta-data element containing the following
elements must be set to http://freedesktop.org.
Other metadata, enclosed inside a metadata element
with another, or no owner, should be ignored.
All meta-data defined in this specification belongs to a namespace,
named bookmark whose URI is http://www.freedesktop.org/standards/desktop-bookmarks,
except for the mime-type element, whose namespace,
named mime,
must have this URI: http://www.freedesktop.org/standards/shared-mime-info.
Each metadata element might contain any combination
of the following elements, in any order:
The mime-type element is mandatory. It must
contain the MIME Type of the target pointed by the URI, as defined
by the Shared MIME Database [SharedMime].
The groups element contains a list of
group elements, each containing a group name.
See Appendix C, Registered Groups for more details on the
group names defined by this specification.
The groups element is not mandatory.
The applications section contains a list of
application elements, each referring to an
application that has registered the bookmark.
Each application element has a number of attributes:
| Attribute | Required | Value |
|---|---|---|
| name | Yes |
The name of the application that has registered the
bookmark. It must a unique name for each application.
Every application element must have
this attribute set.
|
| exec | Yes |
The preferred command line to be used when launching the
application; it might contain variables,
see Section 4.2.1, “List of valid exec attribute variables” for more details. If no
exec attribute has been provided,
implementors should use the application name followed by
the %u variable.
|
| count | Yes |
The number of times the application has registered the
bookmark. If not count attribute has
been defined, then implementors should assume that the
total number of registrations is equal to one.
|
| timestamp | Yes |
The last time, expresses in seconds from the system's Epoch,
the application registered the bookmark. Each application
element must have this attribute set.
|
See Section 4.2, “Applications” for the correct behaviour when handling duplicate application registrations.
The applications element is mandatory; every
bookmark must have at least one application
element.
The icon element, if present, specifies the
icon that should be associated to the bookmark. The
icon element must have the following attributes:
Implementers should use the file specified inside the
href of the icon element when
showing the bookmark.
The private element, if present, alters the
visibility of the bookmark. A bookmark should be considered
private to the groups where it belongs and to the applications
that have registered it. See Section 4.3, “Visibility”.
Desktop bookmarks file might contain a variable number of bookmarks. Each
bookmark file should contain at least one bookmark stored using the format
described previously. The default extension for the desktop bookmarks file
should be xbel. Implementors should not rely on these
files to contain bookmark entries sorted using any method, and should
therefore sort bookmarks using their own sorting methods. Implementors
should also take care of avoiding concurrent accesses to these files; for
instance, by using file locking techniques.
Standard locations for bookmark files defined in this specification are:
Application specific desktop bookmark files should be stored under the
$XDG_DATA_DIRS/desktop-bookmarks directory. Each
directory in the search path should be used. When two desktop bookmark
files have the same name, the one appearing earlier should be used. Only
files with the .xbel extension are used; other files
are ignored.
All text in the file should be stored in the UTF-8 encoding. Standard encoding rules for XML and XBEL documents applies the desktop bookmark files. No local paths are allowed in the URI tag; they should be converted to a valid URI [RFC-2396] with a "file" scheme. Items with the same URI are not allowed.
The meta-data associated to this spec will contain informations about the applications that have registered a bookmark, the groups to which a bookmark belongs and its visibility in relation to applications and groups.
Groups implement meta-classes of bookmarks. The bookmarks belonging to a group (or a set of groups) will be shared across each member of the group.
For instance, each email client application could register its bookmarks
under the group Mail, so that each other mail-related
application could access those bookmarks.
For a list of registered group names, see Appendix C, Registered Groups.
Bookmarks might be registered by more than one application. For each application registering a bookmark, will be stored the application's name, the application's command line, the number of registrations for the application and the last time the application registered a bookmark, the timestamp (seconds from the system's epoch) of the registration time.
If an application tries to register again a bookmark, that is: if there
already is an application tag with its
name attribute set to the same name passed by the
application, then the application tag should
have the content of the timestamp attribute updated,
and the content of the count attribute increased by
one.
Each exec parameter of the
application element may take a number
of arguments which will be expanded by the implementor.
Literal % characters must be escaped as
%%. Each unrecognised variable should be left
unexpanded.
Recognised variables are as follows:
| %f | the path of the file/directory, retrieved from the URI |
| %u | the literal URI for the bookmark |
Any implementor of this specification should conform to these recommendations:
Implementors should use the command line inside the
exec attribute of the
application element, when launching a bookmark
with a specific application. If no exec attribute
was found, implementors should try the application's name stored
inside the name attribute, followed by a space
character and the bookmark's URI. If this fails, the default
application for the bookmark's MIME type should be invoked using the
bookmark's URI.
No duplicate entries should be found inside a valid desktop bookmark
data stream. If two or more applications register a bookmark to the
same URI, implementors should update the modified
attribute of the bookmark element; a new
application element should be added for each
application that is registering the bookmark; if any of the
applications is also adding group names, all of these must be merged
with the previously set group names; the private
element should be set the first time an application requires it.
If the same application registers the same bookmark, only the
modified attribute of the
bookmark element; the
timestamp and count attributes
of the application element with the same
application's name set into the name attribute;
the private element should be modified.
If an icon for the bookmark item is shown, it should be taken from
the image file stored inside the href attribute
of the icon element; if no such element exists
inside the meta-data for the bookmark item, the icon should be
the thumbnail of the resource (if available), retrieved using the
thumbnail managing specification [Thumbnail], or - if no thumbnail is
present - the icon associated to the MIME type of the resource.
<?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">
<title>my Home</title>
<desc>ebassi's home</desc>
<info>
<metadata owner="http://freedesktop.org">
<mime:mime-type type="inode/directory"/>
<bookmark:applications>
<bookmark:application name="Nautilus"
count="4"
exec="nautilus --no-desktop %u"
timestamp="1115726763"/>
</bookmark:applications>
<bookmark:groups>
<bookmark:group>Desktop</bookmark:group>
</bookmark:group>
</metadata>
</info>
</bookmark>
<bookmark href="file:///home/ebassi/bookmark-spec/bookmark-spec.xml">
<title>Bookmarks Storage 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>
<bookmark href="http://www.emmanuelebassi.net/images/ebassi.png">
<title>ebassi.png</title>
<info>
<metadata owner="http://freedesktop.org">
<bookmark:applications>
<bookmark:application name="Gimp" exec="gimp %u" count="1" timestamp="1115716763"/>
<bookmark:application name="Eye of Gnome" exec="eog %u" count="1" timestamp="1115728763"/>
</bookmark:applications>
<mime:mime-type>image/png</mime:mime-type>
<bookmark:groups>
<bookmark:group>Graphics</bookmark:group>
</bookmark:groups>
<bookmark:private/>
</metadata>
</info>
</bookmark>
</xbel>
|
[SharedMime] The shared MIME-info database
[BaseDir] XDG Base Directory Specification
[MenuEntry] XDG Desktop Menu Specification
[FAM] File Alteration Monitor
[dnotify] dnotify, Linux kernel interface for file monitoring.
[inotify] inotify
[RFC-2119] Key words for use in RFCs to Indicate Requirement Levels
[RFC-2396] Uniform Resource Identifiers
[Thumbnail] Thumbnail Managing Standard
Remember, these are case-sensitive. When using a group name described in the list below it is strongly recommended to also include the group listed under Related Groups. If a group has multiple related groups the most suitable related group should be included.
| Group | Description | Related Groups |
|---|---|---|
| Development | A bookmark related to development | |
| Office | A bookmark related to an office type document or folder | |
| Database | A bookmark related to a database application | Office; Development |
| A bookmark related to an email application | Office | |
| Presentation | A bookmark related to a presentation application | Office |
| Spreadsheet | A bookmark related to a spreadsheet application | Office |
| WordProcessor | A bookmark related to a word processing application | Office |
| Graphics | A bookmark related to a graphical application | |
| TextEditor | A bookmark related to a text editor | |
| Viewer | A bookmark related to any kind of file viewer | |
| Archive | A bookmark related to an archive file | |
| Multimedia | A bookmark related to a multimedia file or application | |
| Audio | A bookmark related to an audio file or application | Multimedia |
| Video | A bookmark related to a video file or application | Multimedia |
| Photo | A bookmark related to a digital photography file or application | Multimedia; Graphics; Viewer |
| Application | Special bookmark for application launchers |
In order to properly install a new desktop bookmark file, third party applications should:
Install new desktop bookmark files inside
XDG_DATA_DIR
/desktop-bookmarks/ for each desktop bookmark file. Please, namespace
the filename, as in "vendor-foo.xbel", or use a subdirectory or
XDG_DATA_DIR
/desktop-bookmarks/ so you have "vendor/foo.xbel." Please ensure all
desktop bookmark entries are valid.
The latest version of this document will be available at this URI: http://devel.emmanuelebassi.net/papers/bookmark-spec.html.
This is the URI of this version of the document: http://devel.emmanuelebassi.net/papers/bookmark-spec-0.8.3.html.
Version 0.8.3, March 23, 2006, Emmanuele Bassi.
Some minor typo fixed.
Make the "count" and "timestamp" attributes of the "applicaton" element mandatory again
Version 0.8.2, December 18, 2005, Emmanuele Bassi.
Added the Application group for desktop launchers.
Version 0.8.1, November 15, 2005, Emmanuele Bassi.
Added the implementation recommendations for showing the icon of a bookmark item
Version 0.8, November 9, 2005, Emmanuele Bassi.
Added the icon element to the bookmark meta-data
Added more groups to the Registered Groups
Version 0.7, October 29, 2005, Emmanuele Bassi.
Added the desktop bookmark files section
Specified mandatory and optional storage elements
Added the registered groups appendix
Version 0.6, May 16, 2005, Emmanuele Bassi.
Reordered the sections layout.
Added the References appendix.
Added the Recommendations section.
Version 0.5, May 12, 2005, Emmanuele Bassi.
Logically separated the desktop bookmarks file and the recently used objects file.
Moved the bookmarks file under "$XDG_DATA_DIRS/desktop-bookmarks", as defined by the basedir specification.
Version 0.4, May 10, 2005, Emmanuele Bassi.
Moved to a XBEL compliant format.
Changed the "Bookmarks" group to "Desktop".
Version 0.3, May 6, 2005, Emmanuele Bassi.
Fixed the Visibility section and the Private tag description.
Added the Availability section.
Version 0.2, May 3, 2005, Emmanuele Bassi.
Expanded the Groups, Applications and Visibility sections.
Version 0.1, April 30, 2005, Emmanuele Bassi.
Created initial draft.