| Index: trunk/phase3/docs/skin.txt |
| — | — | @@ -1,59 +1,84 @@ |
| 2 | 2 | skin.txt |
| 3 | 3 | |
| 4 | | -This document describes the overall architecture of MediaWiki's HTML rendering |
| 5 | | -code as well as some history about the skin system. It is placed here rather |
| 6 | | -than in comments in the code itself to help reduce the code size. |
| | 4 | +MediaWiki's default skin is called Monobook, after the black-and-white photo of |
| | 5 | +a book, in the page background. This skin has been the default since MediaWiki |
| | 6 | +1.3 (2004). It is used on Wikipedia, and is popular on other sites. |
| 7 | 7 | |
| 8 | | -== Version 1.6 and greater == |
| | 8 | +There are three legacy skins which were introduced before MediaWiki 1.3: |
| 9 | 9 | |
| 10 | | -PHPTal skins doesn't exist anymore. They were replaced by SkinTemplate skins, |
| 11 | | -introduced since 1.4 to remove the depedency of PHPTal. |
| | 10 | +* Standard (a.k.a. Classic): The old default skin written by Lee Crocker |
| | 11 | +during the phase 3 rewrite, in 2002. |
| 12 | 12 | |
| 13 | | -A new experimental (disabled by default) callback-based template processor |
| 14 | | -has been introduced to try to speed up the generation of html pages. See for |
| 15 | | -example skins/disabled/MonoBookCBT.php. |
| | 13 | +* Nostalgia: A skin which looks like Wikipedia did in its first year (2001). |
| | 14 | +This skin is now used for the old Wikipedia snapshot at |
| | 15 | +http://nostalgia.wikipedia.org/ |
| 16 | 16 | |
| 17 | | -You can find more informations at http://www.mediawiki.org/wiki/Manual:Skins. |
| | 17 | +* Cologne Blue: A nicer-looking alternative to Standard. |
| 18 | 18 | |
| 19 | 19 | |
| 20 | | -== Version 1.4 == |
| | 20 | +And there are four Monobook-derived skins which have been introduced since 1.3: |
| 21 | 21 | |
| 22 | | -MediaWiki still use the PHPTal skin system introduced in version 1.3 but some |
| 23 | | -changes have been made to the file organisation. |
| | 22 | +* MySkin: Monobook without the CSS. The idea is that you customise it using user |
| | 23 | +or site CSS (see below) |
| 24 | 24 | |
| 25 | | -PHP class and PHPTal templates have been moved to /skins/ (respectivly from |
| 26 | | -/includes/ and /templates/). This way skin designer and end user just stick to |
| 27 | | -one directory. |
| | 25 | +* Chick: A lightweight Monobook skin with no sidebar, the sidebar links are |
| | 26 | +given at the bottom of the page instead, as in the unstyled MySkin. |
| 28 | 27 | |
| 29 | | -Two samples are provided to start with, one for PHPTal use (SkinPHPTal.sample) |
| 30 | | -and one without (Skin.sample). |
| | 28 | +* Simple: A lightweight skin with a simple white-background sidebar and no |
| | 29 | +top bar. |
| 31 | 30 | |
| | 31 | +* Modern: An attractive blue/grey theme with sidebar and top bar. |
| 32 | 32 | |
| 33 | | -== Version 1.3 == |
| 34 | 33 | |
| 35 | | -The following might help a bit though. |
| | 34 | +== Custom CSS/JS == |
| 36 | 35 | |
| 37 | | -Firstly, there's Skin.php; this file will check various settings, and it |
| 38 | | -contains a base class from which new skins can be derived. |
| | 36 | +It is possible to customise the site CSS and JavaScript without editing any |
| | 37 | +source files. This is done by editing some pages on the wiki: |
| 39 | 38 | |
| 40 | | -Before version 1.3, each skin had its own PHP file (with a sub-class to Skin) |
| 41 | | -to generate the output. The files are: |
| 42 | | - * SkinCologneBlue.php |
| 43 | | - * SkinNostalgia.php |
| 44 | | - * SkinStandard.php |
| 45 | | - * SkinWikimediaWiki.php |
| 46 | | -If you want to change those skins, you have to edit these PHP files. |
| 47 | | - |
| 48 | | -Since 1.3 a new special skin file is available: SkinPHPTal.php. It makes use of |
| 49 | | -the PHPTal template engine and allows you to separate code and layout of the |
| 50 | | -pages. The default 1.3 skin is MonoBook and it uses the SkinPHPTAL class. |
| | 39 | +* [[MediaWiki:Common.css]] -- for skin-independent CSS |
| | 40 | +* [[MediaWiki:Monobook.css]], [[MediaWiki:Simple.css]], etc. -- for |
| | 41 | +skin-dependent CSS |
| | 42 | +* [[MediaWiki:Common.js]], [[MediaWiki:Monobook.js]], etc. -- for custom |
| | 43 | +site JavaScript |
| 51 | 44 | |
| 52 | | -To change the layout, just edit the PHPTal template (templates/xhtml_slim.pt) |
| 53 | | -as well as the stylesheets (stylesheets/monobook/*). |
| | 45 | +These can also be customised on a per-user basis, by editing |
| | 46 | +[[User:<name>/monobook.css]], [[User:<name>/monobook.js]], etc. |
| 54 | 47 | |
| | 48 | +This feature has led to a wide variety of "user styles" becoming available, |
| | 49 | +which change the appearance of Monobook or MySkin: |
| 55 | 50 | |
| 56 | | -== pre 1.3 version == |
| | 51 | +http://meta.wikimedia.org/wiki/Gallery_of_user_styles |
| 57 | 52 | |
| 58 | | -Unfortunately there isn't any documentation, and the code's in a bit of a mess |
| 59 | | -right now during the transition from the old skin code to the new template-based |
| 60 | | -skin code in 1.3. |
| | 53 | +If you want a different look for your wiki, that gallery is a good place to start. |
| | 54 | + |
| | 55 | +== Drop-in custom skins == |
| | 56 | + |
| | 57 | +If you put a file in MediaWiki's skins directory, ending in .php, the name of |
| | 58 | +the file will automatically be added as a skin name, and the file will be |
| | 59 | +expected to contain a class called Skin<name> with the skin class. You can then |
| | 60 | +make that skin the default by adding to LocalSettings.php: |
| | 61 | + |
| | 62 | +$wgDefaultSkin = '<name>'; |
| | 63 | + |
| | 64 | +You can also disable dropped-in or core skins using: |
| | 65 | + |
| | 66 | +$wgSkipSkins[] = '<name>'; |
| | 67 | + |
| | 68 | +This technique is used by the more ambitious MediaWiki site operators, to |
| | 69 | +create complex custom skins for their wikis. It should be preferred over |
| | 70 | +editing the core Monobook skin directly. |
| | 71 | + |
| | 72 | +See http://www.mediawiki.org/wiki/Manual:Skinning for more information. |
| | 73 | + |
| | 74 | +== Extension skins == |
| | 75 | + |
| | 76 | +It is now possible (since MediaWiki 1.12) to write a skin as a standard |
| | 77 | +MediaWiki extension, enabled via LocalSettings.php. This is done by adding |
| | 78 | +it to $wgValidSkinNames, for example: |
| | 79 | + |
| | 80 | +$wgValidSkinNames['mycoolskin'] = 'My cool skin'; |
| | 81 | + |
| | 82 | +and then registering a class in $wgAutoloadClasses called SkinMycoolskin, which |
| | 83 | +derives from Skin. This technique is apparently not yet used (as of 2008) |
| | 84 | +outside the DumpHTML extension. |
| | 85 | + |
| Index: trunk/phase3/docs/database.txt |
| — | — | @@ -158,13 +158,10 @@ |
| 159 | 159 | following syntax: |
| 160 | 160 | |
| 161 | 161 | $dbw = wfGetDB( DB_MASTER ); |
| 162 | | -$dbw->immediateBegin(); |
| | 162 | +$dbw->begin(); |
| 163 | 163 | /* Do queries */ |
| 164 | | -$dbw->immediateCommit(); |
| | 164 | +$dbw->commit(); |
| 165 | 165 | |
| 166 | | -There are functions called begin() and commit() but they don't do what |
| 167 | | -you would expect. Don't use them. |
| 168 | | - |
| 169 | 166 | Use of locking reads (e.g. the FOR UPDATE clause) is not advised. They |
| 170 | 167 | are poorly implemented in InnoDB and will cause regular deadlock errors. |
| 171 | 168 | It's also surprisingly easy to cripple the wiki with lock contention. If |
| Index: trunk/phase3/docs/memcached.txt |
| — | — | @@ -1,16 +1,20 @@ |
| 2 | | -memcached support for MediaWiki: |
| | 2 | +MediaWiki has optional support for memcached, a "high-performance, |
| | 3 | +distributed memory object caching system". For general information |
| | 4 | +on it, see: http://www.danga.com/memcached/ |
| 3 | 5 | |
| 4 | | -From ca August 2003, MediaWiki has optional support for memcached, a |
| 5 | | -"high-performance, distributed memory object caching system". |
| 6 | | -For general information on it, see: http://www.danga.com/memcached/ |
| 7 | | - |
| 8 | 6 | Memcached is likely more trouble than a small site will need, but |
| 9 | 7 | for a larger site with heavy load, like Wikipedia, it should help |
| 10 | 8 | lighten the load on the database servers by caching data and objects |
| 11 | 9 | in memory. |
| 12 | 10 | |
| 13 | | -== Requirements == |
| | 11 | +== Installation == |
| 14 | 12 | |
| | 13 | +Packages are available for Fedora, Debian, Ubuntu and probably other |
| | 14 | +Linux distributions. If you there's no package available for your |
| | 15 | +distribution, you can compile it from source. |
| | 16 | + |
| | 17 | +== Compilation == |
| | 18 | + |
| 15 | 19 | * PHP must be compiled with --enable-sockets |
| 16 | 20 | |
| 17 | 21 | * libevent: http://www.monkey.org/~provos/libevent/ |
| — | — | @@ -35,26 +39,29 @@ |
| 36 | 40 | memcached servers are not publicly accessible. Otherwise, anyone on |
| 37 | 41 | the internet can put data into and read data from your cache. |
| 38 | 42 | |
| 39 | | -An attacker familiar with MediaWiki internals could use this to give |
| 40 | | -themselves developer access and delete all data from the wiki's |
| 41 | | -database, as well as getting all users' password hashes and e-mail |
| 42 | | -addresses. |
| | 43 | +An attacker familiar with MediaWiki internals could use this to steal |
| | 44 | +passwords and email addresses, or to make themselves a sysop and |
| | 45 | +install malicious javascript on the site. There may be other types |
| | 46 | +of vulnerability, no audit has been done -- so be safe and keep it |
| | 47 | +behind a firewall. |
| 43 | 48 | ********************* W A R N I N G ! ! ! ! ! *********************** |
| 44 | 49 | |
| 45 | 50 | == Setup == |
| 46 | 51 | |
| 47 | | -If you want to start small, just run one memcached on your web |
| 48 | | -server: |
| | 52 | +If you installed memcached using a distro, the daemon should be started |
| | 53 | +automatically using /etc/init.d/memcached. |
| 49 | 54 | |
| 50 | | - memcached -d -l 127.0.0.1 -p 11000 -m 64 |
| | 55 | +To start the daemon manually, use something like: |
| 51 | 56 | |
| | 57 | + memcached -d -l 127.0.0.1 -p 11211 -m 64 |
| | 58 | + |
| 52 | 59 | (to run in daemon mode, accessible only via loopback interface, |
| 53 | 60 | on port 11000, using up to 64MB of memory) |
| 54 | 61 | |
| 55 | 62 | In your LocalSettings.php file, set: |
| 56 | 63 | |
| 57 | 64 | $wgMainCacheType = CACHE_MEMCACHED; |
| 58 | | - $wgMemCachedServers = array( "127.0.0.1:11000" ); |
| | 65 | + $wgMemCachedServers = array( "127.0.0.1:11211" ); |
| 59 | 66 | |
| 60 | 67 | The wiki should then use memcached to cache various data. To use |
| 61 | 68 | multiple servers (physically separate boxes or multiple caches |
| — | — | @@ -70,15 +77,10 @@ |
| 71 | 78 | |
| 72 | 79 | == PHP client for memcached == |
| 73 | 80 | |
| 74 | | -As of this writing, MediaWiki includes version 1.0.10 of the PHP |
| 75 | | -memcached client by Ryan Gilfether <hotrodder@rocketmail.com>. |
| 76 | | -You'll find some documentation for it in the 'php-memcached' |
| 77 | | -subdirectory under the present one. |
| | 81 | +MediaWiki uses a fork of Ryan T. Dean's pure-PHP memcached client. |
| | 82 | +The newer PECL module is not yet supported. |
| 78 | 83 | |
| 79 | | -We intend to track updates, but if you want to check for the lastest |
| 80 | | -released version, see http://www.danga.com/memcached/apis.bml |
| 81 | | - |
| 82 | | -MediaWiki use three object for memcaching: |
| | 84 | +MediaWiki uses three object for object caching: |
| 83 | 85 | * $wgMemc, controlled by $wgMainCacheType |
| 84 | 86 | * $parserMemc, controlled by $wgParserCacheType |
| 85 | 87 | * $messageMemc, controlled by $wgMessageCacheType |
| — | — | @@ -93,6 +95,8 @@ |
| 94 | 96 | |
| 95 | 97 | == Keys used == |
| 96 | 98 | |
| | 99 | +(incomplete, out of date) |
| | 100 | + |
| 97 | 101 | Ajax Search: |
| 98 | 102 | key: $wgDBname:ajaxsearch:md5( $search ) |
| 99 | 103 | ex: wikidb:ajaxsearch:9565814d5d564fa898dd6111b94fae0b |
| — | — | @@ -244,4 +248,4 @@ |
| 245 | 249 | set in: User::saveToCache() |
| 246 | 250 | cleared by: User::saveSettings(), User::clearSharedCache() |
| 247 | 251 | |
| 248 | | -... more to come ... |
| \ No newline at end of file |
| | 252 | +... more to come ... |
| Index: trunk/phase3/docs/README |
| — | — | @@ -13,5 +13,5 @@ |
| 14 | 14 | |
| 15 | 15 | For end user / administrators, most of the documentation |
| 16 | 16 | is located online at: |
| 17 | | - http://www.mediawiki.org/wiki/Project:Help |
| | 17 | + http://www.mediawiki.org/wiki/Help:Contents |
| 18 | 18 | |
| Index: trunk/phase3/docs/title.txt |
| — | — | @@ -9,11 +9,10 @@ |
| 10 | 10 | attributes of the title. This is intended to be an |
| 11 | 11 | immutable "value" class, so there are no mutator functions. |
| 12 | 12 | |
| 13 | | -To get a new instance, call one of the static factory |
| 14 | | -methods Title::newFromURL(), Title::newFromDBKey(), |
| 15 | | -or Title::newFromText(). Once instantiated, the |
| 16 | | -other non-static accessor methods can be used, such as |
| 17 | | -getText(), getDBKey(), getNamespace(), etc. |
| | 13 | +To get a new instance, call Title::newFromText(). Once instantiated, |
| | 14 | +the non-static accessor methods can be used, such as getText(), |
| | 15 | +getDBKey(), getNamespace(), etc. Note that Title::newFromText() may |
| | 16 | +return false if the text is illegal according to the rules below. |
| 18 | 17 | |
| 19 | 18 | The prefix rules: a title consists of an optional interwiki |
| 20 | 19 | prefix (such as "m:" for meta or "de:" for German), followed |
| — | — | @@ -42,35 +41,40 @@ |
| 43 | 42 | |
| 44 | 43 | An initial colon in a title listed in wiki text may however |
| 45 | 44 | suppress special handling for interlanguage links, image links, |
| 46 | | -and category links. |
| | 45 | +and category links. It is also used to indicate the main |
| | 46 | +namespace in template inclusions. |
| 47 | 47 | |
| 48 | | -Character mapping rules: Once prefixes have been stripped, the |
| 49 | | -rest of the title processed this way: spaces and underscores are |
| 50 | | -treated as equivalent and each is converted to the other in the |
| 51 | | -appropriate context (underscore in URL and database keys, spaces |
| 52 | | -in plain text). "Extended" characters in the 0x80..0xFF range |
| 53 | | -are allowed in all places, and are valid characters. They are |
| 54 | | -encoded in URLs. Other characters may be ASCII letters, digits, |
| 55 | | -hyphen, comma, period, apostrophe, parentheses, and colon. No |
| 56 | | -other ASCII characters are allowed, and will be deleted if found |
| 57 | | -(they will probably cause a browser to misinterpret the URL). |
| 58 | | -Extended characters are _not_ urlencoded when used as text or |
| 59 | | -database keys. |
| | 48 | +Once prefixes have been stripped, the rest of the title processed |
| | 49 | +this way: |
| 60 | 50 | |
| 61 | | -Character encoding rules: TODO |
| | 51 | +* Spaces and underscores are treated as equivalent and each |
| | 52 | +is converted to the other in the appropriate context (underscore in |
| | 53 | +URL and database keys, spaces in plain text). |
| | 54 | +* Multiple consecutive spaces are converted to a single space. |
| | 55 | +* Leading or trailing space is removed. |
| | 56 | +* If $wgCapitalLinks is enabled (the default), the first letter is |
| | 57 | +capitalised, using the capitalisation function of the content language |
| | 58 | +object. |
| | 59 | +* The unicode characters LRM (U+200E) and RLM (U+200F) are silently |
| | 60 | +stripped. |
| | 61 | +* Invalid UTF-8 sequences or instances of the replacement character |
| | 62 | +(U+FFFD) are considered illegal. |
| | 63 | +* A percent sign followed by two hexadecimal characters is illegal |
| | 64 | +* Anything that looks like an XML/HTML character reference is illegal |
| | 65 | +* Any character not matched by the $wgLegalTitleChars regex is illegal |
| | 66 | +* Zero-length titles (after whitespace stripping) are illegal |
| 62 | 67 | |
| 63 | | -Canonical forms: the canonical form of a title will always be |
| 64 | | -returned by the object. In this form, the first (and only the |
| 65 | | -first) character of the namespace and title will be uppercased; |
| 66 | | -the rest of the namespace will be lowercased, while the title |
| 67 | | -will be left as is. The text form will use spaces, the URL and |
| 68 | | -DBkey forms will use underscores. Interwiki prefixes are all |
| 69 | | -lowercase. The namespace will use underscores when returned |
| 70 | | -alone; it will use spaces only when attached to the text title. |
| | 68 | +All titles except special pages must be less than 255 bytes when |
| | 69 | +encoded with UTF-8, because that is the size of the database field. |
| | 70 | +Special page titles may be up to 512 bytes. |
| 71 | 71 | |
| | 72 | +Note that Unicode Normal Form C (NFC) is enforced by MediaWiki's user |
| | 73 | +interface input functions, and so titles will typically be in this |
| | 74 | +form. |
| | 75 | + |
| 72 | 76 | getArticleID() needs some explanation: for "internal" articles, |
| 73 | 77 | it should return the "page_id" field if the article exists, else |
| 74 | 78 | it returns 0. For all external articles it returns 0. All of |
| 75 | 79 | the IDs for all instances of Title created during a request are |
| 76 | 80 | cached, so they can be looked up quickly while rendering wiki |
| 77 | | -text with lots of internal links. |
| | 81 | +text with lots of internal links. See linkcache.txt. |