cvs: peardoc / global.ent /en/guide/developers recommendations.xml

mj Wed Mar 3 15:36:49 2004 EDT Modified files: /peardoc global.ent /peardoc/en/guide/developers recommendations.xml Log: * Cleanup http://cvs.php.net/diff.php/peardoc/global.ent?r1=1.28&r2=1.29&ty=u Index: peardoc/global.ent diff -u peardoc/global.ent:1.28 peardoc/global.ent:1.29 --- peardoc/global.ent:1.28 Thu Jan 29 11:49:31 2004 +++ peardoc/global.ent Wed Mar 3 15:36:48 2004 @@ -1,6 +1,6 @@ <!-- -*- SGML -*- - $Id: global.ent,v 1.28 2004/01/29 16:49:31 alan_k Exp $ + $Id: global.ent,v 1.29 2004/03/03 20:36:48 mj Exp $ Contains global "macros" for all the XML documents. @@ -58,6 +58,7 @@ <!ENTITY url.pear 'http://pear.php.net/'> <!ENTITY url.pear.manual 'http://pear.php.net/manual/'> <!ENTITY url.pear.support 'http://pear.php.net/support.php'> +<!ENTITY url.pear.package 'http://pear.php.net/package/'> <!ENTITY url.pear.package.browse 'http://pear.php.net/packages.php'> <!ENTITY url.pear.package.new 'http://pear.php.net/package-new.php'> <!ENTITY url.pear.package.upload 'http://pear.php.net/release-upload.php'> @@ -110,6 +111,8 @@ <!ENTITY email.pear.general-subscribe 'pear-general-subscribe@lists.php.net'> <!ENTITY email.pear.webmaster 'pear-webmaster@php.net'> +<!ENTITY email.pear.core 'pear-core@lists.php.net'> + <!ENTITY email.pear.dev 'pear-dev@lists.php.net'> <!ENTITY email.pear.dev-subscribe 'pear-dev-subscribe@lists.php.net'> http://cvs.php.net/diff.php/peardoc/en/guide/developers/recommendations.xml?r1=1.5&r2=1.6&ty=u Index: peardoc/en/guide/developers/recommendations.xml diff -u peardoc/en/guide/developers/recommendations.xml:1.5 peardoc/en/guide/developers/recommendations.xml:1.6 --- peardoc/en/guide/developers/recommendations.xml:1.5 Wed Mar 3 15:24:53 2004 +++ peardoc/en/guide/developers/recommendations.xml Wed Mar 3 15:36:48 2004 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1" ?> -<!-- $Revision: 1.5 $ --> +<!-- $Revision: 1.6 $ --> <chapter id="developers.recommendations"> <docinfo> <author> @@ -16,33 +16,36 @@ </title> <para> The following recommendations describe topics which were discussed - and agreed upon by the PEAR-developers on the mailinglist pear-dev - and by the core-team. They aren't regulations that you need to follow - (e.g. in contrast to the <link linkend="standards">Coding Stardards</link>) but are - intended as guidelines for a common API-scheme and easier package - interoperability. Please consider following them in your packages + and agreed upon by the PEAR developers on the <ulink + url="mailto:&email.pear.dev;">developers mailinglist</ulink>. + They aren't strict rules, which you need to follow + (like <link linkend="standards">Coding Stardards</link>), but are + intended as guidelines for a common API scheme and easier package + interoperability. Please consider following them in your packages where possible. </para> </sect1> <sect1 id="developers.faq.colorrepresentation"> <title> - Color-representation inside PEAR-packages + Color Representation inside PEAR Packages </title> <titleabbrev> - Color-representation + Color Representation </titleabbrev> <para> - We recommend that developers store and use an array-representation of - color-values in their PEAR-packages. All values are in the range of - 0..255. + In case a package has to deal with colors, it is recommended that + developers store and use an array representation of the color values + in their PEAR packages. All values are in the range of 0..255. </para> <sect2> - <title>RGB-presesentation</title> + <title>RGB represesentation</title> <para> - An example using our "PEAR-green" would look like: + The following snippet defines an array that holds the RGB + definition of the green coloring that is used in the official PEAR + logo. <programlisting role="php"> <![CDATA[ @@ -60,19 +63,19 @@ Please note that the internal, numerical representation of both forms of the example are equal. The values represent the RGB (red, green, - blue) values. It was decided not to use "r", "g" and "b" and indizes - for the array because allows for easier creation of color-arrays in - sourcecode, makes handling less complicated and is an already - commonly used array-representations for colors. + blue) values. It was decided not to use "r", "g" and "b" as indices + for the array, because numerical indices allow easier creation of + color arrays in the sourcecode, make handling less complicated and + are an already commonly used array representation for colors. </para> </sect2> <sect2> - <title>RGB-representation with alpha-values</title> + <title>RGB representation with alpha-values</title> <para> - Since this an extension of the RGB-representation above it's + Since this an extension of the RGB representation above, it is recommended to use a forth value for alpha-channel-prepresentation. - An example of our pear-color with our "PEAR-green" with aprox. 80% + An example of the <quote>PEAR-green</quote> with aprox. 80% intensity would be: <programlisting role="php"> @@ -87,15 +90,15 @@ </para> <para> Please note this is in contrast to the alpha-value used by - imagecolorallocate(). Our alpha-representation was choosen for - consistency with the other RGB-values and because it's commonly - accepted practise in many other applications (image-processing tools, - ...). + imagecolorallocate(). The alpha-representation used in PEAR was + choosen for consistency with the other RGB values and because it is + commonly accepted practise in many other applications + (image-processing tools, etc.). </para> </sect2> <sect2> - <title>Other color-representations than RGB(A)</title> + <title>Other color representations than RGB(A)</title> <para> Since RGB/RGBA will used for graphic generation on a computer we decided to leave out an optional type-identifier classifying colors @@ -123,7 +126,7 @@ </itemizedlist> <para> - Please note that also the RGBA-representation has the type "RGB" + Please note that also the RGBA representation has the type "RGB" since it's closely related. </para> </sect2> @@ -131,10 +134,10 @@ <sect2> <title>Conversion to/between the color-representations</title> <para> - The PEAR-package <ulink url="http://pear.php.net/package/Image_Color">Image_Color</ulink> + The PEAR-package <ulink url="&url.pear.package;Image_Color">Image_Color</ulink> will (hopefully soon) contain all needed functions to convert arbitrary - color-formats to the internal RGBA-representation and convert different - color-representations. + color formats to the internal RGBA representation and convert different + color representations. </para> <para> Status: Currently Image_Color already offers functions to convert