From 41d01202368d5296da77cda72a0f18f3590e9ca9 Mon Sep 17 00:00:00 2001 From: Mikhail Ramendik Date: Sun, 2 Feb 2014 10:47:52 +0100 Subject: Style review of the language in the trash spec --- trash/trashspec.html | 173 ++++++++++++++++++++++++++------------------------- 1 file changed, 87 insertions(+), 86 deletions(-) diff --git a/trash/trashspec.html b/trash/trashspec.html index 81c4954..fa270d3 100644 --- a/trash/trashspec.html +++ b/trash/trashspec.html @@ -49,17 +49,17 @@ 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 +existed before this specification — 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.

+For example, both Gnome and KDE had 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 +can implementations must 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, +

This ability 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 +used on the same machine at different moments (for example, 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 @@ -98,7 +98,7 @@ trash) had prior to getting trashed.

Top directory , $topdir — the directory where a file system is mounted. “/” is the top directory for the root file system, but not for the other mounted file systems. For example, -separate FSes can be mounted on “/home”, “/mnt/flash”, +separate file systems might be mounted on “/home”, “/media/flash”, etc. In this text, the designation “$topdir” is used for “any top directory”.

User identifier , $uid — the numeric user identifier for a @@ -122,14 +122,14 @@ in this document are to be interpreted as described in 2 -a “home trash” directory MUST be available3. -Its name and location are $XDG_DATA_HOME/Trash ; $XDG_DATA_HOME is +a “home trash” directory MUST be available. +Its name and location are $XDG_DATA_HOME/Trash 3; $XDG_DATA_HOME is the base directory for user-specific data, as defined in the Desktop Base Directory Specification .

-

The “home trash” should function as the user's main +

The “home trash” SHOULD function as the user's main trash directory. Files that the user trashes from the same file -system (device/partition) should be stored here (see the next section +system (device/partition) SHOULD be stored here (see the next section for the storage details). A “home trash” directory SHOULD be automatically created for any new user. If this directory is needed for a trashing operation but does not exist, the @@ -146,10 +146,10 @@ security issues arise.

partitions, over the network, from a removable device, etc.) A delay instead of a quick “delete” operation can be unpleasant to users.

-

An implementation may choose not to support trashing in some of +

An implementation MAY choose not to support trashing in some of these cases (notably on network resources and removable devices). This is what some well known operating systems do.

-

It may also choose to provide trashing in the “top +

It MAY also choose to provide trashing in the “top directories” of some or all mounted resources. This trashing is done in two ways, described below as (1) and (2).

@@ -161,7 +161,7 @@ permissions must be set, if the file system supports it.

When trashing a file from a non-home partition/device4 , an implementation (if it supports trashing in top directories) MUST check for the presence of $topdir/.Trash.

-

When preparing a list of all trashed files (i.e. to show to the +

When preparing a list of all trashed files (for example, to show to the user), an implementation also MUST check for .Trash in all top directories that are known to it.

If this directory is present, the implementation MUST, by default, @@ -174,7 +174,7 @@ this directory is not a symbolic link.

If any of these checks fail, the implementation MUST NOT use this directory for either trashing or -undeleting files, even is an appropriate $uid directory (see below) +undeleting files, even if an appropriate $uid directory (see below) already exists in it. Besides, the implementation SHOULD report the failed check to the administrator, and MAY also report it to the user.

@@ -206,30 +206,30 @@ immediately create it, without any warnings or delays for the user.

Notes. If an implementation provides trashing in top directories at all, it MUST support both (1) and (2).

-

If an implementation does NOT provide such trashing, and does +

If an implementation does NOT provide trashing in top directories, and does provide the user with some interface to view and/or undelete trashed files, it SHOULD make a “best effort” to show files trashed in top directories (by both methods) to the user, among other trashed files or in a clearly accessible separate way.

When trashing a file, if the method (1) fails at any point — -i.e. the $topdir/.Trash directory does not exist, or it fails the +that is, the $topdir/.Trash directory does not exist, or it fails the checks, or the system refuses to create an $uid directory in it — the implementation MUST, by default, fall back to method (2), described below. Except for the case when $topdir/.Trash fails the checks, the fallback must be immediate, without any warnings or -delays. The implementation MAY, however, a way for the administrator +delays. The implementation MAY, however, provide a way for the administrator to disable (2) completely.

-

If both (1) and (2) fail (i.e. no +

If both (1) and (2) fail (that is, no $topdir/.Trash directory exists, and an attempt to create $topdir/.Trash-$uid fails), the implementation MUST either trash the file into the user's “home trash” or refuse to trash it. The choice between these options can be pre-determined, or it can -depend on the particular situation (i.e. No trashing of very large -files). However, if an implementation refuses to trash a file after a +depend on the particular situation (for example, “no trashing of very large +files”). However, if an implementation refuses to trash a file after a user action that generally causes trashing, it MUST clearly warn the -user about this, and request confirmation for the action.

+user that the trashing has failed. It MUST NOT erase the file without user confirmation.

For showing trashed files, implementations SHOULD support (1) and -(2) at the same time (i.e. if both $topdir/.Trash/$uid and +(2) at the same time (that is, if both $topdir/.Trash/$uid and $topdir/.Trash-$uid are present, it should list trashed files from both of them).

Contents of a trash directory

@@ -277,15 +277,15 @@ key/value pairs as described in the Desktop Entry Specification:

absolute pathname (starting with the slash character “/”) or a relative pathname (starting with any other character). A relative pathname is to be from the directory in which the trash - directory resides (i.e., from $XDG_DATA_HOME for the “home + directory resides (for example, from $XDG_DATA_HOME for the “home trash” directory); it MUST not include a “..” directory, and for files not “under” that directory, - absolute pathnames must be used. The system SHOULD only support - absolute pathnames in the “home trash” directory, not in + absolute pathnames must be used. The system SHOULD support + absolute pathnames only in the “home trash” directory, not in the directories under $topdir.

The value type for this key is - “string”; it should store the file name as the + “string”; it SHOULD store the file name as the sequence of bytes produced by the file system, with characters escaped as in URLs (as defined by RFC 2396, section 2).

@@ -312,55 +312,14 @@ directories within the directory MUST NOT be altered; the implementation also SHOULD preserve the access and modification time for them.

When trashing a file or directory, the implementation MUST create -the corresponding file in $trash/info first. When trashing a file or -directory, the implementation MUST create thecorresponding file in -$trash/info first. Moreover, it MUST try to do this in an atomic -fashion, so that if two processes try trash files with the same +the corresponding file in $trash/info first. Moreover, it MUST try to do this in an atomic +fashion, so that if two processes try to trash files with the same filename this will result in two different trash files. On Unix-line systems this is done by generating a filename, and then opening with O_EXCL. If that succeeds the creation was atomic (at least on the same machine), if it fails you need to pick another filename.

-

Implementation notes

-

The names of the files/directories in $trash/info SHOULD be -somehow related to original file names. This can help manual recovery -in emergency cases (for example, if the corresponding info file is -lost).

-

When trashing a file or directory, the implementation should check -whether the user has the necessary permissions to delete it, before -starting the trashing operation itself.

-

When copying, rather than moving, a file into the trash (i.e. When -trashing to the “home trash” from a different partition), -exact preservation of permissions might be impossible. Notably, a -file.directory that was owned by another user will now be owned by -this user (changing owners is usually only available to root). This -should not cause the trashing operation to fail.

-

In this same situation, setting the permissions should be done -after writing the copied file, as they may make it -unwriteable..

-

A trashing operation might be refused because of insufficient -permissions, even when the user does have the right to delete a file -or directory. This may happen when the user has the right to delete a -file/directory, but not to read it (or, in the case of a directory, -to list it). In this case, the best solution is probably to warn the -user, offering options to delete the file/directory or leave it -alone.

-

Automatic trash cleaning may, and probably eventually should, be -implemented. But the implementation should be somehow known to the -user.

-

If a directory was trashed in its entirety, it is easiest to -undelete it or remove it from the trash only in its entirety as well, -not as separate files. The user might not have the permissions to -delete some files in it even while he does have the permission to -delete the directory!

-

Important note on scope. This specification currently does -NOT define trashing on remote machines where multiuser permissions -are implemented but the numeric user ID is not supported, like FTP -sites and CIFS shares. In systems implementing this specification, -trashing of files from such machines is to be done only to the user's -home trash directory (if at all). A future version may address this -limitation.

Directory size cache

-

In order to speed up the calculation of the total size of a given trash directory, +

In order to speed up the calculation of the total size of a particular trash directory, implementations (since version 1.0 of this specification) SHOULD create or update the $trash/directorysizes file, which is a cache of the sizes of the directories that were trashed into this trash directory. @@ -368,10 +327,10 @@ Individual trashed files are not present in this cache, since their size can be with a call to stat().

Each entry contains the name and size of the trashed directory, as well as the modification time of the corresponding trashinfo file (IMPORTANT: not the modification time of the directory itself)9.

-

The size is calculated to be the disk space used by the directory and its -contents, i.e. the size of the blocks, in bytes (like `du -B1` would calculate).

-

The modification time is stored as an integer, the number of seconds since Epoch. Implementations should use at least 64 bits for this number in memory.

-

The format of the “directorysizes” file is a simple text-based format, where each line is:

+

The size is calculated as the disk space used by the directory and its +contents, that is, the size of the blocks, in bytes (in the same way as the `du -B1` command calculates).

+

The modification time is stored as an integer, the number of seconds since Epoch. Implementations SHOULD use at least 64 bits for this number in memory.

+

The “directorysizes” file has a simple text-based format, where each line is:

 [size] [mtime] [percent-encoded-directory-name]
@@ -384,19 +343,19 @@ contents, i.e. the size of the blocks, in bytes (like `du -B1` would calculate). sequence of bytes produced by the file system, with characters escaped as in URLs (as defined by RFC 2396, section 2). Strictly speaking, percent-encoding is really only necessary for the newline character and for '%' itself. -Encoding all control characters or fully applying RFC 2396 for consistency with trashinfo files -is perfectly valid, however.

+However, encoding all control characters or fully applying RFC 2396 for consistency with trashinfo files +is perfectly valid, and even if an implementation does not use such encoding. it MUST be able to read names encoded with it.

The character '/' is not allowed in the directory name (even as %2F), since all these -directories must be direct children of the "files" directory, and absolute paths are not allowed.

-

Implementations MUST use a temporary file followed by an atomic rename() operation in order +directories must be direct children of the "files" directory. Absolute paths are not allowed for the same reason.

+

To update the directorysizes file, implementations MUST use a temporary file followed by an atomic rename() operation, in order to avoid corruption due to two implementations writing to the file at the same time. The fact -that the changes from one of the writers could get lost isn't an issue, the cache can be updated again +that the changes from one of the writers could get lost isn't an issue, as the cache can be updated again later on to add that entry.

Non-normative: suggested algorithm for calculating the size of a trash directory

-load directorysizes file into memory, e.g. a hash directory_name -> (size, mtime, seen=false)
+load directorysizes file into memory as a hash directory_name -> (size, mtime, seen=false)
 totalsize = 0
 list "files" directory, and for each item:
     stat the item
@@ -417,9 +376,52 @@ remove entries from hash which have (seen == false)
 write out hash back to directorysizes file
+ +

Implementation notes

+

The names of the files/directories in $trash/info SHOULD be +somehow related to original file names. This can help manual recovery +in emergency cases (for example, if the corresponding info file is +lost).

+

When trashing a file or directory, the implementation SHOULD check +whether the user has the necessary permissions to delete it, before +starting the trashing operation itself.

+

When copying, rather than moving, a file into the trash (when +trashing to the “home trash” from a different partition), +exact preservation of permissions might be impossible. Notably, a +file/directory that was owned by another user will now be owned by +this user (changing owners is usually only available to root). This +SHOULD NOT cause the trashing operation to fail.

+

In this same situation, setting the permissions should be done +after writing the copied file, as they might make it +unwriteable..

+

A trashing operation might be refused because of insufficient +permissions, even when the user does have the right to delete a file +or directory. This may happen when the user has the right to delete a +file/directory, but not to read it (or, in the case of a directory, +to list it). In this case, the best solution is probably to warn the +user, offering options to delete the file/directory or leave it +alone. As noted earlier, when the user reasonably expects a file to be +trashed, the implementation MUST NOT delete it without warning the user. +

+

Automatic trash cleaning may, and probably eventually should, be +implemented. But the implementation should be somehow known to the +user.

+

If a directory was trashed in its entirety, it is easiest to +undelete it or remove it from the trash only in its entirety as well, +not as separate files. The user might not have the permissions to +delete some files in it even while he does have the permission to +delete the directory!

+

Important note on scope. This specification currently does +NOT define trashing on remote machines where multiuser permissions +are implemented but the numeric user ID is not supported, like FTP +sites and CIFS shares. In systems implementing this specification, +trashing of files from such machines is to be done only to the user's +home trash directory (if at all). A future version may address this +limitation.

+

Administrativia

Copyright and License

-

Copyright (C) 2004 Mikhail Ramendik , mr@ramendik.ru +

Copyright (C) 2004-2014 Mikhail Ramendik , mr@ramendik.ru .

The originators of the ideas that are described here did not @@ -456,7 +458,7 @@ document on the freedesktop.org standards page

0.7 April 12, 2005. Added URL-style encoding for the name of the deleted file, as implemented in KDE 3.4

0.8 March 14, 2012. Update David Faure's email address, fix permanent URL for this spec.

-

1.0 April 16, 2013. Add directorysizes cache.

+

1.0 January 2, 2014. Add directorysizes cache; style review.



@@ -474,9 +476,8 @@ as implemented in KDE 3.4

-

3Note - the dot in the beginning, and for case sensitive file systems, note - the case.

+

3For + case sensitive file systems, note the case.

4To @@ -497,7 +498,7 @@ as implemented in KDE 3.4

7For example, if the file in $trash/files is named foo.bar , the - corresponding file in $trash/info must be named foo.bar.trashinfo

+ corresponding file in $trash/info MUST be named foo.bar.trashinfo

8This -- cgit v1.2.3-54-g00ecf