| Index: trunk/extensions/SemanticMediaWiki/INSTALL |
| — | — | @@ -1,4 +1,4 @@ |
| 2 | | -[[Semantic MediaWiki 1.5.6]] |
| | 2 | +[[Semantic MediaWiki 1.6-beta]] |
| 3 | 3 | |
| 4 | 4 | Install instructions for the latest SMW version are also online in a more |
| 5 | 5 | convenient format for reading: |
| — | — | @@ -52,10 +52,10 @@ |
| 53 | 53 | SMW was set up. The script SMW_setup.php can use the DB credentials from |
| 54 | 54 | AdminSettings.php for this purpose, avoiding the need of extra rights for |
| 55 | 55 | the wiki DB user. |
| 56 | | -* SMW creates and alters temporary tables for certain semantic queries. To do |
| 57 | | - this, your wikidb user must have privileges for CREATE TEMPORARY TABLES. The |
| 58 | | - according features can be disabled by adding the following to |
| 59 | | - Localsettings.php: |
| | 56 | +* When using SMWSQLStore2 (default data store for SMW), SMW creates and alters |
| | 57 | + temporary tables for certain semantic queries. To do this, your wikidb user |
| | 58 | + must have privileges for CREATE TEMPORARY TABLES. The according features can |
| | 59 | + be disabled by adding the following to Localsettings.php: |
| 60 | 60 | |
| 61 | 61 | $smwgQSubcategoryDepth=0; |
| 62 | 62 | $smwgQPropertyDepth=0; |
| — | — | @@ -63,7 +63,10 @@ |
| 64 | 64 | $smwgQConceptFeatures = SMW_ANY_QUERY & ~SMW_DISJUNCTION_QUERY & |
| 65 | 65 | ~SMW_CONCEPT_QUERY; |
| 66 | 66 | |
| | 67 | +* When using SMWSparqlStore (RDF store connector), SMW uses the CURL functions |
| | 68 | + of PHP. These functions may have to be enabled/installed to be available. |
| 67 | 69 | |
| | 70 | + |
| 68 | 71 | == Installation == |
| 69 | 72 | |
| 70 | 73 | If you upgrade an existing installation of Semantic MediaWiki, also read the |
| — | — | @@ -88,21 +91,23 @@ |
| 89 | 92 | Afterwards, activate the automatic data update ("Data repair and upgrade"). |
| 90 | 93 | Note that the first step requires permissions to alter/create database |
| 91 | 94 | tables, as explained in the above note. The second step takes some time; |
| 92 | | - go to Special:SMWAdmin to follow its progress. SMW can be used before this |
| 93 | | - completes, but will not have access to all data yet (e.g. page categories). |
| | 95 | + go to Special:SMWAdmin to follow its progress. SMW can be used before this |
| | 96 | + completes, but will not have access to all data yet (e.g. page categories). |
| 94 | 97 | |
| 95 | | - Both of those actions can also be accomplished with the command-line PHP |
| 96 | | - scripts SMW_setup.php and SMW_refreshData.php. Read the documentation in |
| 97 | | - [SMW_path]/maintenance/README for details on how to run such scripts. |
| | 98 | + Both of those actions can also be accomplished with the command-line PHP |
| | 99 | + scripts SMW_setup.php and SMW_refreshData.php. Read the documentation in |
| | 100 | + [SMW_path]/maintenance/README for details on how to run such scripts. |
| 98 | 101 | |
| 99 | 102 | '''Remark:''' Semantic MediaWiki uses ten additional namespace indexes (see |
| 100 | 103 | http://www.mediawiki.org/wiki/Manual:Using_custom_namespaces), in the range from |
| 101 | | -100 to 109. 100 and 101 are not used (they were used in early beta versions). |
| 102 | | -106 and 107 are reserved for the SemanticForms extension. If you have your own |
| 103 | | -custom namespaces, you have to set the parameter $smwgNamespaceIndex before |
| 104 | | -including SemanticMediaWiki.php. See the documentation $within SMW_Settings.php for |
| 105 | | -details. If you add more namespaces later on, then you have to assign them to |
| 106 | | -higher numbers than those used by Semantic MediaWiki. |
| | 104 | +100 to 109. 100 and 101 are not used (they were used in early beta versions), |
| | 105 | +104 and 105 are not used by default (they were used for the Type namespace in |
| | 106 | +SMW up to 1.5.*). 106 and 107 are reserved for the SemanticForms extension. If |
| | 107 | +you have your own custom namespaces, you have to set the parameter |
| | 108 | +$smwgNamespaceIndex before including SemanticMediaWiki.php. See the |
| | 109 | +documentation $within SMW_Settings.php for details. If you add more namespaces |
| | 110 | +later on, then you have to assign them to higher numbers than those used by |
| | 111 | +Semantic MediaWiki. |
| 107 | 112 | |
| 108 | 113 | |
| 109 | 114 | === Testing your Installation === |
| — | — | @@ -143,11 +148,19 @@ |
| 144 | 149 | |
| 145 | 150 | (Please read all of this before upgrading) |
| 146 | 151 | |
| 147 | | -Installations of SMW 1.5.* can be upgraded by just replacing the files, and all |
| 148 | | -extensions compatible with SMW 1.5.1 should work without modification. If |
| 149 | | -problems occur, it is possible to go back to 1.5.1 by simply using the old |
| 150 | | -files, waiting with the upgrade until the relevant extensions provide updates. |
| | 152 | +Installations of SMW 1.5.* and can be upgraded by replacing the files, and by |
| | 153 | +running the database update (Special:SMWAdmin or SMW_setup.php script) as usual. |
| | 154 | +Moreover, it is strongly suggested to enable the refresh process to update all |
| | 155 | +data on Special:SMWAdmin. Older versions of SMW can be upgraded in the same way, |
| | 156 | +but there can be more feature chagnes that require changes of wiki pages. See |
| | 157 | +the current documentation for details on using the current version. |
| 151 | 158 | |
| | 159 | +Extensions for SMW versions up to 1.5.* should not be assumed to work |
| | 160 | +with SMW 1.6 out of the box. All SMW extensions should be upgraded to versions |
| | 161 | +that are compatible with SMW 1.6. Moreover, some functions changed and pages |
| | 162 | +might need updates (see sbelow). Additional remarks on upgrading older SMW |
| | 163 | +versions are given below. |
| | 164 | + |
| 152 | 165 | If not done already, it is suggested to change the inclusion of SMW in |
| 153 | 166 | LocalSettings.php to the following as described in the installation |
| 154 | 167 | instructions above: |
| — | — | @@ -157,74 +170,67 @@ |
| 158 | 171 | Including SMW_Settings.php as in earlier versions will continue to work, but may |
| 159 | 172 | be disabled in some future version. |
| 160 | 173 | |
| 161 | | -Existing SMW 1.4.* installations and all SMW installations that already use the |
| 162 | | -default store (SMWSQLStore2) can basically follow the above installation steps. |
| 163 | | -The latter covers all sites with SMW 1.2 to 1.3 that do not use a special |
| 164 | | -setting to switch back to the old store ("SMWSQLStore" or "SMWRAPStore"). |
| 165 | | -Older versions of SMW can be upgrade in a similar fashion, but must ensure that |
| 166 | | -they do not depend on now peculiarities of the old version. Please read the |
| 167 | | -upgrade instructions for SMW version 1.2 and 1.3 for details. Moreover, |
| 168 | | -SMW 1.5.0 finally removed all backwards compatibility to SMW beta versions |
| 169 | | -below SMW 1.0. If your wiki still uses the setting $smwgSMWBetaCompatible=true |
| 170 | | -then you should not upgrade until you find that disabling this setting works |
| 171 | | -properly and without complications. |
| | 174 | +The main user-visible changes in SMW 1.6 concern the Type namespace, the use of |
| | 175 | +custom units of measurement (with custom conversion factors), and the |
| | 176 | +declaration of Type:Record properties. Moreover, the support for the RAP was |
| | 177 | +replaced by general RDF store support. Please see the documentation for details |
| | 178 | +on how to configure this. |
| 172 | 179 | |
| 173 | | -There are two changes in SMW functionality that may affect some sites that used |
| 174 | | -earlier versions. Additional steps are required if the wiki uses n-ary |
| 175 | | -(multivalued) properties or properties of type Geographic coordinate and the |
| 176 | | -required upgrade steps are described in separate sections below. |
| | 180 | +Users who update from SMW 1.4 or earlier hould note that "n-ary" properties now |
| | 181 | +are declared by properties of Type:Record as explained below, and that support |
| | 182 | +for geographic coordinates has moved to the Semantic Maps extension. For |
| | 183 | +upgrading earlier SMW versions, users should have a look at upgrade instructions |
| | 184 | +released with SMW 1.5. |
| 177 | 185 | |
| 178 | | -Directly after enabling SMW 1.5.1, it could potentially happen that the site |
| 179 | | -shows SQL errors due to background jobs trying to access the new DB structure |
| 180 | | -even before you initialised it. This can even block you from reaching SMWAdmin. |
| 181 | | -In this case, either use the script SMW_setup.php from the command-line, or |
| 182 | | -access your database and delete all entries in the table "job". After this, no |
| 183 | | -errors should show up while accessing the special page for initialisation. |
| 184 | 186 | |
| 185 | | -When upgrading from SMW 1.4.* or older, extensions of SMW (e.g. Semantic Forms) |
| 186 | | -need to be updated to a version that is compatible with SMW 1.5.1. See your |
| 187 | | -extension's homepage for details. If used, it is also necessary to update to a |
| 188 | | -more recent version of SemanticResultFormats (SRF). |
| | 187 | +=== Type namespace === |
| 189 | 188 | |
| 190 | | -=== Upgrading geographic coordinates === |
| | 189 | +SMW no longer uses namespaces "Type" and "Type talk." All types are now built-in |
| | 190 | +and there is no good reason to keep a namespace just for documenting them. A new |
| | 191 | +function of Special:Types allows viewing all properties of a type, like the Type |
| | 192 | +pages did before. |
| 191 | 193 | |
| 192 | | -The datatype Geographic coordinate has been moved from SMW to the Semantic Maps |
| 193 | | -extension. Wikis that use this type should install Semantic Maps version 0.6 |
| 194 | | -or above. No other changes are needed, but it is recommended to install |
| 195 | | -Semantic Maps before upgrading SMW so as to avoid problems at any time. The |
| 196 | | -move has been done to concentrate geo-related features in one extension for |
| 197 | | -better maintenance and ease of use. |
| | 194 | +If you still want to use Type (for example to access pages that existed there), |
| | 195 | +you should set $smwgHistoricTypeNamespace = true; before including SMW in |
| | 196 | +LocalSettings.php. This should only be used to move old content to a better |
| | 197 | +place. The old namespaces will not be kept indefinitely. |
| 198 | 198 | |
| 199 | | -=== Upgrading n-ary (multivalued) properties === |
| 200 | 199 | |
| 201 | | -The way how these properties are declared on their property pages has changed |
| 202 | | -since SMW 1.4.3, and it is necessary to change the pages of all such properties |
| 203 | | -to use them again as before. Until SMW 1.4.*, such properties were declared by |
| 204 | | -type declarations as in the following example: |
| | 200 | +=== Custom units === |
| 205 | 201 | |
| 206 | | - <nowiki>[[has type::Page; Number; String]]</nowiki> |
| | 202 | +The only use of Type pages was the declaration of custom types that would allow |
| | 203 | +unit conversion. The declaration of properties with custom units of measurement |
| | 204 | +has changed in two ways: |
| 207 | 205 | |
| 208 | | -In this case, a property with three fields of the specified types was declared. |
| 209 | | -You can use the inline query {{#ask: [[has type::~ *;*]] }} to obtain a list of |
| 210 | | -all properties in your wiki that are of this form at all. Since SMW 1.5.0, two |
| 211 | | -property assignments must be made on the property page instead: |
| | 206 | +(1) The type of these properties is now "Quantity" (not a "custom" type page) |
| | 207 | +(2) The conversion factors that used to be on the Type page are not given on the |
| | 208 | + property page. So one can simply move this text (Type must be activated for |
| | 209 | + this as described above). |
| 212 | 210 | |
| 213 | | - <nowiki>[[has type::Record]]</nowiki> |
| | 211 | +The internal data format of SMW has not changed for custom units, so stored data |
| | 212 | +will be accessible immediately after the change. |
| | 213 | + |
| | 214 | + |
| | 215 | +=== Type:Record === |
| | 216 | + |
| | 217 | +The fields declaration of Type:Record properties now refer to properties, not to |
| | 218 | +types. If you have a property with [[has type::Record]] that uses a setting like |
| | 219 | + |
| 214 | 220 | <nowiki>[[has fields::Page; Number; String]]</nowiki> |
| 215 | 221 | |
| 216 | | -In other words, all "n-ary" properties are now of the new datatype Record, and |
| 217 | | -the information about their fields is stated independently. This change allowed |
| 218 | | -for many improvements in SMW, and makes it possible to create new (better) |
| 219 | | -extensions for supporting compound property values in the future. |
| | 222 | +then you should now replace it with something like |
| 220 | 223 | |
| 221 | | -To upgrade, ''first'' install the new version of SMW, then use the above inline |
| 222 | | -query to efficiently find all properties that need to be changed. After |
| 223 | | -updating the pages as required, all values should be accessible as before |
| 224 | | -(possibly some repair jobs need to finish before this is really the case; check |
| 225 | | -your job queue). If you change the pages before the upgrade to SMW 1.5.1, then |
| 226 | | -it will be necessary to start a repair cycle of SMW to ensure that all affected |
| 227 | | -page are indeed updated. |
| | 224 | + <nowiki>[[has fields::my page; my number; my string]]</nowiki> |
| 228 | 225 | |
| | 226 | +where "my page", "my number", and "my string" are properties in your wiki that |
| | 227 | +have the right types. The use of properties instead of types is better since it |
| | 228 | +allows custom settings beyond the datatype of a field (e.g. conversion factors). |
| | 229 | + |
| | 230 | +The new method also involves internal changes in the data format, and it is not |
| | 231 | +possible to make the update without tmporarily loosing access to the stored data |
| | 232 | +for Type:Record properties (until SMW's self repair has fixed all data entries). |
| | 233 | + |
| | 234 | + |
| 229 | 235 | === Changed configuration options === |
| 230 | 236 | |
| 231 | 237 | Some configuration options (used in LocalSettings.php) have changed since SMW |