Skip Menu |
 

This queue is for tickets about the Imager CPAN distribution.

Report information
The Basics
Id: 5608
Status: open
Priority: 40/
Queue: Imager

People
Owner: TONYC [...] cpan.org
Requestors: TONYC [...] cpan.org
Cc:
AdminCc:

Bug Information
Severity: Important
Broken in: (no value)
Fixed in: (no value)



From: Tony Cook <tony [...] develop-help.com>
Date: Wed, 10 Mar 2004 10:54:38 +1100
To: bug-imager [...] rt.cpan.org
Subject: Documentation suggestions
Download (untitled) / with headers
text/plain 2.4k
----- Forwarded message from Dave Rolsky <autarch@urth.org> ----- Date: Tue, 9 Mar 2004 17:10:48 -0600 (CST) From: Dave Rolsky <autarch@urth.org> To: Tony Cook <tony@develop-help.com> cc: mason <mason-users@lists.sourceforge.net> Subject: Re: [Mason] Working with PerlMagick [now way OT] On Wed, 10 Mar 2004, Tony Cook wrote: Show quoted text
> On Tue, Mar 09, 2004 at 11:37:12AM -0600, Dave Rolsky wrote:
> > On Tue, 9 Mar 2004, Randal L. Schwartz wrote: > >
> > > As you can tell, I have a great love/hate relationship with > > > ImageMagick.
> > > > Mine is mostly hate ;) > > > > Argh, what a poorly documented monstrosity. And the API is just awful > > once you figure it out. I'd really like to see Imager replace it, though > > it's docs are terrible too. But at least the API is reasonably sane ;)
> > What do you are the main problems with the Imager documentation?
There's just no list of methods! Look at the SYNOPSIS, which references methods like "scale". But where is scale documented besides the synopsis? Basically, you need to list every method and exported constant/var (like %Imager::formats) and say what they do, what arguments they take, and what they return. A few quick examples is simply not sufficiient. It also needs a lot more high-level "here's how you do task X" type of documentation. Right now it's mostly very low-level, and doesn't make much sense unless you already know what the method you want is named. An Imager::Cookbook would be really helpful. Here's a list of things you could cover (taken from the Image Magick home page ;): Convert an image from one format to another (e.g. TIFF to JPEG) Resize, rotate, sharpen, color reduce, or add special effects to an image Create a montage of image thumbnails Create a transparent image suitable for use on the Web Turn a group of images into a GIF animation sequence Create a composite image by combining several separate images Draw shapes or text on an image Decorate an image with a border or frame Describe the format and characteristics of an image Obviously, Imager may not do all of these things, but I know it does some of those. That'd be a great start for a cookbook, I think. Browsing the rest of the Image Magick docs and example will probably give you more ideas for cookbook topics. -dave /*======================= House Absolute Consulting www.houseabsolute.com =======================*/ Show quoted text
----- End forwarded message -----
Download (untitled) / with headers
text/plain 214b
I'm using http://wiki.imager.perl.org/cgi-bin/wiki.pl?ImagerWiki to slowly build up both a cookbook and a tutorial. If you have any ideas for the tutorial (or the cookbook) please add them to the appropriate page.
Download (untitled) / with headers
text/plain 238b
Some progress is being made with this over time. 0.44 includes a method index. 0.45 will include a concept index and the start of a cookbook, and some sample code. Short examples of use are being added to method descriptions over time.
added a cookbook entry for converting image files.
Download (untitled) / with headers
text/plain 203b
Imager's documentation has improved a lot since I added this, but it's still and ongoing process. What else should there be? - lots more example code inline - more detail on the filters where possible


This service is sponsored and maintained by Best Practical Solutions and runs on Perl.org infrastructure.

Please report any issues with rt.cpan.org to rt-cpan-admin@bestpractical.com.