10 files changed, 582 insertions, 0 deletions
diff --git a/apps/shorty/doc/CHANGELOG b/apps/shorty/doc/CHANGELOG
new file mode 100644
index 00000000000..b1b09b50fb8
--- /dev/null
+++ b/apps/shorty/doc/CHANGELOG
@@ -0,0 +1,59 @@
+*****
+* @package shorty an ownCloud url shortener plugin
+* @category internet
+* @author Christian Reiner
+* @copyright 2011-2012 Christian Reiner <foss@christian-reiner.info>
+* @license GNU Affero General Public license (AGPL)
+* @link information
+* @link repository https://svn.christian-reiner.info/svn/app/oc/shorty
+*
+* This library is free software; you can redistribute it and/or
+* modify it under the terms of the GNU AFFERO GENERAL PUBLIC LICENSE
+* License as published by the Free Software Foundation; either
+* version 3 of the license, or any later version.
+*
+* This library is distributed in the hope that it will be useful,
+* but WITHOUT ANY WARRANTY; without even the implied warranty of
+* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+* GNU AFFERO GENERAL PUBLIC LICENSE for more details.
+*
+* You should have received a copy of the GNU Affero General Public
+* License along with this library.
+* If not, see <http://www.gnu.org/licenses/>.
+*****
+
+Changelog: 
+
+* Wed Jun 06 2012 Christian Reiner: version 0.2.2
+Added swallowing of accidential outputs during ajax requests.
+This protects the replies JSON struction from being corrupted.
+Additional server side log entries on level INFO
+* Sat Jun 02 2012 Christian Reiner: version 0.2.1
+Fixed broken Shortlet
+* Fri Jun 01 2012 Christian Reiner: version 0.2.0
+Support of ownCloud version 4 (app interface incompatible to prior versions)
+Additional status 'private' for Shortys only accessible for the owner himself
+Rudimentary SMS support for smart phones (more an assistance, can be disabled)
+Additional QRCodes to publish Shorty source urls on the web (or elsewhere)
+Data migration support as introduced by OC4
+Cleanup of Shortys upon user account deletion
+* Sun May 28 2012 Christian Reiner: version 0.1.6
+Activation of Shorty sharing via SMS. 
+Enhanced backend descriptions. 
+* Sat Apr 28 2012 Christian Reiner: version 0.1.5
+Target url verification is less strict now, this way also more 'exotic' urls notations are accepted.
+A few changes to the initilization scripts to prevent race conditions at startup.
+Changed url specification in the Shortlet to prevent conflicts with a serverside suhosin protection. 
+* Fri Apr 27 2012 Christian Reiner: version 0.1.4
+Visualization of busy state in dialogs whilst fetch meta data from targets.
+* Fri Apr 27 2012 Christian Reiner: version 0.1.3
+Prevented untimely submission of dialogs before having validated their contents.
+* Fri Apr 27 2012 Christian Reiner: version 0.1.2
+Fixed race conditions during initialization.
+* Thu Apr 26 2012 Christian Reiner: version 0.1.1
+Minor appearance corrections. 
+* Wed Apr 25 2012 Christian Reiner: version 0.1.0
+First official release. 
+* Tue Apr 24 2012 Christian Reiner: version 0.0.9
+Initial release.
+Buggy, but some parts actually working. 
diff --git a/apps/shorty/doc/CONFIGURATION b/apps/shorty/doc/CONFIGURATION
new file mode 100644
index 00000000000..2a7dab60d19
--- /dev/null
+++ b/apps/shorty/doc/CONFIGURATION
@@ -0,0 +1,113 @@
+*****
+* @package shorty an ownCloud url shortener plugin
+* @category internet
+* @author Christian Reiner
+* @copyright 2011-2012 Christian Reiner <foss@christian-reiner.info>
+* @license GNU Affero General Public license (AGPL)
+* @link information
+* @link repository https://svn.christian-reiner.info/svn/app/oc/shorty
+*
+* This library is free software; you can redistribute it and/or
+* modify it under the terms of the GNU AFFERO GENERAL PUBLIC LICENSE
+* License as published by the Free Software Foundation; either
+* version 3 of the license, or any later version.
+*
+* This library is distributed in the hope that it will be useful,
+* but WITHOUT ANY WARRANTY; without even the implied warranty of
+* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+* GNU AFFERO GENERAL PUBLIC LICENSE for more details.
+*
+* You should have received a copy of the GNU Affero General Public
+* License along with this library.
+* If not, see <http://www.gnu.org/licenses/>.
+*****
+
+There are five aspects that can be configured:
+1.) System wide "static backend" (optional)
+2.) Selection of a backend per user (optional)
+3.) Import of the "shortlet" into a web browser (optional)
+4.) Access control inside each single "shorty" (implicit)
+5.) Sending of Shortys as SMS
+
+1.) System wide "static backend" (optional)
+(Requires adminisstrative rights)
+This optional setting enables a 'static backend'. That is a backend generting
+source urls based on a static base url, thus the name. That base url should be
+chosen as short as possible, since this defines the total length of all links
+to be posted and used. Most likely the definition of that url requires the
+configuration of rewrite rules on the server side. So it is only an option for
+experienced adminsitrators with access to the server configuration, be it
+centralized or based on decentralized per-directory rules (".htaccess files").
+A basic example is packed in the .htaccess file (might be hidden in a directory
+listing because of the leading dot (.) in the name). The rules must be
+configured such that all requests to urls of the scheme <base url><shorty key>
+are mapped directly onto the web url of the shorty plugin
+(http://<domain>/<owncloud>/apps/shorty/). The <shorty key> is a string, 6-12
+characters long, hard to predict. It is guaranteed to be unique throughout the
+system (though in a technically crude manner...). The perfect situation for the
+definition of a meaningful static backend would be a domain with a very short
+name and configuration access to something close to the web root.
+A random example is my own domain "christian-reiner.info". Since that is not
+exactly short I would love to use the additional domain "c-r.info" for the sole
+purpose of a static backend. Unfortunately that domain has been reserved by a
+domain grabber who asks thousands of Euros for it ! So that's no option. At
+least you should try to find a setup where the web path of the ownCloud
+application is not part of the base url. So that you get something like
+http://<domain name>/<shorty key>.
+(Note that the shorty key is NOT part of the base url configuration).
+You can easily test your setup any time by clicking on the example dynamically
+visualized next to the configuration option. It runs a simple self-tests of the
+setup in background.
+There is no need that the base url must be served by the same http server that
+serves the owncoud system. A static rewrite setup may well forward short source
+urls to the shorty plugin inside a remote ownCloud installation. However, it is
+a known issue that the internal validation of the setup won't work with such
+scenario. 
+
+2.) Selection of a backend per user (optional)
+To generate the a source url that is part of every shorty the plugin uses a
+backend. The configuration is done by using a preference option in the personal
+preference section of the configuration. You can simply chose one of the
+offered backends (combo box). Changing the backend does not affect any
+previously generated shorties. Meaning they stay valid and usable and keep
+their once defined source url.
+
+Different backends are implemented:
+i.) "-none-"
+As you have guessed this is something like a "dummy" backend without any
+implemented logic. That means the source urls generated are exactly based on
+the web url of the shorty plugin in your ownCloud system. This is not a very
+clever setup, but it certainly works and keeps your data private.
+ii.) "static backend"
+If configured in the system administration a "static backend" is offered. For a
+description see C-1. This backend typically offers shorter source urls, but its
+setup required administrative rights on some http server system.
+iii.) online services (url shorteners)
+A few online services are offered as backends to generate short source urls.
+Usage of some of those services requires you to open a free account at their
+site. Detailed configuration requirements are displayed for the chosen backend.
+If you don't care for details and just want short urls then have a try with the
+tin.ny backend. No registration required, reliable service. But keep in mind
+you depend on an external service as opposed to using a local static backend.
+
+3.) Import of the "shortlet" into a web browser  (optional)
+Shorty comes with a neat little "Shortlet" offered in the personal preferneces
+section of ownCloud. It is a "button" you can import into your web browsers
+bookmark toolbar or area by simple drag & drop. The Shortlet should work with
+most modern browsers, though probably not all. Just have a try with it.
+
+4.) Access control inside each single "shorty" (implicit)
+There are a few attributres you can configure freely inside each stored shorty:
+- a title just shown inside the shorty plugin (serves recognition).
+- a notes area, maybe you want to write down whom you send the shorty ?
+- a status option that controls the usage of the shorty.
+
+5.) Sending of Shortys as SMS
+Besides sending of Shortys as email message and copying a Shortys source url 
+to the clipboard a third action can be enabled inside the sharing dialog: 
+To send a Shortys source url as SMS. 
+However, the approach is extremely minimalistic, it relies on the client system 
+to correctly handle a 'sms url'. This is typically only given on a mobile 
+device, a smart phone. In addition, such url does not allow to specify a message
+body, so the Shortys source url has to be copied and pasted manually. 
+The option is disabled by default. 
diff --git a/apps/shorty/doc/COPYRIGHT b/apps/shorty/doc/COPYRIGHT
new file mode 100644
index 00000000000..5e501826f28
--- /dev/null
+++ b/apps/shorty/doc/COPYRIGHT
@@ -0,0 +1,23 @@
+*****
+* @package shorty an ownCloud url shortener plugin
+* @category internet
+* @author Christian Reiner
+* @copyright 2011-2012 Christian Reiner <foss@christian-reiner.info>
+* @license GNU Affero General Public license (AGPL)
+* @link information
+* @link repository https://svn.christian-reiner.info/svn/app/oc/shorty
+*
+* This library is free software; you can redistribute it and/or
+* modify it under the terms of the GNU AFFERO GENERAL PUBLIC LICENSE
+* License as published by the Free Software Foundation; either
+* version 3 of the license, or any later version.
+*
+* This library is distributed in the hope that it will be useful,
+* but WITHOUT ANY WARRANTY; without even the implied warranty of
+* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+* GNU AFFERO GENERAL PUBLIC LICENSE for more details.
+*
+* You should have received a copy of the GNU Affero General Public
+* License along with this library.
+* If not, see <http://www.gnu.org/licenses/>.
+*****
diff --git a/apps/shorty/doc/CREDITS b/apps/shorty/doc/CREDITS
new file mode 100644
index 00000000000..8f7a3dd037c
--- /dev/null
+++ b/apps/shorty/doc/CREDITS
@@ -0,0 +1,32 @@
+*****
+* @package shorty an ownCloud url shortener plugin
+* @category internet
+* @author Christian Reiner
+* @copyright 2011-2012 Christian Reiner <foss@christian-reiner.info>
+* @license GNU Affero General Public license (AGPL)
+* @link information
+* @link repository https://svn.christian-reiner.info/svn/app/oc/shorty
+*
+* This library is free software; you can redistribute it and/or
+* modify it under the terms of the GNU AFFERO GENERAL PUBLIC LICENSE
+* License as published by the Free Software Foundation; either
+* version 3 of the license, or any later version.
+*
+* This library is distributed in the hope that it will be useful,
+* but WITHOUT ANY WARRANTY; without even the implied warranty of
+* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+* GNU AFFERO GENERAL PUBLIC LICENSE for more details.
+*
+* You should have received a copy of the GNU Affero General Public
+* License along with this library.
+* If not, see <http://www.gnu.org/licenses/>.
+*****
+
+The shorty plugin has been developed by:
+
+Christian Reiner, Hamburg, Germany
+E-Mail: foss@christian-reiner.information
+
+Contributions:
+I'd be more than happy to welcome all contributions to this little experiment.
+Drop me a note, an idea, a patch, a good bottle of wine, anything !
diff --git a/apps/shorty/doc/INSTALLATION b/apps/shorty/doc/INSTALLATION
new file mode 100644
index 00000000000..0a98605376a
--- /dev/null
+++ b/apps/shorty/doc/INSTALLATION
@@ -0,0 +1,53 @@
+*****
+* @package shorty an ownCloud url shortener plugin
+* @category internet
+* @author Christian Reiner
+* @copyright 2011-2012 Christian Reiner <foss@christian-reiner.info>
+* @license GNU Affero General Public license (AGPL)
+* @link information
+* @link repository https://svn.christian-reiner.info/svn/app/oc/shorty
+*
+* This library is free software; you can redistribute it and/or
+* modify it under the terms of the GNU AFFERO GENERAL PUBLIC LICENSE
+* License as published by the Free Software Foundation; either
+* version 3 of the license, or any later version.
+*
+* This library is distributed in the hope that it will be useful,
+* but WITHOUT ANY WARRANTY; without even the implied warranty of
+* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+* GNU AFFERO GENERAL PUBLIC LICENSE for more details.
+*
+* You should have received a copy of the GNU Affero General Public
+* License along with this library.
+* If not, see <http://www.gnu.org/licenses/>.
+*****
+
+This package is a plugin for the ownCloud web application ("ownCloud app").
+
+There are two ways of installation: automatic and manual
+
+* Automatic installation:
+You need login to your ownCloud using an account with administrative rights.
+Open the 'Apps' section of the adminstration and select 'shorty', enable it.
+Then go on below with the basic configuration steps. 
+
+* Manual installation:
+Download the package from here: 
+http://apps.owncloud.com/content/show.php/Shorty?content=150401
+Create a subfolder 'shorty' in the "apps" subfolder of your ownCloud web root.
+Unpack the contents of the package into the new folder 'shorty'.
+Now load ownCloud in your favorite web browser and login with an administrative
+account.
+Enable the plugin in the "Apps" section of the configuration ("*") inside
+ownClouds web gui (requires admin rights).
+
+* Basic configuration steps for BOTH types of installation: 
+The "Admin" section of the configuration allows to configure a base url to
+enable usage of the static backend (see USAGE).
+The "Preferences" section of that configuration now offers two elements:
+- a "Shortlet" to be dragged to the browsers bookmark area (see USAGE).
+- a configuration of a backend to use to generate source urls (see USAGE).
+The main part of the plugin can be accessed in the navigation menu as "Shorty".
+
+***
+Have fun !
diff --git a/apps/shorty/doc/ISSUES b/apps/shorty/doc/ISSUES
new file mode 100644
index 00000000000..083c4648636
--- /dev/null
+++ b/apps/shorty/doc/ISSUES
@@ -0,0 +1,58 @@
+*****
+* @package shorty an ownCloud url shortener plugin
+* @category internet
+* @author Christian Reiner
+* @copyright 2011-2012 Christian Reiner <foss@christian-reiner.info>
+* @license GNU Affero General Public license (AGPL)
+* @link information
+* @link repository https://svn.christian-reiner.info/svn/app/oc/shorty
+*
+* This library is free software; you can redistribute it and/or
+* modify it under the terms of the GNU AFFERO GENERAL PUBLIC LICENSE
+* License as published by the Free Software Foundation; either
+* version 3 of the license, or any later version.
+*
+* This library is distributed in the hope that it will be useful,
+* but WITHOUT ANY WARRANTY; without even the implied warranty of
+* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+* GNU AFFERO GENERAL PUBLIC LICENSE for more details.
+*
+* You should have received a copy of the GNU Affero General Public
+* License along with this library.
+* If not, see <http://www.gnu.org/licenses/>.
+*****
+
+This is a short list of known issues:
+
+- The datepicker popup in the edit dialog fails to set the expiration date: 
+I have no idea what the problem is. Exactly the same object works flawlessly
+in the dialog to create a new shorty. I can't see any difference, except in
+the edit dialog the date is taken from the existing row entry (working fine).
+Maybe there is some sort of magic spell to awake a datepicker after changing
+its date value ? No idea...
+
+- Clicking on a source or relay url from within the sharing dialog updates the
+clicks counter and access time correctly, but the shown list entry is not
+updated accordingly. 
+
+- Shorty does not work in the konqueror web browser
+All appears to be working fine except for one annoying thing:
+the standalone dialogs won't open ! (show, create and edit entries)
+Therefore Shorty is currently more or less useless in this browser.
+
+- Shorty does not work in the rekonq web browser
+The basic navigation elements (menu left) work, but the desktop stays empty.
+Apparently no script is executed, an issue with the js document.ready event.
+
+- It appears there is an issue with setting opacity in the Safari browser:
+The status filter in the lists toolbar shows an ugly black brick instead of a
+dimmed icon overlay. Also some other style issues appear, but the plugin seems
+to be completely usable.
+
+- When internally validating the setup of the base url used in the static
+backend you get a false positive ("doesn't work") although things are fine, if
+the mapping of base url to shorty plugin is done via a redirect. This is for
+exaple the case if you implement the mapping on a remote server because you
+want to use a different domain name for statically shortened urls.
+The reason is that jqueries ajax calls won't handle redirects internally. A
+wrapper will have to be implemented. 
diff --git a/apps/shorty/doc/README b/apps/shorty/doc/README
new file mode 100644
index 00000000000..4f590f30cd0
--- /dev/null
+++ b/apps/shorty/doc/README
@@ -0,0 +1,42 @@
+*****
+* @package shorty an ownCloud url shortener plugin
+* @category internet
+* @author Christian Reiner
+* @copyright 2011-2012 Christian Reiner <foss@christian-reiner.info>
+* @license GNU Affero General Public license (AGPL)
+* @link information
+* @link repository https://svn.christian-reiner.info/svn/app/oc/shorty
+*
+* This library is free software; you can redistribute it and/or
+* modify it under the terms of the GNU AFFERO GENERAL PUBLIC LICENSE
+* License as published by the Free Software Foundation; either
+* version 3 of the license, or any later version.
+*
+* This library is distributed in the hope that it will be useful,
+* but WITHOUT ANY WARRANTY; without even the implied warranty of
+* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+* GNU AFFERO GENERAL PUBLIC LICENSE for more details.
+*
+* You should have received a copy of the GNU Affero General Public
+* License along with this library.
+* If not, see <http://www.gnu.org/licenses/>.
+*****
+
+This "shorty" package implements a plugin for the ownCloud web application.
+Shorty offers a service to store, manage and use a collection of short links
+pointing to ressources in the web. The features are a combination of a
+centralized bookmarks collection, an url shortener and a basic access control.
+The collection is presented as a list of "shorties". A shorty can be created
+either manually in the list ("New shorty") or by using the "Shortlet". The
+Shortlet is something like a Bookmarklet, a script based bookmark meant to be
+stored inside the bookmark collection of a web browser. When clicked, the page
+currently open in the browser will be added to the list of existing shorties.
+
+Each Shorty contains a source and a target url. The source url can be used to
+be posted in forums, sent inside an email message or whatever. It is typically
+shorter than the target url, a full blown web url. But that actually depends
+on the target url and the backend used. The target url is the ressource
+identified by the shorty. Basic access control is implemented to control the
+access of shorties posted to forums or sent per email, but not on a per user or
+per group base. Existing shorties can be blocked for usage, set to expire on a
+certain date and obviously can be removed permanently again.
diff --git a/apps/shorty/doc/ROADMAP b/apps/shorty/doc/ROADMAP
new file mode 100644
index 00000000000..b18099c9af2
--- /dev/null
+++ b/apps/shorty/doc/ROADMAP
@@ -0,0 +1,96 @@
+*****
+* @package shorty an ownCloud url shortener plugin
+* @category internet
+* @author Christian Reiner
+* @copyright 2011-2012 Christian Reiner <foss@christian-reiner.info>
+* @license GNU Affero General Public license (AGPL)
+* @link information
+* @link repository https://svn.christian-reiner.info/svn/app/oc/shorty
+*
+* This library is free software; you can redistribute it and/or
+* modify it under the terms of the GNU AFFERO GENERAL PUBLIC LICENSE
+* License as published by the Free Software Foundation; either
+* version 3 of the license, or any later version.
+*
+* This library is distributed in the hope that it will be useful,
+* but WITHOUT ANY WARRANTY; without even the implied warranty of
+* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+* GNU AFFERO GENERAL PUBLIC LICENSE for more details.
+*
+* You should have received a copy of the GNU Affero General Public
+* License along with this library.
+* If not, see <http://www.gnu.org/licenses/>.
+*****
+
+Future versions might implement additional features and services. Currently
+planned are the following:
+
+* Ability to create Shortys directly from shared files inside ownCloud
+Creating a Shorty based on the public url generated for shared files works like
+charm. However it is not very convenient to do that manually. It would be great
+to offer that option directly where file sharing is done, in that very dialog.
+However I currently do not see any means to achieve that on ownCloud. There is
+no feature offered to hook additional functionality into exsiting apps.
+This means either the existing file sharing app has to be modified or such a
+modifying core feature has to be implemented into the ownCLoud core. 
+Or maybe someone has got another idea ?
+
+* Integrated proxy function as an alternative to forwarding:
+Currently all browser requests are forwarded to the final target url, provided
+that the referenced shorty is still valid and accessible. This is a simple but
+effective strategy. Offering a transparent proxy service as an alternative
+would greatly enhance the privacy protection, since the final target url of a
+referenced web ressource would never be handed out. 
+
+* Better, more fine grained access control:
+Currently the only means of access control, apart from defining or removing a
+shorty are its "status". The status can block an otherwise valid shorty from
+usage from outside ownCloud, it can restrict its access to authenticated users
+or it can make an existing shorty freely accessible to the public. Other
+ownCloud plugins allow to define individual access to content on per-user or
+per-group rules.
+
+* Support of further backends: 
+Currently the usage of six url shortener services is implemented, besides the
+two private or local ones. Unfortunately three of these had to be disabled due
+to stability issues. Besides correcting the implementation for the disabled it
+might make sense to support further backends, especially other types besides
+online services.
+
+* Performance, stability and usability enhancements: 
+"Shorty" is my first web application using up to date web technologies.
+Therefore the implementation certainly is far from the quality one could expect
+from a serious and experienced web developer. One could also put this into more
+constructive terms: there is definately much room for enhancements   :-) 
+
+* Translations of the shorty module itself (i18n/l10n):
+Main development language is english (us), a german translation exists. I do
+not feel fit enough in other languages to create a translation myself. So I
+certainly welcome any assistance in that aspect. The effort consists of editing
+one single file, take a look at the german example in file l10n/de.php. 
+
+* Usage of svg icons instead of png graphics:
+I created all icons in svg format. ownCloud implements a mechanism to use those
+in browsers supporting svg directly. However I did not yet figure out how to
+use that feature without adding too much scripting overhead. Is it possible
+to reference icons the ownCloud way directly in a php based template, without
+the need to explicit handling via javascript ?
+I wish a better API documentation would exist for ownCloud !
+
+* Localization for the date picker fields
+Currently date inputs (expiration date) are not validated explicitly.
+A number of formats work, are accepted correct, but there is no localization
+of the input format to the users language.
+
+* Integrated help button
+One thing I miss throughout the ownCloud application is a context sensitive
+help, or a help button at all ! Originally I planned to integrate on into this 
+plugin. However I think that is more something that should be implemented as a
+core feature of ownCloud. Maybe as a separate plugin (app). SOmehing like a
+help framework with a documented api where other plugins (and core apps) can
+attach help texts or documents to. Context sensivity would then simply mean to
+update the reference in the help button for each action taken.
+
+Contributions:
+I'd be more than happy to welcome all contributions to this little experiment.
+Drop me a note, an idea, a patch, a good bottle of wine, anything !
diff --git a/apps/shorty/doc/STATUS b/apps/shorty/doc/STATUS
new file mode 100644
index 00000000000..0b85d147028
--- /dev/null
+++ b/apps/shorty/doc/STATUS
@@ -0,0 +1,42 @@
+*****
+* @package shorty an ownCloud url shortener plugin
+* @category internet
+* @author Christian Reiner
+* @copyright 2011-2012 Christian Reiner <foss@christian-reiner.info>
+* @license GNU Affero General Public license (AGPL)
+* @link information
+* @link repository https://svn.christian-reiner.info/svn/app/oc/shorty
+*
+* This library is free software; you can redistribute it and/or
+* modify it under the terms of the GNU AFFERO GENERAL PUBLIC LICENSE
+* License as published by the Free Software Foundation; either
+* version 3 of the license, or any later version.
+*
+* This library is distributed in the hope that it will be useful,
+* but WITHOUT ANY WARRANTY; without even the implied warranty of
+* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+* GNU AFFERO GENERAL PUBLIC LICENSE for more details.
+*
+* You should have received a copy of the GNU Affero General Public
+* License along with this library.
+* If not, see <http://www.gnu.org/licenses/>.
+*****
+
+The current status of this package is as follows:
+
+The initial release is definately buggy and contains annoying shortcomings.
+It has been developed on a linux system using a firefox browser, so this is
+most likely the best working combination. Basic usage test have been made with
+a few other browsers. The package appears to be working in general though there
+might be some minor differences in apeparance.
+
+Known shortcomings are:
+- only very basic input validation is done. 
+- access control is not yet fine grained, no user or group support exists.
+- markup, scripting and style definitions are the work of a web app newbie.
+
+So "sorry for any inconveniences" !
+
+Contributions:
+I'd be more than happy to welcome all contributions to this little experiment.
+Drop me a note, an idea, a patch, a good bottle of wine, anything !
diff --git a/apps/shorty/doc/USAGE b/apps/shorty/doc/USAGE
new file mode 100644
index 00000000000..a82f881992a
--- /dev/null
+++ b/apps/shorty/doc/USAGE
@@ -0,0 +1,64 @@
+*****
+* @package shorty an ownCloud url shortener plugin
+* @category internet
+* @author Christian Reiner
+* @copyright 2011-2012 Christian Reiner <foss@christian-reiner.info>
+* @license GNU Affero General Public license (AGPL)
+* @link information
+* @link repository https://svn.christian-reiner.info/svn/app/oc/shorty
+*
+* This library is free software; you can redistribute it and/or
+* modify it under the terms of the GNU AFFERO GENERAL PUBLIC LICENSE
+* License as published by the Free Software Foundation; either
+* version 3 of the license, or any later version.
+*
+* This library is distributed in the hope that it will be useful,
+* but WITHOUT ANY WARRANTY; without even the implied warranty of
+* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+* GNU AFFERO GENERAL PUBLIC LICENSE for more details.
+*
+* You should have received a copy of the GNU Affero General Public
+* License along with this library.
+* If not, see <http://www.gnu.org/licenses/>.
+*****
+
+=== Overview ===
+See file README.
+
+=== Installation ===
+See file INSTALLATION.
+
+=== Requirements ===
+ownCloud version 2 or newer on the server side.
+A css3 capable and reasonably standards conform web browser.
+A scripting capable bookmarks feature for the optional Shortlet thing. 
+
+=== Usage ===
+This is only a very basic description. The plugin should be fairly intuitive to
+use, just have a try with a few web urls. To get going I suggest that you
+- chose a backend (see configuration below).
+- import the shortlet into your preferred web browser (see configuration below).
+- define a few shorties either manually ("New") or by using the shortlet.
+All actions on existing shorties are accessed using the action icons shown to
+the right of the shorty in the list. Daily uses is probably based on selection
+the 'share' action and grabbing the visualized "source url".
+By clicking on the header row of the list of shorties you can open (and close)
+a "toolbox" offering options to sort, filter and reload the list. The sorting
+you chose is stored in a persistant manner, not so any filters defined. You
+cannot accidentially close the toolbox when there are still filters active. 
+You can remove (delete) existing shorties, but those shorties will only be
+marked as deleted. This way you can 'undelete' them if required. Permanent
+removal is done next time you access the shorty plugin. If you really want to
+make sure the removal is done NOW then simply reload the list. This is done in
+the "toolbox" of the list (click on the header row) by chosing the "reload"
+icon on the left (or by a simple browser reload). 
+
+=== PRIVACY ===
+Shorty allows you to stay more in control over links you post or send. It is up
+to you to decide wether a once posted link should stay valid and usable or not.
+However it is also very important to keep in mind that such form of control can
+never replace any serious form of access control over the content published via
+a published link. Shorty works as a short url resolver, meaning it forwards any
+requesting web browser to the real address of the published content. This might
+change when if future an integrated proxy function gets implemented, as opposed
+to the current forwarding mechanism.