| Index: trunk/extensions/SemanticMediaWiki/INSTALL |
| — | — | @@ -1,4 +1,4 @@ |
| 2 | | -[[Semantic MediaWiki 1.2.2]] |
| | 2 | +[[Semantic MediaWiki 1.3]] |
| 3 | 3 | |
| 4 | 4 | Install instructions for the latest SMW version are also online in a more |
| 5 | 5 | convenient format for reading: |
| — | — | @@ -14,18 +14,13 @@ |
| 15 | 15 | ** Testing your Installation |
| 16 | 16 | ** Customising Semantic MediaWiki |
| 17 | 17 | ** Running SMW on older versions of MediaWiki |
| 18 | | -* Notes on Upgrading |
| 19 | | - ** General Upgrading Instructions |
| 20 | | - ** Upgrading from SMW 1.2 and SMW 1.2.1 |
| 21 | | - ** Upgrading from SMW 1.0.* and SMW 1.1.* |
| 22 | | - ** Upgrading from 1.0 RC1, 1.0 RC2, 1.0 RC3 |
| 23 | | - ** Upgrading from version 0.7 |
| 24 | | - ** Upgrading from versions 0.6 and 0.5 |
| 25 | | - ** Upgrading from 0.4.x |
| | 18 | +* Upgrading existing installations |
| | 19 | + ** Changed configuration options |
| 26 | 20 | * Troubleshooting |
| 27 | 21 | * SMW is installed. What should I do now? |
| 28 | 22 | * Contact |
| 29 | 23 | |
| | 24 | + |
| 30 | 25 | == Disclaimer == |
| 31 | 26 | |
| 32 | 27 | For a proper legal disclaimer, see the file "COPYING". |
| — | — | @@ -36,9 +31,10 @@ |
| 37 | 32 | provided). Every serious wiki should be subject to regular database backups! |
| 38 | 33 | If you have any specific questions, please contact the authors. |
| 39 | 34 | |
| | 35 | + |
| 40 | 36 | == Requirements == |
| 41 | 37 | |
| 42 | | -* MediaWiki 1.11.* or greater (tested from 1.11.0 to 1.13alpha (r37479)). |
| | 38 | +* MediaWiki 1.11.* or greater (tested from 1.11.0 to 1.14alpha (r40427)). |
| 43 | 39 | * PHP 5.x or greater installed and working |
| 44 | 40 | * MySQL >= 4.0.14 (version required by MediaWiki) |
| 45 | 41 | |
| — | — | @@ -55,14 +51,17 @@ |
| 56 | 52 | AdminSettings.php for this purpose, avoiding the need of extra rights for |
| 57 | 53 | the wiki DB user. |
| 58 | 54 | * SMW creates and alters temporary tables for certain semantic queries. To do |
| 59 | | - this, your wikidb user must have privileges for CREATE TEMPORARY TABLES. The |
| 60 | | - according features can be disabled by adding the following to Localsettings.php: |
| | 55 | + this, your wikidb user must have privileges for CREATE TEMPORARY TABLES. The |
| | 56 | + according features can be disabled by adding the following to |
| | 57 | + Localsettings.php: |
| 61 | 58 | |
| 62 | 59 | $smwgQSubcategoryDepth=0; |
| 63 | 60 | $smwgQPropertyDepth=0; |
| 64 | 61 | $smwgQFeatures = SMW_ANY_QUERY & ~SMW_DISJUNCTION_QUERY; |
| 65 | | - $smwgQConceptFeatures = SMW_ANY_QUERY & ~SMW_DISJUNCTION_QUERY & ~SMW_CONCEPT_QUERY; |
| | 62 | + $smwgQConceptFeatures = SMW_ANY_QUERY & ~SMW_DISJUNCTION_QUERY & |
| | 63 | + ~SMW_CONCEPT_QUERY; |
| 66 | 64 | |
| | 65 | + |
| 67 | 66 | == Installation == |
| 68 | 67 | |
| 69 | 68 | If you upgrade an existing installation of Semantic MediaWiki, also read the |
| — | — | @@ -87,6 +86,9 @@ |
| 88 | 87 | Please consider announcing your new site to the SMW semantic wiki list by |
| 89 | 88 | using the according button on "Special:SMWAdmin". |
| 90 | 89 | |
| | 90 | + Note that this requires persmissions to alter/create database tables, as |
| | 91 | + explained in the above note. |
| | 92 | + |
| 91 | 93 | (4) If you already have categories in your wiki, they will not immediately be |
| 92 | 94 | available for SMW queries. Category information becomes available if a |
| 93 | 95 | page in a category is edited next time. To make all information available |
| — | — | @@ -106,7 +108,6 @@ |
| 107 | 109 | There is currently no working Postgres support. If you need that, please |
| 108 | 110 | contact the developers and support them in adjusting SMW appropriately. |
| 109 | 111 | |
| 110 | | - |
| 111 | 112 | === Testing your Installation === |
| 112 | 113 | |
| 113 | 114 | If you are uncertain that everything went well, you can do some testing steps |
| — | — | @@ -119,8 +120,10 @@ |
| 120 | 121 | Create a regular wiki page named "TestSMW", and in it enter the wiki text |
| 121 | 122 | Property test: [[testproperty::Dummypage]] |
| 122 | 123 | |
| 123 | | -when you preview and save the page, the SMW "Factbox" should appear showing |
| 124 | | -the Testproperty as a link Dummypage. |
| | 124 | +When previewing the page before saving, you should see a Factbox at the bottom |
| | 125 | +of the article that shows your input. After saving the page, click on the link |
| | 126 | +"Browse properties" in the page's toolbox. This view should show Testproperty |
| | 127 | +with value Dummypage. |
| 125 | 128 | |
| 126 | 129 | If you don't get these results, check the steps in the Installation section, |
| 127 | 130 | consult the FAQ section, then contact the user support list (see the Contact |
| — | — | @@ -141,58 +144,9 @@ |
| 142 | 145 | parameters that are available are documented in the file SMW_Settings.php. Do |
| 143 | 146 | not change this file directly, but put adoptions into your LocalSettings.php. |
| 144 | 147 | |
| 145 | | -==== Semantic MediaWiki on small wikis -- extended features ==== |
| | 148 | +Further options are explained at |
| | 149 | +http://semantic-mediawiki.org/wiki/Help:Configuration |
| 146 | 150 | |
| 147 | | -Some features of SMW are turned off by default, since they could slow down |
| 148 | | -larger sites. If you run a small site or have a controlled user base, then you |
| 149 | | -may wish to enable these additional features. Suggested entries for |
| 150 | | -LocalSettings.php are: |
| 151 | | - |
| 152 | | -$smwgQComparators = '<|>|!|~'; // + pattern search comparator ~ for strings |
| 153 | | - |
| 154 | | -Further relaxation of default limits e.g. on query size are possible. |
| 155 | | -See SMW_Settings.php. |
| 156 | | - |
| 157 | | -In controlled wikis that do not use extremely length property values, it may |
| 158 | | -also be save to allow links in property values, as in [[area::42 [[m�]] ]]. |
| 159 | | -This is done with the setting |
| 160 | | - |
| 161 | | -$smwgLinksInValues = true; |
| 162 | | - |
| 163 | | -This may cause PHP crashes in some cases -- see SMW_Settings.php for details. |
| 164 | | - |
| 165 | | -==== Semantic MediaWiki on very large wikis -- improving performance ==== |
| 166 | | - |
| 167 | | -On very large or high traffic sites, further restriction of SMW features might |
| 168 | | -be desirable for performance reasons. Besides setting up the usual external |
| 169 | | -caches and distributed DB-servers, you can also modify some SMW options to |
| 170 | | -increase speed (while switching off features). Try some or all of the below in |
| 171 | | -LocalSettings.php: |
| 172 | | - |
| 173 | | -$smwgQEnabled = false; // most radical -- no more semantic queries, just browsing/display features |
| 174 | | -$smwgQSubcategoryDepth = 0; // disable subcategory reasoning in queries |
| 175 | | -$smwgQSubpropertyDepth = 0; // disable subproperty reasoning in queries |
| 176 | | -$smwgQFeatures = SMW_ANY_QUERY & ~SMW_DISJUNCTION_QUERY; // disable disjunctions in queries |
| 177 | | -$smwgQConceptFeatures = SMW_ANY_QUERY & ~SMW_DISJUNCTION_QUERY & ~SMW_CONCEPT_QUERY; |
| 178 | | -$smwgQMaxSize = 5; // allow only queries of 5 or fewer conditions (default 12) |
| 179 | | -$smwgQMaxDepth = 2; // allow only queries of depth 2 or smaller (default 4) |
| 180 | | -$smwgQMaxLimit = 100; // never ever return more than 100 results to a query (default 10000) |
| 181 | | -$smwgQDefaultLimit = 10; // only return 10 query results by default |
| 182 | | -$smwgRSSWithPages = false; // do not include pages into RSS feeds, speeds up feed generation |
| 183 | | -$smwgRSSEnabled = false; // switch off RSS feeds completely, so as not to atttract too many queries |
| 184 | | - |
| 185 | | -These settings have different effects, and their effectiveness depends very |
| 186 | | -much on the usage and content structure of your wiki. You may wish to try out |
| 187 | | -conservative settings first and relax these step by step when things work |
| 188 | | -reliably. You can also restrict complex queries to Concept pages (wich may be |
| 189 | | -editable only to certain user groups) as follows: |
| 190 | | - |
| 191 | | -$smwgQFeatures = SMW_CONCEPT_QUERY; // only allow queries {{#ask: [[Concept:...]] }} |
| 192 | | -$smwgQConceptFeatures = SMW_ANY_QUERY & ~SMW_CONCEPT_QUERY; |
| 193 | | - |
| 194 | | -If you have continued performance issues on your *large* wiki, please do not |
| 195 | | -hesitate to contact the SMW developers for support. |
| 196 | | - |
| 197 | 151 | === Running SMW on older versions of MediaWiki === |
| 198 | 152 | |
| 199 | 153 | If your site is still running on PHP4, SMW is not supported. It would hardly |
| — | — | @@ -201,165 +155,66 @@ |
| 202 | 156 | Download an older release of SMW and have a look at the included INSTALL |
| 203 | 157 | instructions to find out whether other changes are recommended therein. |
| 204 | 158 | |
| 205 | | -== Notes on Upgrading == |
| 206 | 159 | |
| 207 | | -This section starts with some generic upgrading instructions that may or may |
| 208 | | -not be needed for particular upgrades. Please read upgrading instructions for |
| 209 | | -your wiki first to see whether this is actually needed. |
| | 160 | +== Upgrading existing installations == |
| 210 | 161 | |
| 211 | | -=== General Upgrading Instructions === |
| | 162 | +SMW 1.3 does not require major steps for upgrading from SMW 1.2. You can follow |
| | 163 | +the same steps as for new installations above (you just do not need to edit |
| | 164 | +LocalSettings.php). Especially, you must trigger the SMW database setup via |
| | 165 | +Special:SMWAdmin or using the script SMW_setup.php. Further actions may be |
| | 166 | +required only if one of the following applies to you. |
| 212 | 167 | |
| 213 | | -All SMW data is extracted from wiki pages, and SMW offers an easy way of |
| 214 | | -recreating all internal data from the current wiki pages. Basically, this |
| 215 | | -could be done by executing Special:SMWAdmin as during the installation, |
| 216 | | -and by newly saving all wiki pages afterwards. Since the latter would be |
| 217 | | -rather cumbversome, SMW provides a maintenance script for refreshing all |
| 218 | | -data: SMW_refreshData.php reads all pages and recreates their semantic data. |
| | 168 | +If you still use a version before SMW 1.2, follow the upgrading instructions |
| | 169 | +given at |
| | 170 | +http://semantic-mediawiki.org/wiki/Help:Installation_1.2#Notes_on_Upgrading, |
| | 171 | +or SMW will not be working any more. If you have a version that is even older |
| | 172 | +than SMW 1.0, then read the installation steps given for your version in the |
| | 173 | +installation instructions for SMW 1.1: |
| | 174 | +http://semantic-mediawiki.org/wiki/Help:Installation_1.1#Notes_on_Upgrading |
| 219 | 175 | |
| 220 | | -Instructions: |
| 221 | | -(0) Read the rest of this section first. |
| 222 | | -(1) Install the new SMW version as described above. |
| 223 | | -(2) Install SMW_refreshData.php as described in [SMW_path]/maintenance/README |
| 224 | | -(3) Login to your server, and change directory to [wikipath]/maintenance |
| 225 | | -(4) Run "php SMW_refreshData.php -ftpv" and follow its progress. |
| 226 | | -(5) Run "php SMW_refreshData.php -v" and follow its progress. |
| 227 | | -(6) Run "touch [wikipath]/LocalSettings.php" to make sure that no cached old |
| 228 | | - versions of wiki pages are used in the wiki. |
| | 176 | +If you use imported vocabulary, you will have to re-store the data for all |
| | 177 | +pages that use the property imported from. This can often be done manually by |
| | 178 | +just editing those (typically few) pages. If there are many affected pages, use |
| | 179 | +the script to repair all data at once. |
| 229 | 180 | |
| 230 | | -Since the databse updates can take a long time, it might be better to perform |
| 231 | | -them via an SMW maintenance script as well instead of using Special:SMWAdmin. |
| 232 | | -The according script is called SMW_setup.php. For later updates, you can leave |
| 233 | | -away the "f" option in step (4), so that your existing database is not deleted |
| 234 | | -before the refresh (however, deletion is the most secure way to fully update). |
| | 181 | +If you use concepts, then it might be useful to re-store the data for the |
| | 182 | +concept pages, but only if you are interested in using the new concept caching |
| | 183 | +features of SMW. Otherwise concepts will also continue to work normally without |
| | 184 | +taking any actions. |
| 235 | 185 | |
| 236 | | -Some versions of SMW also introduced incompatibilities in the wiki syntax that |
| 237 | | -may need to be fixed. You may want to read this first. |
| | 186 | +=== Changed configuration options === |
| 238 | 187 | |
| 239 | | -=== Upgrtading from SMW 1.2 and SMW 1.2.1 === |
| | 188 | +Some configuration options (used in LocalSettings.php) have changed since SMW |
| | 189 | +1.0. All settings are documented in detail in the file SMW_Settings.php. The |
| | 190 | +following list gives the version in which a setting was first introduced, so it |
| | 191 | +can be ignored if you already run this version or a more recent one. |
| 240 | 192 | |
| 241 | | -No special changes are needed, but one default setting has changed from SMW 1.2: |
| 242 | | -SMW will no longer support nested link syntax in property values by default, |
| 243 | | -since this requires a complex pattern match that causes PHP to crash if property |
| 244 | | -values are very long (in the order of 3400 characters). If you have no such long |
| 245 | | -values, you may activate the feature with the option |
| | 193 | +* [1.3] Since SMW 1.3, the Factbox is hidden by default and will only appear. |
| | 194 | +As a compensation, the toolbox (usually on the left below the search field) |
| | 195 | +shows a link to Special:Browse. To use the display behaviour of the Factbox as |
| | 196 | +it was before SMW 1.3, set $smwgShowFactbox = SMW_FACTBOX_NONEMPTY; The new |
| | 197 | +link and the Factbox during editing can also be configured; see |
| | 198 | +SMW_Settings.php for details. |
| 246 | 199 | |
| | 200 | +* [1.2.1] SMW will no longer support nested link syntax in property values by |
| | 201 | +default, since this was known to cause problems. To re-enable this, set |
| 247 | 202 | $smwgLinksInValues = true; |
| 248 | 203 | |
| 249 | | -=== Upgrading from SMW 1.0.* and SMW 1.1.* === |
| | 204 | +* [1.2] If your wiki uses <ask> syntax or the Relation: namespace, you may want |
| | 205 | +to set $smwgSMWBetaCompatible = true; before the line including |
| | 206 | +SMW_Settings.php in LocalSettings.php. Consider changing <ask> to #ask to be |
| | 207 | +able to drop SMW beta compatibility. |
| 250 | 208 | |
| 251 | | -After file installation, you wiki will not show any semantic data at first! To |
| 252 | | -use fix that temporarily, use the setting $smwgDefaultStore = 'SMWSQLStore'; |
| 253 | | -in your LocalSettings.php. This uses the existing old store, which is slower |
| 254 | | -and has less features. |
| | 209 | +* [1.2] If you had a setting $smwgQDisjunctionSupport = false, then you now |
| | 210 | +need the following settings: |
| 255 | 211 | |
| 256 | | -To upgrade to the new store, do the following: |
| 257 | | -(1) Login to your server, and change directory to [wikipath]/maintenance |
| 258 | | -(2) Run "php SMW_setup.php -b SMWSQLStore2" and follow its progress. |
| 259 | | -(3) Run "php SMW_refreshData.php -tpv -b SMWSQLStore2" and follow its progress. |
| 260 | | -(4) Run "php SMW_refreshData.php -v -b SMWSQLStore2" and follow its progress. |
| | 212 | + $smwgQFeatures = SMW_ANY_QUERY & ~SMW_DISJUNCTION_QUERY; |
| | 213 | + $smwgQConceptFeatures = SMW_ANY_QUERY & ~SMW_DISJUNCTION_QUERY & ~SMW_CONCEPT_QUERY; |
| 261 | 214 | |
| 262 | | -After completing this successfully, remove the $smwgDefaultStore setting from |
| 263 | | -your LocalSettings.php again. Then check the whether the contents of the wiki |
| 264 | | -is displayed properly. In case of problems, you can always go back to the old |
| 265 | | -store again with $smwgDefaultStore. If the new store works well, you can free |
| 266 | | -the space taken by the old store with |
| | 215 | +Older configuration changes are found online, see |
| | 216 | +http://semantic-mediawiki.org/wiki/Help:Installation_1.3 |
| 267 | 217 | |
| 268 | | - "php SMW_setup.php --delete -b SMWSQLStore" |
| 269 | 218 | |
| 270 | | -Changed configuration options: |
| 271 | | -(all documented in detail in SMW_Settings.php) |
| 272 | | - |
| 273 | | -* If your wiki uses <ask> syntax or the Relation: namespace, you may want to |
| 274 | | - set $smwgSMWBetaCompatible = true; *before* including SMW_Settings.php. |
| 275 | | - Consider changing <ask> to #ask to be able to drop SMW beta compatibility. |
| 276 | | -* If you had a setting $smwgQDisjunctionSupport = false, then you now need the |
| 277 | | - following settings: |
| 278 | | - |
| 279 | | - $smwgQFeatures = SMW_ANY_QUERY & ~SMW_DISJUNCTION_QUERY; |
| 280 | | - $smwgQConceptFeatures = SMW_ANY_QUERY & ~SMW_DISJUNCTION_QUERY & ~SMW_CONCEPT_QUERY; |
| 281 | | - |
| 282 | | -=== Upgrading from 1.0 RC1, 1.0 RC2, 1.0 RC3 === |
| 283 | | - |
| 284 | | -Following the generic upgrading instructions above is recommended in any case. |
| 285 | | -Moreover, some configuration options have changed slightly between release |
| 286 | | -candidates. Currently these are: |
| 287 | | - |
| 288 | | -* $smwgQEqualitySupport now is no longer true/false, but one of SMW_EQ_NONE, |
| 289 | | - SMW_EQ_SOME, SMW_EQ_FULL |
| 290 | | -* $smwgQDefaultNamespaces is now NULL by default, so that all namespaces are |
| 291 | | - queried. The old default was "array(NS_MAIN, NS_IMAGE)". |
| 292 | | -* $smwgQDefaultLinking now defaults to 'all' such that all query results are |
| 293 | | - linked. This is not a performance issue any more. The old default was |
| 294 | | - 'subject'. |
| 295 | | - |
| 296 | | -If you set any of these parameters in your LocalSettings.php, you need to |
| 297 | | -update the config. Please see SMW_Settings.php for more documentation on the |
| 298 | | -available parameters. |
| 299 | | - |
| 300 | | -=== Upgrading from version 0.7 === |
| 301 | | - |
| 302 | | -The above generic steps are strictly necessary, and suffice to get a wiki that |
| 303 | | -basically works. |
| 304 | | - |
| 305 | | -However, some further steps are strongly suggested. SMW1.0 mainly introduced |
| 306 | | -the following incompatible changes to SMW0.7: |
| 307 | | - |
| 308 | | -(a) The concepts (and namespaces) "Relation" and "Attribute" are now unified |
| 309 | | - into "Property" |
| 310 | | -(b) The special property "Main display unit" is obsolete, and the property |
| 311 | | - "display unit" shows slightly modified behaviour. |
| 312 | | -(c) The configuration options in LocalSettings.php have changed. |
| 313 | | - |
| 314 | | -For (a), the namespace "Attribute:" was renamed into "Property:" -- you will |
| 315 | | -find all your former attribute pages in the new place. All SMW-generated |
| 316 | | -property links now point to "Property", and thus work for your former |
| 317 | | -Attributes. But the former Relations are still in their old namespace and need |
| 318 | | -to be moved. SMW provides the maintenance script SMW_unifyProperties.php for |
| 319 | | -this purpose. |
| 320 | | - |
| 321 | | -Instructions: |
| 322 | | -(1) Install SMW_unifyProperties.php following [SMW_path]/maintenance/README |
| 323 | | -(2) Run "php SMW_unifyProperties" and follow its progress. |
| 324 | | - |
| 325 | | -The script moves all Relation pages to the according Property page. Problems |
| 326 | | -occur if you had Attribute and Relation pages of the same title. It will report |
| 327 | | -in which cases this occurred and leave it to you to clean up the merged pages. |
| 328 | | -You can also run the script with option "-c" to get an overview of the |
| 329 | | -conflicts, e.g. to delete undesired pages first. The script can be run safely |
| 330 | | -more than once. |
| 331 | | - |
| 332 | | -In addition, you should run the MediaWiki maintenance script "refreshLinks.php" |
| 333 | | -so that old links in SMW Factboxes are refreshed to point to Property: instead |
| 334 | | -of Relation:/Attribute:. |
| 335 | | - |
| 336 | | -For (b), all (property) pages using properties "Main display unit" and "display |
| 337 | | -unit" should be updated: delete these annotations and use a single annotation |
| 338 | | -"[[display units::...]]" instead. Its value is the list of units you like to |
| 339 | | -have diplayed, separated by ",". See the online docu for details. Running |
| 340 | | -SMW_refreshData.php again (once) is required to reliably propagate the updated |
| 341 | | -property setting to all pages. |
| 342 | | - |
| 343 | | -For (c), please consult the file [SMW_path]/includes/SMW_Settings.php to find |
| 344 | | -out about the current options, and use only those in your LocalSettings.php |
| 345 | | -(using older options will not hurt, but has no effect). Note that some options |
| 346 | | -have just changed labels, while others were added or removed. |
| 347 | | - |
| 348 | | -=== Upgrading from version 0.6 or 0.5 === |
| 349 | | - |
| 350 | | -It should in principle be possible to delete (move away) SMW, install a fresh |
| 351 | | -SMW version, and run all updates as in the case of SMW0.7. Patches to MediaWiki |
| 352 | | -(known before SMW0.7) are no longer required. Note that this upgrade has not |
| 353 | | -been tested. An alternative would be to upgrade to SMW0.7 first, and to move on |
| 354 | | -to SMW1.0 next. |
| 355 | | - |
| 356 | | -=== Upgrading from 0.4.x === |
| 357 | | - |
| 358 | | -Upgrading should work like for versions 0.6 and 0.5. The type "Geographic area" |
| 359 | | -and "Geographic length" are no longer built in. But you can easily create them |
| 360 | | -by yourself with the new type customisation features. See the docu at |
| 361 | | -http://semantic-mediawiki.org for details. |
| 362 | | - |
| 363 | | - |
| 364 | 219 | == Troubleshooting == |
| 365 | 220 | |
| 366 | 221 | Some technical problems are well known and have easy fixes. Please view the |
| — | — | @@ -415,7 +270,8 @@ |
| 416 | 271 | |
| 417 | 272 | == Contact == |
| 418 | 273 | |
| 419 | | -See "Contact" in the file README. |
| | 274 | +See "Contact" in the file README, or view the current online information |
| | 275 | +http://semantic-mediawiki.org/wiki/Contact |
| 420 | 276 | |
| 421 | 277 | If you have remarks or questions, please send them to |
| 422 | 278 | semediawiki-user@lists.sourceforge.net |