docs/title.doc

   1 TITLE.DOC
   2
   3 The Wikipedia software's "Title" class represents article
   4 titles, which are used for many purposes: as the human-readable
   5 text title of the article, in the URL used to access the article,
   6 the wikitext link to the article, the key into the article
   7 database, and so on. The class in instantiated from one of
   8 these forms and can be queried for the others, and for other
   9 attributes of the title. This is intended to be an
  10 immutable "value" class, so there are no mutator functions.
  11
  12 To get a new instance, call one of the static factory
  13 methods WikiTitle::newFromURL(), WikiTitle::newFromDBKey(),
  14 or WikiTitle::newFromText(). Once instantiated, the
  15 other non-static accessor methods can be used, such as
  16 getText(), getDBKey(), getNamespace(), etc.
  17
  18 The prefix rules: a title consists of an optional Interwiki
  19 prefix (such as "m:" for meta or "de:" for German), followed
  20 by an optional namespace, followed by the remainder of the
  21 title. Both Interwiki prefixes and namespace prefixes have
  22 the same rules: they contain only letters, digits, space, and
  23 underscore, must start with a letter, are case insensitive,
  24 and spaces and underscores are interchangeable.  Prefixes end
  25 with a ":". A prefix is only recognized if it is one of those
  26 specifically allowed by the software. For example, "de:name"
  27 is a link to the article "name" in the German Wikipedia, because
  28 "de" is recognized as one of the allowable interwikis. The
  29 title "talk:name" is a link to the article "name" in the "talk"
  30 namespace of the current wiki, because "talk" is a recognized
  31 namespace. Both may be present, and if so, the interwiki must
  32 come first, for example, "m:talk:name". If a title begins with
  33 a colon as its first character, no prefixes are scanned for,
  34 and the colon is just removed. Note that because of these
  35 rules, it is possible to have articles with colons in their
  36 names. "E. Coli 0157:H7" is a valid title, as is "2001: A Space
  37 Odyssey", because "E. Coli 0157" and "2001" are not valid
  38 interwikis or namespaces. Likewise, ":de:name" is a link to
  39 the article "de:name"--even though "de" is a valid interwiki,
  40 the initial colon stops all prefix matching.
  41
  42 Character mapping rules: Once prefixes have been stripped, the
  43 rest of the title processed this way: spaces and underscores are
  44 treated as equivalent and each is converted to the other in the
  45 appropriate context (underscore in URL and database keys, spaces
  46 in plain text). "Extended" characters in the 0x80..0xFF range
  47 are allowed in all places, and are valid characters. They are
  48 encoded in URLs.  Other characters may be ASCII letters, digits,
  49 hyphen, comma, period, apostrophe, parentheses, and colon. No
  50 other ASCII characters are allowed, and will be deleted if found
  51 (they will probably cause a browser to misinterpret the URL).
  52 Extended characters are _not_ urlencoded when used as text or
  53 database keys.
  54
  55 Character encoding rules: TODO
  56
  57 Canonical forms: the canonical form of a title will always be
  58 returned by the object. In this form, the first (and only the
  59 first) character of the namespace and title will be uppercased;
  60 the rest of the namespace will be lowercased, while the title
  61 will be left as is. The text form will use spaces, the URL and
  62 DBkey forms will use underscores. Interwiki prefixes are all
  63 lowercase. The namespace will use underscores when returned
  64 alone; it will use spaces only when attached to the text title.
  65
  66 getArticleID() needs some explanation: for "internal" articles,
  67 it should return the "cur_id" field if the article exists, else
  68 it returns 0. For all external articles it returns 0. All of
  69 the IDs for all instances of Title created during a request are
  70 cached, so they can be looked up wuickly while rendering wiki
  71 text with lots of internal links.
  72