From 75c88000bc5c53e4fca0471ab1bf929d8981dd9d Mon Sep 17 00:00:00 2001
From: Philip Olson <philip@php.net>
Date: Sun, 23 Dec 2007 03:55:12 +0000
Subject: [PATCH] MFB: Upgrade to the new-reference-structure - Split
 reference.xml into book.xml, setup.xml, and examples.xml - Moved from
 reference.xml to book.xml:   - The intro text (partintro), and link to
 various pages - Moved from reference.xml to setup.xml:   - The requirements,
 installation, configuration, and resources - Moved examples to the new
 examples.xml - Changed See Also in reference.xml from section to partintro -
 Changed the constants section to be an <appendix> - Changed the intro ID from
 <extname>.intro to intro.<extname>

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@248796 c90b9560-bf6c-de11-be94-00142212c4b1
---
 reference/pcntl/book.xml      |  76 ++++++++++++++++++++
 reference/pcntl/constants.xml |   6 +-
 reference/pcntl/examples.xml  |  85 +++++++++++++++++++++++
 reference/pcntl/reference.xml | 126 +---------------------------------
 reference/pcntl/setup.xml     |  54 +++++++++++++++
 5 files changed, 220 insertions(+), 127 deletions(-)
 create mode 100644 reference/pcntl/book.xml
 create mode 100644 reference/pcntl/examples.xml
 create mode 100644 reference/pcntl/setup.xml

diff --git a/reference/pcntl/book.xml b/reference/pcntl/book.xml
new file mode 100644
index 0000000000..ab01430721
--- /dev/null
+++ b/reference/pcntl/book.xml
@@ -0,0 +1,76 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision: 1.2 $ -->
+<!-- Purpose: fileprocess.process -->
+<!-- Membership: bundled -->
+ 
+<book xml:id="book.pcntl" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
+ <title>PCNTL</title>
+ 
+ <!-- {{{ preface -->
+ <preface xml:id="intro.pcntl">
+  &reftitle.intro;
+  <para>
+   Process Control support in PHP implements the Unix style of
+   process creation, program execution, signal handling and process
+   termination. Process Control should not be enabled within a
+   web server environment and unexpected results may happen if any
+   Process Control functions are used within a web server environment.
+  </para>
+  <para>
+   This documentation is intended to explain the general usage of
+   each of the Process Control functions. For detailed information
+   about Unix process control you are encouraged to consult your
+   systems documentation including fork(2), waitpid(2) and signal(2)
+   or a comprehensive reference such as Advanced Programming in the
+   UNIX Environment by W. Richard Stevens (Addison-Wesley).
+  </para>
+  <para>
+   PCNTL now uses ticks as the signal handle callback mechanism, which is
+   much faster than the previous mechanism. This change follows the same
+   semantics as using "user ticks". You use the <function>declare</function> 
+   statement to specify the locations in your program where callbacks are
+   allowed to occur. This allows you to minimize the overhead of handling
+   asynchronous events. In the past, compiling PHP with pcntl enabled would
+   always incur this overhead, whether or not your script actually used
+   pcntl.
+  </para>
+  <para>
+   There is one adjustment that all pcntl scripts prior to PHP 4.3.0 must
+   make for them to work which is to either to use
+   <function>declare</function> on a section where you wish to allow
+   callbacks or to just enable it across the entire script using 
+   the new global syntax of <function>declare</function>.
+  </para>
+
+  &note.no-windows.extension;
+ </preface>
+ <!-- }}} -->
+ 
+ &reference.pcntl.setup;
+ &reference.pcntl.constants;
+ &reference.pcntl.examples;
+ &reference.pcntl.reference;
+
+</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:"../../../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
+-->
+
diff --git a/reference/pcntl/constants.xml b/reference/pcntl/constants.xml
index dc2ab17e1d..815f629f74 100644
--- a/reference/pcntl/constants.xml
+++ b/reference/pcntl/constants.xml
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.4 $ -->
-<section xml:id="pcntl.constants" xmlns="http://docbook.org/ns/docbook">
+<!-- $Revision: 1.5 $ -->
+<appendix xml:id="pcntl.constants" xmlns="http://docbook.org/ns/docbook">
  &reftitle.constants;
  <para>
   The following list of signals are supported by the Process Control
@@ -449,7 +449,7 @@
    </listitem>
   </varlistentry>
  </variablelist>
-</section>
+</appendix>
 
 <!-- Keep this comment at the end of the file
 Local variables:
diff --git a/reference/pcntl/examples.xml b/reference/pcntl/examples.xml
new file mode 100644
index 0000000000..23e92b5bcc
--- /dev/null
+++ b/reference/pcntl/examples.xml
@@ -0,0 +1,85 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<!-- $Revision: 1.2 $ -->
+<chapter xml:id="pcntl.examples" xmlns="http://docbook.org/ns/docbook">
+ &reftitle.examples;
+ <section xml:id="pcntl.example">
+  <para>
+   This example forks off a daemon process with a signal handler.
+  </para>
+  <example>
+   <title>Process Control Example</title>
+   <programlisting role="php">
+<![CDATA[
+<?php
+declare(ticks=1);
+
+$pid = pcntl_fork();
+if ($pid == -1) {
+     die("could not fork"); 
+} else if ($pid) {
+     exit(); // we are the parent 
+} else {
+     // we are the child
+}
+
+// detatch from the controlling terminal
+if (posix_setsid() == -1) {
+    die("could not detach from terminal");
+}
+
+// setup signal handlers
+pcntl_signal(SIGTERM, "sig_handler");
+pcntl_signal(SIGHUP, "sig_handler");
+
+// loop forever performing tasks
+while (1) {
+
+    // do something interesting here
+
+}
+
+function sig_handler($signo) 
+{
+
+     switch ($signo) {
+         case SIGTERM:
+             // handle shutdown tasks
+             exit;
+             break;
+         case SIGHUP:
+             // handle restart tasks
+             break;
+         default:
+             // handle all other signals
+     }
+
+}
+
+?>
+]]>
+   </programlisting>
+  </example>
+ </section>
+</chapter>
+
+<!-- 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:"../../../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
+-->
+
diff --git a/reference/pcntl/reference.xml b/reference/pcntl/reference.xml
index 0a4c55827d..c3e309bc29 100644
--- a/reference/pcntl/reference.xml
+++ b/reference/pcntl/reference.xml
@@ -1,138 +1,16 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.15 $ -->
-<!-- Purpose: fileprocess.process -->
-<!-- Membership: bundled -->
+<!-- $Revision: 1.16 $ -->
 
  <reference xml:id="ref.pcntl" xmlns="http://docbook.org/ns/docbook">
   <title>Process Control Functions</title>
-  <titleabbrev>PCNTL</titleabbrev>
 
-  <partintro>
-   <section xml:id="pcntl.intro">
-    &reftitle.intro;
-    <para>
-     Process Control support in PHP implements the Unix style of
-     process creation, program execution, signal handling and process
-     termination. Process Control should not be enabled within a
-     web server environment and unexpected results may happen if any
-     Process Control functions are used within a web server environment.
-    </para>
-    <para>
-     This documentation is intended to explain the general usage of
-     each of the Process Control functions. For detailed information
-     about Unix process control you are encouraged to consult your
-     systems documentation including fork(2), waitpid(2) and signal(2)
-     or a comprehensive reference such as Advanced Programming in the
-     UNIX Environment by W. Richard Stevens (Addison-Wesley).
-    </para>
-    <para>
-     PCNTL now uses ticks as the signal handle callback mechanism, which is
-     much faster than the previous mechanism. This change follows the same
-     semantics as using "user ticks". You use the <function>declare</function> 
-     statement to specify the locations in your program where callbacks are
-     allowed to occur. This allows you to minimize the overhead of handling
-     asynchronous events. In the past, compiling PHP with pcntl enabled would
-     always incur this overhead, whether or not your script actually used
-     pcntl.
-    </para>
-    <para>
-     There is one adjustment that all pcntl scripts prior to PHP 4.3.0 must
-     make for them to work which is to either to use
-     <function>declare</function> on a section where you wish to allow
-     callbacks or to just enable it across the entire script using 
-     the new global syntax of <function>declare</function>.
-    </para>
-
-    &note.no-windows.extension;
-   </section>
-
-   <section xml:id="pcntl.requirements">
-    &reftitle.required;
-    &no.requirement;
-   </section>
-
-   &reference.pcntl.configure;
-
-   <section xml:id="pcntl.configuration">
-    &reftitle.runtime;
-    &no.config;
-   </section>
-
-   <section xml:id="pcntl.resources">
-    &reftitle.resources;
-    &no.resource;
-   </section>
-
-   &reference.pcntl.constants;
-
-   <section xml:id="pcntl.example">
-    &reftitle.examples;
-    <para>
-     This example forks off a daemon process with a signal handler.
-    </para>
-    <example>
-     <title>Process Control Example</title>
-     <programlisting role="php">
-<![CDATA[
-<?php
-declare(ticks=1);
-
-$pid = pcntl_fork();
-if ($pid == -1) {
-     die("could not fork"); 
-} else if ($pid) {
-     exit(); // we are the parent 
-} else {
-     // we are the child
-}
-
-// detatch from the controlling terminal
-if (posix_setsid() == -1) {
-    die("could not detach from terminal");
-}
-
-// setup signal handlers
-pcntl_signal(SIGTERM, "sig_handler");
-pcntl_signal(SIGHUP, "sig_handler");
-
-// loop forever performing tasks
-while (1) {
-
-    // do something interesting here
-
-}
-
-function sig_handler($signo) 
-{
-
-     switch ($signo) {
-         case SIGTERM:
-             // handle shutdown tasks
-             exit;
-             break;
-         case SIGHUP:
-             // handle restart tasks
-             break;
-         default:
-             // handle all other signals
-     }
-
-}
-
-?>
-]]>
-     </programlisting>
-    </example>
-   </section>
-
-   <section xml:id="pcntl.seealso">
+  <partintro xml:id="pcntl.seealso">
     &reftitle.seealso;
     <para>
      A look at the section about
      <link linkend="ref.posix">POSIX functions</link>
      may be useful.
     </para>
-   </section>
 
   </partintro>
 
diff --git a/reference/pcntl/setup.xml b/reference/pcntl/setup.xml
new file mode 100644
index 0000000000..5e8405a031
--- /dev/null
+++ b/reference/pcntl/setup.xml
@@ -0,0 +1,54 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision: 1.2 $ -->
+
+<chapter xml:id="pcntl.setup" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
+ &reftitle.setup;
+
+ <!-- {{{ Requirements -->
+ <section xml:id="pcntl.requirements">
+  &reftitle.required;
+  &no.requirement;
+ </section>
+ <!-- }}} -->
+
+ <!-- {{{ Installation -->
+ &reference.pcntl.configure;
+ <!-- }}} -->
+
+ <!-- {{{ Configuration -->
+ <section xml:id="pcntl.configuration">
+  &reftitle.runtime;
+  &no.config;
+ </section>
+ <!-- }}} -->
+
+ <!-- {{{ Resources -->
+ <section xml:id="pcntl.resources">
+  &reftitle.resources;
+  &no.resource;
+ </section>
+ <!-- }}} -->
+
+</chapter>
+
+<!-- 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:"../../../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
+-->
+