8 files changed, 286 insertions, 0 deletions
diff --git a/doc/developers/TODO.rst b/doc/developers/TODO.rst
new file mode 100644
index 0000000..59dd655
--- /dev/null
+++ b/doc/developers/TODO.rst
@@ -0,0 +1,104 @@
+- SemanticScuttle_Filter
+  -> class with static filter functions to filter
+     ids, usernames, passwords, sorting etc.
+- when a user gets deleted from database, he should not be
+  logged in anymore (name not shown on top right)
+- Make users inactive by default when registered newly
+  - have to be activated by admins
+- Add RDFa to user profile page
+- use recaptcha or alike -> quickform
+- tutorial about sidebar
+- update php-gettext
+- index on bookmarks->modified, since created is not used in selects/sort
+  - how to optimize sorts, to prevent mysql filesort? -> index enough?
+  - how to optimize DISTINCT bHash
+
+
+Tracker items:
+#1908041 - klick counter
+  a counter how many people klicked one link
+#1964906 - Page numbers list / alternative pagination
+  I would love to have page numbers like for example google has for terms
+  with many hits. You can have a look at what exactly I'm talking about here:
+  http://www.jenst.se/wp-content/uploads/2008/04/wp-page-numbers-themes.gif .
+  With this you can more easily browse through the pages by clicking the
+  numbers and not those 'next' and 'previous' buttons.
+#1989984 - Branding Improvements
+  Create an ability to brand the installed site on several levels:
+  Level 1 - add a logo and text to the header
+  Level 2 - add a logo and text to the top header and add html (logos, text,
+   flickr widgets, youtube widgets, etc.) to the left and right side bars
+   through an interface similar to the theme editor on Wordpress. Also
+   include easy interface to Google AdWords.
+  Level 3 - add the items in Level 2 plus a banner ad manager.
+  Requirements:
+  - add comments to the CSS to allow for the novice to edit the CSS based on
+   known widget or image size. This is an important addition.
+#1969682 - private bookmarks
+  I think the handling of private bookmarks could be improved. Now it is so
+  that you just see a smaller amount of bookmarks as a visitor as you would
+  see when you are logged in as a member (and if had added some private
+  bookmarks to the site).
+  There should be a separate count of this private bookmarks to indicate that
+  there are some. Something like '80 public/total bookmark(s) - 5 private
+  bookmarks(s)'. It also should be easier to find them. Maybe the above
+  mentioned line counting the private bookmarks could be a link to a page
+  listing them.
+#2035563 - Delete bookmarks based on user votes
+  I'm using Semantic Scuttle for ONE topic based bookmarks sharing. Sometimes
+  I, as admin is not sure if the bookmark submitted is right for or not.
+  I'l like to propose a function, where 5 (numbers can be selected)of top
+  users (or sub admins if they can be created) of the site marks the bookmark
+  not applicable to the site, then that bookmark is deleted.
+#2862548 - Disable email TLD verification
+  It should be possible to disable the top level domain verification in the
+  email verification for new users. Use cases are
+  a) new top level domains (TLD) that are created in the future
+  b) company-internal non-standard TLDs
+#2830219 - Edit by other people
+  We use SemanticScruttle to share bookmarks in the company I work for.
+  It'd be helpful if there was a way all people could edit public bookmarks.
+#1969705 - adjustable thumbnail height and width in config.inc.php
+  I put two vars in the config file to adjust the size of the thumbnails and
+  accordingly changed the bookmarks.tpl.php file:
+  bookmarks.tpl.php
+  $websiteThumbnailsWidth = 90; # width of thumbnails in pixel, max value
+  240
+  $websiteThumbnailsHeight = 68; # height of thumbnails in pixel, max value
+  180
+#1933227 - custom maximum number of items in RSS-feeds
+  for Mozilla Firefox's Live Bookmarks feature, the current 15 items
+  delivered by RSS may not be enough.
+  note: by changing getPerPageCount() in functions.inc.php in a similar
+  manner, it should be possible to make the max-entries-per-page
+  customizable
+#1926991 - Admin Approval of New Users
+  Create a way for admins to select if they have to approve all new users.
+  Then have the following methods for new user approval:
+  - by email to selected admin on a per instance basis
+  - through an admin panel on a per instance basis
+  - through an admin panel on a batch basis
+  - through an admin panel by setting up rules for approval (for example:
+    user admin must have a specific domain - helpful for big companies)
+  This would help reduce the amount of spam for some users.
+#1932109 - tag counting: count each URL only once
+  I don't know if it's only me, but I have would prefer another way of
+  calculating a tag's weight:
+  current behaviour:
+   existing tags are currently counted by summing up the entries in the system
+   that have that tag.
+  example:
+   one user added youtube.com with the tag "videos".
+   one user added video.google.com with the tag "videos".
+   ten users added amazon.com with the tag "books".
+  the tags are now weighed like this: 2 videos, 10 books.
+  although there are more unique URLs in the system with the tag "videos".
+  preferred behaviour:
+   for tag-weighing, count the unique URLs, instead of the entries.
+   in the example above: count 2 for "videos", one for "books".
+#2830224 - Shorturl/tinyurl service
+  It would be cool if SemanticScruttle could be used as shorturl service with
+  configurable short urls.
+  So I'd define "freddy" as short url name in the bookmark, and anyone could
+  access it e.g. via our-bookmarks.com/s/freddy and get redirected to the
+  real url. Useful to get permanent URLs to moving targets.
diff --git a/doc/developers/api.rst b/doc/developers/api.rst
new file mode 100644
index 0000000..efa05fe
--- /dev/null
+++ b/doc/developers/api.rst
@@ -0,0 +1,10 @@
+SemanticScuttle API
+===================
+
+SemanticScuttle tries to implement the delicious API v1 as closely as sensible.
+
+Where it makes sense and the delicious API just does things plainly wrong
+(i.e. when returning a wrong status code on an error), we do it better.
+
+- http://www.delicious.com/help/api
+- http://support.delicious.com/forum/comments.php?DiscussionID=5286&page=1
diff --git a/doc/developers/debugging.rst b/doc/developers/debugging.rst
new file mode 100644
index 0000000..6bee309
--- /dev/null
+++ b/doc/developers/debugging.rst
@@ -0,0 +1,24 @@
+How to debug SemanticScuttle
+============================
+
+
+Database queries
+----------------
+
+In ``data/config.php``, enable ``debugMode``.
+Further, add the following afterwards: ::
+
+  register_shutdown_function(
+      create_function('', <<<FNC
+  \$GLOBALS['db'] = SemanticScuttle_Service_Factory::getDb();
+  \$GLOBALS['db']->sql_report('display');
+  FNC
+      )
+  );
+
+
+To see database queries in SemanticScuttle, add ::
+
+  ?explain=1
+
+to your URL.
diff --git a/doc/developers/doc-TODO.rst b/doc/developers/doc-TODO.rst
new file mode 100644
index 0000000..4fac4ab
--- /dev/null
+++ b/doc/developers/doc-TODO.rst
@@ -0,0 +1,9 @@
+- Bookmarklets: Text selection is used as description
+- Tag nesting: Paris > France > World
+- Tag alias: Deutschland = Germany
+
+
+- Which fields are searched?
+  title, description, private note, username, tags
+
+- What are [isbn] and so for?
diff --git a/doc/developers/release-new-version.rst b/doc/developers/release-new-version.rst
new file mode 100644
index 0000000..de2c4e3
--- /dev/null
+++ b/doc/developers/release-new-version.rst
@@ -0,0 +1,31 @@
+How to release a new version of SemanticScuttle
+===============================================
+
+0. Run unit tests and verify that all of them pass
+1. Update ``doc/ChangeLog``
+2. Update ``doc/UPGRADE.txt``
+3. Update version in ``data/templates/default/about.tpl.php``,
+   ``build.xml`` and ``doc/README.rst``
+4. Create a release zip file via the build script:
+   Just type "``phing``".
+5. Make a test installation from your zip file with a fresh
+   database. Register a user, add bookmarks etc.
+6. When all is fine, it's time to release.
+   The build script takes care for most of the
+   tasks.
+   Run "``phing release``", and it will upload the release to
+   sourceforge.
+7. Create a git tag and push it
+8. Create the PEAR package and test it:
+   Run ``phing package``, then
+   ``pear upgrade dist/pear/SemanticScuttle-0.xx.tgz``
+9. Publish the PEAR package: ``phing deploy-sf-pear``
+10. Publish the documentation: ``phing deploy-docs``
+11. Write announcement mail to the SemanticScuttle mailing list
+    semanticscuttle-devel@lists.sourceforge.net
+12. Announce the new release in the sourceforge project news
+    https://sourceforge.net/news/submit.php?group_id=211356
+    Help about the process is available in
+    https://sourceforge.net/apps/trac/sourceforge/wiki/News
+13. Set the default file in
+    https://sourceforge.net/projects/semanticscuttle/files/SemanticScuttle/
diff --git a/doc/developers/rules.rst b/doc/developers/rules.rst
new file mode 100644
index 0000000..701a215
--- /dev/null
+++ b/doc/developers/rules.rst
@@ -0,0 +1,30 @@
+Rules for developers
+====================
+
+1. Coding style
+---------------
+SemanticScuttle uses the PEAR Coding Standards.
+While quite some parts still do not follow them, all of the
+code will be coverted to them. When developing new code,
+adhere to it.
+
+A helpful tool to check your coding style is PHP CodeSniffer,
+http://pear.php.net/package/PHP_CodeSniffer
+
+
+2. Unit tests
+-------------
+At least the service and model classes have unit tests.
+If you fix things in there, make sure you
+a) do not break the tests or
+b) fix the tests if the old behavior was broken
+
+
+3. Keep security in mind
+------------------------
+As a web application, there are several attack vectors to SemanticScuttle.
+When processing user input (form variables, URL parameters)
+be sure to convert and validate them. If you expect a bookmark id,
+there is no reason not to cast the variable to (int).
+
+Filter input, escape output.
diff --git a/doc/developers/running-unit-tests.rst b/doc/developers/running-unit-tests.rst
new file mode 100644
index 0000000..f75cb81
--- /dev/null
+++ b/doc/developers/running-unit-tests.rst
@@ -0,0 +1,31 @@
+Running unit tests
+==================
+The tests are dependent on the pear packages HTTP_Request2 and Stream_Var.
+
+Install them with: ::
+  $ pear install HTTP_Request2
+  $ pear install Stream_Var
+
+Go to the SemanticScuttle ``tests`` directory and run ``phpunit``::
+
+  $ cd tests
+  $ phpunit .
+
+also remember the ``--verbose`` parameter to PHPUnit.
+
+If you want to run a specific test class only: ::
+
+ $ cd tests
+ $ phpunit BookmarksTest.php
+
+If you need to test one method only: ::
+
+ $ cd tests
+ $ phpunit --filter BookmarkTest::testUnificationOfBookmarks tests/BookmarkTest.php
+
+
+Caveats
+-------
+Having debugging enabled and database driver "``mysql4``" activated
+will lead to failing tests because of ``FOUND_ROWS()`` usage, which
+does not work nicely with database debugging.
diff --git a/doc/developers/translation.rst b/doc/developers/translation.rst
new file mode 100644
index 0000000..008f66e
--- /dev/null
+++ b/doc/developers/translation.rst
@@ -0,0 +1,47 @@
+===========================
+Translating SemanticScuttle
+===========================
+
+SemanticScuttle uses gnu gettext for translation. It does not
+rely on the php extension but ships with a pure php implementation,
+php-gettext_.
+
+Using gettext from within the code is really easy:
+Enclose the string you want to translate in a "``T_``" function call.
+
+For example, to translate::
+
+  echo "Vote for";
+
+just write ::
+
+  echo T_("Vote for");
+
+.. _php-gettext: https://launchpad.net/php-gettext/
+
+Translation basics
+==================
+
+We keep one base translation file, ``data/locales/messages.po``.
+This file is auto-generated via ``xgettext`` from all our php source files.
+In case you added a new string to the code that needs translation,
+update the base translation file by running ::
+
+  $ php scripts/update-translation-base.php
+
+After that has been done, the changes to the base ``messages.po`` file
+need to be merged into the single language translation files,
+for example ``data/locales/de_DE/LC_MESSAGES/messages.po``.
+
+Updating them from the master file is as easy as running::
+
+  $ php scripts/update-translation.php de_DE
+
+When the translation is ready, the ``.po`` file needs to be compiled
+in a machine-readable ``.mo`` file. Use ::
+
+  $ php scripts/compile-translation.php de_DE
+
+to achieve that.
+
+