diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/ChangeLog | 26 | ||||
| -rw-r--r-- | doc/INSTALL.txt | 50 | ||||
| -rw-r--r-- | doc/README.rst | 67 | ||||
| -rw-r--r-- | doc/README.txt | 91 | ||||
| -rw-r--r-- | doc/UPGRADE.txt | 269 | ||||
| -rw-r--r-- | doc/authentication.rst | 213 | ||||
| -rw-r--r-- | doc/authentication.txt | 197 | ||||
| -rw-r--r-- | doc/developers/TODO.rst (renamed from doc/developers/TODO) | 0 | ||||
| -rw-r--r-- | doc/developers/api.rst (renamed from doc/developers/api) | 0 | ||||
| -rw-r--r-- | doc/developers/debugging | 20 | ||||
| -rw-r--r-- | doc/developers/debugging.rst | 24 | ||||
| -rw-r--r-- | doc/developers/doc-TODO.rst (renamed from doc/developers/doc-TODO) | 0 | ||||
| -rw-r--r-- | doc/developers/release-new-version.rst (renamed from doc/developers/release-new-version) | 0 | ||||
| -rw-r--r-- | doc/developers/rules.rst (renamed from doc/developers/rules) | 0 | ||||
| -rw-r--r-- | doc/developers/running-unit-tests | 21 | ||||
| -rw-r--r-- | doc/developers/running-unit-tests.rst | 26 | ||||
| -rw-r--r-- | doc/developers/translation | 40 | ||||
| -rw-r--r-- | doc/developers/translation.rst | 47 | ||||
| -rw-r--r-- | doc/index.rst | 45 | ||||
| -rw-r--r-- | doc/themes.rst | 48 |
20 files changed, 605 insertions, 579 deletions
diff --git a/doc/ChangeLog b/doc/ChangeLog index 3c4e939..cde9e61 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,23 +1,28 @@ ChangeLog for SemantiScuttle ============================ + 0.98.0 - 2011-XX-XX ------------------- - Switch to jQuery and drop dojo - Fix bug #3187177: Wrong URL / Export XML Bookmarks -- Fix bug in getTagsForBookmarks() that fetched all tags +- Fix bug in ``getTagsForBookmarks()`` that fetched all tags - Fix bug #3097187: Using opensearch with two tags does not work in Firefox - Fix bug #3251877: French translation JavaScript Bug when editing bookmarks +- Fix bug #3168521: Title of tag-filtered RSS Feed is broken +- Fix bug #2853627: Javascript warning +- Implement request #1989987: Theming support - Implement request #3054906: Show user's full name instead of nickname -- Implement patch #3059829: update FR_CA translation +- Implement patch #3059829: update ``FR_CA`` translation - Show error message on mysqli connection errors - Update php-gettext library to 1.0.10 -- api/posts/add respects the "replace" parameter now +- ``api/posts/add`` respects the "replace" parameter now - Fix privacy issue when fetching tags of several users - Fix Google custom search XML - Only URLs with an allowed protocol may be added to the database -- Support HTTPS connections when $root is not configured +- Support HTTPS connections when ``$root`` is not configured - SQL schema version table to ease future database upgrades +- Documentation is written with rST (reStructuredText) now 0.97.2 - 2011-02-17 @@ -68,11 +73,13 @@ your SemanticScuttle installations! - Fix several SQL injection possibilities - Fix E_NOTICE when calling alltags.php without any parameter - Implement part of request #2928950: + - User adjustable entry count: rss.php?count=20 - Fix HTTP content type header for RSS - Add config option to allow sorting by bookmark creation date instead of modification date -- Implement request #2833793: Export to avahi config files + + - Implement request #2833793: Export to avahi config files - we support zeroconf networking! - Implement request #2934868: Do not display full redirection URL Patch by fnorder@users.sourceforge.net @@ -181,7 +188,7 @@ your SemanticScuttle installations! - Major Refactoring: add a tag cache improving query processing (knowledge inference on tag relations) [DB modified] - Interface fix: allows to remove a tag from the selection into - subtitle bar thanks to a *. + subtitle bar thanks to a \*. - New Feature: authorizes anchors with brackets into descriptions of bookmark. For example: "[city]Paris[/city]". This text between anchors will be highlighted when the @@ -219,6 +226,7 @@ your SemanticScuttle installations! 0.90 - 2008-06-05 ----------------- The main improvements of this new version are: + - menu tags (tags which are included into the "menu" tag and thus which appear on the main page) - connexion with Google Custom Search Engine which allows to @@ -227,6 +235,7 @@ The main improvements of this new version are: All the changes: + - New feature: add Google Custom Search Engine into gsearch/ folder and looking into all bookmarks [Config modified] - Interface design: antispam question is hidden when @@ -279,6 +288,7 @@ The main change of this release is the possibility to preview websites through thumbnails (thanks to artviper.net). All the changes: + - Interface design: display SemanticScuttle version number on "about" page - Bug fix: allow clean urls thanks to .htaccess @@ -298,6 +308,7 @@ All the changes: 0.87 - 2008-02-14 ----------------- This new version brings two major features to SemanticScuttle: + 1) You can now create a synonym link between tags. For example, by linking the tags "monument" and "monuments", you can find resources tagged with the first one when you navigate @@ -310,6 +321,7 @@ This new version brings two major features to SemanticScuttle: ones (more difficult but more powerful). All the changes: + - Interface design: allow to access to users' bookmarks from last user sidebox. (Currently, we can just access to their profiles). - Interface design: hide multiple URLs repeated into history page @@ -335,9 +347,11 @@ All the changes: ----------------- - New feature: Add stats (nb children, nb descendants, depth, nb update) to structured tags + - Allow to visualize structured tags according to stats - Add admin page to update stats from the existing structured tags in the database + - Translation: improve French translation (add missing translations, transform "labels" into "tags") - New feature: List all users in a users page and users block on diff --git a/doc/INSTALL.txt b/doc/INSTALL.txt index b2dd3b2..5afc732 100644 --- a/doc/INSTALL.txt +++ b/doc/INSTALL.txt @@ -1,51 +1,60 @@ +============================ SemanticScuttle installation ============================ Prerequisites -------------- +============= To run SemanticScuttle, you need: + - PHP5 with filter functions enabled - A web server, for example Apache Installation instructions -------------------------- +========================= 1. Create a new MySQL database -2. Import tables.sql into that database, i.e. - run - > mysql -umyusername semanticscuttle < data/tables.sql +2. Import ``data/tables.sql`` into that database, i.e. + run :: + + $ mysql -umyusername semanticscuttle < data/tables.sql + on the shell ("semanticscuttle" being the database name) -3. Copy data/config.php.dist to data/config.php and modify it as + +3. Copy ``data/config.php.dist`` to ``data/config.php`` and modify it as necessary. 4. Make the cache directory writable by your web server. - For example, run - > chmod 0777 cache + For example, run :: + + $ chmod 0777 cache + on the shell. -5. Set the www/ directory as document root in your web server, +5. Set the ``www/`` directory as document root in your web server, restart the web server. Ugly www directory in URLs --------------------------- +========================== In case point 5 of the installation instructions cannot be put into practice by you because you are not able to change the web server configuration, you are not lost! There is a way to get rid of -www/ in your URL! +``www/`` in your URL! + +Imagine following directory layout: :: -Imagine following directory layout: /home/customer123/ www/ subdomain1/ subdomain2/ subdomain3/ -Create a SemanticScuttle directory somewhere outside www if possible -and put all directories except www/ in there. Move all files and -directories from www/ into your subdomain directory. Then modify -subdomain/www-header.php to include the correct file path. +Create a SemanticScuttle directory somewhere outside ``www`` if possible +and put all directories except ``www/`` in there. Move all files and +directories from ``www/`` into your subdomain directory. Then modify +``subdomain/www-header.php`` to include the correct file path. + +The new directory layout should look that way: :: -The new directory layout should look that way: /home/customer123/ semanticscuttle/ doc/ @@ -60,8 +69,11 @@ The new directory layout should look that way: www-header.php subdomain3/ -Now open www-header.php and replace +Now open www-header.php and replace :: + require_once '../src/SemanticScuttle/header.php'; -with + +with :: + require_once '../../semanticscuttle/src/SemanticScuttle/header.php'; diff --git a/doc/README.rst b/doc/README.rst new file mode 100644 index 0000000..0c7befe --- /dev/null +++ b/doc/README.rst @@ -0,0 +1,67 @@ +==================== +SemanticScuttle 0.98 +==================== +A social bookmarking tool experimenting with new features +like structured tags or collaborative descriptions of tags. + +https://sourceforge.net/projects/semanticscuttle/ + +Available under the GNU General Public License + + +Installation +============ +See `INSTALL.rst`__ + + +__ INSTALL.html + + +Upgrading from a previous version +================================= +See `UPGRADE.txt`__ + +__ UPGRADE.html + + +Public API +========== +SemanticScuttle supports most of the `del.icio.us API`__. +Almost all of the neat tools made for that system can be modified +to work with your SemanticScuttle installation. If you find a tool +that won't let you change the API address, ask the creator to add +this setting. You never know, they might just do it. + +__ http://del.icio.us/doc/api + + + +Links +----- +- `further documentation`__ +- `support and help questions`__ +- `development mailing list instructions`__ +- `suggestions`_ for SemanticScuttle +- `bug reports`_ +- `feature requests`_ +- `patches`_ + +__ http://semanticscuttle.wiki.sourceforge.net/ +__ http://sourceforge.net/forum/forum.php?forum_id=759510 +__ https://sourceforge.net/mailarchive/forum.php?forum_name=semanticscuttle-devel +.. _suggestions: http://sourceforge.net/forum/forum.php?forum_id=759511 +.. _bug reports: http://sourceforge.net/tracker/?group_id=211356&atid=1017430 +.. _feature requests: https://sourceforge.net/tracker/?group_id=211356&atid=1017433 +.. _patches: https://sourceforge.net/tracker/?group_id=211356&atid=1017432 + + + + +Known issues +============ + +Number of bookmarks always 0: "0 bookmark(s)" +--------------------------------------------- +This issue occurs when debug mode is enabled. +Technically, this is because the database layers ``DEBUG_EXTRA`` gets +enabled through debug mode. diff --git a/doc/README.txt b/doc/README.txt deleted file mode 100644 index 97387d2..0000000 --- a/doc/README.txt +++ /dev/null @@ -1,91 +0,0 @@ -SemanticScuttle 0.94 -==================== -A social bookmarking tool experimenting with new features -like structured tags or collaborative descriptions of tags. - -https://sourceforge.net/projects/semanticscuttle/ - -Available under the GNU General Public License - - -Installation ------------- -See INSTALL.txt - - -Upgrading from a previous version ---------------------------------- -See UPGRADE.txt - - -Public API ----------- -Scuttle supports most of the del.icio.us API [1]. -Almost all of the neat tools made for that system can be modified -to work with your SemanticScuttle installation. If you find a tool -that won't let you change the API address, ask the creator to add -this setting. You never know, they might just do it. - -[1] http://del.icio.us/doc/api - - -Translations ------------- -Scuttle is available in the following languages : - -English en-GB 100% (Default) -Chinese zh-CN 86% -Danish dk-DK 100% -Dutch nl-NL 68% -French fr-FR 100% -German de-DE 100% -Hindi hi-IN 100% -Italian it-IT 89% -Japanese ja-JP 100% -Lithuanian lt-LT 100% -Portuguese pt-BR 100% -Spanish es-ES 94% - -Translations are managed with gettext <includes/php-gettext>. - -To provide additional translations: -- execute of of the scripts in <includes/php-gettext/bin/> - for example to complete french (France) translation on a - GNU/Linux system, type - ./gettexts.sh fr_FR -- then edit the file <locales/fr_FR/LC_MESSAGES/messages.po> - with poedit - (that will update <locales/fr_FR/LC_MESSAGES/messages.mo>) - - -Links ------ -http://semanticscuttle.wiki.sourceforge.net/ - - further documentation - -http://sourceforge.net/forum/forum.php?forum_id=759510 - - support and help questions - -https://sourceforge.net/mailarchive/forum.php?forum_name=semanticscuttle-devel - - development mailing list instructions - -http://sourceforge.net/forum/forum.php?forum_id=759511 - - suggestions for SemanticScuttle - -http://sourceforge.net/tracker/?group_id=211356&atid=1017430 - - bug reports - -https://sourceforge.net/tracker/?group_id=211356&atid=1017433 - - feature requests - -https://sourceforge.net/tracker/?group_id=211356&atid=1017432 - - patches - - -Known issues ------------- - -Number of bookmarks always 0: "0 bookmark(s)" - This issue occurs when debug mode is enabled. - Technically, this is because the database layers DEBUG_EXTRA gets - enabled through debug mode. diff --git a/doc/UPGRADE.txt b/doc/UPGRADE.txt index 53ccbf4..1a0b964 100644 --- a/doc/UPGRADE.txt +++ b/doc/UPGRADE.txt @@ -1,266 +1,165 @@ +================================================= Upgrading SemanticScuttle from a previous version ================================================= From version 0.97 to 0.98 -------------------------- -Database updates: Apply data/schema/6.sql or do the following: - - CREATE TABLE `sc_version` ( - `schema_version` int(11) NOT NULL - ) DEFAULT CHARSET=utf8; - - INSERT INTO `sc_version` (`schema_version`) VALUES ('6'); +========================= +Database updates +---------------- +Apply ``data/schema/6.sql`` ALTER TABLE `sc_users` ADD `privateKey` VARCHAR(33) NULL; CREATE UNIQUE INDEX `privateKey` ON `sc_users` (`privateKey`); From version 0.96 to 0.97 -------------------------- +========================= No database changes necessary. From version 0.95 to 0.96 -------------------------- -Update your database: -- ALTER TABLE `sc_bookmarks` ADD `bShort` VARCHAR(16) NULL DEFAULT NULL; +========================= +Database updates +---------------- +Apply ``data/schema/5.sql`` -API: -The method signatures of addBookmark() and updateBookmark() -changed due to the addition of the $short parameter. +API +--- +The method signatures of ``addBookmark()`` and ``updateBookmark()`` +changed due to the addition of the ``$short`` parameter. We got complaints about the changed file structure, and people told -us that they just cannot set the document root to www/, because they -are not admins on their http server. This is a valid point, and -with 0.96.0 you can easily change it. See INSTALL.txt for more information -about moving www/. +us that they just cannot set the document root to ``www/``, because they +are not admins on their HTTP server. This is a valid point, and +with 0.96.0 you can easily change it. See `INSTALL.txt`_ for more information +about moving ``www/``. + +.. _INSTALL.txt: INSTALL.html From version 0.94 to 0.95 --------------------------- +========================= The file structure completely changed in 0.95.0 compared to previous versions. We recommend that you start with a -fresh installation, just copying over your config.php file. -Set your web server document root directory to www/. +fresh installation, just copying over your ``config.php`` file. +Set your web server document root directory to ``www/``. Yes, we kind of lost the ability to run SemanticScuttle in a subdirectory of a hostname. This functionality will be back in one of the next releases, but for now, you have to live with it. -Update your database: -- ALTER TABLE `sc_bookmarks` ADD `bVoting` INT NOT NULL; -- ALTER TABLE `sc_bookmarks` ADD `bVotes` INT NOT NULL; -- Add the new votes database table. See data/tables.sql. +Update your database +-------------------- +Apply ``data/schema/4.sql``. Currently, only MySQL can be used as database backend. All other DBMS (database management systems) have not been tested except for PostgreSQL, and SemanticScuttle fails there. -The de_AT translation has been re-added. This is because -de_AT provides a rather ugly "official German" style, -while the normal de_DE is friendlier. Choose what you like. +Translation +----------- +The ``de_AT`` translation has been re-added. This is because +``de_AT`` provides a rather ugly "official German" style, +while the normal ``de_DE`` is friendlier. Choose what you like. From version 0.93 to 0.94 -------------------------- +========================= - Nothing changed except for the default configuration file. It is recommended to start with a fresh config file, but not neccesary. Old config files still work. -- If you used translation de_AT, please switch to de_DE. - de_AT was moved to de_DE and de_AT has been removed. +- If you used translation ``de_AT``, please switch to ``de_DE``. + ``de_AT`` was moved to ``de_DE`` and ``de_AT`` has been removed. From version 0.92 to 0.93 -------------------------- +========================= - Backup your database - Make a copy from your SemanticScuttle Web directory -- Upgrade your database by following instructions ONE after ONE (order is important) : -#NOTHING TO CHANGE IN DB -- Upgrade your current configuration file (config.inc.php) with respect to config.inc.php.example -$footerMessage = ''; #HTML message appearing at the bottom of the page (just above SemanticScuttle credits) -$sidebarTopMessage = ''; #HTML message appearing at the top of the sidebar -$sidebarBottomMessage = ''; #HTML message appearing at the bottom of the sidebar -$adminsCanModifyBookmarksFromOtherUsers = true; # 'true' if admin users can edit or delete bookmarks belonging to other users. Else 'false'. -$adminsAreAdvisedTagsFromOtherAdmins = false; # 'true' if tags from other admins are proposed to each admin (in add/edit a bookmark page). Else 'false'. -$defaultPerPageForAdmins = 20; # default number of bookmarks per page for admins (-1 means no limit) +- Upgrade your current configuration file (``config.inc.php``) with respect to ``config.inc.php.example`` :: + + $footerMessage = ''; #HTML message appearing at the bottom of the page (just above SemanticScuttle credits) + $sidebarTopMessage = ''; #HTML message appearing at the top of the sidebar + $sidebarBottomMessage = ''; #HTML message appearing at the bottom of the sidebar + $adminsCanModifyBookmarksFromOtherUsers = true; # 'true' if admin users can edit or delete bookmarks belonging to other users. Else 'false'. + $adminsAreAdvisedTagsFromOtherAdmins = false; # 'true' if tags from other admins are proposed to each admin (in add/edit a bookmark page). Else 'false'. + $defaultPerPageForAdmins = 20; # default number of bookmarks per page for admins (-1 means no limit) From version 0.91 to 0.92 -------------------------- +========================= Message: this version modifies the database to UTF-8 charset. The idea is to convert the content (through BLOB type) and then to change the tables' charsets. - Backup your database - Make a copy from your SemanticScuttle Web directory -- Upgrade your database by following instructions ONE after ONE (order is important) : - -/* modify and add fields */ -ALTER TABLE `sc_bookmarks` MODIFY `bAddress` varchar(1500) NOT NULL; -ALTER TABLE `sc_bookmarks` MODIFY `bDescription` TEXT default NULL; -ALTER TABLE `sc_bookmarks` ADD `bPrivateNote` TEXT NULL AFTER `bDescription` ; -ALTER TABLE `sc_tags` MODIFY `tDescription` TEXT default NULL; -ALTER TABLE `sc_commondescription` MODIFY `cdDescription` TEXT default NULL; - -/* convert to UTF-8 if your table is ISO-something (through BLOB: tips provided by MYSQL documentation)*/ -/* first need to remove index keys because of BLOB constraints*/ -ALTER TABLE `sc_tags` DROP INDEX `sc_tags_tag_uId`; -ALTER TABLE `sc_bookmarks2tags` DROP INDEX `sc_bookmarks2tags_tag_bId`; -ALTER TABLE `sc_bookmarks2tags` DROP INDEX `sc_bookmarks2tags_bId`; -ALTER TABLE `sc_tags2tags` DROP INDEX `sc_tags2tags_tag1_tag2_uId`; -ALTER TABLE `sc_commondescription` DROP INDEX `sc_commondescription_tag_datetime`; -ALTER TABLE `sc_tagscache` DROP INDEX `sc_tagscache_tag1_tag2_type_uId`; -ALTER TABLE `sc_tagsstats` DROP INDEX `sc_tagsstats_tag1_type_uId`; - -/* secondly convert through BLOB type */ -ALTER TABLE `sc_bookmarks` CHANGE `bTitle` `bTitle` BLOB; -ALTER TABLE `sc_bookmarks` CHANGE `bTitle` `bTitle` varchar(255) CHARACTER SET utf8; -ALTER TABLE `sc_bookmarks` CHANGE `bAddress` `bAddress` BLOB; -ALTER TABLE `sc_bookmarks` CHANGE `bAddress` `bAddress` varchar(1500) CHARACTER SET utf8; -ALTER TABLE `sc_bookmarks` CHANGE `bDescription` `bDescription` BLOB; -ALTER TABLE `sc_bookmarks` CHANGE `bDescription` `bDescription` text CHARACTER SET utf8; -ALTER TABLE `sc_bookmarks` CHANGE `bPrivateNote` `bPrivateNote` BLOB; -ALTER TABLE `sc_bookmarks` CHANGE `bPrivateNote` `bPrivateNote` text CHARACTER SET utf8; - -ALTER TABLE `sc_tags` CHANGE `tag` `tag` BLOB; -ALTER TABLE `sc_tags` CHANGE `tag` `tag` varchar(100) CHARACTER SET utf8; -ALTER TABLE `sc_tags` CHANGE `tDescription` `tDescription` BLOB; -ALTER TABLE `sc_tags` CHANGE `tDescription` `tDescription` text CHARACTER SET utf8; - -ALTER TABLE `sc_bookmarks2tags` CHANGE `tag` `tag` BLOB; -ALTER TABLE `sc_bookmarks2tags` CHANGE `tag` `tag` varchar(100) CHARACTER SET utf8; - -ALTER TABLE `sc_users` CHANGE `name` `name` BLOB; -ALTER TABLE `sc_users` CHANGE `name` `name` varchar(50) CHARACTER SET utf8; -ALTER TABLE `sc_users` CHANGE `uContent` `uContent` BLOB; -ALTER TABLE `sc_users` CHANGE `uContent` `uContent` text CHARACTER SET utf8; - -ALTER TABLE `sc_tags2tags` CHANGE `tag1` `tag1` BLOB; -ALTER TABLE `sc_tags2tags` CHANGE `tag1` `tag1` varchar(100) CHARACTER SET utf8; -ALTER TABLE `sc_tags2tags` CHANGE `tag2` `tag2` BLOB; -ALTER TABLE `sc_tags2tags` CHANGE `tag2` `tag2` varchar(100) CHARACTER SET utf8; - -ALTER TABLE `sc_tagsstats` CHANGE `tag1` `tag1` BLOB; -ALTER TABLE `sc_tagsstats` CHANGE `tag1` `tag1` varchar(100) CHARACTER SET utf8; - -ALTER TABLE `sc_tagscache` CHANGE `tag1` `tag1` BLOB; -ALTER TABLE `sc_tagscache` CHANGE `tag1` `tag1` varchar(100) CHARACTER SET utf8; -ALTER TABLE `sc_tagscache` CHANGE `tag2` `tag2` BLOB; -ALTER TABLE `sc_tagscache` CHANGE `tag2` `tag2` varchar(100) CHARACTER SET utf8; - -ALTER TABLE `sc_commondescription` CHANGE `tag` `tag` BLOB; -ALTER TABLE `sc_commondescription` CHANGE `tag` `tag` varchar(100) CHARACTER SET utf8; -ALTER TABLE `sc_commondescription` CHANGE `cdTitle` `cdTitle` BLOB; -ALTER TABLE `sc_commondescription` CHANGE `cdTitle` `cdTitle` varchar(255) CHARACTER SET utf8; -ALTER TABLE `sc_commondescription` CHANGE `cdDescription` `cdDescription` BLOB; -ALTER TABLE `sc_commondescription` CHANGE `cdDescription` `cdDescription` text CHARACTER SET utf8; - -ALTER TABLE `sc_searchhistory` CHANGE `shTerms` `shTerms` BLOB; -ALTER TABLE `sc_searchhistory` CHANGE `shTerms` `shTerms` varchar(255) CHARACTER SET utf8; -ALTER TABLE `sc_searchhistory` CHANGE `shRange` `shRange` BLOB; -ALTER TABLE `sc_searchhistory` CHANGE `shRange` `shRange` varchar(32) CHARACTER SET utf8; - -/* Thirdly re-add index keys */ -ALTER TABLE `sc_tags` ADD UNIQUE KEY `sc_tags_tag_uId` (`tag`, `uId`); -ALTER TABLE `sc_bookmarks2tags` ADD UNIQUE KEY `sc_bookmarks2tags_tag_bId` (`tag`,`bId`); -ALTER TABLE `sc_bookmarks2tags` ADD KEY `sc_bookmarks2tags_bId` (`bId`); -ALTER TABLE `sc_tags2tags` ADD UNIQUE KEY `sc_tags2tags_tag1_tag2_uId` (`tag1`,`tag2`,`relationType`,`uId`); -ALTER TABLE `sc_commondescription` ADD UNIQUE KEY `sc_commondescription_tag_datetime` (`tag`,`cdDatetime`); -ALTER TABLE `sc_tagscache` ADD UNIQUE KEY `sc_tagscache_tag1_tag2_type_uId` (`tag1`,`tag2`,`relationType`,`uId`); -ALTER TABLE `sc_tagsstats` ADD UNIQUE KEY `sc_tagsstats_tag1_type_uId` (`tag1`,`relationType`,`uId`); - -/* Change tables to utf-8 charset */ -ALTER TABLE `sc_bookmarks` CHARACTER SET utf8 COLLATE utf8_general_ci; -ALTER TABLE `sc_tags` CHARACTER SET utf8 COLLATE utf8_general_ci; -ALTER TABLE `sc_bookmarks2tags` CHARACTER SET utf8 COLLATE utf8_general_ci; -ALTER TABLE `sc_users` CHARACTER SET utf8 COLLATE utf8_general_ci; -ALTER TABLE `sc_watched` CHARACTER SET utf8 COLLATE utf8_general_ci; -ALTER TABLE `sc_tags2tags` CHARACTER SET utf8 COLLATE utf8_general_ci; -ALTER TABLE `sc_tagsstats` CHARACTER SET utf8 COLLATE utf8_general_ci; -ALTER TABLE `sc_tagscache` CHARACTER SET utf8 COLLATE utf8_general_ci; -ALTER TABLE `sc_commondescription` CHARACTER SET utf8 COLLATE utf8_general_ci; -ALTER TABLE `sc_searchhistory` CHARACTER SET utf8 COLLATE utf8_general_ci; +- Upgrade your database by applying ``data/schema/3.sql`` +- Upgrade your current configuration file (``config.inc.php``) with respect to ``config.inc.php.example`` -- Upgrade your current configuration file (config.inc.php) with respect to config.inc.php.example -* Add variable : $descriptionAnchors = array("author", "isbn", "address"=>"[address][street][/street][city][/city][/address]"); #add a possible anchor (structured content) for bookmarks' description field -* Add variable : $enableCommonTagDescriptionEditedByAll = true; #true mean everybody can edit common description. Else just the admins can do it. -* Add variable : $googleAnalyticsCode = ''; #Allow GoogleAnalytics tracker https://www.google.com/analytics/ + - Add variable :: + + $descriptionAnchors = array("author", "isbn", "address"=>"[address][street][/street][city][/city][/address]"); #add a possible anchor (structured content) for bookmarks' description field + + - Add variable :: + + $enableCommonTagDescriptionEditedByAll = true; #true mean everybody can edit common description. Else just the admins can do it. + - Add variable :: + + $googleAnalyticsCode = ''; #Allow GoogleAnalytics tracker https://www.google.com/analytics/ From version 0.90 to 0.91 -------------------------- +========================= - Backup you database - Make a copy from your SemanticScuttle Web directory -- Upgrade your database by following instructions ONE after ONE (order is important) : - * ALTER TABLE `sc_bookmarks` CHANGE `bDescription` `bDescription` VARCHAR( 1500 ) - * CREATE TABLE `sc_tagscache` ( - `tcId` int(11) NOT NULL auto_increment, - `tag1` varchar(100) NOT NULL default '', - `tag2` varchar(100) NOT NULL default '', - `relationType` varchar(32) NOT NULL default '', - `uId` int(11) NOT NULL default '0', - PRIMARY KEY (`tcId`), - UNIQUE KEY `sc_tagscache_tag1_tag2_type_uId` (`tag1`,`tag2`,`relationType`,`uId`) -); -- Upgrade your current configuration file (config.inc.php) with respect to config.inc.php.example - * Delete last line : include_once('debug.inc.php'); - * Add variable: $menu2Tags = array('example', 'of', 'menu', 'tags'); - * Add variable: $debugMode = true; # if true, show debug messages +- Upgrade your database by applying ``data/schema/2.sql`` +- Upgrade your current configuration file (``config.inc.php``) with respect to ``config.inc.php.example`` + - Delete last line :: -From version 0.89 to 0.90 -------------------------- + include_once('debug.inc.php'); -- Backup you database -- Make a copy from your SemanticScuttle Web directory + - Add variable:: -- Upgrade your current configuration file (config.inc.php) with respect to config.inc.php.example -# add these lines under $enableWebsiteThumbnails = false; # enableWebsiteThumbnails {true|false}: -$thumbnailsUserId = ''; -$thumbnailsKey = ''; + $menu2Tags = array('example', 'of', 'menu', 'tags'); + - Add variable:: + $debugMode = true; # if true, show debug messages -From version 0.88 to 0.89 -------------------------- + +From version 0.89 to 0.90 +========================= - Backup you database - Make a copy from your SemanticScuttle Web directory -- Upgrade your database by following instructions ONE after ONE (order is important) : +- Upgrade your current configuration file (config.inc.php) with respect to config.inc.php.example -* change the table called 'sc_tags' into 'sc_bookmarks2tags' by executing the following SQL commands (after changing 'yourdatabasename' and adapting its name prefix 'sc_' to your convenience): + add these lines under ``$enableWebsiteThumbnails = false; # enableWebsiteThumbnails {true|false}``:: - RENAME TABLE `yourdatabasename`.`sc_tags` TO `yourdatabasename`.`sc_bookmarks2tags` ; + $thumbnailsUserId = ''; + $thumbnailsKey = ''; -* add the following table (adapt its name prefix to your convenience) executing the following SQL commands: +From version 0.88 to 0.89 +========================= - CREATE TABLE `sc_searchhistory` ( - `shId` int(11) NOT NULL auto_increment, - `shTerms` varchar(255) NOT NULL default '', - `shRange` varchar(32) NOT NULL default '', - `shDatetime` datetime NOT NULL default '0000-00-00 00:00:00', - `shNbResults` int(6) NOT NULL default '0', - `uId` int(11) NOT NULL default '0', - PRIMARY KEY (`shId`) - ); +- Backup you database +- Make a copy from your SemanticScuttle Web directory +- Upgrade your database by applying ``data/schema/1.sql`` +- Upgrade your current configuration file (``config.inc.php``) with respect to ``config.inc.php.example`` - CREATE TABLE `sc_tags` ( - `tId` int(11) NOT NULL auto_increment, - `tag` varchar(32) NOT NULL default '', - `uId` int(11) NOT NULL default '0', - `tDescription` varchar(255) default NULL, - PRIMARY KEY (`tId`), - UNIQUE KEY `sc_tags_tag_uId` (`tag`, `uId`) - ); + - add line:: -- Upgrade your current configuration file (config.inc.php) with respect to config.inc.php.example - # add line: $sizeSearchHistory = 10; - # add sidebar block index line: + + - add sidebar block index line:: + $index_sidebar_blocks = array('search','menu','users','popular'); - # add line: + + - add line:: $enableGoogleCustomSearch = true; diff --git a/doc/authentication.rst b/doc/authentication.rst new file mode 100644 index 0000000..c3ccb47 --- /dev/null +++ b/doc/authentication.rst @@ -0,0 +1,213 @@ +============================================ +External authentication with SemanticScuttle +============================================ + +Most times, one piece of software is only a part in the big puzzle +that makes the software landscape of a company or organization. +SemanticScuttle is not different and should integrate as nicely as +possible with all other systems. + +One of the basic tasks of integration is user authentication against +a central database - be it a central user database, an LDAP or a +active directory server. + +Since version 0.96, SemanticScuttle supports user authentication against +external systems. To provide a wide range of supported systems, we chose +to utilize PEAR's `Authentication package`__. +It does this by providing different "`authentication containers`__", +for example Database, IMAP, LDAP, POP3, RADIUS, SAP and SOAP. + +Please be aware of the fact that, after successful authentication, the user +and his scrambled password are stored in the SemanticScuttle database. +This is required for proper functioning of the software. It does not mean +that you will be able to login if your external authentication provider +is offline - you won't, execpt you switch it off in the SemanticScuttle +configuration. + + +__ http://pear.php.net/package/Auth +__ http://pear.php.net/manual/en/package.authentication.auth.intro-storage.php + + +Basic configuration +=================== +The default configuration file ``data/config.default.php`` has an own section +on auth options and an explanation of the single entries. + +To utilize the external authentication, you need to install the +PEAR Auth package: :: + + $ pear install auth + +If you do not have a PEAR installation available, you can try to manually +install the files in the src/ directory. If you choose to do that, the +src/ directory should look similar to that: :: + + src/ + Auth.php + Auth/ + Anonymous.php + Container.php + Container/ + .. + SemanticScuttle/ + header.php + .. + +After that, modify your ``data/config.php`` file. The most important change +is to use :: + + $serviceoverrides['User'] = 'SemanticScuttle_Service_AuthUser'; + +which tells SemanticScuttle to switch to the special authentication service. + +Now that's done, you can configure the single auth options: + +``$authType = 'MDB2';`` + selects the authentication container. + +``$authOptions`` + is an array of options specific to the authentication container. Please + consult the PEAR Auth documentation for more information. + +``$authDebug = true;`` + should be used when setup fails, since it may give important hints + where it fails. + + Please note that login will seem to fail with + debugging activated. Going back to the main page after that will + show that you are logged in. + + + +Authentication examples +======================= + +General database authentification +--------------------------------- +Here you also need the PEAR `MDB2 package`_. +The "``new_link``" option is important! + +``config.php`` settings: :: + + $serviceoverrides['User'] = 'SemanticScuttle_Service_AuthUser'; + $authType = 'MDB2'; + $authOptions = array( + 'dsn' => array( + 'phptype' => 'mysql', + 'hostspec' => 'FIXME', + 'username' => 'FIXME', + 'password' => 'FIXME', + 'database' => 'FIXME', + 'new_link' => true, + ), + 'table' => 'usersFIXME', + 'usernamecol' => 'usernameFIXME', + 'passwordcol' => 'passwordFIXME', + 'cryptType' => 'md5', + ); + + +Mantis Bugtracker +----------------- +Here you also need the PEAR `MDB2 package`_. + +``config.php`` settings: :: + + $serviceoverrides['User'] = 'SemanticScuttle_Service_AuthUser'; + $authType = 'MDB2'; + $authOptions = array( + 'dsn' => array( + 'phptype' => 'mysql', + 'hostspec' => 'FIXME', + 'username' => 'FIXME', + 'password' => 'FIXME', + 'database' => 'FIXME', + 'new_link' => true, + ), + 'table' => 'mantis_user_table', + 'usernamecol' => 'username', + 'passwordcol' => 'password', + 'cryptType' => 'md5', + ); + +.. _MDB2 package: http://pear.php.net/package/MDB2 + + +MediaWiki +--------- +Unfortunately, the password column does not contain a simple hashed +password - for good reasons as described on +http://www.mediawiki.org/wiki/Manual_talk:User_table#user_password_column + +If you configure your MediaWiki_ to use passwords without salt, you +can make it work nevertheless: + +MediaWiki ``LocalSettings.php``: :: + + $wgPasswordSalt = false; + +\- after that, users need to change/update their passwords to get them +unsalted in the database. You can verify if the passwords are unhashed +if you do :: + + SELECT CAST( user_password AS CHAR ) FROM user + +on your MediaWiki database. Passwords prefixed with "``:A:``" can be used. + +Another problem is that mediawiki user names begin with an uppercase letter. +You need to modify ``www/login.php`` and remove the "``utf8_strtolower``" function +call: :: + + $posteduser = trim(utf8_strtolower(POST_USERNAME)); + +becomes :: + + $posteduser = trim(POST_USERNAME); + + +``config.php`` settings: :: + + $serviceoverrides['User'] = 'SemanticScuttle_Service_AuthUser'; + $authType = 'MDB2'; + $authOptions = array( + 'dsn' => array( + 'phptype' => 'mysql', + 'hostspec' => 'FIXME', + 'username' => 'FIXME', + 'password' => 'FIXME', + 'database' => 'FIXME', + 'new_link' => true, + ), + 'table' => 'user', + 'usernamecol' => 'user_name', + 'passwordcol' => 'user_password', + 'cryptType' => 'md5_mediawiki', + ); + function md5_mediawiki($password) { + return ':A:' . md5($password); + } + + +.. _MediaWiki: http://www.mediawiki.org/wiki/MediaWiki + +Active Directory / LDAP +----------------------- +Here we authenticate against an active directory server. + +``config.php`` settings: :: + + $serviceoverrides['User'] = 'SemanticScuttle_Service_AuthUser'; + $authType = 'LDAP'; + $authOptions = array( + 'host' => '192.168.1.4', + 'version' => 3, + 'basedn' => 'DC=EXAMPLE,DC=ORG', + 'binddn' => 'readuser', + 'bindpw' => 'readuser', + 'userattr' => 'sAMAccountName', + 'userfilter' => '(objectClass=user)', + 'attributes' => array(''), + ); + $authEmailSuffix = '@example.org'; + diff --git a/doc/authentication.txt b/doc/authentication.txt deleted file mode 100644 index da49e5a..0000000 --- a/doc/authentication.txt +++ /dev/null @@ -1,197 +0,0 @@ -External authentication with SemanticScuttle -============================================ - -Most times, one piece of software is only a part in the big puzzle -that makes the software landscape of a company or organization. -SemanticScuttle is not different and should integrate as nicely as -possible with all other systems. - -One of the basic tasks of integration is user authentication against -a central database - be it a central user database, an LDAP or a -active directory server. - -Since version 0.96, SemanticScuttle supports user authentication against -external systems. To provide a wide range of supported systems, we chose -to utilize PEAR's Authentication package [1]. -It does this by providing different "authentication containers" [2], -for example Database, IMAP, LDAP, POP3, RADIUS, SAP and SOAP. - -Please be aware of the fact that, after successful authentication, the user -and his scrambled password are stored in the SemanticScuttle database. -This is required for proper functioning of the software. It does not mean -that you will be able to login if your external authentication provider -is offline - you won't, execpt you switch it off in the SemanticScuttle -configuration. - - -[1] http://pear.php.net/package/Auth -[2] http://pear.php.net/manual/en/package.authentication.auth.intro-storage.php - - -Basic configuration -=================== -The default configuration file data/config.default.php has an own section -on auth options and an explanation of the single entries. - -To utilize the external authentication, you need to install the -PEAR Auth package: - $ pear install auth -If you do not have a PEAR installation available, you can try to manually -install the files in the src/ directory. If you choose to do that, the -src/ directory should look similar to that: - - src/ - Auth.php - Auth/ - Anonymous.php - Container.php - Container/ - .. - SemanticScuttle/ - header.php - .. - -After that, modify your data/config.php file. The most important change -is to use - $serviceoverrides['User'] = 'SemanticScuttle_Service_AuthUser'; -which tells SemanticScuttle to switch to the special authentication service. - -Now that's done, you can configure the single auth options: - $authType = 'MDB2'; -selects the authentication container. - - $authOptions -is an array of options specific to the authentication container. Please -consult the PEAR Auth documentation for more information. - - $authDebug = true; -should be used when setup fails, since it may give important hints -where it fails. Please note that login will seem to fail with -debugging activated. Going back to the main page after that will -show that you are logged in. - - - -Authentication examples -======================= - -General database authentification ---------------------------------- -Here you also need the PEAR MDB2 package. -The "new_link" option is important! - -config.php settings: --8<------------------ -$serviceoverrides['User'] = 'SemanticScuttle_Service_AuthUser'; -$authType = 'MDB2'; -$authOptions = array( - 'dsn' => array( - 'phptype' => 'mysql', - 'hostspec' => 'FIXME', - 'username' => 'FIXME', - 'password' => 'FIXME', - 'database' => 'FIXME', - 'new_link' => true, - ), - 'table' => 'usersFIXME', - 'usernamecol' => 'usernameFIXME', - 'passwordcol' => 'passwordFIXME', - 'cryptType' => 'md5', -); --8<------------------ - - -Mantis Bugtracker ------------------ -Here you also need the PEAR MDB2 package. - -config.php settings: --8<------------------ -$serviceoverrides['User'] = 'SemanticScuttle_Service_AuthUser'; -$authType = 'MDB2'; -$authOptions = array( - 'dsn' => array( - 'phptype' => 'mysql', - 'hostspec' => 'FIXME', - 'username' => 'FIXME', - 'password' => 'FIXME', - 'database' => 'FIXME', - 'new_link' => true, - ), - 'table' => 'mantis_user_table', - 'usernamecol' => 'username', - 'passwordcol' => 'password', - 'cryptType' => 'md5', -); --8<------------------ - - -MediaWiki ---------- -Unfortunately, the password column does not contain a simple hashed -password - for good reasons as described on -http://www.mediawiki.org/wiki/Manual_talk:User_table#user_password_column - -If you configure your mediawiki to use passwords without salt, you -can make it work nevertheless: - -MediaWiki LocalSettings.php: - $wgPasswordSalt = false; -- after that, users need to change/update their passwords to get them -unsalted in the database. You can verify if the passwords are unhashed -if you do - SELECT CAST( user_password AS CHAR ) FROM user -on your MediaWiki database. Passwords prefixed with ":A:" can be used. - -Another problem is that mediawiki user names begin with an uppercase letter. -You need to modify www/login.php and remove the "utf8_strtolower" function -call: - $posteduser = trim(utf8_strtolower(POST_USERNAME)); -becomes - $posteduser = trim(POST_USERNAME); - - -config.php settings: --8<------------------ -$serviceoverrides['User'] = 'SemanticScuttle_Service_AuthUser'; -$authType = 'MDB2'; -$authOptions = array( - 'dsn' => array( - 'phptype' => 'mysql', - 'hostspec' => 'FIXME', - 'username' => 'FIXME', - 'password' => 'FIXME', - 'database' => 'FIXME', - 'new_link' => true, - ), - 'table' => 'user', - 'usernamecol' => 'user_name', - 'passwordcol' => 'user_password', - 'cryptType' => 'md5_mediawiki', -); -function md5_mediawiki($password) { - return ':A:' . md5($password); -} --8<------------------ - - -Active Directory / LDAP ------------------------ -Here we authenticate against an active directory server. - -config.php settings: --8<------------------ -$serviceoverrides['User'] = 'SemanticScuttle_Service_AuthUser'; -$authType = 'LDAP'; -$authOptions = array( - 'host' => '192.168.1.4', - 'version' => 3, - 'basedn' => 'DC=EXAMPLE,DC=ORG', - 'binddn' => 'readuser', - 'bindpw' => 'readuser', - 'userattr' => 'sAMAccountName', - 'userfilter' => '(objectClass=user)', - 'attributes' => array(''), -); -$authEmailSuffix = '@example.org'; --8<------------------ diff --git a/doc/developers/TODO b/doc/developers/TODO.rst index 59dd655..59dd655 100644 --- a/doc/developers/TODO +++ b/doc/developers/TODO.rst diff --git a/doc/developers/api b/doc/developers/api.rst index efa05fe..efa05fe 100644 --- a/doc/developers/api +++ b/doc/developers/api.rst 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('', <<<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/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 b/doc/developers/doc-TODO.rst index 4fac4ab..4fac4ab 100644 --- a/doc/developers/doc-TODO +++ b/doc/developers/doc-TODO.rst diff --git a/doc/developers/release-new-version b/doc/developers/release-new-version.rst index 4b2540a..4b2540a 100644 --- a/doc/developers/release-new-version +++ b/doc/developers/release-new-version.rst diff --git a/doc/developers/rules b/doc/developers/rules.rst index 701a215..701a215 100644 --- a/doc/developers/rules +++ b/doc/developers/rules.rst 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..8b0fa0d --- /dev/null +++ b/doc/developers/running-unit-tests.rst @@ -0,0 +1,26 @@ +Running unit tests +================== + +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 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..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. + + diff --git a/doc/index.rst b/doc/index.rst new file mode 100644 index 0000000..1b8feea --- /dev/null +++ b/doc/index.rst @@ -0,0 +1,45 @@ +============================= +SemanticScuttle documentation +============================= + + +First reads +=========== +- README_ +- `installation guide`_ +- `upgrade instructions`_ + +.. _README: README.html +.. _installation guide: INSTALL.html +.. _upgrade instructions: UPGRADE.html + + + +Features +======== +- `Custom user authentication`__ +- `SSL Client certificates`__ +- Themes__ + +__ authentication.html +__ 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`__ + +__ developers/rules.html +__ developers/api.html +__ developers/debugging.html +__ developers/release-new-version.html +__ developers/running-unit-tests.html +__ developers/translation.html + diff --git a/doc/themes.rst b/doc/themes.rst new file mode 100644 index 0000000..6f34a36 --- /dev/null +++ b/doc/themes.rst @@ -0,0 +1,48 @@ +====================== +SemanticScuttle Themes +====================== +SemanticScuttle may be changed visually by supplying custom "themes" (skins) +that modify the visual appearance. + + +Changing the current theme +========================== +In ``data/config.php``, set your theme like this: :: + + $theme = 'darkmood'; + +The available themes are the folders in ``www/themes/``. +By default, SemanticScuttle ships only one usable theme ("default") and one +to demonstrate how to create your own theme ("testdummy"). + + +Creating your own theme +======================= +Have a look at the "testdummy" theme in ``www/themes/testdummy/``. + +CSS and image files +------------------- +Since both file types need to be accessible via the web server directly, +they are located in the ``www/`` folder: :: + + www/themes/$themename/ + +The main CSS file that automatically gets included is :: + + www/themes/$themename/scuttle.css + +Several template files in SemanticScuttle include image files. If they do not +exist in your theme, the default ones are used automatically. +Note that this is not true for images that are specified in the CSS files. + + +Template files +-------------- +The templates of the default file are located in :: + + data/templates/default/ + +You may put your theme template files into :: + + data/templates/$themename/ + |