Fix GH-1568: No info on return value of ctype_alnum() in case of empty string

We explicitly add the info to every ctype's function return value
section.

We also overhaul the ctype introduction section by removing obsolete
information, adding a warning about the deprecation of int parameters,
and removing personalization.

language-snippets.ent

@@ -1872,6 +1872,8 @@ In the future, the argument will be interpreted as a string instead of an ASCII
 Depending on the intended behavior, the argument should either be cast to &string;
 or an explicit call to <function>chr</function> should be made.</para></warning>'>
 
+<!ENTITY ctype.result.empty-string 'When called with an empty string the result will always be &false;.'>
+
 <!-- FTP Notes -->
 <!ENTITY ftp.changelog.ftp-param '<row xmlns="http://docbook.org/ns/docbook">
  <entry>8.1.0</entry>

reference/ctype/book.xml

@@ -17,17 +17,17 @@
    When called with an integer argument these functions 
    behave exactly like their C counterparts from
    <filename>ctype.h</filename>.
-   It means that if you pass an integer smaller than 256 it will use the
+   It means that if an integer smaller than 256 is passed, it will use the
    ASCII value of it to see if it fits in the specified range (digits are in
    0x30-0x39). If the number is between -128 and -1 inclusive then 256 will
    be added and the check will be done on that.
   </para>
+  &note.ctype.parameter.non-string;
   <para>
    When called with a string argument they will check
    every character in the string and will only return
    &true; if every character in the string matches the
-   requested criteria. When called with an empty string 
-   the result will always be &true; in PHP &lt; 5.1 and &false; since 5.1.
+   requested criteria. &ctype.result.empty-string;
   </para>
   <para>
    Passing anything else but a string or integer will
@@ -47,7 +47,7 @@
    </para>
    <para>
     This extension also predates Python "ctypes" so any confusion 
-    caused by this naming is hardly our fault ...
+    caused by this naming is hardly PHP's fault.
    </para>
   </note>
  </preface>

reference/ctype/functions/ctype-alnum.xml

@@ -42,6 +42,7 @@
   <para>
    Returns &true; if every character in <parameter>text</parameter> is either
    a letter or a digit, &false; otherwise.
+   &ctype.result.empty-string;
   </para>
  </refsect1>
 

reference/ctype/functions/ctype-alpha.xml

@@ -47,6 +47,7 @@
   <para>
    Returns &true; if every character in <parameter>text</parameter> is 
    a letter from the current locale, &false; otherwise.
+   &ctype.result.empty-string;
   </para>
  </refsect1>
 

reference/ctype/functions/ctype-cntrl.xml

@@ -43,6 +43,7 @@
   <para>
    Returns &true; if every character in <parameter>text</parameter> is 
    a control character from the current locale, &false; otherwise.
+   &ctype.result.empty-string;
   </para>
  </refsect1>
 

reference/ctype/functions/ctype-digit.xml

@@ -42,6 +42,7 @@
   <para>
    Returns &true; if every character in the string
    <parameter>text</parameter> is a decimal digit, &false; otherwise.
+   &ctype.result.empty-string;
   </para>
  </refsect1>
 

reference/ctype/functions/ctype-graph.xml

@@ -43,6 +43,7 @@
    Returns &true; if every character in <parameter>text</parameter> is 
    printable and actually creates visible output (no white space), &false;
    otherwise.
+   &ctype.result.empty-string;
   </para>
  </refsect1>
 

reference/ctype/functions/ctype-lower.xml

@@ -42,6 +42,7 @@
   <para>
    Returns &true; if every character in <parameter>text</parameter> is 
    a lowercase letter in the current locale.
+   &ctype.result.empty-string;
   </para>
  </refsect1>
 

reference/ctype/functions/ctype-print.xml

@@ -44,6 +44,7 @@
    will actually create output (including blanks). Returns &false; if 
    <parameter>text</parameter> contains control characters or characters 
    that do not have any output or control function at all.
+   &ctype.result.empty-string;
   </para>
  </refsect1>
 

reference/ctype/functions/ctype-punct.xml

@@ -45,6 +45,7 @@
   <para>
    Returns &true; if every character in <parameter>text</parameter> 
    is printable, but neither letter, digit or blank, &false; otherwise.
+   &ctype.result.empty-string;
   </para>
  </refsect1>
 

reference/ctype/functions/ctype-space.xml

@@ -44,6 +44,7 @@
    creates some sort of white space, &false; otherwise. Besides the 
    blank character this also includes tab, vertical tab, line feed,
    carriage return and form feed characters.
+   &ctype.result.empty-string;
   </para>
  </refsect1>
 

reference/ctype/functions/ctype-upper.xml

@@ -42,6 +42,7 @@
   <para>
    Returns &true; if every character in <parameter>text</parameter> is 
    an uppercase letter in the current locale.
+   &ctype.result.empty-string;
   </para>
  </refsect1>
 

reference/ctype/functions/ctype-xdigit.xml

@@ -45,6 +45,7 @@
    Returns &true; if every character in <parameter>text</parameter> is 
    a hexadecimal 'digit', that is a decimal digit or a character from 
    <literal>[A-Fa-f]</literal> , &false; otherwise.
+   &ctype.result.empty-string;
   </para>
  </refsect1>