Bootstrap ext/random docs with docgen

Closes GH-1916.

appendices/extensions.xml

@@ -21,7 +21,6 @@
    <listitem><simpara><xref linkend="book.cmark"/></simpara></listitem>
    <listitem><simpara><xref linkend="book.com"/></simpara></listitem>
    <listitem><simpara><xref linkend="book.componere"/></simpara></listitem>
-   <listitem><simpara><xref linkend="book.csprng"/></simpara></listitem>
    <listitem><simpara><xref linkend="book.ctype"/></simpara></listitem>
    <listitem><simpara><xref linkend="book.cubrid"/></simpara></listitem>
    <listitem><simpara><xref linkend="book.curl"/></simpara></listitem>
@@ -121,6 +120,7 @@
    <listitem><simpara><xref linkend="book.pthreads"/></simpara></listitem>
    <listitem><simpara><xref linkend="book.quickhash"/></simpara></listitem>
    <listitem><simpara><xref linkend="book.radius"/></simpara></listitem>
+   <listitem><simpara><xref linkend="book.random"/></simpara></listitem>
    <listitem><simpara><xref linkend="book.rar"/></simpara></listitem>
    <listitem><simpara><xref linkend="book.readline"/></simpara></listitem>
    <listitem><simpara><xref linkend="book.recode"/></simpara></listitem>
@@ -202,7 +202,6 @@
    <itemizedlist>
     <listitem><para><xref linkend="book.array"/></para></listitem>
     <listitem><para><xref linkend="book.classobj"/></para></listitem>
-    <listitem><para><xref linkend="book.csprng"/></para></listitem>
     <listitem><para><xref linkend="book.datetime"/></para></listitem>
     <listitem><para><xref linkend="book.dir"/></para></listitem>
     <listitem><para><xref linkend="book.errorfunc"/></para></listitem>
@@ -221,6 +220,7 @@
     <listitem><para><xref linkend="book.outcontrol"/></para></listitem>
     <listitem><para><xref linkend="book.password"/></para></listitem>
     <listitem><para><xref linkend="book.pcre"/></para></listitem>
+    <listitem><para><xref linkend="book.random"/></para></listitem>
     <listitem><para><xref linkend="book.reflection"/></para></listitem>
     <listitem><para><xref linkend="book.spl"/></para></listitem>
     <listitem><para><xref linkend="book.stream"/></para></listitem>

appendices/migration70/new-features.xml

@@ -640,7 +640,7 @@ session_start([
  </sect2>
 
  <sect2 xml:id="migration70.new-features.csprng-functions">
-  <title><link linkend="book.csprng">CSPRNG</link> Functions</title>
+  <title>CSPRNG Functions</title>
 
   <para>
    Two new functions have been added to generate cryptographically secure

appendices/migration70/new-functions.xml

@@ -17,7 +17,7 @@
  </sect2>
 
  <sect2 xml:id="migration70.new-functions.csprng">
-  <title><link linkend="book.csprng">CSPRNG</link></title>
+  <title>CSPRNG</title>
 
   <itemizedlist>
    <listitem>

reference/math/versions.xml

@@ -26,31 +26,24 @@
  <function name="fdiv" from="PHP 8"/>
  <function name="floor" from="PHP 4, PHP 5, PHP 7, PHP 8"/>
  <function name="fmod" from="PHP 4 &gt;= 4.2.0, PHP 5, PHP 7, PHP 8"/>
- <function name="getrandmax" from="PHP 4, PHP 5, PHP 7, PHP 8"/>
  <function name="hexdec" from="PHP 4, PHP 5, PHP 7, PHP 8"/>
  <function name="hypot" from="PHP 4 &gt;= 4.1.0, PHP 5, PHP 7, PHP 8"/>
  <function name="is_finite" from="PHP 4 &gt;= 4.2.0, PHP 5, PHP 7, PHP 8"/>
  <function name="is_infinite" from="PHP 4 &gt;= 4.2.0, PHP 5, PHP 7, PHP 8"/>
  <function name="is_nan" from="PHP 4 &gt;= 4.2.0, PHP 5, PHP 7, PHP 8"/>
- <function name="lcg_value" from="PHP 4, PHP 5, PHP 7, PHP 8"/>
  <function name="log" from="PHP 4, PHP 5, PHP 7, PHP 8"/>
  <function name="log10" from="PHP 4, PHP 5, PHP 7, PHP 8"/>
  <function name="log1p" from="PHP 4 &gt;= 4.1.0, PHP 5, PHP 7, PHP 8"/>
  <function name="max" from="PHP 4, PHP 5, PHP 7, PHP 8"/>
  <function name="min" from="PHP 4, PHP 5, PHP 7, PHP 8"/>
- <function name="mt_getrandmax" from="PHP 4, PHP 5, PHP 7, PHP 8"/>
- <function name="mt_rand" from="PHP 4, PHP 5, PHP 7, PHP 8"/>
- <function name="mt_srand" from="PHP 4, PHP 5, PHP 7, PHP 8"/>
  <function name="octdec" from="PHP 4, PHP 5, PHP 7, PHP 8"/>
  <function name="pi" from="PHP 4, PHP 5, PHP 7, PHP 8"/>
  <function name="pow" from="PHP 4, PHP 5, PHP 7, PHP 8"/>
  <function name="rad2deg" from="PHP 4, PHP 5, PHP 7, PHP 8"/>
- <function name="rand" from="PHP 4, PHP 5, PHP 7, PHP 8"/>
  <function name="round" from="PHP 4, PHP 5, PHP 7, PHP 8"/>
  <function name="sin" from="PHP 4, PHP 5, PHP 7, PHP 8"/>
  <function name="sinh" from="PHP 4 &gt;= 4.1.0, PHP 5, PHP 7, PHP 8"/>
  <function name="sqrt" from="PHP 4, PHP 5, PHP 7, PHP 8"/>
- <function name="srand" from="PHP 4, PHP 5, PHP 7, PHP 8"/>
  <function name="tan" from="PHP 4, PHP 5, PHP 7, PHP 8"/>
  <function name="tanh" from="PHP 4 &gt;= 4.1.0, PHP 5, PHP 7, PHP 8"/>
  <function name="intdiv" from="PHP 7, PHP 8"/>

reference/random/book.xml

@@ -0,0 +1,52 @@
+<?xml version="1.0" encoding="utf-8"?>
+<book xml:id="book.random" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
+ <?phpdoc extension-membership="core" ?>
+ <title>Random Number Generators and Functions Related to Randomness</title>
+ <titleabbrev>random</titleabbrev>
+
+ <preface xml:id="intro.random">
+  &reftitle.intro;
+  <para>
+
+  </para>
+ </preface>
+
+ &reference.random.setup;
+ &reference.random.constants;
+ &reference.random.examples;
+ &reference.random.reference;
+
+ &reference.random.random.randomizer;
+
+ &reference.random.random.engine;
+ &reference.random.random.engine.mt19937;
+ &reference.random.random.engine.pcgoneseq128xslrr64;
+ &reference.random.random.engine.xoshiro256starstar;
+ &reference.random.random.cryptosafeengine;
+ &reference.random.random.engine.secure;
+
+ &reference.random.random.randomerror;
+ &reference.random.random.brokenrandomengineerror;
+ &reference.random.random.randomexception;
+
+</book>
+<!-- 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:"~/.phpdoc/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
+-->

reference/random/constants.xml

@@ -0,0 +1,49 @@
+<?xml version="1.0" encoding="utf-8"?>
+<appendix xml:id="random.constants" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
+ &reftitle.constants;
+ &extension.constants.core;
+ <para>
+  <variablelist>
+   <varlistentry xml:id="constant.mt-rand-mt19937">
+    <term>
+     <constant>MT_RAND_MT19937</constant>
+     (<type>integer</type>)
+    </term>
+    <listitem>
+     <simpara>
+     </simpara>
+    </listitem>
+   </varlistentry>
+   <varlistentry xml:id="constant.mt-rand-php">
+    <term>
+     <constant>MT_RAND_PHP</constant>
+     (<type>integer</type>)
+    </term>
+    <listitem>
+     <simpara>
+     </simpara>
+    </listitem>
+   </varlistentry>
+  </variablelist>
+ </para>
+</appendix>
+<!-- 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:"~/.phpdoc/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
+-->

reference/csprng/versions.xml → reference/random/examples.xml

@@ -1,14 +1,25 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- $Revision$ -->
-<!--
-  Do NOT translate this file
--->
+<chapter xml:id="random.examples" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
+ &reftitle.examples;
+ <example>
+  <title>Random Example</title>
+  <programlisting role="php">
+<![CDATA[
+<?php
 
-<versions>
- <function name="random_bytes" from="PHP 7, PHP 8"/>
- <function name="random_int" from="PHP 7, PHP 8"/>
-</versions>
+/* ... */
 
+?>
+]]>
+  </programlisting>
+  &example.outputs.similar;
+  <screen>
+<![CDATA[
+...
+]]>
+  </screen>
+ </example>
+</chapter>
 <!-- Keep this comment at the end of the file
 Local variables:
 mode: sgml

reference/math/functions/getrandmax.xml → reference/random/functions/getrandmax.xml

@@ -21,7 +21,7 @@
   &reftitle.parameters;
   &no.function.parameters;
  </refsect1>
- 
+
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>

reference/math/functions/lcg-value.xml → reference/random/functions/lcg-value.xml

@@ -24,7 +24,7 @@
   &reftitle.parameters;
   &no.function.parameters;
  </refsect1>
- 
+
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>

reference/math/functions/mt-getrandmax.xml → reference/random/functions/mt-getrandmax.xml

@@ -21,12 +21,12 @@
   &reftitle.parameters;
   &no.function.parameters;
  </refsect1>
- 
+
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
    Returns the maximum random value returned by a call to
-   <function>mt_rand</function> without arguments, which is the maximum value 
+   <function>mt_rand</function> without arguments, which is the maximum value
    that can be used for its <parameter>max</parameter> parameter without the
    result being scaled up (and therefore less random).
   </para>

reference/math/functions/mt-rand.xml → reference/random/functions/mt-rand.xml

@@ -19,7 +19,7 @@
   &caution.cryptographically-insecure;
   <simpara>
    Many random number generators of older libcs
-   have dubious or unknown characteristics and are slow. 
+   have dubious or unknown characteristics and are slow.
    The <function>mt_rand</function> function is a drop-in replacement
    for the older <function>rand</function>. It uses a random
    number generator with known characteristics using the

reference/math/functions/mt-srand.xml → reference/random/functions/mt-srand.xml

@@ -17,9 +17,9 @@
    <parameter>seed</parameter> or with a random value
    if no <parameter>seed</parameter> is given.
   </para>
-  
+
   &note.randomseed;
-  
+
  </refsect1>
  <refsect1 role="parameters">
   &reftitle.parameters;
@@ -56,7 +56,7 @@
           <row>
            <entry><constant>MT_RAND_PHP</constant></entry>
            <entry>
-            Uses an incorrect Mersenne Twister implementation which was used as the default up till PHP 7.1.0. 
+            Uses an incorrect Mersenne Twister implementation which was used as the default up till PHP 7.1.0.
             This mode is available for backward compatibility.
            </entry>
           </row>
@@ -69,14 +69,14 @@
    </variablelist>
   </para>
  </refsect1>
- 
+
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
    &return.void;
   </para>
  </refsect1>
- 
+
  <refsect1 role="changelog">
   &reftitle.changelog;
   <para>

reference/math/functions/rand.xml → reference/random/functions/rand.xml

@@ -126,7 +126,7 @@ echo rand(5, 15);
    </example>
   </para>
  </refsect1>
- 
+
  <refsect1 role="notes">
   &reftitle.notes;
   <warning>
@@ -138,7 +138,7 @@ echo rand(5, 15);
    </para>
   </warning>
  </refsect1>
- 
+
  <refsect1 role="seealso">
   &reftitle.seealso;
   <para>