From 985050a6b07f171700b529cb3bc53100a7848e5e Mon Sep 17 00:00:00 2001 From: Alexandre Emsenhuber Date: Thu, 17 Jul 2008 18:12:20 +0000 Subject: [PATCH] Doc tweaks: * Moved doc about primary scripts to scripts.txt * Lines ending to 80 chars --- docs/README | 13 ++-- docs/design.txt | 188 +++++++++++++++++++++------------------------- docs/globals.txt | 51 ++++++------- docs/language.txt | 37 +++++---- docs/scripts.txt | 63 ++++++++++++++++ docs/title.txt | 113 ++++++++++++---------------- 6 files changed, 241 insertions(+), 224 deletions(-) create mode 100644 docs/scripts.txt diff --git a/docs/README b/docs/README index e538fb9d0d..8ccb9aed52 100644 --- a/docs/README +++ b/docs/README @@ -1,17 +1,14 @@ [May 31st 2007] -The 'docs' directory contain various text files that should help you -understand the most importants classes in MediaWiki. +The 'docs' directory contain various text files that should help you understand +the most importants classes in MediaWiki. API documentation is automatically generated and updated daily at: http://svn.wikimedia.org/doc/ -You can get a fresh version using 'make doc' or mwdocgen.php -in the ../maintenance/ directory. +You can get a fresh version using 'make doc' or mwdocgen.php in the +../maintenance/ directory. - -For end user / administrators, most of the documentation -is located online at: +For end user / administrators, most of the documentation is located online at: http://www.mediawiki.org/wiki/Help:Contents - diff --git a/docs/design.txt b/docs/design.txt index 1a35d5b0dd..d1904e1e7b 100644 --- a/docs/design.txt +++ b/docs/design.txt @@ -1,128 +1,110 @@ +design.txt + This is a brief overview of the new design. More thorough and up-to-date information is available on the documentation wiki at http://www.mediawiki.org/ -Primary source files/objects: - - index.php - Main script. It creates the necessary global objects and parses - the URL to determine what to do, which it then generally passes - off to somebody else (depending on the action to be taken). - - All of the functions to which it might delegate generally do - their job by sending content to the $wgOut object. After returning, - the script flushes that out by calling $wgOut->output(). If there - are any changes that need to be made to the database that can be - deferred until after page display, those happen at the end. - - Note that the order in the includes is touchy; Language uses - some global functions, etc. Likewise with the creation of the - global variables. Don't move them around without some forethought. +Primary classes: User - Encapsulates the state of the user viewing/using the site. - Can be queried for things like the user's settings, name, etc. - Handles the details of getting and saving to the "user" table - of the database, and dealing with sessions and cookies. - More details in USER.TXT. + Encapsulates the state of the user viewing/using the site. Can be queried + for things like the user's settings, name, etc. Handles the details of + getting and saving to the "user" table of the database, and dealing with + sessions and cookies. OutputPage - Encapsulates the entire HTML page that will be sent in - response to any server request. It is used by calling its - functions to add text, headers, etc., in any order, and then - calling output() to send it all. It could be easily changed - to send incrementally if that becomes useful, but I prefer - the flexibility. This should also do the output encoding. - The system allocates a global one in $wgOut. + Encapsulates the entire HTML page that will be sent in response to any + server request. It is used by calling its functions to add text, headers, + etc., in any order, and then calling output() to send it all. It could be + easily changed to send incrementally if that becomes useful, but I prefer + the flexibility. This should also do the output encoding. The system + allocates a global one in $wgOut. Title - Represents the title of an article, and does all the work - of translating among various forms such as plain text, URL, - database key, etc. For convenience, and for historical - reasons, it also represents a few features of articles that - don't involve their text, such as access rights. + Represents the title of an article, and does all the work of translating + among various forms such as plain text, URL, database key, etc. For + convenience, and for historical reasons, it also represents a few features + of articles that don't involve their text, such as access rights. + See also title.txt. Article - Encapsulates access to the "page" table of the database. The - object represents a an article, and maintains state such as - text (in Wikitext format), flags, etc. + Encapsulates access to the "page" table of the database. The object + represents a an article, and maintains state such as text (in Wikitext + format), flags, etc. Revision Encapsulates individual page revision data and access to the - revision/text/blobs storage system. Higher-level code should - never touch text storage directly; this class mediates it. + revision/text/blobs storage system. Higher-level code should never touch + text storage directly; this class mediates it. Skin - Encapsulates a "look and feel" for the wiki. All of the - functions that render HTML, and make choices about how to - render it, are here, and are called from various other - places when needed (most notably, OutputPage::addWikiText()). - The StandardSkin object is a complete implementation, and is - meant to be subclassed with other skins that may override - some of its functions. The User object contains a reference - to a skin (according to that user's preference), and so - rather than having a global skin object we just rely on the - global User and get the skin with $wgUser->getSkin(). + Encapsulates a "look and feel" for the wiki. All of the functions that + render HTML, and make choices about how to render it, are here, and are + called from various other places when needed (most notably, + OutputPage::addWikiText()). The StandardSkin object is a complete + implementation, and is meant to be subclassed with other skins that may + override some of its functions. The User object contains a reference to a + skin (according to that user's preference), and so rather than having a + global skin object we just rely on the global User and get the skin with + $wgUser->getSkin(). + See also skin.txt. Language - Represents the language used for incidental text, and also - has some character encoding functions and other locale stuff. - The current user interface language is instantiated as $wgLang, - and the local content language as $wgContLang; be sure to use - the *correct* language object depending upon the circumstances. + Represents the language used for incidental text, and also has some + character encoding functions and other locale stuff. The current user + interface language is instantiated as $wgLang, and the local content + language as $wgContLang; be sure to use the *correct* language object + depending upon the circumstances. + See also language.txt. + + Parser + Class used to transform wikitext to html. LinkCache - Keeps information on existence of articles. See LINKCACHE.TXT. + Keeps information on existence of articles. See linkcache.txt. Naming/coding conventions: - These are meant to be descriptive, not dictatorial; I won't - presume to tell you how to program, I'm just describing the - methods I chose to use for myself. If you do choose to - follow these guidelines, it will probably be easier for you - to collaborate with others on the project, but if you want - to contribute without bothering, by all means do so (and don't - be surprised if I reformat your code). - - - I have the code indented with tabs to save file size and - so that users can set their tab stops to any depth they like. - I use 4-space tab stops, which work well. I also use K&R brace - matching style. I know that's a religious issue for some, - so if you want to use a style that puts opening braces on the - next line, that's OK too, but please don't use a style where - closing braces don't align with either the opening brace on - its own line or the statement that opened the block--that's - confusing as hell. - - - Certain functions and class members are marked with - /* private */, rather than being marked as such. This is a - hold-over from PHP 4, which didn't support proper visibilities. - You should not access things marked in this manner outside the - class/inheritance line as this code is subjected to be updated - in a manner that enforces this at some time in the near future, - and things will break. New code should use the standard method of - setting visibilities as normal. - - - Member variables are generally "mXxx" to distinguish them. - This should make it easier to spot errors of forgetting the - required "$this->", which PHP will happily accept by creating - a new local variable rather than complaining. - - - Globals are particularly evil in PHP; it sets a lot of them - automatically from cookies, query strings, and such, leading to - namespace conflicts; when a variable name is used in a function, - it is silently declared as a new local masking the global, so - you'll get weird error because you forgot the global declaration; - lack of static class member variables means you have to use - globals for them, etc. Evil, evil. - - I think I've managed to pare down the number of globals we use - to a scant few dozen or so, and I've prefixed them all with "wg" - so you can spot errors better (odds are, if you see a "wg" - variable being used in a function that doesn't declare it global, - that's probably an error). - - Other conventions: Top-level functions are wfFuncname(), names - of session variables are wsName, cookies wcName, and form field - values wpName ("p" for "POST"). \ No newline at end of file + These are meant to be descriptive, not dictatorial; I won't presume to tell + you how to program, I'm just describing the methods I chose to use for myself. + If you do choose to follow these guidelines, it will probably be easier for + you to collaborate with others on the project, but if you want to contribute + without bothering, by all means do so (and don't be surprised if I reformat + your code). + + - I have the code indented with tabs to save file size and so that users can + set their tab stops to any depth they like. I use 4-space tab stops, which + work well. I also use K&R brace matching style. I know that's a religious + issue for some, so if you want to use a style that puts opening braces on + the next line, that's OK too, but please don't use a style where closing + braces don't align with either the opening brace on its own line or the + statement that opened the block--that's confusing as hell. + + - Certain functions and class members are marked with /* private */, rather + than being marked as such. This is a hold-over from PHP 4, which didn't + support proper visibilities. You should not access things marked in this + manner outside the class/inheritance line as this code is subjected to be + updated in a manner that enforces this at some time in the near future, and + things will break. New code should use the standard method of setting + visibilities as normal. + + - Member variables are generally "mXxx" to distinguish them. This should make + it easier to spot errors of forgetting the required "$this->", which PHP + will happily accept by creating a new local variable rather than complaining. + + - Globals are particularly evil in PHP; it sets a lot of them automatically + from cookies, query strings, and such, leading to namespace conflicts; when + a variable name is used in a function, it is silently declared as a new + local masking the global, so you'll get weird error because you forgot the + global declaration; lack of static class member variables means you have to + use globals for them, etc. Evil, evil. + + I think I've managed to pare down the number of globals we use to a scant + few dozen or so, and I've prefixed them all with "wg" so you can spot errors + better (odds are, if you see a "wg" variable being used in a function that + doesn't declare it global, that's probably an error). + + Other conventions: Top-level functions are wfFuncname(), names of session + variables are wsName, cookies wcName, and form field values wpName ("p" for + "POST"). diff --git a/docs/globals.txt b/docs/globals.txt index 11780df832..46486dd824 100644 --- a/docs/globals.txt +++ b/docs/globals.txt @@ -1,12 +1,10 @@ globals.txt -Globals are evil. The original MediaWiki code relied on -globals for processing context far too often. MediaWiki -development since then has been a story of slowly moving -context out of global variables and into objects. Storing -processing context in object member variables allows those -objects to be reused in a much more flexible way. Consider -the elegance of: +Globals are evil. The original MediaWiki code relied on globals for processing +context far too often. MediaWiki development since then has been a story of +slowly moving context out of global variables and into objects. Storing +processing context in object member variables allows those objects to be reused +in a much more flexible way. Consider the elegance of: # Generate the article HTML as if viewed by a web request $article = new Article( Title::newFromText( $t ) ); @@ -27,22 +25,19 @@ versus $wgTitle = $oldTitle $wgArticle = $oldArticle -Some of the current MediaWiki developers have an idle -fantasy that some day, globals will be eliminated from -MediaWiki entirely, replaced by an application object which -would be passed to constructors. Whether that would be an -efficient, convenient solution remains to be seen, but -certainly PHP 5 makes such object-oriented programming -models easier than they were in previous versions. - -For the time being though, MediaWiki programmers will have -to work in an environment with some global context. At the -time of writing, 418 globals were initialised on startup by -MediaWiki. 304 of these were configuration settings, which -are documented in DefaultSettings.php. There is no -comprehensive documentation for the remaining 114 globals, -however some of the most important ones are listed below. -They are typically initialised either in index.php or in +Some of the current MediaWiki developers have an idle fantasy that some day, +globals will be eliminated from MediaWiki entirely, replaced by an application +object which would be passed to constructors. Whether that would be an +efficient, convenient solution remains to be seen, but certainly PHP 5 makes +such object-oriented programming models easier than they were in previous +versions. + +For the time being though, MediaWiki programmers will have to work in an +environment with some global context. At the time of writing, 418 globals were +initialised on startup by MediaWiki. 304 of these were configuration settings, +which are documented in DefaultSettings.php. There is no comprehensive +documentation for the remaining 114 globals, however some of the most important +ones are listed below. They are typically initialised either in index.php or in Setup.php. For a description of the classes, see design.txt. @@ -57,19 +52,16 @@ $wgOut OutputPage object for HTTP response. $wgUser - User object for the user associated with the current - request. + User object for the user associated with the current request. $wgLang Language object selected by user preferences. $wgContLang - Language object associated with the wiki being - viewed. + Language object associated with the wiki being viewed. $wgParser - Parser object. Parser extensions register their - hooks here. + Parser object. Parser extensions register their hooks here. $wgRequest WebRequest object, to get request data @@ -79,4 +71,3 @@ $wgMemc, $messageMemc, $parserMemc $wgMessageCache Message cache, to manage interface messages - diff --git a/docs/language.txt b/docs/language.txt index 9d6a0db329..1df9881005 100644 --- a/docs/language.txt +++ b/docs/language.txt @@ -1,24 +1,21 @@ language.txt -The Language object handles all readable text produced by the -software. The most used function is getMessage(), usually -called with the wrapper function wfMsg() which calls that method -on the global language object. It just returns a piece of text -given a text key. It is recommended that you use each key only -once--bits of text in different contexts that happen to be -identical in English may not be in other languages, so it's -better to add new keys than to reuse them a lot. Likewise, -if there is text that gets combined with things like names and -titles, it is better to put markers like "$1" inside a piece -of text and use str_replace() than to compose such messages in -code, because their order may change in other languages too. +The Language object handles all readable text produced by the software. The most +used function is getMessage(), usually called with the wrapper function wfMsg() +which calls that method on the global language object. It just returns a piece +of text given a text key. It is recommended that you use each key only +once--bits of text in different contexts that happen to be identical in English +may not be in other languages, so it's better to add new keys than to reuse them +a lot. Likewise, if there is text that gets combined with things like names and +titles, it is better to put markers like "$1" inside a piece of text and use +str_replace() than to compose such messages in code, because their order may +change in other languages too. -While the system is running, there will be one global language -object, which will be a subtype of Language. The methods in -these objects will return the native text requested if available, -otherwise they fall back to sending English text (which is why -the LanguageEn object has no code at all--it just inherits the -English defaults of the Language base class). +While the system is running, there will be one global language object, which +will be a subtype of Language. The methods in these objects will return the +native text requested if available, otherwise they fall back to sending English +text (which is why the LanguageEn object has no code at all--it just inherits +the English defaults of the Language base class). -The names of the namespaces are also contained in the language -object, though the numbers are fixed. +The names of the namespaces are also contained in the language object, though +the numbers are fixed. diff --git a/docs/scripts.txt b/docs/scripts.txt new file mode 100644 index 0000000000..819261d72f --- /dev/null +++ b/docs/scripts.txt @@ -0,0 +1,63 @@ +scripts.txt + +MediaWiki primary scripts are in the root directory of the software. Users +should only use these scripts to access the wiki. There are also some .php that +aren't primary scripts but helper files and won't work if they are accessed +directly by the web. + +Primary scripts: + + index.php + Main access point. It handles the most of requests. + See http://www.mediawiki.org/wiki/Manual:Index.php + + api.php + Script to provide an API for bots to fetch content and informations about + the site and also modify it. See http://www.mediawiki.org/wiki/API + for more informations. + + img_auth.php + Script that only serve images to logged in users. To configure the wiki + to use that script, see http://www.mediawiki.org/wiki/Manual:Image_Authorisation. + + opensearch_desc.php + Returns a OpenSearch description document (see http://www.opensearch.org/) + that points to the search engines of the wiki. + + profileinfo.php + Allow users to see the profiling information that are stored in the + database. + + To save the profiling information in the database (required to use this + script), you have to modify StartProfiler.php to use the Profiler class and + not the stub profiler which is enabled by default. + You will also need to set $wgProfileToDatabase to true in LocalSettings.php + to force the profiler to save the informations in the database and apply the + maintenance/archives/patch-profiling.sql patch to the database. + + To enable the profileinfo.php itself, you'll need to create the + AdminSettings.php file (see AdminSettings.sample for more information) and + set $wgEnableProfileInfo to true in that file. See also + http://www.mediawiki.org/wiki/How_to_debug#Profiling. + + redirect.php + Script that only redirect to the article passed in the wpDropdown parameter + of the request. Used by the nostalgia skin to access special pages with the + dropdown box at the top of the page. + + thumb.php + Script used to resize images if it is configured to be done when to web + browser requests the image and not when generating the page. This script can + be used as a 404 handler to generate image thumbs when they don't exist. + + trackback.php + Allow to add a new trackback to the database. This script returns XML + and require a POST request to work, thus it should only be accessed by some + specific programs and won't work with normal web browsers. + +There is also a file with a .php5 extension for each script. They can be used if +the web server needs a .php5 to run the file with the PHP 5 engine and runs .php +scripts with PHP 4. To use these files, you have to modify $wgScriptExtension to +'.php5' is LocalSettings.php but it is already done by the config script if you +used the config/index.php5 script. + diff --git a/docs/title.txt b/docs/title.txt index 2432bae50b..d2d91c9c28 100644 --- a/docs/title.txt +++ b/docs/title.txt @@ -1,80 +1,67 @@ title.txt -The MediaWiki software's "Title" class represents article -titles, which are used for many purposes: as the human-readable -text title of the article, in the URL used to access the article, -the wikitext link to the article, the key into the article -database, and so on. The class in instantiated from one of -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. +The MediaWiki software's "Title" class represents article titles, which are used +for many purposes: as the human-readable text title of the article, in the URL +used to access the article, the wikitext link to the article, the key into the +article database, and so on. The class in instantiated from one of 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 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. +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 -by an optional namespace, followed by the remainder of the -title. Both interwiki prefixes and namespace prefixes have -the same rules: they contain only letters, digits, space, and -underscore, must start with a letter, are case insensitive, -and spaces and underscores are interchangeable. Prefixes end -with a ":". A prefix is only recognized if it is one of those -specifically allowed by the software. For example, "de:name" -is a link to the article "name" in the German Wikipedia, because -"de" is recognized as one of the allowable interwikis. The -title "talk:name" is a link to the article "name" in the "talk" -namespace of the current wiki, because "talk" is a recognized -namespace. Both may be present, and if so, the interwiki must -come first, for example, "m:talk:name". If a title begins with -a colon as its first character, no prefixes are scanned for, -and the colon is just removed. Note that because of these -rules, it is possible to have articles with colons in their -names. "E. Coli 0157:H7" is a valid title, as is "2001: A Space -Odyssey", because "E. Coli 0157" and "2001" are not valid -interwikis or namespaces. +The prefix rules: a title consists of an optional interwiki prefix (such as "m:" +for meta or "de:" for German), followed by an optional namespace, followed by +the remainder of the title. Both interwiki prefixes and namespace prefixes have +the same rules: they contain only letters, digits, space, and underscore, must +start with a letter, are case insensitive, and spaces and underscores are +interchangeable. Prefixes end with a ":". A prefix is only recognized if it is +one of those specifically allowed by the software. For example, "de:name" is a +link to the article "name" in the German Wikipedia, because "de" is recognized +as one of the allowable interwikis. The title "talk:name" is a link to the +article "name" in the "talk" namespace of the current wiki, because "talk" is a +recognized namespace. Both may be present, and if so, the interwiki must +come first, for example, "m:talk:name". If a title begins with a colon as its +first character, no prefixes are scanned for, and the colon is just removed. +Note that because of these rules, it is possible to have articles with colons in +their names. "E. Coli 0157:H7" is a valid title, as is "2001: A Space Odyssey", +because "E. Coli 0157" and "2001" are not valid interwikis or namespaces. -It is not possible to have an article whose bare name includes -a namespace or interwiki prefix. +It is not possible to have an article whose bare name includes 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. It is also used to indicate the main -namespace in template inclusions. +An initial colon in a title listed in wiki text may however suppress special +handling for interlanguage links, image links, and category links. It is also +used to indicate the main namespace in template inclusions. -Once prefixes have been stripped, the rest of the title processed -this way: +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). +* 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. +* 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 -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. +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. +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. See linkcache.txt. +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. See linkcache.txt. -- 2.20.1