[GENERIC] Manual:

- added section for supported options
- unified section headers
- small rewrite

git-svn-id: http://framework.zend.com/svn/framework/standard/trunk@21247 44c647ce-9c0f-0410-b52a-842ac1e357ba

documentation/manual/en/module_specs/Zend_Validate-Hostname.xml

@@ -10,12 +10,54 @@
         localhost). By default only DNS hostnames are matched.
     </para>
 
-    <para>
-        <emphasis>Basic usage</emphasis>
-    </para>
-
-    <para>
-        A basic example of usage is below:
+    <sect3 id="zend.validate.set.hostname.options">
+        <title>Supported options for Zend_Validate_Hostname</title>
+
+        <para>
+            The following options are supported for <classname>Zend_Validate_Hostname</classname>:
+        </para>
+
+        <itemizedlist>
+            <listitem>
+                <para>
+                    <emphasis><property>allow</property></emphasis>: Defines the sort of hostname
+                    which is allowed to be used. See <link
+                        linkend="zend.validate.set.hostname.types">Hostname types</link> for
+                    details.
+                </para>
+            </listitem>
+
+            <listitem>
+                <para>
+                    <emphasis><property>idn</property></emphasis>: Defines if <acronym>IDN</acronym>
+                    domains are allowed or not. This option defaults to <constant>TRUE</constant>.
+                </para>
+            </listitem>
+
+            <listitem>
+                <para>
+                    <emphasis><property>ip</property></emphasis>: Allows to define a own IP
+                    validator. This option defaults to a new instance of
+                    <classname>Zend_Validate_Ip</classname>.
+                </para>
+            </listitem>
+
+            <listitem>
+                <para>
+                    <emphasis><property>tld</property></emphasis>: Defines if
+                    <acronym>TLD</acronym>s are validated. This option defaults to
+                    <constant>TRUE</constant>.
+                </para>
+            </listitem>
+        </itemizedlist>
+    </sect3>
+
+    <sect3 id="zend.validate.set.hostname.basic">
+        <title>Basic usage</title>
+
+        <para>
+            A basic example of usage is below:
+        </para>
 
         <programlisting language="php"><![CDATA[
 $validator = new Zend_Validate_Hostname();
@@ -29,28 +71,31 @@ if ($validator->isValid($hostname)) {
 }
 ]]></programlisting>
 
-        This will match the hostname <varname>$hostname</varname> and on failure populate
-        <methodname>getMessages()</methodname> with useful error messages.
-    </para>
-
-    <para>
-        <emphasis>Validating different types of hostnames</emphasis>
-    </para>
-
-    <para>
-        You may find you also want to match IP addresses, Local hostnames, or a combination of all
-        allowed types. This can be done by passing a parameter to
-        <classname>Zend_Validate_Hostname</classname> when you instantiate it. The parameter should
-        be an integer which determines what types of hostnames are allowed. You are encouraged to
-        use the <classname>Zend_Validate_Hostname</classname> constants to do this.
-    </para>
-
-    <para>
-        The Zend_Validate_Hostname constants are: <constant>ALLOW_DNS</constant> to allow only DNS
-        hostnames, <constant>ALLOW_IP</constant> to allow IP addresses,
-        <constant>ALLOW_LOCAL</constant> to allow local network names, and
-        <constant>ALLOW_ALL</constant> to allow all three types. To just check for IP addresses you
-        can use the example below:
+        <para>
+            This will match the hostname <varname>$hostname</varname> and on failure populate
+            <methodname>getMessages()</methodname> with useful error messages.
+        </para>
+    </sect3>
+
+    <sect3 id="zend.validate.set.hostname.types">
+        <title>Validating different types of hostnames</title>
+
+        <para>
+            You may find you also want to match IP addresses, Local hostnames, or a combination of
+            all allowed types. This can be done by passing a parameter to
+            <classname>Zend_Validate_Hostname</classname> when you instantiate it. The parameter
+            should be an integer which determines what types of hostnames are allowed. You are
+            encouraged to use the <classname>Zend_Validate_Hostname</classname> constants to do
+            this.
+        </para>
+
+        <para>
+            The Zend_Validate_Hostname constants are: <constant>ALLOW_DNS</constant> to allow only
+            <acronym>DNS</acronym> hostnames, <constant>ALLOW_IP</constant> to allow IP addresses,
+            <constant>ALLOW_LOCAL</constant> to allow local network names, and
+            <constant>ALLOW_ALL</constant> to allow all three types. To just check for IP addresses
+            you can use the example below:
+        </para>
 
         <programlisting language="php"><![CDATA[
 $validator = new Zend_Validate_Hostname(Zend_Validate_Hostname::ALLOW_IP);
@@ -63,44 +108,50 @@ if ($validator->isValid($hostname)) {
     }
 }
 ]]></programlisting>
-    </para>
 
-    <para>
-        As well as using <constant>ALLOW_ALL</constant> to accept all hostnames types you can
-        combine these types to allow for combinations. For example, to accept DNS and Local
-        hostnames instantiate your Zend_Validate_Hostname object as so:
+        <para>
+            As well as using <constant>ALLOW_ALL</constant> to accept all hostnames types you can
+            combine these types to allow for combinations. For example, to accept DNS and Local
+            hostnames instantiate your Zend_Validate_Hostname object as so:
+        </para>
 
         <programlisting language="php"><![CDATA[
 $validator = new Zend_Validate_Hostname(Zend_Validate_Hostname::ALLOW_DNS |
                                         Zend_Validate_Hostname::ALLOW_IP);
 ]]></programlisting>
-    </para>
-
-    <para>
-        <emphasis>Validating International Domains Names</emphasis>
-    </para>
-
-    <para>
-        Some Country Code Top Level Domains (ccTLDs), such as 'de' (Germany), support international
-        characters in domain names. These are known as International Domain Names (IDN). These
-        domains can be matched by <classname>Zend_Validate_Hostname</classname> via extended
-        characters that are used in the validation process.
-    </para>
-
-    <para>
-        Until now more than 50 ccTLDs support IDN domains.
-    </para>
-
-    <para>
-        To match an IDN domain it's as simple as just using the standard Hostname validator since
-        IDN matching is enabled by default. If you wish to disable IDN validation this can be done
-        by either passing a parameter to the <classname>Zend_Validate_Hostname</classname>
-        constructor or via the <methodname>setValidateIdn()</methodname> method.
-    </para>
-
-    <para>
-        You can disable IDN validation by passing a second parameter to the Zend_Validate_Hostname
-        constructor in the following way.
+    </sect3>
+
+    <sect3 id="zend.validate.set.hostname.idn">
+        <title>Validating International Domains Names</title>
+
+        <para>
+            Some Country Code Top Level Domains (ccTLDs), such as 'de' (Germany), support
+            international characters in domain names. These are known as International Domain Names
+            (<acronym>IDN</acronym>). These domains can be matched by
+            <classname>Zend_Validate_Hostname</classname> via extended characters that are used in
+            the validation process.
+        </para>
+
+        <note>
+            <title>IDN domains</title>
+
+            <para>
+                Until now more than 50 ccTLDs support IDN domains.
+            </para>
+        </note>
+
+        <para>
+            To match an <acronym>IDN</acronym> domain it's as simple as just using the standard
+            Hostname validator since <acronym>IDN</acronym> matching is enabled by default. If you
+            wish to disable <acronym>IDN</acronym> validation this can be done by either passing a
+            parameter to the <classname>Zend_Validate_Hostname</classname> constructor or via the
+            <methodname>setValidateIdn()</methodname> method.
+        </para>
+
+        <para>
+            You can disable <acronym>IDN</acronym> validation by passing a second parameter to the
+            <classname>Zend_Validate_Hostname</classname> constructor in the following way.
+        </para>
 
         <programlisting language="php"><![CDATA[
 $validator =
@@ -112,27 +163,37 @@ $validator =
     );
 ]]></programlisting>
 
-        Alternatively you can either pass <constant>TRUE</constant> or <constant>FALSE</constant> to
-        <methodname>setValidateIdn()</methodname> to enable or disable IDN validation.
-        If you are trying to match an IDN hostname which isn't currently supported it is likely
-        it will fail validation if it has any international characters in it. Where a ccTLD file
-        doesn't exist in Zend/Validate/Hostname specifying the additional characters a normal
-        hostname validation is performed.
-    </para>
-
-    <para>
-        Please note IDNs are only validated if you allow DNS hostnames to be validated.
-    </para>
-
-    <para>
-        <emphasis>Validating Top Level Domains</emphasis>
-    </para>
-
-    <para>
-        By default a hostname will be checked against a list of known TLDs. If this functionality
-        is not required it can be disabled in much the same way as disabling IDN support. You can
-        disable TLD validation by passing a third parameter to the Zend_Validate_Hostname
-        constructor. In the example below we are supporting IDN validation via the second parameter.
+        <para>
+            Alternatively you can either pass <constant>TRUE</constant> or
+            <constant>FALSE</constant> to <methodname>setValidateIdn()</methodname> to enable or
+            disable <acronym>IDN</acronym> validation. If you are trying to match an
+            <acronym>IDN</acronym> hostname which isn't currently supported it is likely it will
+            fail validation if it has any international characters in it. Where a ccTLD file doesn't
+            exist in <filename>Zend/Validate/Hostname</filename> specifying the additional
+            characters a normal hostname validation is performed.
+        </para>
+
+        <note>
+            <title>IDN validation</title>
+
+            <para>
+                Please note that <acronym>IDN</acronym>s are only validated if you allow
+                <acronym>DNS</acronym> hostnames to be validated.
+            </para>
+        </note>
+    </sect3>
+
+    <sect3 id="zend.validate.set.hostname.tld">
+        <title>Validating Top Level Domains</title>
+
+        <para>
+            By default a hostname will be checked against a list of known <acronym>TLD</acronym>s.
+            If this functionality is not required it can be disabled in much the same way as
+            disabling <acronym>IDN</acronym> support. You can disable <acronym>TLD</acronym>
+            validation by passing a third parameter to the
+            <classname>Zend_Validate_Hostname</classname> constructor. In the example below we are
+            supporting <acronym>IDN</acronym> validation via the second parameter.
+        </para>
 
         <programlisting language="php"><![CDATA[
 $validator =
@@ -145,13 +206,21 @@ $validator =
     );
 ]]></programlisting>
 
-        Alternatively you can either pass <constant>TRUE</constant> or <constant>FALSE</constant> to
-        <methodname>setValidateTld()</methodname> to enable or disable TLD validation.
-    </para>
-
-    <para>
-        Please note TLDs are only validated if you allow DNS hostnames to be validated.
-    </para>
+        <para>
+            Alternatively you can either pass <constant>TRUE</constant> or
+            <constant>FALSE</constant> to <methodname>setValidateTld()</methodname> to enable or
+            disable <acronym>TLD</acronym> validation.
+        </para>
+
+        <note>
+            <title>TLD validation</title>
+
+            <para>
+                Please note <acronym>TLD</acronym>s are only validated if you allow
+                <acronym>DNS</acronym> hostnames to be validated.
+            </para>
+        </note>
+    </sect3>
 </sect2>
 <!--
 vim:se ts=4 sw=4 et: