From 436a9ecab8d76ceb86688e100a2a37852f538407 Mon Sep 17 00:00:00 2001 From: David Faure Date: Wed, 14 Mar 2012 15:37:35 +0100 Subject: trash: Import version 0.2 of the trash spec. --- trash/trashspec.html | 196 ++++++++++++++++++++++++++------------------------- 1 file changed, 100 insertions(+), 96 deletions(-) (limited to 'trash') diff --git a/trash/trashspec.html b/trash/trashspec.html index b2ad642..ac6d18f 100644 --- a/trash/trashspec.html +++ b/trash/trashspec.html @@ -1,7 +1,7 @@ - + Trash specification @@ -14,68 +14,70 @@

The FreeDesktop.org Trash specification

By Mikhail Ramendik <mr@ramendik.ru>

Version 0.1 “First Try”

Based on network discussion by David Faure -<dfaure@trolltech.com>, +

Written by Mikhail Ramendik <mr@ramendik.ru>

Content by David Faure <dfaure@trolltech.com>, Alexander Larsson <alexl@redhat.com> -and others on the FreeDesktop.org mailing list.

Overview

An ability to recover accidentally deleted files has -become the de facto standard for today's desktop user experience. -

Users do not expect that anything they delete is -permanently gone. Instead, they are used to a “Trash can” -metaphor. A deleted document ends up in a “Trash can”, -and stays there at least for some time – until the can is -manually or automatically cleaned. -

This system has its own problems. Notably, cleaning -disk space becomes a two-step operation – delete files and -empty trash; this can lead to confusion for inexperienced users -(“what's taking up my space?!”). Also, it is not easy to -adapt the system to a multiuser environment. Besides, there is a -potential for abuse by uneducated users – anecdotal evidence -says they sometimes store important documents in the Trash can, and -lose them when it gets cleaned!

However, the benefits of this system are so great, -and the user expectation for it so high, that it definitely should be -implemented on a free desktop system. And in fact, several -implementations already exist – some as command line utilities, -some as preloaded libraries, and some as parts of major desktop -environments. For example, both Gnome and KDE have their own trash -mechanisms.

The purpose of this Specification is to provide a -common way in which all Trash can implementation should store, list, +and others on the FreeDesktop.org mailing list +

Version 0.2 +

Abstract

The purpose of this Specification is to provide a common way in +which all “Trash can” implementations should store, list, and undelete trashed files. By complying with this Specification, various Trash implementations will be able to work with the same devices and use the same Trash storage. For example, if one implementation sends a file into the Trash can, another will be able to list it, undelete it, or clear it from the Trash.

This is important, at least, for shared network -resources, removable devices, and in cases when different -implementations are used on the same machine at different moments -(i.e. some users prefer Gnome, others prefer KDE, and yet others are -command-line fans).

Introduction

An ability to recover accidentally deleted files has become the de +facto standard for today's desktop user experience. +

Users do not expect that anything they delete is permanently gone. +Instead, they are used to a “Trash can” metaphor. A +deleted document ends up in a “Trash can”, and stays +there at least for some time – until the can is manually or +automatically cleaned. +

This system has its own problems. Notably, cleaning disk space +becomes a two-step operation – delete files and empty trash; +this can lead to confusion for inexperienced users (“what's +taking up my space?!”). Also, it is not easy to adapt the +system to a multiuser environment. Besides, there is a potential for +abuse by uneducated users – anecdotal evidence says they +sometimes store important documents in the Trash can, and lose them +when it gets cleaned!

However, the benefits of this system are so great, and the user +expectation for it so high, that it definitely should be implemented +on a free desktop system. And in fact, several implementations +already exist – some as command line utilities, some as +preloaded libraries, and some as parts of major desktop environments. +For example, both Gnome and KDE have their own trash mechanisms.

This Specification is to provide a common way in which all Trash +can implementations should store trashed files. By complying with +this Specification, various Trash implementations will be able to +work with the same devices and use the same Trash storage. +

This is important, at least, for shared network resources, +removable devices, and in cases when different implementations are +used on the same machine at different moments (i.e. some users prefer +Gnome, others prefer KDE, and yet others are command-line fans).

Scope and limitations

This Specification only describes the Trash storage. -It does not limit the ways in which the actual implementations -should operate, as long as they use the same Trash storage. Command -line utilities, desktop-integrated solutions and preloaded libraries -can work with this specification. ¹

This Specification is -geared towards the Unix file system tree approach. However, with -slight modifications, it can easily be used with another kind of file -system tree (for example, with drive letters). +

This Specification only describes the Trash storage. It does not +limit the ways in which the actual implementations should operate, as +long as they use the same Trash storage. Command line utilities, +desktop-integrated solutions and preloaded libraries can work with +this specification. ¹

This Specification is geared towards the Unix file system tree +approach. However, with slight modifications, it can easily be used +with another kind of file system tree (for example, with drive +letters).

A multi-user environment, -where users have specific alphanumeric names, is essential for this -Specification. +

A multi-user environment, where users have specific alphanumeric +names, is essential for this Specification.

File systems and logon -systems can be case-sensitive or non-case-sensitive; therefore, -systems should generally not allow user names that differ only in -case.

File systems and logon systems can be +case-sensitive or non-case-sensitive; therefore, systems should +generally not allow user names that differ only in case.

Definitions

Trash, or Trash can – the storage of files that were trashed (“deleted”) by the user. These files can be listed, @@ -109,13 +111,11 @@ trashing, are stored. There may be several trash directories on one system; this Specification defines their location and contents. In this text, the designation “$trash” is used for “any trash directory”.

MUST – an -implementation has to do this in order to be in compliance with this -Specification.

SHOULD – doing this -is recommended, but not required.

MAY – doing this is -optional.

The key words "MUST", "MUST NOT", "REQUIRED", +"SHALL", "SHALL NOT", "SHOULD", "SHOULD +NOT", "RECOMMENDED", "MAY", and "OPTIONAL" +in this document are to be interpreted as described in RFC +2119.

Trash directories

A system can have one or more trash directories. The contents of any trash directory are to be compliant with the same standard, @@ -123,8 +123,9 @@ described below.

For every user² a $HOME/.Trash directory MUST be available³. It should function as the user's Trash directory. Files that the user -trashes from the home directory should be stored here (see the next -section for the storage details). $HOME/.Trash SHOULD be +trashes from the home directory, and from other directories on the +same file system (device/partition), should be stored here (see the +next section for the storage details). $HOME/.Trash SHOULD be automatically created for new user. If this directory is needed for a trashing operation but does not exist, the implementation SHOULD automatically create it, without any warnings or delays.

@@ -145,27 +146,24 @@ This is what some well known operating systems do.

directories of some mounted file systems. How these directories are created (by the system administrator, a daemon, etc.) is determined by the implementation.

Such .Trash directories are not -in themselves trash storage directories; this would break multi-user -support. Instead, an $topdir/.Trash directory can contain any number -of subdirectories, named for users that perform trashing operations; -i.e. $topdir/.Trash/user . Each of these is a trash storage +

Such .Trash directories are not in themselves trash storage +directories; this would break multi-user support. Instead, an +$topdir/.Trash directory can contain any number of subdirectories, +named for users that perform trashing operations; i.e. +$topdir/.Trash/user . Each of these is a trash storage directory, containing the files trashed by this user. (See the next section for the storage details).

Note that an -implementation MAY choose to support or not support trashing into -$topdir/.Trash/user. If it does support it, it SHOULD make it a -configuration option, so that the administrator can disable it for -any or all mount points for security reasons (and use $HOME/.Trash or -no trashing at all).

However, if a -.Trash directory does exist in any top directory, an implementation -MUST be able to list and undelete files that are in the current -user's subdirectory within it.

The use of -$topdir/$Trash can lead to some peculiar issues. These are discussed -in the “Implementation notes” section, at the end of -this document.

Note that an implementation MAY choose to support or not support +trashing into $topdir/.Trash/user. If it does support it, it SHOULD +make it a configuration option, so that the administrator can disable +it for any or all mount points for security reasons (and use +$HOME/.Trash or no trashing at all).

However, if a .Trash directory does exist in any top directory, an +implementation MUST be able to list and undelete files that are in +the current user's subdirectory within it.

The use of $topdir/$Trash can lead to some peculiar issues. These +are discussed in the “Implementation notes” section, at +the end of this document.

Contents of a trash directory

The previous section has described the location of trash directories. This section concerns the contents of any trash @@ -173,9 +171,9 @@ directory (including $HOME/.Trash). This trash directory will be named “$trash” here.

A trash directory contains two subdirectories, named info and files.

The $trash/files directory -contains the files and directories that were trashed. When a file or -directory is trashed, it MUST be moved into this directory⁴ +

The $trash/files directory contains the files and +directories that were trashed. When a file or directory is trashed, +it MUST be moved into this directory⁴ . The names of files in this directory are to be determined by the implementation; the only limitation is that they must be unique within the directory. Even if a file with the same name and @@ -187,15 +185,16 @@ same as the file/directory had before getting trashed.

filenames in the $trash/files directory on the original filenames, this is never to be taken for granted⁵. A filename in the $trash/files directory MUST NEVER be used to -recover the original filename (except in an emergency case when -an info file has been lost; this case must be clearly marked to the -user as an emergency). +recover the original filename; use the info file (see below) for +that. (If an info file +corresponding to a file/directory in $trash/files is not available, +this is an emergency case, and MUST be clearly presented as such to +the user or to the system administrator).
-
The $trash/info directory -contains an “information file” for every file and -directory in $trash/files. This file MUST have exactly the same name -as the file or directory in $trash/files. The contents of this file -are:
+
The $trash/info directory contains an “information +file” for every file and directory in $trash/files. This file +MUST have exactly the same name as the file or directory in +$trash/files. The contents of this file are:

original_location\n trashing_time\n
Where:
@@ -242,21 +241,26 @@ the future.
will serve as evidence of prior art for any patent filed after this date.

License
-
Use as you wish. If you make a modified version and redistribute +
Use and disribute as you wish. If you make a modified version and redistribute it, (a) keep the name of the author and contributors somewhere, and (b) indicate that this is a modified version.
-
Redistribution and implementation under any license at all is +
Implementation under any license at all is explicitly allowed.

Location

http://www.ramendik.ru/docs/trashspec.html . If this document gets hosted by FreeDesktop.org, a link to the page will still be available at this location.
-
http://www.ramendik.ru/docs/trashspec.0.1.html +
http://www.ramendik.ru/docs/trashspec.0.2.html is the permanent location of this version.

Version history

0.1 “First try”, August 30, 2004. Initial draft. “Implementation notes” not written as yet.
+
0.2 August 30, 2004. Updated with feedback by Alexander Larsson +<alexl@redhat.com> and by +Dave Cridland <dave@cridland.net>
+

+

1However, developers of preloaded libraries should somehow work around the -- cgit v1.2.3-70-g09d2