Thijs/wiki.techinc.nl
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Updated various things in the docs directory. Completely rewrote skin.txt, updated database.txt, memcached.txt and title.txt.

Browse source
This commit is contained in:
Tim Starling 2008-07-09 05:50:05 +00:00
parent 302805bfd7
commit c8aaab18c5
5 changed files with 126 additions and 96 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
docs/README
View file

@ -13,5 +13,5 @@ in the ../maintenance/ directory.
For end user / administrators, most of the documentation
is located online at:
http://www.mediawiki.org/wiki/Project:Help
http://www.mediawiki.org/wiki/Help:Contents

7
docs/database.txt
View file

@ -158,12 +158,9 @@ enclose small groups of queries in their own transaction. Use the
following syntax:
$dbw = wfGetDB( DB_MASTER );
$dbw->immediateBegin();
$dbw->begin();
/* Do queries */
$dbw->immediateCommit();
There are functions called begin() and commit() but they don't do what
you would expect. Don't use them.
$dbw->commit();
Use of locking reads (e.g. the FOR UPDATE clause) is not advised. They
are poorly implemented in InnoDB and will cause regular deadlock errors.

50
docs/memcached.txt
View file

@ -1,15 +1,19 @@
memcached support for MediaWiki:
From ca August 2003, MediaWiki has optional support for memcached, a
"high-performance, distributed memory object caching system".
For general information on it, see: http://www.danga.com/memcached/
MediaWiki has optional support for memcached, a "high-performance,
distributed memory object caching system". For general information
on it, see: http://www.danga.com/memcached/
Memcached is likely more trouble than a small site will need, but
for a larger site with heavy load, like Wikipedia, it should help
lighten the load on the database servers by caching data and objects
in memory.
== Requirements ==
== Installation ==
Packages are available for Fedora, Debian, Ubuntu and probably other
Linux distributions. If you there's no package available for your
distribution, you can compile it from source.
== Compilation ==
* PHP must be compiled with --enable-sockets
@ -35,18 +39,21 @@ server is appropriately firewalled, and that the port(s) used for
memcached servers are not publicly accessible. Otherwise, anyone on
the internet can put data into and read data from your cache.
An attacker familiar with MediaWiki internals could use this to give
themselves developer access and delete all data from the wiki's
database, as well as getting all users' password hashes and e-mail
addresses.
An attacker familiar with MediaWiki internals could use this to steal
passwords and email addresses, or to make themselves a sysop and
install malicious javascript on the site. There may be other types
of vulnerability, no audit has been done -- so be safe and keep it
behind a firewall.
********************* W A R N I N G ! ! ! ! ! ***********************
== Setup ==
If you want to start small, just run one memcached on your web
server:
If you installed memcached using a distro, the daemon should be started
automatically using /etc/init.d/memcached.
memcached -d -l 127.0.0.1 -p 11000 -m 64
To start the daemon manually, use something like:
memcached -d -l 127.0.0.1 -p 11211 -m 64
(to run in daemon mode, accessible only via loopback interface,
on port 11000, using up to 64MB of memory)
@ -54,7 +61,7 @@ on port 11000, using up to 64MB of memory)
In your LocalSettings.php file, set:
$wgMainCacheType = CACHE_MEMCACHED;
$wgMemCachedServers = array( "127.0.0.1:11000" );
$wgMemCachedServers = array( "127.0.0.1:11211" );
The wiki should then use memcached to cache various data. To use
multiple servers (physically separate boxes or multiple caches
@ -70,15 +77,10 @@ usage evenly), make its entry a subarray:
== PHP client for memcached ==
As of this writing, MediaWiki includes version 1.0.10 of the PHP
memcached client by Ryan Gilfether <hotrodder@rocketmail.com>.
You'll find some documentation for it in the 'php-memcached'
subdirectory under the present one.
MediaWiki uses a fork of Ryan T. Dean's pure-PHP memcached client.
The newer PECL module is not yet supported.
We intend to track updates, but if you want to check for the lastest
released version, see http://www.danga.com/memcached/apis.bml
MediaWiki use three object for memcaching:
MediaWiki uses three object for object caching:
* $wgMemc, controlled by $wgMainCacheType
* $parserMemc, controlled by $wgParserCacheType
* $messageMemc, controlled by $wgMessageCacheType
@ -93,6 +95,8 @@ this is mentionned below.
== Keys used ==
(incomplete, out of date)
Ajax Search:
key: $wgDBname:ajaxsearch:md5( $search )
ex: wikidb:ajaxsearch:9565814d5d564fa898dd6111b94fae0b
@ -244,4 +248,4 @@ User:
set in: User::saveToCache()
cleared by: User::saveSettings(), User::clearSharedCache()
... more to come ...
... more to come ...

103
docs/skin.txt
View file

@ -1,59 +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.
== Version 1.6 and greater ==
There are three legacy skins which were introduced before MediaWiki 1.3:
PHPTal skins doesn't exist anymore. They were replaced by SkinTemplate skins,
introduced since 1.4 to remove the depedency of PHPTal.
* Standard (a.k.a. Classic): The old default skin written by Lee Crocker
during the phase 3 rewrite, in 2002.
A new experimental (disabled by default) callback-based template processor
has been introduced to try to speed up the generation of html pages. See for
example skins/disabled/MonoBookCBT.php.
* 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/
You can find more informations at http://www.mediawiki.org/wiki/Manual:Skins.
* Cologne Blue: A nicer-looking alternative to Standard.
== Version 1.4 ==
And there are four Monobook-derived skins which have been introduced since 1.3:
MediaWiki still use the PHPTal skin system introduced in version 1.3 but some
changes have been made to the file organisation.
* MySkin: Monobook without the CSS. The idea is that you customise it using user
or site CSS (see below)
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.
* 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.
Two samples are provided to start with, one for PHPTal use (SkinPHPTal.sample)
and one without (Skin.sample).
* 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.
== Version 1.3 ==
== Custom CSS/JS ==
The following might help a bit though.
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:
Firstly, there's Skin.php; this file will check various settings, and it
contains a base class from which new skins can be derived.
* [[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
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.
These can also be customised on a per-user basis, by editing
[[User:<name>/monobook.css]], [[User:<name>/monobook.js]], etc.
To change the layout, just edit the PHPTal template (templates/xhtml_slim.pt)
as well as the stylesheets (stylesheets/monobook/*).
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
== pre 1.3 version ==
If you want a different look for your wiki, that gallery is a good place to start.
== Drop-in custom skins ==
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:
$wgDefaultSkin = '<name>';
You can also disable dropped-in or core skins using:
$wgSkipSkins[] = '<name>';
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.
See http://www.mediawiki.org/wiki/Manual:Skinning for more information.
== Extension skins ==
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';
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.

60
docs/title.txt
View file

@ -9,11 +9,10 @@ these forms and can be queried for the others, and for other
attributes of the title. This is intended to be an
immutable "value" class, so there are no mutator functions.
To get a new instance, call one of the static factory
methods Title::newFromURL(), Title::newFromDBKey(),
or Title::newFromText(). Once instantiated, the
other non-static accessor methods can be used, such as
getText(), getDBKey(), getNamespace(), etc.
To get a new instance, call Title::newFromText(). Once instantiated,
the non-static accessor methods can be used, such as getText(),
getDBKey(), getNamespace(), etc. Note that Title::newFromText() may
return false if the text is illegal according to the rules below.
The prefix rules: a title consists of an optional interwiki
prefix (such as "m:" for meta or "de:" for German), followed
@ -42,35 +41,40 @@ a namespace or interwiki prefix.
An initial colon in a title listed in wiki text may however
suppress special handling for interlanguage links, image links,
and category links.
and category links. It is also used to indicate the main
namespace in template inclusions.
Character mapping rules: Once prefixes have been stripped, the
rest of the title processed this way: spaces and underscores are
treated as equivalent and each is converted to the other in the
appropriate context (underscore in URL and database keys, spaces
in plain text). "Extended" characters in the 0x80..0xFF range
are allowed in all places, and are valid characters. They are
encoded in URLs. Other characters may be ASCII letters, digits,
hyphen, comma, period, apostrophe, parentheses, and colon. No
other ASCII characters are allowed, and will be deleted if found
(they will probably cause a browser to misinterpret the URL).
Extended characters are _not_ urlencoded when used as text or
database keys.
Once prefixes have been stripped, the rest of the title processed
this way:
Character encoding rules: TODO
* Spaces and underscores are treated as equivalent and each
is converted to the other in the appropriate context (underscore in
URL and database keys, spaces in plain text).
* Multiple consecutive spaces are converted to a single space.
* Leading or trailing space is removed.
* If $wgCapitalLinks is enabled (the default), the first letter is
capitalised, using the capitalisation function of the content language
object.
* The unicode characters LRM (U+200E) and RLM (U+200F) are silently
stripped.
* Invalid UTF-8 sequences or instances of the replacement character
(U+FFFD) are considered illegal.
* A percent sign followed by two hexadecimal characters is illegal
* Anything that looks like an XML/HTML character reference is illegal
* Any character not matched by the $wgLegalTitleChars regex is illegal
* Zero-length titles (after whitespace stripping) are illegal
Canonical forms: the canonical form of a title will always be
returned by the object. In this form, the first (and only the
first) character of the namespace and title will be uppercased;
the rest of the namespace will be lowercased, while the title
will be left as is. The text form will use spaces, the URL and
DBkey forms will use underscores. Interwiki prefixes are all
lowercase. The namespace will use underscores when returned
alone; it will use spaces only when attached to the text title.
All titles except special pages must be less than 255 bytes when
encoded with UTF-8, because that is the size of the database field.
Special page titles may be up to 512 bytes.
Note that Unicode Normal Form C (NFC) is enforced by MediaWiki's user
interface input functions, and so titles will typically be in this
form.
getArticleID() needs some explanation: for "internal" articles,
it should return the "page_id" field if the article exists, else
it returns 0. For all external articles it returns 0. All of
the IDs for all instances of Title created during a request are
cached, so they can be looked up quickly while rendering wiki
text with lots of internal links.
text with lots of internal links. See linkcache.txt.