Improve SOAP constructor docs (#4930)

* Move </link> to its own line

* Small grammar corrections

* Change <example> to <informalexample>

Since examples are numbered, and we don't want that here. Since informalexample doesn't accept a title, moped it to a comment to keep the context.

* Mark-up WSDL as an acronym

Now that the acronym was merged in doc-base.

reference/soap/constants.xml

@@ -140,7 +140,8 @@
       Specifies use of an "Accept-Encoding" header
       when passed as part of
       <link linkend="soapclient.construct.options.compression">
-      the <parameter>compression</parameter> option</link>
+       the <parameter>compression</parameter> option
+      </link>
       to <methodname>SoapClient::__construct</methodname>.
      </entry>
     </row>
@@ -154,7 +155,8 @@
       Specifies use of gzip compression
       when passed as part of
       <link linkend="soapclient.construct.options.compression">
-       the <parameter>compression</parameter> option</link>
+       the <parameter>compression</parameter> option
+      </link>
       to <methodname>SoapClient::__construct</methodname>.
      </entry>
     </row>
@@ -168,7 +170,8 @@
       Specifies use of deflate compression
       when passed as part of
       <link linkend="soapclient.construct.options.compression">
-       the <parameter>compression</parameter> option</link>
+       the <parameter>compression</parameter> option
+      </link>
       to <methodname>SoapClient::__construct</methodname>.
      </entry>
     </row>
@@ -205,7 +208,8 @@
      <entry>
       Used with the deprecated
       <link linkend="soapclient.construct.options.ssl-method">
-      <parameter>ssl_method</parameter> option</link>
+       <parameter>ssl_method</parameter> option
+      </link>
       to <methodname>SoapClient::__construct</methodname>.
      </entry>
     </row>
@@ -218,7 +222,8 @@
      <entry>
       Used with the deprecated
       <link linkend="soapclient.construct.options.ssl-method">
-       <parameter>ssl_method</parameter> option</link>
+       <parameter>ssl_method</parameter> option
+      </link>
       to <methodname>SoapClient::__construct</methodname>.
      </entry>
     </row>
@@ -231,7 +236,8 @@
      <entry>
       Used with the deprecated
       <link linkend="soapclient.construct.options.ssl-method">
-       <parameter>ssl_method</parameter> option</link>
+       <parameter>ssl_method</parameter> option
+      </link>
       to <methodname>SoapClient::__construct</methodname>.
      </entry>
     </row>
@@ -244,7 +250,8 @@
      <entry>
       Used with the deprecated
       <link linkend="soapclient.construct.options.ssl-method">
-       <parameter>ssl_method</parameter> option</link>
+       <parameter>ssl_method</parameter> option
+      </link>
       to <methodname>SoapClient::__construct</methodname>.
      </entry>
     </row>
@@ -681,7 +688,8 @@
      <entry>
       Used with the
       <link linkend="soapclient.construct.options.features">
-       <parameter>features</parameter> option</link>
+       <parameter>features</parameter> option
+      </link>
       to <methodname>SoapClient::__construct</methodname>.
      </entry>
     </row>
@@ -694,7 +702,8 @@
      <entry>
       Used with the
       <link linkend="soapclient.construct.options.features">
-       <parameter>features</parameter> option</link>
+       <parameter>features</parameter> option
+      </link>
       to <methodname>SoapClient::__construct</methodname>.
      </entry>
     </row>
@@ -707,7 +716,8 @@
      <entry>
       Used with the
       <link linkend="soapclient.construct.options.features">
-       <parameter>features</parameter> option</link>
+       <parameter>features</parameter> option
+      </link>
       to <methodname>SoapClient::__construct</methodname>.
      </entry>
     </row>

reference/soap/soapclient/construct.xml

@@ -26,7 +26,7 @@
      <term><parameter>wsdl</parameter></term>
      <listitem>
       <para>
-       URI of a WSDL file describing the service, which is used to automatically
+       URI of a <acronym>WSDL</acronym> file describing the service, which is used to automatically
        configure the client. If not provided, the client will operate in non-WSDL
        mode.
       </para>
@@ -200,7 +200,7 @@
          <listitem>
           <para>
            Path to a client certificate for use with HTTPS authentication.
-           It must be a <acronym>PEM</acronym> encoded file which contains your certificate
+           It must be a <acronym>PEM</acronym> encoded file which contains the certificate
            and private key.
           </para>
           <para>
@@ -352,7 +352,7 @@
            Used to map types defined in the WSDL to PHP classes.
            It should be specified as an associative <type>array</type> with
            type names from the WSDL as keys and names of PHP classes as values.
-           Note that the type names of an element is not necessarily the same as
+           Note that the type name of an element is not necessarily the same as
            the element (tag) name.
           </para>
           <para>
@@ -590,7 +590,7 @@
            or SSL 3, respectively.
            Specifying <constant>SOAP_SSL_METHOD_SSLv23</constant> has no effect;
            the constant exists only for backwards compatibility.
-           As of PHP 7.2, specifying <constant>SOAP_SSL_METHOD_TLS</constant>
+           As of PHP 7.2.0, specifying <constant>SOAP_SSL_METHOD_TLS</constant>
            also has no effect; in earlier versions, it forced use of TLS 1.0.
           </para>
           <para>
@@ -598,17 +598,17 @@
            be supported by the installed OpenSSL library.
           </para>
           <para>
-           This option is <emphasis>DEPRECATED</emphasis> as of PHP 8.1.0.
+           This option is <emphasis role="strong">deprecated</emphasis> as of PHP 8.1.0.
            A more flexible alternative, which allows specifying
            individual versions of TLS, is to use the
            <link linkend="soapclient.construct.options.stream-context">
            <parameter>stream_context</parameter></link> option with
            the 'crypto_method' context parameter.
-           <example>
-            <title>Specifying use of TLS 1.3 only</title>
+           <informalexample>
             <programlisting role="php">
 <![CDATA[
 <?php
+// Specifying use of TLS 1.3 only
 $context = stream_context_create([
     'ssl' => [
         'crypto_method' => STREAM_CRYPTO_METHOD_TLSv1_3_CLIENT
@@ -617,7 +617,7 @@ $context = stream_context_create([
 $client = new SoapClient("some.wsdl", ['context' => $context]);
 ]]>
             </programlisting>
-           </example>
+           </informalexample>
           </para>
          </listitem>
         </varlistentry>