From 18989f97f1c4299f447b011c28961ca5c8310c13 Mon Sep 17 00:00:00 2001 From: Christian Weiske Date: Thu, 26 May 2011 08:20:04 +0200 Subject: documentation index --- doc/developers/TODO | 104 --------------------------------- doc/developers/TODO.rst | 104 +++++++++++++++++++++++++++++++++ doc/developers/api | 10 ---- doc/developers/api.rst | 10 ++++ doc/developers/debugging | 20 ------- doc/developers/debugging.rst | 20 +++++++ doc/developers/doc-TODO | 9 --- doc/developers/doc-TODO.rst | 9 +++ doc/developers/release-new-version | 22 ------- doc/developers/release-new-version.rst | 22 +++++++ doc/developers/rules | 30 ---------- doc/developers/rules.rst | 30 ++++++++++ doc/developers/running-unit-tests | 21 ------- doc/developers/running-unit-tests.rst | 21 +++++++ doc/developers/translation | 40 ------------- doc/developers/translation.rst | 40 +++++++++++++ doc/index.rst | 43 ++++++++++++++ 17 files changed, 299 insertions(+), 256 deletions(-) delete mode 100644 doc/developers/TODO create mode 100644 doc/developers/TODO.rst delete mode 100644 doc/developers/api create mode 100644 doc/developers/api.rst delete mode 100644 doc/developers/debugging create mode 100644 doc/developers/debugging.rst delete mode 100644 doc/developers/doc-TODO create mode 100644 doc/developers/doc-TODO.rst delete mode 100644 doc/developers/release-new-version create mode 100644 doc/developers/release-new-version.rst delete mode 100644 doc/developers/rules create mode 100644 doc/developers/rules.rst delete mode 100644 doc/developers/running-unit-tests create mode 100644 doc/developers/running-unit-tests.rst delete mode 100644 doc/developers/translation create mode 100644 doc/developers/translation.rst create mode 100644 doc/index.rst diff --git a/doc/developers/TODO b/doc/developers/TODO deleted file mode 100644 index 59dd655..0000000 --- a/doc/developers/TODO +++ /dev/null @@ -1,104 +0,0 @@ -- 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/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 b/doc/developers/api deleted file mode 100644 index efa05fe..0000000 --- a/doc/developers/api +++ /dev/null @@ -1,10 +0,0 @@ -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/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 b/doc/developers/debugging deleted file mode 100644 index 7f84da6..0000000 --- a/doc/developers/debugging +++ /dev/null @@ -1,20 +0,0 @@ -How to debug SemanticScuttle -============================ - - -Database queries ----------------- -In config.php, enable debugMode. -Further, add the following there: -------- -register_shutdown_function( - create_function('', <<sql_report('display'); -FNC - ) -); ------- -To see database queries in SemanticScuttle, add -> ?explain=1 -to your URL. diff --git a/doc/developers/debugging.rst b/doc/developers/debugging.rst new file mode 100644 index 0000000..7f84da6 --- /dev/null +++ b/doc/developers/debugging.rst @@ -0,0 +1,20 @@ +How to debug SemanticScuttle +============================ + + +Database queries +---------------- +In config.php, enable debugMode. +Further, add the following there: +------- +register_shutdown_function( + create_function('', <<sql_report('display'); +FNC + ) +); +------ +To see database queries in SemanticScuttle, add +> ?explain=1 +to your URL. diff --git a/doc/developers/doc-TODO b/doc/developers/doc-TODO deleted file mode 100644 index 4fac4ab..0000000 --- a/doc/developers/doc-TODO +++ /dev/null @@ -1,9 +0,0 @@ -- 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/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 b/doc/developers/release-new-version deleted file mode 100644 index 4b2540a..0000000 --- a/doc/developers/release-new-version +++ /dev/null @@ -1,22 +0,0 @@ -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/about.tpl.php, - build.xml and doc/README.txt -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 and create a svn tag. -7. Write announcement mail to the SemanticScuttle mailing list - semanticscuttle-devel@lists.sourceforge.net -8. Announce the new release in the sourceforge project news - https://sourceforge.net/apps/trac/sourceforge/wiki/News - diff --git a/doc/developers/release-new-version.rst b/doc/developers/release-new-version.rst new file mode 100644 index 0000000..4b2540a --- /dev/null +++ b/doc/developers/release-new-version.rst @@ -0,0 +1,22 @@ +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/about.tpl.php, + build.xml and doc/README.txt +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 and create a svn tag. +7. Write announcement mail to the SemanticScuttle mailing list + semanticscuttle-devel@lists.sourceforge.net +8. Announce the new release in the sourceforge project news + https://sourceforge.net/apps/trac/sourceforge/wiki/News + diff --git a/doc/developers/rules b/doc/developers/rules deleted file mode 100644 index 701a215..0000000 --- a/doc/developers/rules +++ /dev/null @@ -1,30 +0,0 @@ -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/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 b/doc/developers/running-unit-tests deleted file mode 100644 index 556055f..0000000 --- a/doc/developers/running-unit-tests +++ /dev/null @@ -1,21 +0,0 @@ -Running unit tests -================== - -Go to the SemanticScuttle main directory and run - $ php tests/AllTests.php -or - $ phpunit tests/AllTests.php -also remember the --verbose parameter to PHPUnit. - -If you want to run a specific test class only: - $ phpunit tests/BookmarksTest.php - -If you need to test one method only: - $ 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/running-unit-tests.rst b/doc/developers/running-unit-tests.rst new file mode 100644 index 0000000..556055f --- /dev/null +++ b/doc/developers/running-unit-tests.rst @@ -0,0 +1,21 @@ +Running unit tests +================== + +Go to the SemanticScuttle main directory and run + $ php tests/AllTests.php +or + $ phpunit tests/AllTests.php +also remember the --verbose parameter to PHPUnit. + +If you want to run a specific test class only: + $ phpunit tests/BookmarksTest.php + +If you need to test one method only: + $ 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 b/doc/developers/translation deleted file mode 100644 index 776b5d7..0000000 --- a/doc/developers/translation +++ /dev/null @@ -1,40 +0,0 @@ -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[1]. - -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"); - - -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. - - - -[1] https://launchpad.net/php-gettext/ \ No newline at end of file diff --git a/doc/developers/translation.rst b/doc/developers/translation.rst new file mode 100644 index 0000000..776b5d7 --- /dev/null +++ b/doc/developers/translation.rst @@ -0,0 +1,40 @@ +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[1]. + +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"); + + +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. + + + +[1] https://launchpad.net/php-gettext/ \ No newline at end of file diff --git a/doc/index.rst b/doc/index.rst new file mode 100644 index 0000000..fc75aa6 --- /dev/null +++ b/doc/index.rst @@ -0,0 +1,43 @@ +============================= +SemanticScuttle documentation +============================= + + +First reads +=========== +- README_ +- `installation guide`_ +- `upgrade instructions`_ + +.. _README: README.html +.. _installation guide: INSTALL.html +.. _upgrade instructions: UPGRADE.html + + + +Features +======== +- `SSL Client certificates`__ +- Themes__ + +__ ssl-client-certificates.html +__ themes.html + + + +Developer documentation +======================= +- `General development rules`__ +- `Delicious API`__ +- `Debugging HowTo`__ +- `How to release a new version`__ +- `Running unit testes`__ +- `How to translate SemanticScuttle`__ + +__ rules.html +__ api.html +__ debugging.html +__ release-new-version.html +__ running-unit-tests.html +__ translation.html + -- cgit v1.2.3