Integrate SPL language-snippets and rearrange SPL docs (php#4286)

* Integrate SPL language-snippets They are only used once, having them as entities is useless. * Move SPL interfaces from misc to interface page * Rearrange SPL docs Move ArrayObject to data structures, get rid of misc page, do not chunk introduction * Remove interface list, the ToC shows the same info
lufei · Dec 10, 2024 · e93feee · e93feee
1 parent 557acaf
commit e93feee
Show file tree

Hide file tree

Showing 8 changed files with 61 additions and 136 deletions.
diff --git a/language-snippets.ent b/language-snippets.ent
@@ -2721,32 +2721,6 @@ to be references, then they must be references in the passed argument list.'>
 </listitem>
 </varlistentry>'>
 
-<!-- SPL -->
-<!ENTITY spl.datastructures.intro.title '<title xmlns="http://docbook.org/ns/docbook">Datastructures</title>'>
-
-<!ENTITY spl.exceptions.intro.title '<title xmlns="http://docbook.org/ns/docbook">Exceptions</title>'>
-<!ENTITY spl.exceptions.intro '
- <para xmlns="http://docbook.org/ns/docbook">
-  SPL provides a set of standard Exceptions.
- </para>
- <para xmlns="http://docbook.org/ns/docbook">
-  See also the <xref linkend="reserved.exceptions" />.
- </para>
-'>
-
-<!ENTITY spl.files.intro.title '<title xmlns="http://docbook.org/ns/docbook">File Handling</title>'>
-<!ENTITY spl.files.intro '<partintro xmlns="http://docbook.org/ns/docbook"><para>SPL provides a number of classes to work with files.</para></partintro>'>
-
-<!ENTITY spl.interfaces.intro.title '<title xmlns="http://docbook.org/ns/docbook">Interfaces</title>'>
-<!ENTITY spl.interfaces.intro '<para xmlns="http://docbook.org/ns/docbook">SPL provides a set of interfaces.</para><para xmlns="http://docbook.org/ns/docbook">See also the <xref linkend="reserved.interfaces" /></para>'>
-<!ENTITY spl.interfaces.list '<title xmlns="http://docbook.org/ns/docbook">Interface list</title>'>
-
-<!ENTITY spl.iterators.intro.title '<title xmlns="http://docbook.org/ns/docbook">Iterators</title>'>
-<!ENTITY spl.iterators.intro '<para xmlns="http://docbook.org/ns/docbook">SPL provides a set of iterators to traverse over objects.</para>'>
-
-<!ENTITY spl.misc.intro.title '<title xmlns="http://docbook.org/ns/docbook">Miscellaneous Classes and Interfaces</title>'>
-<!ENTITY spl.misc.intro '<partintro xmlns="http://docbook.org/ns/docbook"><para>Classes and interfaces which do not fit into the other SPL categories.</para></partintro>'>
-
 <!-- ZIP -->
 <!ENTITY zip.filename.separator '<note xmlns="http://docbook.org/ns/docbook"><simpara>For maximum portability, it is recommended to always use forward slashes (<literal>/</literal>) as directory separator in ZIP filenames.</simpara></note>'>
 

diff --git a/reference/spl/book.xml b/reference/spl/book.xml
@@ -1,37 +1,31 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-
-<book xml:id="book.spl" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
+<book xml:id="book.spl" xmlns="http://docbook.org/ns/docbook">
  <?phpdoc extension-membership="core" ?>
  <title>Standard PHP Library (SPL)</title>
  <titleabbrev>SPL</titleabbrev>
 
- <preface xml:id="intro.spl">
+ <preface xml:id="intro.spl" annotations="chunk:false">
   &reftitle.intro;
-  <para>
-   The Standard PHP Library (SPL) is a collection of interfaces and classes that are meant to solve
-   common problems.
-  </para>
-  <para>
-   SPL provides a set of standard datastructure, a set of iterators to traverse over objects, a set of interfaces, a set of standard Exceptions,  a number of classes to work with files and it provides a set of functions like <function>spl_autoload_register</function>
-  </para>
+  <simpara>
+   The Standard PHP Library (SPL) extension defines interfaces and classes
+   that are meant to solve common problems.
+  </simpara>
+  <simpara>
+   The extension provides various datastructures, generic exceptions,
+   iterators, classes to work with filesystems using an object
+   oriented <acronym>API</acronym>, and utility functions.
+  </simpara>
  </preface>
 
- &reference.spl.datastructures;
- &reference.spl.iterators;
  &reference.spl.interfaces;
+ &reference.spl.datastructures;
  &reference.spl.exceptions;
- &reference.spl.reference;
+ &reference.spl.iterators;
  &reference.spl.files;
- &reference.spl.miscellaneous;
-
-<!-- TODO: Not documented
- &reference.spl.splfixedarray;
- &reference.spl.splobjectstorage;
--->
+ &reference.spl.reference;
 
 </book>
-
 <!-- Keep this comment at the end of the file
 Local variables:
 mode: sgml
@@ -52,4 +46,3 @@ vim600: syn=xml fen fdm=syntax fdl=2 si
 vim: et tw=78 syn=sgml
 vi: ts=1 sw=1
 -->
-
diff --git a/reference/spl/datastructures.xml b/reference/spl/datastructures.xml
@@ -1,9 +1,7 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-
-<part xml:id="spl.datastructures" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
-
- &spl.datastructures.intro.title;
+<part xml:id="spl.datastructures" xmlns="http://docbook.org/ns/docbook">
+ <title>Datastructures</title>
 
  <partintro>
   <para>
@@ -61,10 +59,17 @@
    <title>Arrays</title>
 
    <para>
-    Arrays are structures that store the data in a continuous way, accessible
-    via indexes. Don't confuse them with PHP arrays: PHP arrays are in fact 
-    implemented as ordered hashtables.
+    Arrays are structures that store the data in a contiguous way,
+    accessible via indexes.
    </para>
+   <note>
+    <simpara>
+     Do not confuse this with PHP's native <type>array</type> type.
+     PHP arrays are in reality ordered hashtables.
+     However, SPL provides the <classname>ArrayObject</classname> class
+     to wrap PHP arrays into an object.
+    </simpara>
+   </note>
 
    <itemizedlist>
     <listitem>
@@ -100,12 +105,11 @@
  &reference.spl.splpriorityqueue;
 
  &reference.spl.splfixedarray;
+ &reference.spl.arrayobject;
+
  &reference.spl.splobjectstorage;
 
 </part>
-
-
-
 <!-- Keep this comment at the end of the file
 Local variables:
 mode: sgml
@@ -126,4 +130,3 @@ vim600: syn=xml fen fdm=syntax fdl=2 si
 vim: et tw=78 syn=sgml
 vi: ts=1 sw=1
 -->
-
diff --git a/reference/spl/exceptions.xml b/reference/spl/exceptions.xml
@@ -1,12 +1,12 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-
-<part xml:id="spl.exceptions" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
-
- &spl.exceptions.intro.title;
+<part xml:id="spl.exceptions" xmlns="http://docbook.org/ns/docbook">
+ <title>Exceptions</title>
 
  <partintro>
-  &spl.exceptions.intro;
+  <simpara>
+   SPL provides a set of standard Exceptions.
+  </simpara>
 
   <section xml:id="spl.exceptions.tree">
    <title>SPL Exceptions Class Tree</title>
@@ -39,6 +39,13 @@
    </itemizedlist>
   </section>
 
+  <section role="seealso">
+   &reftitle.seealso;
+   <simplelist>
+    <member><xref linkend="reserved.exceptions"/></member>
+   </simplelist>
+  </section>
+
  </partintro>
 
  &reference.spl.badfunctioncallexception;
@@ -56,7 +63,6 @@
  &reference.spl.unexpectedvalueexception;
 
 </part>
-
 <!-- Keep this comment at the end of the file
 Local variables:
 mode: sgml
@@ -77,4 +83,3 @@ vim600: syn=xml fen fdm=syntax fdl=2 si
 vim: et tw=78 syn=sgml
 vi: ts=1 sw=1
 -->
-
diff --git a/reference/spl/files.xml b/reference/spl/files.xml
@@ -1,17 +1,19 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
+<part xml:id="spl.files" xmlns="http://docbook.org/ns/docbook">
+ <title>File Handling</title>
 
-<part xml:id="spl.files" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
-
- &spl.files.intro.title;
- &spl.files.intro;
+ <partintro>
+  <simpara>
+   SPL provides a number of classes to work with files.
+  </simpara>
+ </partintro>
 
  &reference.spl.splfileinfo;
  &reference.spl.splfileobject;
  &reference.spl.spltempfileobject;
 
 </part>
-
 <!-- Keep this comment at the end of the file
 Local variables:
 mode: sgml

diff --git a/reference/spl/interfaces.xml b/reference/spl/interfaces.xml
@@ -1,21 +1,18 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-
-<part xml:id="spl.interfaces" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
-
- &spl.interfaces.intro.title;
+<part xml:id="spl.interfaces" xmlns="http://docbook.org/ns/docbook">
+ <title>Interfaces</title>
 
  <partintro>
-  &spl.interfaces.intro;
+  <simpara>
+   SPL provides a set of interfaces to enhance iterators,
+   and a pair of interfaces to implement the Observer Design Pattern.
+  </simpara>
 
-  <section xml:id="spl.interfaces.list">
-   &spl.interfaces.list;
+  <section role="seealso">
+   &reftitle.seealso;
    <simplelist>
-    <member><classname>OuterIterator</classname></member>
-    <member><classname>RecursiveIterator</classname></member>
-    <member><classname>SeekableIterator</classname></member>
-    <member><classname>SplObserver</classname></member>
-    <member><classname>SplSubject</classname></member>
+    <member><xref linkend="reserved.interfaces"/></member>
    </simplelist>
   </section>
 
@@ -24,15 +21,10 @@
  &reference.spl.outeriterator;
  &reference.spl.recursiveiterator;
  &reference.spl.seekableiterator;
-<!-- TODO: Not documented
  &reference.spl.splobserver;
  &reference.spl.splsubject;
--->
 
 </part>
-
-
-
 <!-- Keep this comment at the end of the file
 Local variables:
 mode: sgml
@@ -53,4 +45,3 @@ vim600: syn=xml fen fdm=syntax fdl=2 si
 vim: et tw=78 syn=sgml
 vi: ts=1 sw=1
 -->
-
diff --git a/reference/spl/iterators.xml b/reference/spl/iterators.xml
@@ -1,12 +1,12 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-
-<part xml:id="spl.iterators" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
-
- &spl.iterators.intro.title;
+<part xml:id="spl.iterators" xmlns="http://docbook.org/ns/docbook">
+ <title>Iterators</title>
 
  <partintro>
-  &spl.iterators.intro;
+  <simpara>
+   SPL provides a set of iterators to traverse over objects.
+  </simpara>
 
   <section xml:id="spl.iterators.tree">
    <title>SPL Iterators Class Tree</title>
@@ -114,10 +114,6 @@
 
  </partintro>
 
-<!-- TODO: Not documented
- &reference.spl.recursivetreeiterator;
--->
-
  &reference.spl.appenditerator;
  &reference.spl.arrayiterator;
  &reference.spl.cachingiterator;
@@ -144,9 +140,6 @@
  &reference.spl.regexiterator;
 
 </part>
-
-
-
 <!-- Keep this comment at the end of the file
 Local variables:
 mode: sgml
@@ -167,4 +160,3 @@ vim600: syn=xml fen fdm=syntax fdl=2 si
 vim: et tw=78 syn=sgml
 vi: ts=1 sw=1
 -->
-
diff --git a/reference/spl/miscellaneous.xml b/reference/spl/miscellaneous.xml