From 95081de7517c29e25a9a7ffee8457e0b5b15df57 Mon Sep 17 00:00:00 2001
From: Brion Vibber <brion@users.mediawiki.org>
Date: Fri, 13 Aug 2010 23:37:45 +0000
Subject: [PATCH] More explanatory (and English ;) doc comments for Esperanto
 surrogate conversion in LanguageEo::iconv()

---
 languages/classes/LanguageEo.php | 34 ++++++++++++++++++++++++++++++--
 1 file changed, 32 insertions(+), 2 deletions(-)

diff --git a/languages/classes/LanguageEo.php b/languages/classes/LanguageEo.php
index 8df9965791..3486a7d957 100644
--- a/languages/classes/LanguageEo.php
+++ b/languages/classes/LanguageEo.php
@@ -3,11 +3,41 @@
 /** Esperanto (Esperanto)
  *
  * @ingroup Language
+ * @author Brion Vibber <brion@pobox.com>
  */
 class LanguageEo extends Language {
+	/**
+	 * Wrapper for charset conversions.
+	 *
+	 * In most languages, this calls through to standard system iconv(), but
+	 * for Esperanto we're also adding a special pseudo-charset to convert
+	 * accented characters to/from the ASCII-friendly "X" surrogate coding:
+	 *
+	 *     cx = ĉ     cxx = cx
+	 *     gx = ĝ     gxx = gx
+	 *     hx = ĥ     hxx = hx
+	 *     jx = ĵ     jxx = jx
+	 *     sx = ŝ     sxx = sx
+	 *     ux = Å­     uxx = ux
+	 *     xx = x
+	 *
+	 *   http://en.wikipedia.org/wiki/Esperanto_orthography#X-system
+	 *   http://eo.wikipedia.org/wiki/X-sistemo
+	 *
+	 * X-conversion is applied, in either direction, between "utf-8" and "x" charsets;
+	 * this comes into effect when input is run through $wgRequest->getText() and the
+	 * $wgEditEncoding is set to 'x'.
+	 *
+	 * In the long run, this should be moved out of here and into the client-side
+	 * editor behavior; the original server-side translation system dates to 2002-2003
+	 * when many browsers will really bad Unicode support were still in use.
+	 *
+	 * @param string $in input character set
+	 * @param string $out output character set
+	 * @param string $string text to be converted
+	 * @return string
+	 */
 	function iconv( $in, $out, $string ) {
-		# Por multaj lingvoj, ĉi tiu nur voku la sisteman funkcion iconv()
-		# Ni ankaÅ­ konvertu X-sistemajn surogotajn
 		if ( strcasecmp( $in, 'x' ) == 0 && strcasecmp( $out, 'utf-8' ) == 0 ) {
 			return preg_replace_callback (
 				'/([cghjsu]x?)((?:xx)*)(?!x)/i',
-- 
2.20.1