first rev of docs; far from complete

andreiz · Jun 6, 2010 · c3c3a53 · c3c3a53
1 parent 599e569
commit c3c3a53
Show file tree

Hide file tree

Showing 10 changed files with 466 additions and 0 deletions.
diff --git a/doc/book.developer.xml b/doc/book.developer.xml
@@ -0,0 +1,76 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V5.0//EN"
+"{PATH_TO_DOCBASE}/docbook/docbook-xml/docbook.dtd" [
+
+<!-- $Revision$ -->
+<!-- We use xhtml entities all over the place -->
+<!ENTITY % xhtml-lat1        SYSTEM "{PATH_TO_DOCBASE}/entities/ISO/xhtml1-lat1.ent">
+<!ENTITY % xhtml-symbol      SYSTEM "{PATH_TO_DOCBASE}/entities/ISO/xhtml1-symbol.ent">
+<!ENTITY % xhtml-special     SYSTEM "{PATH_TO_DOCBASE}/entities/ISO/xhtml1-special.ent">
+<!ENTITY % isopub            SYSTEM "{PATH_TO_DOCBASE}/entities/ISO/isopub.ent">
+%xhtml-lat1;
+%xhtml-symbol;
+%xhtml-special;
+%isopub;
+
+<!-- Fallback to English definitions and snippets (in case of missing translation) -->
+<!ENTITY % language-defs.default     SYSTEM "{PATH_TO_DOC}/language-defs.ent">
+<!ENTITY % language-snippets.default SYSTEM "{PATH_TO_DOC}/language-snippets.ent">
+<!ENTITY % extensions.default        SYSTEM "{PATH_TO_DOC}/extensions.ent">
+
+%language-defs.default;
+%extensions.default;
+%language-snippets.default;
+
+<!-- All global entities for the XML files -->
+<!ENTITY % global.entities  SYSTEM "{PATH_TO_DOCBASE}/entities/global.ent">
+
+<!-- These are language independent -->
+<!ENTITY % frontpage.entities SYSTEM "{PATH_TO_DOC}/contributors.ent">
+<!ENTITY % file.entities      SYSTEM "{PATH_TO_DOCBASE}/entities/file-entities.ent">
+
+<!-- Include all external DTD parts defined previously -->
+%global.entities;
+%file.entities;
+%frontpage.entities;
+]>
+
+<book xml:id="book.prep" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:lang="en">
+ <title>Prep</title>
+ <titleabbrev>Prep</titleabbrev>
+
+ <preface xml:id="intro.prep">
+  &reftitle.intro;
+  <para>
+
+  </para>
+ </preface>
+
+ &reference.prep.setup;
+ &reference.prep.constants;
+ &reference.prep.examples;
+ &reference.prep.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/doc/book.xml b/doc/book.xml
@@ -0,0 +1,41 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision$ -->
+
+<book xml:id="book.prep" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
+ <title>Prep preprocessor</title>
+ <titleabbrev>Prep</titleabbrev>
+
+ <preface xml:id="intro.prep">
+  &reftitle.intro;
+  <para>
+   Prep is a hook for PHP that allows developers to write preprocessor scripts
+   in any language, using any script.
+  </para>
+ </preface>
+
+ &reference.prep.setup;
+ &reference.prep.constants;
+ &reference.prep.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:"~/.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
+-->
diff --git a/doc/configure.xml b/doc/configure.xml
@@ -0,0 +1,39 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision$ -->
+
+<section xml:id="prep.installation" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
+ &reftitle.install;
+
+ <para>
+  &pecl.info;
+  <link xlink:href="&url.pecl.package;prep">&url.pecl.package;prep</link>
+ </para>
+
+ <para>
+  The latest PECL/prep Win32 DLL is available here:
+  <link xlink:href="&url.pecl.win.ext;php_prep.dll">php_prep.dll</link>
+ </para>
+
+</section>
+
+
+<!-- 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
+-->
diff --git a/doc/constants.xml b/doc/constants.xml
@@ -0,0 +1,28 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision$ -->
+
+<appendix xml:id="prep.constants" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
+ &reftitle.constants;
+ &no.constants;
+</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
+-->
diff --git a/doc/entities.functions.xml b/doc/entities.functions.xml
@@ -0,0 +1 @@
+&reference.prep.functions.prep-get-file;
diff --git a/doc/functions/prep-get-file.xml b/doc/functions/prep-get-file.xml
@@ -0,0 +1,73 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision$ -->
+
+<refentry xml:id="function.prep-get-file" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
+ <refnamediv>
+  <refname>prep_get_file</refname>
+  <refpurpose>Perform a lookup on the original un-preprocessed filename</refpurpose>
+ </refnamediv>
+
+ <refsect1 role="description">
+  &reftitle.description;
+  <methodsynopsis>
+   <type>string</type><methodname>prep_get_file</methodname>
+   <methodparam><type>string</type><parameter>from_file</parameter></methodparam>
+  </methodsynopsis>
+  <para>
+   When a PHP script is preprocessed, the result of the preprocessor command
+   is stored in a temporary file, and the original file is preserved.
+  </para>
+  <para>
+   <function>prep_get_file</function> is used to retrieve the temporary file
+   name from the original file name (such as <constant>__FILE__</constant>).
+  </para>
+
+ </refsect1>
+
+ <refsect1 role="parameters">
+  &reftitle.parameters;
+  <para>
+   <variablelist>
+    <varlistentry>
+     <term><parameter>from_file</parameter></term>
+     <listitem>
+      <para>
+       The original file name; this is used to look up the temporary file
+       name.
+      </para>
+     </listitem>
+    </varlistentry>
+   </variablelist>
+  </para>
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+  &reftitle.returnvalues;
+  <para>
+   The temporary file name; &false; on failure
+  </para>
+ </refsect1>
+
+
+</refentry>
+
+<!-- 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
+-->
diff --git a/doc/ini.xml b/doc/ini.xml
@@ -0,0 +1,98 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision$ -->
+
+<section xml:id="prep.configuration" xmlns="http://docbook.org/ns/docbook">
+ &reftitle.runtime;
+ &extension.runtime;
+ <para>
+  <table>
+   <title>Prep &ConfigureOptions;</title>
+   <tgroup cols="4">
+    <thead>
+     <row>
+      <entry>&Name;</entry>
+      <entry>&Default;</entry>
+      <entry>&Changeable;</entry>
+      <entry>&Changelog;</entry>
+     </row>
+    </thead>
+    <tbody>
+     <row>
+      <entry>prep.command</entry>
+      <entry>&null;</entry>
+      <entry>PHP_INI_PERDIR</entry>
+      <entry><!-- leave empty, this will be filled by an automatic script --></entry>
+     </row>
+</tbody>
+   </tgroup>
+  </table>
+ </para>
+
+ &ini.descriptions.title;
+
+ <para>
+  <variablelist>
+   <varlistentry xml:id="ini.prep.command">
+     <term>
+      <parameter>prep.command</parameter>
+      <type>string</type>
+     </term>
+     <listitem>
+      <para>
+       The command that Prep will call to handle preprocessing. The file to
+       process will be passed as the first argument of the
+       <literal>prep.command</literal>, and the output of the command will be
+       used by PHP as the source.
+      </para>
+      <para>
+       The script should exit with a <literal>0</literal> status on success.
+       If a status of <literal>-1</literal> (or <literal>255</literal>) is
+       returned (such as on a PHP parse error), Prep will interpret the error
+       message and raise it as an <constant>E_FATAL</constant> error.
+      </para>
+      <para>
+       Returning a status of <literal>1</literal> will cause Prep to ignore
+       the command's output, and use the original file. This is useful for
+       performing simple checks in the preprocessor, and returning
+       <literal>1</literal> if a precondition is not met.
+      </para>
+      <para>
+       Multiple <literal>prep.command</literal>s may be set in &php.ini;. If
+       more than one command is set, Prep will pass the script (and the
+       results of other preprocessor scripts) to the command, in the order in
+       which they are set.
+      </para>
+     </listitem>
+    </varlistentry>
+
+  </variablelist>
+ </para>
+
+ <para>
+  If the <literal>PHP_SUPPRESS_PREP</literal> environment variable is set,
+  Prep will skip preprocessing. This variable is set implicitly by Prep, but
+  may also be set by a user in order to temporarily suppress Preprocessing.
+ </para>
+
+</section>
+
+<!-- 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
+-->
diff --git a/doc/reference.xml b/doc/reference.xml
@@ -0,0 +1,30 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision$ -->
+
+<reference xml:id="ref.prep" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
+ <title>Prep &Functions;</title>
+
+ &reference.prep.entities.functions;
+
+</reference>
+
+<!-- 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
+-->