########################################################
# TopShelf - a current files manager applet, using GTK #
########################################################


The goal of TopShelf is to help a typical user manage their 'currently important files'. Such a user may have at any one time only a few files which are currently important; for example, a school paper, an ebook, etc. These files will generally be opened at least once a day. Now, the 'recent documents' facility in GNOME and others DEs is somewhat useful in helping to access such files, since typically they would indeed be recently used. However, the recently used files list can be overridden by temporary files, say, documents the user receives and reads just once; music files, dozens of which can be listened to in a single day; etc. The user can get annoyed when a currently important file is bumped off of the recent files list. TopShelf provides a solution for this.

TopShelf lets the user manage the list of currently important files. The main difference with the recent files list is that the currently important files list is explicitly managed by the user: files are added and removed only by direct request. Thus, the recent files list and TopShelf provide separate functionality: TopShelf gives guaranteed access to files the user asked for, like the examples given before (a school paper, an ebook being read, etc.), whereas the recent files list tries to guess by itself which files will be requested in the future based on past access (for example, a music file listened to once would be on the recent files list but not TopShelf).


Running TopShelf
================

TopShelf is a panel applet. To run it, add it to a panel. That is, rightclick on a panel, select add to panel, and select TopShelf (should be in the 'accessories'). You can add it to a GNOME panel or an XFce panel; for Xfce, see

	http://goodies.xfce.org/projects/panel-plugins/xfce4-xfapplet-plugin

You can also run TopShelf standalone, simply do "python topshelf.py" (change the path to wherever you place the topshelf.py file, or see where the installer placed it with the 'locate' command). This is not recommended, in general, however.


Installation:
=============

Installing TopShelf from source should be as simple as "sudo make install" (or "make install" as superuser). There is no need to run "make" before.

Please file a bug if this doesn't work in your distro. TopShelf is developed and tested on Ubuntu, but is intended to work everywhere.

Dependencies: python-gnome2-desktop, python-gtk2 >= 2.12



Notes:
======

* Upgrading TopShelf: If you currently have TopShelf on your panel, and you upgrade it, not all changes will be implemented until you restart it. You can do so by either removing TopShelf and re-adding it (which will *not* discard your list of files or preferences), or by reloading the gnome panel, which is easiest to do by logging out and logging in.


CHANGELOG:
==========

0.1 (Rev. 18, Jan 12 2008):
---
	Basic functionality

0.2 (Rev. 36, Jan 16 2008):
---
	Ability to run standalone, i.e., not in a GNOME panel
	Show directories with nice mimetype
	Icons without transparency issues and other aesthetic matters
	Show missing files with red filenames (good for pluggable USB drives etc.)
	"Open containing folder" action
	Help docbook and tooltips for assistance
	No longer a popup window (can be resized normally)
	Keyboard actions: escape to close window, delete to remove a file
	"Are you sure?" on removal
	Rightclick menu for files

	0.2.1 (Rev. 39): Changes to let TopShelf work in Python 2.4 (the "x if c else y" is 2.5 only)

0.3 (Rev. 53, Jan 26 2008):
---
	* F5 to refresh list
	* Multifile actions: in main view, and in add dialog
	* Remember last directory in add dialog, and default to home directory if none
	* New icons, somewhat Tango-ized. These should now look ok with more themes
	* Transparency and scaling of icons


TODO:
=====

	* Allow opening files with other apps than the default that gnome-open uses



Random brainstorming for the far-off future:
============================================

	- Backup. A single-click backup of all the files in the current files list, giving a compressed file which can be saved.
	- View stats. Show the last time the file was modified.
	- Integration with versioning systems: let the current files be version-managed.

...but the goal is not to create an overly-complex app, but rather a simple one to fulfill a simple function.

