From 5fb92b7d1260465b935140d64d71f01b83b9f880 Mon Sep 17 00:00:00 2001
From: Erik Moeller <erik@users.mediawiki.org>
Date: Thu, 25 Aug 2005 03:07:45 +0000
Subject: [PATCH] try to better document the distinction between wfMsg() and
 wfMsgForContent()

---
 includes/GlobalFunctions.php | 32 ++++++++++++++++++++++++++++++--
 1 file changed, 30 insertions(+), 2 deletions(-)

diff --git a/includes/GlobalFunctions.php b/includes/GlobalFunctions.php
index ddb39ffb91..f5ef44b72e 100644
--- a/includes/GlobalFunctions.php
+++ b/includes/GlobalFunctions.php
@@ -264,9 +264,18 @@ function wfReadOnly() {
 
 
 /**
- * Get a message from anywhere, for the current user language
+ * Get a message from anywhere, for the current user language.
  *
- * @param string
+ * Use wfMsgForContent() instead if the message should NOT 
+ * change depending on the user preferences.
+ *
+ * Note that the message may contain HTML, and is therefore
+ * not safe for insertion anywhere. Some functions such as
+ * addWikiText will do the escaping for you. Use wfMsgHtml()
+ * if you need an escaped message.
+ *
+ * @param string lookup key for the message, usually 
+ *    defined in languages/Language.php
  */
 function wfMsg( $key ) {
 	$args = func_get_args();
@@ -276,6 +285,25 @@ function wfMsg( $key ) {
 
 /**
  * Get a message from anywhere, for the current global language
+ * set with $wgLanguageCode.
+ * 
+ * Use this if the message should NOT change  dependent on the 
+ * language set in the user's preferences. This is the case for 
+ * most text written into logs, as well as link targets (such as 
+ * the name of the copyright policy page). Link titles, on the 
+ * other hand, should be shown in the UI language.
+ *
+ * Note that MediaWiki allows users to change the user interface 
+ * language in their preferences, but a single installation 
+ * typically only contains content in one language.
+ * 
+ * Be wary of this distinction: If you use wfMsg() where you should 
+ * use wfMsgForContent(), a user of the software may have to 
+ * customize over 70 messages in order to, e.g., fix a link in every
+ * possible language.
+ *
+ * @param string lookup key for the message, usually 
+ *    defined in languages/Language.php
  */
 function wfMsgForContent( $key ) {
 	global $wgForceUIMsgAsContentMsg;
-- 
2.20.1