Hello list,
With Pierre's agreement, I am submitting changes for the
documentation of imagecopy() and imagecopymerge() for inclusion in
the PHP documentation.
I have put my changes in the tagline (refentry) rather than the
description (refsect1 role="description"), with the following rationale:
When I skim a PHP online manual page, my attention is grabbed by the
parts that stand out - the tagline synopsis (just below the function
name and above the description box) and the function arguments - i.e.
the areas with highest contrast. The taglines for imagecopy() and
imagecopymerge() both need disabiguating, and imagecopymerge()'s
tagline is also misleading. By putting a fuller explanation there, I
hope to aid people in selecting the right one.
The changes in the patch file aim to clarify the difference between
the functions. The explanation of $pct for imagecopymerge() is
in-line for further work, as the last sentence (referring to $pct =
100) is currently misleading.
Kind regards,
Peter
--
Maple Design Ltd - Web design and application development
http://www.mapledesign.co.uk
+44 (0)845 123 8008
Reg. in England no. 05920531
Index: en/reference/image/functions/imagecopy.xml
===================================================================
RCS file: /repository/phpdoc/en/reference/image/functions/imagecopy.xml,v
retrieving revision 1.6
diff -u -r1.6 imagecopy.xml
--- en/reference/image/functions/imagecopy.xml 20 Jun 2007 22:24:38 -0000
1.6
+++ en/reference/image/functions/imagecopy.xml 15 Feb 2008 13:13:43 -0000
@@ -3,7 +3,9 @@
<refentry xml:id="function.imagecopy" xmlns="http://docbook.org/ns/docbook";>
<refnamediv>
<refname>imagecopy</refname>
- <refpurpose>Copy part of an image</refpurpose>
+ <refpurpose>Copy part of an image <parameter>src_im</parameter> onto
+ <parameter>dst_im</parameter>. If the images are true color with alpha
+ channels, the alpha transparency will be preserved</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
Index: en/reference/image/functions/imagecopymerge.xml
===================================================================
RCS file: /repository/phpdoc/en/reference/image/functions/imagecopymerge.xml,v
retrieving revision 1.7
diff -u -r1.7 imagecopymerge.xml
--- en/reference/image/functions/imagecopymerge.xml 20 Jun 2007 22:24:38
-0000 1.7
+++ en/reference/image/functions/imagecopymerge.xml 15 Feb 2008 13:11:54
-0000
@@ -3,7 +3,12 @@
<refentry xml:id="function.imagecopymerge"
xmlns="http://docbook.org/ns/docbook";>
<refnamediv>
<refname>imagecopymerge</refname>
- <refpurpose>Copy and merge part of an image</refpurpose>
+ <refpurpose>Copy part of an image <parameter>src_im</parameter> onto
+ <parameter>dst_im</parameter> with an alpha transparency level
+ <parameter>$pct</parameter>. If the source image
+ <parameter>src_im</parameter> contains an alpha channel, it will be ignored
+ and discarded. To use <parameter>src_im</parameter>'s alpha channel, use
+ imagecopy().</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
@@ -103,7 +108,8 @@
<para>
The two images will be merged according to <parameter>pct</parameter>
which can range from 0 to 100. When <parameter>pct</parameter> = 0,
- no action is taken, when 100 this function behaves identically
+ no action is taken (the source image is totally transparent), when 100
+ this function behaves identically
to <function>imagecopy</function> for pallete images, while it
implements alpha transparency for true colour images.
</para>
