cvs: peardoc /en/pyrus configuration.xml /en/pyrus/configuration system.xml user.xml /en/pyrus/differences frompear.xml

cellog		Sun Jun 28 03:13:25 2009 UTC

  Modified files:              
    /peardoc/en/pyrus	configuration.xml 
    /peardoc/en/pyrus/configuration	system.xml user.xml 
    /peardoc/en/pyrus/differences	frompear.xml 
  Log:
  more docs on configuration
  
http://cvs.php.net/viewvc.cgi/peardoc/en/pyrus/configuration.xml?r1=1.1&r2=1.2&diff_format=u
Index: peardoc/en/pyrus/configuration.xml
diff -u peardoc/en/pyrus/configuration.xml:1.1 peardoc/en/pyrus/configuration.xml:1.2
--- peardoc/en/pyrus/configuration.xml:1.1	Sat Jun 27 05:18:06 2009
+++ peardoc/en/pyrus/configuration.xml	Sun Jun 28 03:13:25 2009
@@ -7,9 +7,28 @@
    <date>2009-06-26</date>
   </info>
 
-  <simpara>
-   Work in progress.
-  </simpara>
+  <para>
+   Pyrus has two kinds of configuration files, system configuration files, which
+   are stored directly in the installation location, and user configuration files,
+   which are stored in the home directory of the user, or in the Windows
+   equivalent, <literal>My Documents</literal>.
+  </para>
+  <para>
+   Each installation is tightly bound to the configuration that defines where
+   files should be installed, which PHP executable to use, and which php.ini
+   is used to manage that installation.
+  </para>
+  <para>
+   On the other hand, user-specific preferences are tightly bound to each
+   user, by placing them in the user's home directory.  These values are
+   universal to all installations and include things like the amount of
+   information to display, the preferred mirror to use for a channel, the
+   openssl certificate to use for package signing, and so on.
+  </para>
+  <para>
+   This way, multiple PEAR installations can be managed very safely without
+   ambiguity over what configuration values should be used.
+  </para>
 
   &pyrus.configuration.user;
   &pyrus.configuration.system;
http://cvs.php.net/viewvc.cgi/peardoc/en/pyrus/configuration/system.xml?r1=1.2&r2=1.3&diff_format=u
Index: peardoc/en/pyrus/configuration/system.xml
diff -u peardoc/en/pyrus/configuration/system.xml:1.2 peardoc/en/pyrus/configuration/system.xml:1.3
--- peardoc/en/pyrus/configuration/system.xml:1.2	Sat Jun 27 19:00:15 2009
+++ peardoc/en/pyrus/configuration/system.xml	Sun Jun 28 03:13:25 2009
@@ -4,7 +4,40 @@
 
  <section xml:id="pyrus.configuration.system.intro">
   <info><title>Introduction</title></info>
-  <para>This is a work in progress.</para>
+  <para>
+   The system configuration file is always saved in a file named <literal>.config</literal>
+   in the base of the PEAR installation.  Thus, if php files are installed in
+   <literal>/usr/local/lib/pear/php</literal>, then the configuration for
+   that installation is installed in <literal>/usr/local/lib/pear/.config</literal>.
+   The configuration is stored in XML format, and can be modified by hand if
+   necessary.
+  </para>
+  <para>
+   The configuration will not be saved if no values are modified from the default values
+  </para>
+  <para>
+   Here is a sample system configuration file (with line breaks added for readability):
+  </para>
+  <para>
+   <programlisting role="xml">
+    <![CDATA[
+<?xml version="1.0"?>
+<pearconfig version="1.0">
+ <ext_dir>/usr/local/lib/php/extensions/debug-non-zts-20090115</ext_dir>
+ <cfg_dir>/home/user/testpear/cfg</cfg_dir>
+ <doc_dir>/home/user/testpear/mydata</doc_dir>
+ <bin_dir>/usr/local/bin</bin_dir>
+ <www_dir>/home/user/testpear/www</www_dir>
+ <test_dir>/home/user/testpear/tests</test_dir>
+ <src_dir>/home/user/testpear/src</src_dir>
+ <php_bin>/usr/local/bin/php</php_bin>
+ <php_ini>/usr/local/lib/php.ini</php_ini>
+ <php_prefix></php_prefix>
+ <php_suffix></php_suffix>
+</pearconfig>
+    ]]>
+   </programlisting>
+  </para>
 
  </section>
  &pyrus.configuration.system.bindir;
http://cvs.php.net/viewvc.cgi/peardoc/en/pyrus/configuration/user.xml?r1=1.2&r2=1.3&diff_format=u
Index: peardoc/en/pyrus/configuration/user.xml
diff -u peardoc/en/pyrus/configuration/user.xml:1.2 peardoc/en/pyrus/configuration/user.xml:1.3
--- peardoc/en/pyrus/configuration/user.xml:1.2	Sat Jun 27 19:00:15 2009
+++ peardoc/en/pyrus/configuration/user.xml	Sun Jun 28 03:13:25 2009
@@ -4,7 +4,60 @@
 
  <section xml:id="pyrus.configuration.user.intro">
   <info><title>Introduction</title></info>
-  <para>This is a work in progress.</para>
+  <para>
+   The user configuration file is always stored in the user's personal directory,
+   the home directory on unix, and <literal>My Documents</literal> on Windows.
+   For a unix user with username <literal>user</literal>, the user configuration
+   file is stored in <literal>/home/user/.pear/pearconfig.xml</literal>.  For
+   a Windows user, the configuration is stored in
+   <literal>My Documents\pear\pearconfig.xml</literal>.  The file is saved in
+   XML format and can be hand-edited if necessary.
+  </para>
+  <para>
+   Unlike the system configuration file, the user configuration file is always
+   saved when an operation that writes to disk is called, such as installing
+   a package.  On startup, Pyrus uses the configuration file's existence to
+   determine whether it is being executed for the first time, and if so, prompts
+   the user to initialize a few default settings such as the PEAR path.
+  </para>
+  <para>
+   There are two kinds of user configuration variables, installation-wide variables
+   such as <literal>verbose</literal>, and channel-specific variables such as
+   <literal>openssl_cert</literal>.  Channel-specific variables can have different
+   values for different channels.  This allows setting a different certificate
+   for each channel, for instance.  The channel name is used as a tag, with
+   non-XML friendly characters translated into simple mnemonics (such as
+   <literal>.</literal> becoming <literal>DOT</literal>).
+  </para>
+  <para>
+   Here is a sample user configuration file (with line breaks added for readability):
+  </para>
+  <para>
+   <programlisting role="xml">
+    <![CDATA[
+<?xml version="1.0"?>
+<pearconfig version="1.0">
+ <default_channel>pear2.php.net</default_channel>
+ <auto_discover>0</auto_discover>
+ <http_proxy></http_proxy>
+ <cache_dir>/home/user/testpear/cache</cache_dir>
+ <temp_dir>/home/user/testpear/temp</temp_dir>
+ <verbose>1</verbose>
+ <preferred_state>stable</preferred_state>
+ <umask>0022</umask>
+ <cache_ttl>3600</cache_ttl>
+ <my_pear_path>/home/user/testpear:/usr/local/lib/php</my_pear_path>
+ <plugins_dir>/home/user/.pear</plugins_dir>
+ <openssl_cert>
+  <pear2DOTphpDOTnet>/home/user/mykey.p12</pear2DOTphpDOTnet>
+ </openssl_cert>
+ <handle>
+  <pear2DOTphpDOTnet>cellog</pear2DOTphpDOTnet>
+ </handle>
+</pearconfig>
+    ]]>
+   </programlisting>
+  </para>
  </section>
  
  &pyrus.configuration.user.autodiscover;
http://cvs.php.net/viewvc.cgi/peardoc/en/pyrus/differences/frompear.xml?r1=1.8&r2=1.9&diff_format=u
Index: peardoc/en/pyrus/differences/frompear.xml
diff -u peardoc/en/pyrus/differences/frompear.xml:1.8 peardoc/en/pyrus/differences/frompear.xml:1.9
--- peardoc/en/pyrus/differences/frompear.xml:1.8	Thu Jun 25 17:59:11 2009
+++ peardoc/en/pyrus/differences/frompear.xml	Sun Jun 28 03:13:25 2009
@@ -219,6 +219,10 @@
    The above command will list the installed packages in both registries in
    <literal>/home/username/pear</literal> and in <literal>/usr/local/lib/pear/php</literal>.
   </para>
+  <para>
+   A detailed reference of Pyrus's handling of configuration files is
+   <link linkend="pyrus.configuration">here</link>
+  </para>
  </section>
  <section xml:id="pyrus.differences.frompear.registry">
   <info><title>Registries</title></info>