From 8f77b0e18991810cbfad321d0ae455be8a9ce066 Mon Sep 17 00:00:00 2001
From: Stanislav Malyshev <stas@php.net>
Date: Thu, 23 Jul 2009 22:21:32 +0000
Subject: [PATCH] add IDN docs, refactor a bit

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@284667 c90b9560-bf6c-de11-be94-00142212c4b1
---
 reference/intl/book.xml                       |   3 +
 reference/intl/constants.xml                  |  36 +++++-
 reference/intl/grapheme.xml                   |  27 +++++
 .../grapheme-extract.xml                      |   2 +-
 .../grapheme-stripos.xml                      |   2 +-
 .../grapheme-stristr.xml                      |   2 +-
 .../grapheme-strlen.xml                       |   2 +-
 .../grapheme-strpos.xml                       |   2 +-
 .../grapheme-strripos.xml                     |   2 +-
 .../grapheme-strrpos.xml                      |   2 +-
 .../grapheme-strstr.xml                       |   2 +-
 .../grapheme-substr.xml                       |   2 +-
 reference/intl/idn.xml                        |  27 +++++
 reference/intl/idn/idn-to-ascii.xml           | 104 ++++++++++++++++++
 reference/intl/idn/idn-to-unicode.xml         |  38 +++++++
 reference/intl/idn/idn-to-utf8.xml            | 104 ++++++++++++++++++
 reference/intl/versions.xml                   |   4 +
 17 files changed, 351 insertions(+), 10 deletions(-)
 create mode 100644 reference/intl/grapheme.xml
 rename reference/intl/{functions => grapheme}/grapheme-extract.xml (99%)
 rename reference/intl/{functions => grapheme}/grapheme-stripos.xml (99%)
 rename reference/intl/{functions => grapheme}/grapheme-stristr.xml (99%)
 rename reference/intl/{functions => grapheme}/grapheme-strlen.xml (98%)
 rename reference/intl/{functions => grapheme}/grapheme-strpos.xml (99%)
 rename reference/intl/{functions => grapheme}/grapheme-strripos.xml (99%)
 rename reference/intl/{functions => grapheme}/grapheme-strrpos.xml (99%)
 rename reference/intl/{functions => grapheme}/grapheme-strstr.xml (99%)
 rename reference/intl/{functions => grapheme}/grapheme-substr.xml (99%)
 create mode 100644 reference/intl/idn.xml
 create mode 100644 reference/intl/idn/idn-to-ascii.xml
 create mode 100644 reference/intl/idn/idn-to-unicode.xml
 create mode 100644 reference/intl/idn/idn-to-utf8.xml

diff --git a/reference/intl/book.xml b/reference/intl/book.xml
index 2c3754d9ae..ca3d9fc9ad 100644
--- a/reference/intl/book.xml
+++ b/reference/intl/book.xml
@@ -95,6 +95,9 @@
  &reference.intl.messageformatter;
  &reference.intl.dateformatter; 
 
+ &reference.intl.grapheme;
+ &reference.intl.idn;
+
  &reference.intl.reference;
 </book>
 
diff --git a/reference/intl/constants.xml b/reference/intl/constants.xml
index 05ea60c15e..28459bdc0c 100644
--- a/reference/intl/constants.xml
+++ b/reference/intl/constants.xml
@@ -1,4 +1,4 @@
-<?xml version="1.0" encoding="utf-8"?>
+<?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
 <appendix xml:id="intl.constants" xmlns="http://docbook.org/ns/docbook"
  xmlns:xlink="http://www.w3.org/1999/xlink">
@@ -17,6 +17,40 @@
      </simpara>
     </listitem>
    </varlistentry>
+   <varlistentry>
+    <term>
+     <constant>IDNA_DEFAULT</constant>
+     (<type>integer</type>)
+    </term>
+    <listitem>
+     <simpara>
+      Prohibit processing of unassigned codepoints in the input for IDN 		
+	  functions and do not check if the input conforms to domain name ASCII rules.
+     </simpara>
+    </listitem>
+   </varlistentry>
+   <varlistentry>
+    <term>
+     <constant>IDNA_ALLOW_UNASSIGNED</constant>
+     (<type>integer</type>)
+    </term>
+    <listitem>
+     <simpara>
+      Allow processing of unassigned codepoints in the input for IDN functions.
+     </simpara>
+    </listitem>
+   </varlistentry>
+   <varlistentry>
+    <term>
+     <constant>IDNA_USE_STD3_RULES</constant>
+     (<type>integer</type>)
+    </term>
+    <listitem>
+     <simpara>
+      Check if the input for IDN functions conforms to domain name ASCII rules.
+     </simpara>
+    </listitem>
+   </varlistentry>
   </variablelist>
  </para>
 </appendix>
diff --git a/reference/intl/grapheme.xml b/reference/intl/grapheme.xml
new file mode 100644
index 0000000000..c37e20e8db
--- /dev/null
+++ b/reference/intl/grapheme.xml
@@ -0,0 +1,27 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision: 283819 $ -->
+<reference xml:id="ref.intl.grapheme" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
+ <title>Grapheme &Functions;</title>
+ &reference.intl.entities.grapheme;
+</reference>
+
+<!-- Keep this comment at the end of the file
+ Local variables:
+ mode: sgml
+ sgml-omittag:t
+ sgml-shorttag:t
+ sgml-minimize-attributes:nil
+ sgml-always-quote-attributes:t
+ sgml-indent-step:1
+ sgml-indent-data:t
+ indent-tabs-mode:nil
+ sgml-parent-document:nil
+ sgml-default-dtd-file:"../../../manual.ced"
+ sgml-exposed-tags:nil
+ sgml-local-catalogs:nil
+ sgml-local-ecat-files:nil
+ End:
+ vim600: syn=xml fen fdm=syntax fdl=2 si
+ vim: et tw=78 syn=sgml
+ vi: ts=1 sw=1
+-->
diff --git a/reference/intl/functions/grapheme-extract.xml b/reference/intl/grapheme/grapheme-extract.xml
similarity index 99%
rename from reference/intl/functions/grapheme-extract.xml
rename to reference/intl/grapheme/grapheme-extract.xml
index ab2386eb01..d87aeeaa08 100644
--- a/reference/intl/functions/grapheme-extract.xml
+++ b/reference/intl/grapheme/grapheme-extract.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- $Revision$ -->
+<!-- $Revision: 283819 $ -->
 <refentry xml:id="function.grapheme-extract" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
   <refname>grapheme_extract</refname>
diff --git a/reference/intl/functions/grapheme-stripos.xml b/reference/intl/grapheme/grapheme-stripos.xml
similarity index 99%
rename from reference/intl/functions/grapheme-stripos.xml
rename to reference/intl/grapheme/grapheme-stripos.xml
index 6924c44c0a..3f77a480dc 100644
--- a/reference/intl/functions/grapheme-stripos.xml
+++ b/reference/intl/grapheme/grapheme-stripos.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- $Revision$ -->
+<!-- $Revision: 283819 $ -->
 <refentry xml:id="function.grapheme-stripos" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
   <refname>grapheme_stripos</refname>
diff --git a/reference/intl/functions/grapheme-stristr.xml b/reference/intl/grapheme/grapheme-stristr.xml
similarity index 99%
rename from reference/intl/functions/grapheme-stristr.xml
rename to reference/intl/grapheme/grapheme-stristr.xml
index db0e58a3f1..6edf155d43 100644
--- a/reference/intl/functions/grapheme-stristr.xml
+++ b/reference/intl/grapheme/grapheme-stristr.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- $Revision$ -->
+<!-- $Revision: 283819 $ -->
 <refentry xml:id="function.grapheme-stristr" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
   <refname>grapheme_stristr</refname>
diff --git a/reference/intl/functions/grapheme-strlen.xml b/reference/intl/grapheme/grapheme-strlen.xml
similarity index 98%
rename from reference/intl/functions/grapheme-strlen.xml
rename to reference/intl/grapheme/grapheme-strlen.xml
index 3095f643c8..2c27d0dd54 100644
--- a/reference/intl/functions/grapheme-strlen.xml
+++ b/reference/intl/grapheme/grapheme-strlen.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- $Revision$ -->
+<!-- $Revision: 283819 $ -->
 <refentry xml:id="function.grapheme-strlen" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
   <refname>grapheme_strlen</refname>
diff --git a/reference/intl/functions/grapheme-strpos.xml b/reference/intl/grapheme/grapheme-strpos.xml
similarity index 99%
rename from reference/intl/functions/grapheme-strpos.xml
rename to reference/intl/grapheme/grapheme-strpos.xml
index e719f0c89f..84d2656f56 100644
--- a/reference/intl/functions/grapheme-strpos.xml
+++ b/reference/intl/grapheme/grapheme-strpos.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- $Revision$ -->
+<!-- $Revision: 283819 $ -->
 <refentry xml:id="function.grapheme-strpos" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
   <refname>grapheme_strpos</refname>
diff --git a/reference/intl/functions/grapheme-strripos.xml b/reference/intl/grapheme/grapheme-strripos.xml
similarity index 99%
rename from reference/intl/functions/grapheme-strripos.xml
rename to reference/intl/grapheme/grapheme-strripos.xml
index 4e72066d64..a78b3384e5 100644
--- a/reference/intl/functions/grapheme-strripos.xml
+++ b/reference/intl/grapheme/grapheme-strripos.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- $Revision$ -->
+<!-- $Revision: 283819 $ -->
 <refentry xml:id="function.grapheme-strripos" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
   <refname>grapheme_strripos</refname>
diff --git a/reference/intl/functions/grapheme-strrpos.xml b/reference/intl/grapheme/grapheme-strrpos.xml
similarity index 99%
rename from reference/intl/functions/grapheme-strrpos.xml
rename to reference/intl/grapheme/grapheme-strrpos.xml
index fa57b66614..ae0a877dd4 100644
--- a/reference/intl/functions/grapheme-strrpos.xml
+++ b/reference/intl/grapheme/grapheme-strrpos.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- $Revision$ -->
+<!-- $Revision: 283819 $ -->
 <refentry xml:id="function.grapheme-strrpos" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
   <refname>grapheme_strrpos</refname>
diff --git a/reference/intl/functions/grapheme-strstr.xml b/reference/intl/grapheme/grapheme-strstr.xml
similarity index 99%
rename from reference/intl/functions/grapheme-strstr.xml
rename to reference/intl/grapheme/grapheme-strstr.xml
index dc8e0d31ec..6ce79f6748 100644
--- a/reference/intl/functions/grapheme-strstr.xml
+++ b/reference/intl/grapheme/grapheme-strstr.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- $Revision$ -->
+<!-- $Revision: 283819 $ -->
 <refentry xml:id="function.grapheme-strstr" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
   <refname>grapheme_strstr</refname>
diff --git a/reference/intl/functions/grapheme-substr.xml b/reference/intl/grapheme/grapheme-substr.xml
similarity index 99%
rename from reference/intl/functions/grapheme-substr.xml
rename to reference/intl/grapheme/grapheme-substr.xml
index 91b94927f7..b27e69b364 100644
--- a/reference/intl/functions/grapheme-substr.xml
+++ b/reference/intl/grapheme/grapheme-substr.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- $Revision$ -->
+<!-- $Revision: 283819 $ -->
 <refentry xml:id="function.grapheme-substr" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
   <refname>grapheme_substr</refname>
diff --git a/reference/intl/idn.xml b/reference/intl/idn.xml
new file mode 100644
index 0000000000..bea7ba5d10
--- /dev/null
+++ b/reference/intl/idn.xml
@@ -0,0 +1,27 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision: 283819 $ -->
+<reference xml:id="ref.intl.idn" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
+ <title>IDN &Functions;</title>
+ &reference.intl.entities.idn;
+</reference>
+
+<!-- Keep this comment at the end of the file
+ Local variables:
+ mode: sgml
+ sgml-omittag:t
+ sgml-shorttag:t
+ sgml-minimize-attributes:nil
+ sgml-always-quote-attributes:t
+ sgml-indent-step:1
+ sgml-indent-data:t
+ indent-tabs-mode:nil
+ sgml-parent-document:nil
+ sgml-default-dtd-file:"../../../manual.ced"
+ sgml-exposed-tags:nil
+ sgml-local-catalogs:nil
+ sgml-local-ecat-files:nil
+ End:
+ vim600: syn=xml fen fdm=syntax fdl=2 si
+ vim: et tw=78 syn=sgml
+ vi: ts=1 sw=1
+-->
diff --git a/reference/intl/idn/idn-to-ascii.xml b/reference/intl/idn/idn-to-ascii.xml
new file mode 100644
index 0000000000..4d54bfefb1
--- /dev/null
+++ b/reference/intl/idn/idn-to-ascii.xml
@@ -0,0 +1,104 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision: 283819 $ -->
+<refentry xml:id="function.idn-to-ascii" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
+ <refnamediv>
+  <refname>idn_to_ascii</refname>
+  <refpurpose>Convert domain name to IDNA ASCII form.</refpurpose>
+ </refnamediv>
+ <refsect1 role="description">
+  &reftitle.description;
+  <para>Procedural style</para>
+  <methodsynopsis>
+   <type>string</type><methodname>idn_to_ascii</methodname>
+   <methodparam><type>string</type><parameter>domain</parameter></methodparam>
+   <methodparam choice='opt'><type>int</type><parameter>options</parameter></methodparam>
+  </methodsynopsis>
+  <para>
+   This function converts Unicode domain name to IDNA ASCII-compatible format.  
+  </para> 
+  </refsect1>
+
+ <refsect1 role="parameters">
+  &reftitle.parameters;
+  <para>
+   <variablelist>
+    <varlistentry>
+     <term><parameter>domain</parameter></term>
+     <listitem>
+      <para>
+       Domain to convert. In PHP 5 must be UTF-8 encoded.
+      </para>
+     </listitem>
+    </varlistentry>
+    <varlistentry>
+     <term><parameter>options</parameter></term>
+     <listitem>
+      <para>
+       Conversion options - combination of IDNA_* constants.
+      </para>
+     </listitem>
+    </varlistentry>
+   </variablelist>
+  </para>
+ </refsect1>
+   
+ 
+ <refsect1 role="returnvalues">
+  &reftitle.returnvalues;
+  <para>
+   Domain name encoded in ASCII-compatible form.
+  </para>
+ </refsect1>
+ 
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <example>
+   <title><function>idn_to_ascii</function> example</title>
+   <programlisting role="php">
+<![CDATA[
+<?php
+
+echo idn_to_ascii('täst.de'); 
+
+?>
+]]>
+   </programlisting>
+  </example>
+  &example.outputs;
+  <screen>
+<![CDATA[
+xn--tst-qla.de
+]]>
+  </screen>
+ </refsect1>
+
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <para>
+   <simplelist>
+    <member><function>idn_to_unicode</function></member>
+   </simplelist>
+  </para>
+ </refsect1>
+</refentry>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+indent-tabs-mode:nil
+sgml-parent-document:nil
+sgml-default-dtd-file:"../../../../manual.ced"
+sgml-exposed-tags:nil
+sgml-local-catalogs:nil
+sgml-local-ecat-files:nil
+End:
+vim600: syn=xml fen fdm=syntax fdl=2 si
+vim: et tw=78 syn=sgml
+vi: ts=1 sw=1
+-->
diff --git a/reference/intl/idn/idn-to-unicode.xml b/reference/intl/idn/idn-to-unicode.xml
new file mode 100644
index 0000000000..2188d14ec6
--- /dev/null
+++ b/reference/intl/idn/idn-to-unicode.xml
@@ -0,0 +1,38 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<!-- $Revision: 283839 $ -->
+<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.idn-to-unicode">
+ <refnamediv>
+  <refname>idn_to_unicode</refname>
+  <refpurpose>&Alias; <function>idn_to_utf8</function></refpurpose>
+ </refnamediv>
+
+ <refsect1 role="description">
+  &reftitle.description;
+  <simpara>
+   &info.function.alias;
+   <function>idn_to_utf8</function>.
+  </simpara>
+ </refsect1>
+
+</refentry>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+indent-tabs-mode:nil
+sgml-parent-document:nil
+sgml-default-dtd-file:"../../../../manual.ced"
+sgml-exposed-tags:nil
+sgml-local-catalogs:nil
+sgml-local-ecat-files:nil
+End:
+vim600: syn=xml fen fdm=syntax fdl=2 si
+vim: et tw=78 syn=sgml
+vi: ts=1 sw=1
+-->
diff --git a/reference/intl/idn/idn-to-utf8.xml b/reference/intl/idn/idn-to-utf8.xml
new file mode 100644
index 0000000000..e953649987
--- /dev/null
+++ b/reference/intl/idn/idn-to-utf8.xml
@@ -0,0 +1,104 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision: 283819 $ -->
+<refentry xml:id="function.idn-to-utf8" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
+ <refnamediv>
+  <refname>idn_to_utf8</refname>
+  <refpurpose>Convert domain name from IDNA ASCII to Unicode.</refpurpose>
+ </refnamediv>
+ <refsect1 role="description">
+  &reftitle.description;
+  <para>Procedural style</para>
+  <methodsynopsis>
+   <type>string</type><methodname>idn_to_utf8</methodname>
+   <methodparam><type>string</type><parameter>domain</parameter></methodparam>
+   <methodparam choice='opt'><type>int</type><parameter>options</parameter></methodparam>
+  </methodsynopsis>
+  <para>
+   This function converts Unicode domain name from IDNA ASCII-compatible format to plain Unicode.  
+  </para> 
+  </refsect1>
+
+ <refsect1 role="parameters">
+  &reftitle.parameters;
+  <para>
+   <variablelist>
+    <varlistentry>
+     <term><parameter>domain</parameter></term>
+     <listitem>
+      <para>
+       Domain to convert in IDNA ASCII-compatible format.
+      </para>
+     </listitem>
+    </varlistentry>
+    <varlistentry>
+     <term><parameter>options</parameter></term>
+     <listitem>
+      <para>
+       Conversion options - combination of IDNA_* constants.
+      </para>
+     </listitem>
+    </varlistentry>
+   </variablelist>
+  </para>
+ </refsect1>
+   
+ 
+ <refsect1 role="returnvalues">
+  &reftitle.returnvalues;
+  <para>
+   Domain name in Unicode. In PHP5, domain name will be in UTF-8.
+  </para>
+ </refsect1>
+ 
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <example>
+   <title><function>idn_to_utf8</function> example</title>
+   <programlisting role="php">
+<![CDATA[
+<?php
+
+echo idn_to_utf8('xn--tst-qla.de'); 
+
+?>
+]]>
+   </programlisting>
+  </example>
+  &example.outputs;
+  <screen>
+<![CDATA[
+täst.de
+]]>
+  </screen>
+ </refsect1>
+
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <para>
+   <simplelist>
+    <member><function>idn_to_unicode</function></member>
+   </simplelist>
+  </para>
+ </refsect1>
+</refentry>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+indent-tabs-mode:nil
+sgml-parent-document:nil
+sgml-default-dtd-file:"../../../../manual.ced"
+sgml-exposed-tags:nil
+sgml-local-catalogs:nil
+sgml-local-ecat-files:nil
+End:
+vim600: syn=xml fen fdm=syntax fdl=2 si
+vim: et tw=78 syn=sgml
+vi: ts=1 sw=1
+-->
diff --git a/reference/intl/versions.xml b/reference/intl/versions.xml
index da37ae0f70..ed3518e0ef 100644
--- a/reference/intl/versions.xml
+++ b/reference/intl/versions.xml
@@ -134,6 +134,10 @@
  <function name='intl_get_error_message' from='PHP 5 &gt;= 5.3.0, PECL intl &gt;= 1.0.0'/>
  <function name='intl_is_failure' from='PHP 5 &gt;= 5.3.0, PECL intl &gt;= 1.0.0'/>
  <function name='intl_error_name' from='PHP 5 &gt;= 5.3.0, PECL intl &gt;= 1.0.0'/>
+ <function name='idn_to_ascii' from='PHP 5 &gt;= 5.3.0, PECL intl &gt;= 1.0.2'/>
+ <function name='idn_to_utf8' from='PHP 5 &gt;= 5.3.0, PECL intl &gt;= 1.0.2'/>
+ <function name='idn_to_unicode' from='PHP 6'/>
+
  <function name='locale_get_default' from='PHP 5 &gt;= 5.3.0, PECL intl &gt;= 1.0.0'/>
  <function name='locale_set_default' from='PHP 5 &gt;= 5.3.0, PECL intl &gt;= 1.0.0'/>
  <function name='locale_get_primary_language' from='PHP 5 &gt;= 5.3.0, PECL intl &gt;= 1.0.0'/>