1 files changed, 69 insertions, 33 deletions
diff --git a/docs/skin.txt b/docs/skin.txt
index 82a5b72e..524a0397 100644
--- a/docs/skin.txt
+++ b/docs/skin.txt
@@ -1,48 +1,84 @@
-
 skin.txt
 
-This document describes the overall architecture of MediaWiki's HTML rendering
-code as well as some history about the skin system. It is placed here rather
-than in comments in the code itself to help reduce the code size.
+MediaWiki's default skin is called Monobook, after the black-and-white photo of
+a book, in the page background. This skin has been the default since MediaWiki 
+1.3 (2004). It is used on Wikipedia, and is popular on other sites.
+
+There are three legacy skins which were introduced before MediaWiki 1.3:
+
+* Standard (a.k.a. Classic): The old default skin written by Lee Crocker 
+during the phase 3 rewrite, in 2002.
+
+* Nostalgia: A skin which looks like Wikipedia did in its first year (2001). 
+This skin is now used for the old Wikipedia snapshot at
+http://nostalgia.wikipedia.org/
+
+* Cologne Blue: A nicer-looking alternative to Standard.
+
+
+And there are four Monobook-derived skins which have been introduced since 1.3:
+
+* MySkin: Monobook without the CSS. The idea is that you customise it using user
+or site CSS (see below)
+
+* Chick: A lightweight Monobook skin with no sidebar, the sidebar links are
+given at the bottom of the page instead, as in the unstyled MySkin.
+
+* Simple: A lightweight skin with a simple white-background sidebar and no
+top bar.
+
+* Modern: An attractive blue/grey theme with sidebar and top bar.
+
+
+== Custom CSS/JS ==
+
+It is possible to customise the site CSS and JavaScript without editing any
+source files. This is done by editing some pages on the wiki:
+
+* [[MediaWiki:Common.css]] -- for skin-independent CSS
+* [[MediaWiki:Monobook.css]], [[MediaWiki:Simple.css]], etc. -- for
+skin-dependent CSS
+* [[MediaWiki:Common.js]], [[MediaWiki:Monobook.js]], etc. -- for custom
+site JavaScript
+
+These can also be customised on a per-user basis, by editing
+[[User:<name>/monobook.css]], [[User:<name>/monobook.js]], etc.
+
+This feature has led to a wide variety of "user styles" becoming available,
+which change the appearance of Monobook or MySkin:
+
+http://meta.wikimedia.org/wiki/Gallery_of_user_styles
 
-== Version 1.4 ==
+If you want a different look for your wiki, that gallery is a good place to start.
 
-MediaWiki still use the PHPTal skin system introduced in version 1.3 but some
-changes have been made to the file organisation.
+== Drop-in custom skins ==
 
-PHP class and PHPTal templates have been moved to /skins/ (respectivly from
-/includes/ and /templates/). This way skin designer and end user just stick to
-one directory.
+If you put a file in MediaWiki's skins directory, ending in .php, the name of 
+the file will automatically be added as a skin name, and the file will be
+expected to contain a class called Skin<name> with the skin class. You can then
+make that skin the default by adding to LocalSettings.php:
 
-Two samples are provided to start with, one for PHPTal use (SkinPHPTal.sample)
-and one without (Skin.sample).
+$wgDefaultSkin = '<name>';
 
+You can also disable dropped-in or core skins using:
 
-== Version 1.3 ==
+$wgSkipSkins[] = '<name>';
 
-The following might help a bit though.
+This technique is used by the more ambitious MediaWiki site operators, to 
+create complex custom skins for their wikis. It should be preferred over 
+editing the core Monobook skin directly. 
 
-Firstly, there's Skin.php; this file will check various settings, and it 
-contains a base class from which new skins can be derived.
+See http://www.mediawiki.org/wiki/Manual:Skinning for more information.
 
-Before version 1.3, each skin had its own PHP file (with a sub-class to Skin) 
-to generate the output. The files are:
- * SkinCologneBlue.php
- * SkinNostalgia.php
- * SkinStandard.php
- * SkinWikimediaWiki.php
-If you want to change those skins, you have to edit these PHP files.
- 
-Since 1.3 a new special skin file is available: SkinPHPTal.php. It makes use of
-the PHPTal template engine and allows you to separate code and layout of the
-pages. The default 1.3 skin is MonoBook and it uses the SkinPHPTAL class.
+== Extension skins ==
 
-To change the layout, just edit the PHPTal template (templates/xhtml_slim.pt) 
-as well as the stylesheets (stylesheets/monobook/*).
+It is now possible (since MediaWiki 1.12) to write a skin as a standard
+MediaWiki extension, enabled via LocalSettings.php. This is done by adding 
+it to $wgValidSkinNames, for example:
 
+$wgValidSkinNames['mycoolskin'] = 'My cool skin';
 
-== pre 1.3 version ==
+and then registering a class in $wgAutoloadClasses called SkinMycoolskin, which 
+derives from Skin. This technique is apparently not yet used (as of 2008) 
+outside the DumpHTML extension.
 
-Unfortunately there isn't any documentation, and the code's in a bit of a mess
-right now during the transition from the old skin code to the new template-based
-skin code in 1.3.