On Feb 15, 2008, at 9:13 AM, Peter Bowyer wrote:
Hello list,
With Pierre's agreement, I am submitting changes for the
documentation of imagecopy() and imagecopymerge() for inclusion in
the PHP documentation.
Excellent!
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 refpurpose should be much shorter, please instead add the bulk of
information to the description. Current repurpose for these:
imagecopy — Copy part of an image
imagecopymerge — Copy and merge part of an image
It copies, and merges, I think changing/adding a word or two could
help instead of describing the entire use of the function. Maybe use
a word like splice. Imagine if every refpurpose was this verbose,
finding functions from php.net/ref.image would become about
impossible. Also, these functions should have See Also links. So good
thought, as helping users find information is an excellent goal, but
I don't think verbose refpurpose lines is the way to do it.
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.
Sounds good but be sure to watch your whitespace... a tab found its
way in there.
Regards,
Philip
