summaryrefslogtreecommitdiffstats
path: root/recent-files
diff options
context:
space:
mode:
Diffstat (limited to 'recent-files')
-rw-r--r--recent-files/recent-file-spec.xml156
1 files changed, 156 insertions, 0 deletions
diff --git a/recent-files/recent-file-spec.xml b/recent-files/recent-file-spec.xml
new file mode 100644
index 0000000..b473de8
--- /dev/null
+++ b/recent-files/recent-file-spec.xml
@@ -0,0 +1,156 @@
+<?xml version="1.0"?>
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
+]>
+<article id="index">
+ <articleinfo>
+ <title>Recent File Storage Specification</title>
+ <releaseinfo>Version 0.2</releaseinfo>
+ <date>12 August 2002</date>
+ <authorgroup>
+ <author>
+ <firstname>James</firstname>
+ <surname>Willcox</surname>
+ <affiliation>
+ <address>
+ <email>jwillcox@gnome.org</email>
+ </address>
+ </affiliation>
+ </author>
+ </authorgroup>
+ </articleinfo>
+
+ <sect1 id="overview">
+ <title>Overview</title>
+ <para>
+ Many applications choose to have a menu containing a list of recently
+ used files, which can be used as an alternative to opening a file
+ selector. GNOME, and KDE applications have done this for quite some
+ time, and probably others have as well.
+ This specification aims to do the following things:
+ </para>
+ <itemizedlist mark="bullet">
+ <listitem>
+ <para>Provide a standard mechanism for storing a list of recently used
+ files (really, URIs)</para>
+ </listitem>
+ <listitem>
+ <para>Allow for notification of changes in the list</para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ Accomplishing this will make using applications that are not native
+ to the user's desktop a bit nicer, and give a more unified feel to
+ the X desktop in general. It will be especially useful to applications
+ that don't belong to a specific desktop at all, such as Mozilla and
+ Open Office,
+ since those applications could become compatible with all desktops
+ in this area without special case considerations for each one.
+ </para>
+ </sect1>
+
+ <sect1 id="storage">
+ <title>Storage</title>
+ <para>
+ For different desktops and applications to have access to the same
+ information, a protocol for storing the recent file list has to be
+ determined. An XML document will be used, of the form below:
+ </para>
+ <programlisting><![CDATA[
+<?xml version="1.0"?>
+<RecentFiles>
+ <RecentItem>
+ <URI>file:///home/jwillcox/testfile.txt</URI>
+ <Mime-Type>text/plain</Mime-Type>
+ <Timestamp>1028181153</Timestamp>
+ <Private/>
+ <Groups>
+ <Group>Recent File Test</Group>
+ </Groups>
+ </RecentItem>
+ <RecentItem>
+ <URI>file:///home/jwillcox/recent-file-spec.xml</URI>
+ <Mime-Type>text/xml</Mime-Type>
+ <Timestamp>1028181158</Timestamp>
+ <Private/>
+ <Groups>
+ <Group>Recent File Test</Group>
+ </Groups>
+ </RecentItem>
+</RecentFiles>
+ ]]></programlisting>
+ <para>
+ The URI, Mime-Type, Timestamp tags are required, but the
+ Private, Groups, and Group tags are not. The Timestamp tag should be
+ the number of
+ seconds sinced the Epoch when the item was added to the list.
+ The Group tags exist for the purpose of
+ making groups of items with an arbitrary set of MIME types. A single item
+ can belong to an unlimited number of groups. If the Private tag is
+ specified, it means that implementations should only include the item if
+ requestor has specifically asked for items in a group that the item
+ belongs to. For instance, maybe a file selector would like to hold a list
+ of directories that you have recently saved files in, and allow you to
+ choose from one of these next time you save a file. You wouldn't want
+ those directories showing up in the "Recent Documents" menu. If the items
+ are put into the "File Selector Save Directories" group and marked as
+ private, this problem is solved.
+ </para>
+ <para>
+ All text in the file should be stored in the UTF-8 encoding.
+ No local paths are allowed in the URI tag. They should be converted to a
+ valid
+ <ulink url="http://www.ietf.org/rfc/rfc2396.txt">URI</ulink>
+ with a "file" scheme. Items with the
+ same URI should not be allowed. If a duplicate is found, it should have
+ its timestamp updated, and any new groups added to it. No other
+ information should be changed. The document should be stored in
+ "~/.recently-used", and it should contain no more than 500 items.
+ </para>
+ <para>
+ Before reading or writing the document, it should be locked using the
+ POSIX lockf() mechanism, and unlocked when finished.
+ </para>
+ </sect1>
+
+ <sect1 id="notification">
+ <title>Notification</title>
+ <para>
+ Notification should be accomplished by simply monitoring the document for
+ changes. This can be done by either polling the file every so often,
+ or using a library like
+ <ulink url="http://oss.sgi.com/projects/fam/">FAM</ulink>.
+ </para>
+ </sect1>
+
+ <appendix id="changes">
+ <title>Change history</title>
+ <formalpara>
+ <title>Version 0.2, 12 August 2002, James Willcox</title>
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Switched from flat-file storage to XML. This was done to
+ facilitate easier storage of meta-data. Files can now belong
+ to "groups", and the timestamp is now a required piece of
+ meta-data.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </formalpara>
+ <formalpara>
+ <title>Version 0.1, 8 July 2002, James Willcox</title>
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Created initial draft.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </formalpara>
+ </appendix>
+</article>