incubator-zeta-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From t...@apache.org
Subject [zeta-commits] svn commit: r1032115 - /incubator/zetacomponents/website/content/documentation/install.txt
Date Sat, 06 Nov 2010 17:17:26 GMT
Author: toby
Date: Sat Nov  6 17:17:26 2010
New Revision: 1032115

URL: http://svn.apache.org/viewvc?rev=1032115&view=rev
Log:
- Fixed: Re-worked installation docs for Apache Zeta Components.
# Some parts still refer to eZ Components, since we did not roll a release,
# yet. I added corresponding notes about the status. This needs to be updated,
# as soon as we have a release.

Modified:
    incubator/zetacomponents/website/content/documentation/install.txt

Modified: incubator/zetacomponents/website/content/documentation/install.txt
URL: http://svn.apache.org/viewvc/incubator/zetacomponents/website/content/documentation/install.txt?rev=1032115&r1=1032114&r2=1032115&view=diff
==============================================================================
--- incubator/zetacomponents/website/content/documentation/install.txt (original)
+++ incubator/zetacomponents/website/content/documentation/install.txt Sat Nov  6 17:17:26
2010
@@ -1,49 +1,42 @@
 An Introduction to Apache Zeta Components
 =========================================
 
-.. note::
-    This document has to be refactored to cosistently refer to Apache Zeta
-    Components and the Apache Foundation instead of eZ*.
-
-This guide provides a glimpse into the usage of the eZ Components for PHP 5.
-They are object oriented and reusable building blocks which will speed up
-development and deployment of enterprise applications based on PHP 5.
+This guide provides a glimpse into the usage of the Apache Zeta Components for
+PHP 5.  They are object oriented and reusable building blocks which will speed
+up development and deployment of enterprise applications based on PHP 5.
 
 What is it?
 -----------
 
-eZ Components is an enterprise ready general purpose PHP components library. As
-a collection of high quality independent building blocks for PHP application
-development eZ Components will both speed up development and reduce risks. An
-application can use one or more components effortlessly as they all adhere to
-the same naming conventions and follow the same structure. All components are
-currently based on PHP 5.2.1.
-
-The eZ Components in a nutshell:
-
-* Designed for enterprise PHP application development
-* Open source and licensed under the `New BSD license`_
-* Clear intellectual property (IP) rights
-* Thoroughly documented
-* Developed, supported and maintained by `eZ Systems`_
-
-More general information about the eZ Components is available at the product
-page. Furthermore, there is a list of available components. Technical aspects
-of how the library is built-up are explained at the technical details page.
+Apache Zeta Components is an enterprise ready general purpose PHP components
+library. As a collection of high quality independent building blocks for PHP
+application development Apache Zeta Components will both speed up development
+and reduce risks. An application can use one or more components effortlessly as
+they all adhere to the same naming conventions and follow the same structure.
+All components are currently based on PHP 5.2.1.
+
+The Apache Zeta Components in a nutshell:
+
+- Designed for enterprise PHP application development
+- Open source and licensed under the `Apache License, Version 2.0`__
+- Clear intellectual property (IP) rights
+- Thoroughly documented
+- Fully maintained by the open source community, initially developed by `eZ
+  Systems`__
 
-.. _`New BSD License`: /zetacomponents/overview/license
-.. _`eZ Systems`: http://ez.no
+__ http://www.apache.org/licenses/LICENSE-2.0
+__ http://ez.no
 
 Usage
 -----
 
-The purpose of the eZ Components is to hide complexity of routines behind an
-object oriented API. Regular tasks of programming become much easier, and due
-to the fact that complexity is being reduced, the risk of application
+The purpose of Apache Zeta Components is to hide complexity of routines behind
+an object oriented API. Regular tasks of programming become much easier, and
+due to the fact that complexity is being reduced, the risk of application
 development is minimized. In general, your development process will become more
 efficient.
 
-For example, sending an email with the help of the eZ Mail component, looks
+For example, sending an email with the help of the Zeta Mail component, looks
 like this::
 
 	<?php
@@ -56,40 +49,52 @@ like this::
 	   $mail->subject = "[Components test] SMTP test";
 	   $mail->body = new ezcMailText( "Content" );
 	   $transport->send( $mail ); 
-
 	}
-
 	catch ( Exception $e )
 	{
 	   echo "Failed: ", $e->getMessage(), "\n";
 	}
 	?>
 
-Of course you need to change the SMTP server's IP ( smtp.example.com) and
-definitely the email adresses in the sample code to fit your needs. For more
-examples of each of the eZ Components, take a look at the doc/ directory of
-each component where some sample code is provided.
-
-Please notice that the eZ Components will only work on PHP 5.2.1 or higher.
-They can be used side-by-side with PEAR packages that as well run on PHP >=
-5.2.1.
+Of course you need to change the SMTP server's IP (smtp.example.com) and
+definitely the email addresses in the sample code to fit your needs. For more
+examples of each of the Apache Zeta Components, take a look at the doc/
+directory of each component where some sample code is provided.
+
+Furthermore, extensive API documentation and a tutorial are provided online in
+the `docs section`__.
+
+__ /zetacomponents/documentation/trunk.html
+
+Please notice that the Apache Zeta Components will only work on PHP 5.2.1 or
+higher. They can be used side-by-side with, for example, PEAR packages and the
+Zend Framework, which as well run on PHP >= 5.2.1.
 
 Installation
 ------------
 
-There are three ways how to make eZ components available for your PHP
+There are three ways how to make Apache Zeta Components available for your PHP
 environment, please read the whole of this article before continuing with the
 practical part:
 
-* Use `PEAR Installer`_ for convenient installation via command line
-* Download_ eZ components packaged in an archive
+* Use `PEAR Installer`__ for convenient installation via command line
+* Download__ Apache Zeta Components packaged in an archive
 * Get the latest sources from SVN
 
-.. _`PEAR Installer`: http://pear.php.net
-.. _download: /zetacomponents/download
+__ http://pear.php.net
+__ /zetacomponents/download
+
+.. note:: There is no release of the project source as Apache Zeta Components,
+          yet. We are working on making a release possible. In the mean while,
+          please use the PEAR packages provided by the old eZ Components PEAR
+          channel on ``components.ez.no``, or download the full library package
+          from the `old eZ Components website`__. **Apache Zeta Components are
+          fully API compatible with eZ Components!**
+
+          __ http://ezcomponents.org/download
 
-Installing the eZ components with the help of the PEAR Installer is highly
-recommended, as it is the most convenient and safest way. The given
+Installing the Apache Zeta Components with the help of the PEAR Installer is
+highly recommended, as it is the most convenient and safest way. The given
 instructions serve as guidelines on a Linux system, but are also useful for
 those who run PHP on Windows, of course they just need to adjust the paths
 accordingly.
@@ -97,6 +102,11 @@ accordingly.
 PEAR Installer
 ~~~~~~~~~~~~~~
 
+.. note:: The following instructions still refer to the eZ Components PEAR
+          channel, since Apache Zeta Components did not roll a release, yet.
+          Apache Zeta Components are fully API compatible with the old
+          (discontinued) eZ Components library.
+
 After you have installed PHP 5.2.1 or a higher version, you will have the PEAR
 Installer available automatically. Simply issue the following commands in the
 shell::
@@ -104,7 +114,7 @@ shell::
 	pear channel-discover components.ez.no
 
 This will let PEAR Installer connect to the server components.ez.no where the
-eZ components are stored for distribution::
+eZ Components are stored for distribution::
 
 	pear install -a ezc/eZComponents
 
@@ -119,47 +129,57 @@ In case you already have installed the c
 Download of Archives
 ~~~~~~~~~~~~~~~~~~~~
 
+.. note:: The following instructions still refer to the eZ Components download
+          page, since Apache Zeta Components did not roll a release, yet.
+          Apache Zeta Components are fully API compatible with the old
+          (discontinued) eZ Components library.
+
 The packaged releases of eZ components can be downloaded as .tar.bz2 or .zip
-archive from the download_ page. The bundles that we offer for download always
-include the whole library.
+archive from the `download page`__. The bundles that we offer for download
+always include the whole library. You just need to extract the package and
+adjust your ``include_path`` directive.
+
+__ http://ezcomponents.org/download
 
 SVN
 ---
 
 If you love to live on the edge and would like to work with the latest
-development version of the eZ components, you can get it from SVN. For a
-successful installation from SVN, procede in the given order.
+development version of Apache Zeta Components, you can get it from SVN. For a
+successful installation from SVN, proceed in the given order.
 
-First, create a directory where you want the eZ components to be placed.
+First, create a directory where you want the Apache Zeta Components to be
+placed.
 
-Next, you should checkout the tree. To checkout, do::
+Next, you should checkout the trunk, which contains the latest development
+sources. To checkout, do::
 
-	svn co http://svn.ez.no/svn/ezcomponents/trunk
+	svn co https://svn.apache.org/repos/asf/incubator/zetacomponents/trunk
 
 When working with the SVN version, it is important to setup the environment for
-the eZ components. Hence, checkout the needed script with::
+Apache Zeta Components. Hence, checkout the needed script with::
 
-	svn co http://svn.ez.no/svn/ezcomponents/scripts
+	svn co https://svn.apache.org/repos/asf/incubator/zetacomponents/scripts
 
 and execute it::
 
 	./scripts/setup-env.sh
 
 This will create the symlinks for autoload, which will of course not work on
-Windows.
-
-From version 1.1 of the components there is also a script for Windows. Here you
-need to execute the following script instead::
+Windows. For this platform, the alternative script::
 
 	scripts\setup-env.bat
 
-This will create copies of necessary files for autoload.
+will create copies of necessary files for autoload. Note that you will need to
+re-run this script whenever you performed SVN up (and new class have been
+added) or if you added new classes yourself. This step is not necessary on
+\*nix systems.
 
 Partial check out
 ~~~~~~~~~~~~~~~~~
 
-It is of course also possible to check out from SVN per component. Again, you
-first have to create a directory again, something like::
+A per component check out from SVN is of course also possible. Again, you first
+have to create a directory again, something like::
 
 	mkdir /tmp/mydir/ezc
 	cd /tmp/mydir/ezc
@@ -170,12 +190,12 @@ Inside this directory, create the trunk 
 
 Then check out the scripts directory and Base component::
 
-	svn co http://svn.ez.no/svn/ezcomponents/scripts
-	svn co http://svn.ez.no/svn/ezcomponents/trunk/Base trunk/Base
+	svn co https://svn.apache.org/repos/asf/incubator/zetacomponents/scripts
+	svn co https://svn.apache.org/repos/asf/incubator/zetacomponents/trunk/Base trunk/Base
 
 Then you can check out each component that you want with a command like::
 
-	svn co http://svn.ez.no/svn/ezcomponents/trunk/Mail trunk/Mail
+	svn co https://svn.apache.org/repos/asf/incubator/zetacomponents/trunk/Mail trunk/Mail
 
 Make sure to checkout all dependencies as well, if they exist. You can find
 whether a component has dependencies in the DEPS file in the root of each
@@ -189,23 +209,23 @@ or::
 
 	scripts\setup-env.bat
 
-
 Configuration
 -------------
 
-After installation of the eZ Components, either via PEAR Installer, downloading
-of the archives, or getting them from SVN, you need to do a bit of
+After installation of Apache Zeta Components, either via PEAR Installer,
+downloading of the archives, or getting them from SVN, you need to do a bit of
 configuration:
 
-* Adjust the include path to have the eZ Components classes available via PHP
-* Create the autoload environment for calling eZ Components from your script
+- Adjust the ``include_path`` to have the Apache Zeta Components classes
+  available via PHP
+- Create the autoload environment for calling eZ Components from your script
 
 Include Path
 ~~~~~~~~~~~~
 
-The PHP include path should point to the directory where the eZ Components
-reside. You can either set it in the php.ini configuration file or with the
-set_include_path() function from within your script.
+The PHP include path should point to the directory where the Apache Zeta
+Components reside. You can either set it in the *php.ini* configuration file or
+with the ``set_include_path()`` function from within your script.
 
 If you installed the components with the PEAR installer, then in most cases you
 do not have to make any changes as PHP's include path will already cover the
@@ -213,36 +233,45 @@ default::
 
 	/usr/local/lib/php
 
-into which the PEAR installer will install the eZ Components. In case it is
-different, please set it at the top of your script with::
+into which the PEAR installer will install the Apache Zeta Components. In case
+it is different, please set it at the top of your script with::
 
 	<?php
-	set_include_path( "/path/to/root/pear/directory" . PATH_SEPARATOR .  get_include_path());
+	set_include_path(
+        '/path/to/root/pear/directory' . PATH_SEPARATOR .  get_include_path()
+    );
 	?>
 
 In case you downloaded a bundle, or checked out the components from SVN, set
 the include path to the root of the checked out archive. For example with::
 
 	<?php
-	set_include_path( "/path/to/ezcomponents-1.0rc1" . PATH_SEPARATOR .  get_include_path());
+	set_include_path(
+        '/path/to/ezcomponents-version' . PATH_SEPARATOR .  get_include_path()
+    );
 	?>
 
 Autoload Environment
 ~~~~~~~~~~~~~~~~~~~~
 
-The PHP classes of the eZ Components can be conveniently used from within your
-PHP script. You don't have to use any require or include statements for any of
-the eZ Components classes that you use, this is because of the integrated
-autoload mechanism which can locate the classes for you when you instantiate or
-use them otherwise.
-
-There are three different ways of getting the autoload mechanism going.
+The PHP classes of Apache Zeta Components can be conveniently used from within
+your PHP script. You don't have to use any ``require`` or ``include``
+statements for any of the Apache Zeta Components classes that you use, this is
+because of the integrated autoload mechanism which can locate the classes for
+you when you instantiate or use them otherwise.
+
+There are three different ways of getting the autoload mechanism going:
+
+- Normal autoload, if you require a custom autoload function
+- Bootstrap file, if you only use Apache Zeta autoloading
+- SPL autoload, if you need to register several autoload functions
 
 Normal Autoload
 ```````````````
 
 With the first method, you require the ezcBase class, and defined your own
-autoload mechanism. You should add the following code on top of your PHP script::
+autoload mechanism. You should add the following code on top of your PHP
+script::
 
 	<?php
 	require_once "Base/base.php"; // dependent on installation method, see below
@@ -250,61 +279,70 @@ autoload mechanism. You should add the f
 	{
 		ezcBase::autoload( $className );
 	}
-	// your code here
+	// your code here …
 	?>
 
-Beware, that the require_once() statement is different depending on the
-installation method:
+Beware, that the ``require_once()`` statement is different depending on the
+installation method, due to the PEAR directory structure:
 
-* PEAR Installer::
+- PEAR Installer::
 
     ezc/Base/base.php
 
-* Downloaded bundle and SVN::
+- Downloaded bundle and SVN::
 
     Base/src/base.php
 
 Boot strap
 ``````````
-In case you only have to use autoload for the eZ Components, and not for your
-application or another library, you can just simple include the
+In case you only have to use autoload for the Apache Zeta Components, and not
+for your application or another library, you can just simple include the
 ``ezc_bootstrap.php`` file. Again, the file to require depends on the
 installation method.
 
-* PEAR Installer::
+- PEAR Installer::
 
 	<?php
 	require 'ezc/Base/ezc_bootstrap.php';
 	?>
 
-* Downloaded bundle and SVN::
+- Downloaded bundle and SVN::
 
 	<?php
 	require 'Base/src/ezc_bootstrap.php';
 	?>
 
+``ezc_bootstrap.php`` basically contains the code seen in the `Normal
+Autoload`_ section.
+
 SPL
 ```
-SPL (Standard PHP Library) also allows autoloading to be set up through the
-spl_autoload_register_ function. In this case, you require() the base class,
-just like in the `Normal Autoload`_ method, but instead of defining an
-__autoload() function, you do::
+SPL__ (Standard PHP Library) also allows autoloading to be set up through the
+`spl_autoload_register`__ function. In this case, you ``require`` the base
+class, just like in the `Normal Autoload`_ method, but instead of defining an
+``__autoload()`` function, you do::
 
 	<?php
 	spl_autoload_register( array( 'ezcBase', 'autoload' ) );
 	?>
 
-.. _spl_autoload_register: http://php.net/manual/en/function.spl-autoload-register.php
+This way, you can register additional autoload functions for your own
+application or additional libraries.
 
+__ http://php.net/spl
+__ http://php.net/manual/en/function.spl-autoload-register.php
 
 Worth knowing
 -------------
 
+In following, we present some additional information on Apache Zeta Components,
+which you should know when starting to work with the library.
+
 Required extensions
 ~~~~~~~~~~~~~~~~~~~
 
-eZ Components require as few extensions by default. Required by all components
-are:
+Apache Zeta Components require as few extensions by default. Required by all
+components are:
 
 - SPL_
 - iconv_
@@ -317,30 +355,28 @@ actively remove these from your PHP inst
 care about them.
 
 Specific components may require additional extensions, for example the database
-related components (Database_, DatabaseSchema_, PersistentObject_) rely on
-PDO_ being available. The components documentation will give a hint, if
-special extensions are required. You can find a full overview in the
-documentation__.
-
-.. _Database: /s/Database
-.. _DatabaseSchema: /s/DatabaseSchema
-.. _PersistentObject: /s/PersistentObject
+related components (Database_, DatabaseSchema_, PersistentObject_) rely on PDO_
+being available. The components documentation will give a hint, if special
+extensions are required.
+
+.. _Database: http://zetac.org/Database
+.. _DatabaseSchema: http://zetac.org/DatabaseSchema
+.. _PersistentObject: http://zetac.org/PersistentObject
 .. _PDO: http://php.net/pdo
-__ /zetacomponents/introduction/requirements
 
 Some components provide different drivers, which use different extensions or
-external programs. You can choose one of these to make the component
-use the backend that you have available. An example is the Graph_ component,
-which can use different extensions to render graphics in different formats.
+external programs. You can choose one of these to make the component use the
+back end that you have available. An example is the Graph_ component, which can
+use different extensions to render graphics in different formats.
 
-.. _Graph: /s/Graph
+.. _Graph: http://zetac.org/Graph
 
 Character encoding
 ~~~~~~~~~~~~~~~~~~
 
-If not stated otherwise in the documentation, eZ Components assumes that the
-data that you provide is `UTF-8`__ encoded. In the same way, the output and
-return values generated by each are UTF-8 encoded as well.
+If not stated otherwise in the documentation, Apache Zeta Components assume
+that the data that you provide is `UTF-8`__ encoded. In the same way, the
+output and return values generated by each are UTF-8 encoded as well.
 
 If you need to work with data in different encodings, make sure to convert this
 data to UTF-8 before handing it into any of the components. 
@@ -348,25 +384,25 @@ data to UTF-8 before handing it into any
 .. __: http://en.wikipedia.org/wiki/Utf-8
 
 To perform binary safe operations, the iconv_ extension is used internally in
-eZ Components. As mentioned before, this extension is delivered with PHP and
-activated by default. We recommend that you use this extension also for
+Apache Zeta Components. As mentioned before, this extension is delivered with
+PHP and activated by default. We recommend that you use this extension also for
 potential encoding conversions.
 
 Some components allow you to work with different encodings than UTF-8. For
 example, the Mail_ component can work with several different encodings in
 parallel. Such exceptions of the rule are clearly marked in the documentation.
 
-.. _Mail: http://ezcomponents.org/s/Mail
+.. _Mail: http://zetac.org/Mail
 
 Conclusion
 ----------
 
 Now you have a working environment which lets you integrate the object oriented
-eZ Components for efficient application development with PHP 5.2.1. Besides
-using the eZ Components for developing your own mission-critical applications,
-you can as well take a look at the source code to see how eZ Systems makes use
-of the new PHP 5 features for object oriented programming within the eZ
-Components. Have a lot of fun!
+Apache Zeta Components for efficient application development with PHP 5.2.1.
+Besides using the Apache Zeta Components for developing your own
+mission-critical applications, you can as well take a look at the source code
+to see how Apache Zeta Components make use of the new PHP 5 features for object
+oriented programming. Have a lot of fun!
 
 Resources
 ---------



Mime
View raw message