String comparison / similarity doc improvements (#4647)

* strcmp: Improve behavior description and direct users to alternative functions (strcoll and Collator::compare) where appropriate;
Add the "similarity" functions to seealso
Removed substr from seealso (why is it here?)

* Cross-link all the string similarity functions

* Trailing whitespace removal

* Update reference/strings/functions/strcmp.xml

Co-authored-by: Kamil Tekiela <tekiela246@gmail.com>

* strcmp: Improve behavior description and direct users to alternative functions (strcoll and Collator::compare) where appropriate

---------

Co-authored-by: Kamil Tekiela <tekiela246@gmail.com>

reference/strings/functions/levenshtein.xml

@@ -5,7 +5,7 @@
   <refname>levenshtein</refname>
   <refpurpose>Calculate Levenshtein distance between two strings</refpurpose>
  </refnamediv>
- 
+
  <refsect1 role="description">
   &reftitle.description;
   <methodsynopsis>
@@ -83,7 +83,7 @@
    </variablelist>
   </para>
  </refsect1>
- 
+
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>

reference/strings/functions/metaphone.xml

@@ -5,7 +5,7 @@
   <refname>metaphone</refname>
   <refpurpose>Calculate the metaphone key of a string</refpurpose>
  </refnamediv>
- 
+
  <refsect1 role="description">
   &reftitle.description;
   <methodsynopsis>
@@ -155,6 +155,16 @@ string(6) "ASTRKS"
   </para>
  </refsect1><!-- }}} -->
 
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <para>
+   <simplelist>
+    <member><function>levenshtein</function></member>
+    <member><function>similar_text</function></member>
+    <member><function>soundex</function></member>
+   </simplelist>
+  </para>
+ </refsect1>
 </refentry>
 <!-- Keep this comment at the end of the file
 Local variables:

reference/strings/functions/similar-text.xml

@@ -5,7 +5,7 @@
   <refname>similar_text</refname>
   <refpurpose>Calculate the similarity between two strings</refpurpose>
  </refnamediv>
- 
+
  <refsect1 role="description">
   &reftitle.description;
   <methodsynopsis>
@@ -110,6 +110,7 @@ similarity: 3 (42.857142857143 %)
   <para>
    <simplelist>
     <member><function>levenshtein</function></member>
+    <member><function>metaphone</function></member>
     <member><function>soundex</function></member>
    </simplelist>
   </para>

reference/strings/functions/soundex.xml

@@ -5,7 +5,7 @@
   <refname>soundex</refname>
   <refpurpose>Calculate the soundex key of a string</refpurpose>
  </refnamediv>
- 
+
  <refsect1 role="description">
   &reftitle.description;
   <methodsynopsis>

reference/strings/functions/strcmp.xml

@@ -5,7 +5,7 @@
   <refname>strcmp</refname>
   <refpurpose>Binary safe string comparison</refpurpose>
  </refnamediv>
- 
+
  <refsect1 role="description">
   &reftitle.description;
   <methodsynopsis>
@@ -14,7 +14,12 @@
    <methodparam><type>string</type><parameter>string2</parameter></methodparam>
   </methodsynopsis>
   <simpara>
-   Note that this comparison is case sensitive.
+   Note that this comparison is case sensitive. For case-insensitive comparison,
+   see <function>strcasecmp</function>.
+  </simpara>
+  <simpara>
+   Note that this comparison is not locale aware. For locale aware comparison see
+   <function>strcoll</function> or <methodname>Collator::compare</methodname>
   </simpara>
  </refsect1>
 
@@ -83,18 +88,38 @@ if (strcmp($var1, $var2) !== 0) {
    </example>   
   </para>
  </refsect1>
- 
+
  <refsect1 role="seealso">
   &reftitle.seealso;
   <para>
-   <simplelist>
-    <member><function>strcasecmp</function></member>
-    <member><function>preg_match</function></member>
-    <member><function>substr_compare</function></member>
-    <member><function>strncmp</function></member>
-    <member><function>strstr</function></member>
-    <member><function>substr</function></member>
-   </simplelist>
+   <itemizedlist>
+    <listitem>
+     <simpara>Full string comparison</simpara>
+     <simplelist>
+      <member><function>strcasecmp</function></member>
+      <member><methodname>Collator::compare</methodname></member>
+      <member><function>strcoll</function></member>
+     </simplelist>
+    </listitem>
+    <listitem>
+     <simpara>Partial string comparison</simpara>
+     <simplelist>
+      <member><function>substr_compare</function></member>
+      <member><function>strncmp</function></member>
+      <member><function>strstr</function></member>
+     </simplelist>
+    </listitem>
+    <listitem>
+     <simpara>Similar / other string comparison</simpara>
+     <simplelist>
+      <member><function>preg_match</function></member>
+      <member><function>levenshtein</function></member>
+      <member><function>metaphone</function></member>
+      <member><function>similar_text</function></member>
+      <member><function>soundex</function></member>
+     </simplelist>
+    </listitem>
+   </itemizedlist>
   </para>
  </refsect1>