Re: Improving imagemagick.bug-presubj
(With last-minute amendments for feedback)
Jonathan Nieder wrote:
> [...]
>> When reporting imagemagick errors, please provide the actual
>> input files (images) and options given to the tool
>> (convert, mogrify, identify) at run time.
>>
>> This can mean the difference between a pleasant debugging experience
>> and a heisenbug that becomes unreproducible.
>
> I'd remove the above two paragraphs. They are common sense and
> redundant next to item 6 below.
(Also, "heisenbug" might just confuse people who don't get the joke.)
>> Please notices, that imagemagick depends for converting some file
>> format on various package. These formats includes
>> svg, dots (graphviz), tiff, png, jpeg, wmf.
>
> I'd remove the above paragraph or replace it with a new item in the
> itemized list below.
>
>> Debugging imagemagick could be difficult and it is really helpful to
>> follow the following steps:
>
> Nice. s/could/can/; s/it is really helpful to follow/you can help
> by following/.
This now becomes the first sentence, and works well enough except for
the repetition of "follow"...
Debugging imagemagick can be difficult, so you can help by sticking
to the following procedure:
Or maybe:
Debugging imagemagick can be difficult, so you can help by following
the steps listed below.
>> 1. verify that you have installed imagemagick and not graphickmagick-compat:
>> - run under a terminal: convert 2>&1 | grep -i GraphicsMagick
>> - if you see graphicmagick on the output,
>> please reportbug to graphickmagick
>
> s/under a terminal/in a terminal/
> s/graphicmagick/graphicsmagick/
> s/graphickmagick/graphicsmagick/
>
> The indentation in the line about the graphicsmagick is strange --- it
> would be easier to read formatted like this:
>
> - if you see graphicsmagick in the output, please report against
> the graphicsmagick package.
>
> Aside from that, sounds good.
It was rather a stunted list when there were two bulletpoints; a list
with only one is getting ridiculous.
Also, why the "2>&1" when using -version would send it to STDOUT? Why
grep when you know it's in the first line? Oh, and hang on, it isn't
"graphicksmagick-compat"; it's the even more unwieldy
"graphicsmagick-imagemagick-compat"! So:
1. Verify that you have installed imagemagick and not the graphicksmagick
compatibility package by running "convert -version" in a terminal. If
you see "GraphicsMagick" in the first line of output, please make your
report against the graphicsmagick package.
>> 2. install the imagemagick-dbg,libjpeg8-dbg,libwmf-bin,librsvg2-dbg,librsvg2-bin and
>> inkscape package.
>
> This list is likely to go out of date quickly. Is there some page
> in the Debian wiki about how to find -dbg packages corresponding to
> a particular executable?
Meanwhile just fixing the English (and sorting the list) I'd suggest:
2. Install the packages imagemagick-dbg, inkscape, libjpeg8-dbg,
librsvg2-dbg, librsvg2-bin, and libwmf-bin.
(I'm surprised to see just how much gconf/avahi nonsense Inkscape
pulls in, considering it's not explicitly a GNOME app...)
Oops, I'm out of date. Revised version for review:
| 2 install the imagemagick-dbg, as root run:
| apt-get install --install-suggest imagemagick-dbg
It's "--install-suggests", and no need for any more than:
2. As root, run "apt-get install --install-suggests imagemagick-dbg".
(Mind you, this installs none of the other packages you mention...)
>> 3. Instead of running convert, mogrify, display or identify run
>> convert.im6, mogrify.im6, display.im6 or identify.im6 directly.
>
> Good idea. Missing comma before "run".
And if we're following d-l-e house style, there are also missing
"serial commas" before the conjunctions! I might as well sort them
into alphabetical order while I'm at it.
3. Instead of running convert, display, identify, or mogrify, run
convert.im6, display.im6, identify.im6, or mogrify.im6 directly.
>> 4. if imagemagick coredump, could you please send a backtrace. See
>> http://wiki.debian.org/HowToGetABacktrace to get it.
>
> s/coredump/dumps core/
> s/could you please send/please attach/
Or just:
4. If imagemagick dumps core, please attach a backtrace - see
"http://wiki.debian.org/HowToGetABacktrace";.
>> 5. if the input format is svg, run the following program:
>> - rsvg-convert yourinput.svg > outrsvg.png
>> - inkscape yourinput.svg --export-png=outputinkscape.png
>> - join to your bug report outrsvg.png and outputinkscape.png
The format name is "SVG".
Again, prepending dashes to verbatim command lines is a bad idea.
Why give the output files inconsistent names?
> s/join/attach/
In fact I'd say "include", to emphasise that this is as well as the
files you're told to attach in the following step.
5. If the input format is SVG, run the commands
"rsvg-convert yourinput.svg > rsvg.png" and
"inkscape yourinput.svg --export-png=inkscape.png", and include
the output files in your bug report.
>> 6. Document the exact command line used, and join the input files.
>
> s/join/attach/
Should this perhaps be step 1, to make sure they document the original
command line and not one of the ones you've asked them to perform?
This would make it:
Debugging imagemagick can be difficult, so you can help by following
the steps listed below.
1. Document the exact command line used, and attach the input files.
2. Verify that you have installed imagemagick and not the graphicksmagick
compatibility package by running "convert -version" in a terminal. If
you see "GraphicsMagick" in the first line of output, please make your
report against the graphicsmagick package.
3. As root, run "apt-get install --install-suggests imagemagick-dbg".
4. Instead of running convert, display, identify, or mogrify, run
convert.im6, display.im6, identify.im6, or mogrify.im6 directly.
5. If imagemagick dumps core, please attach a backtrace - see
"http://wiki.debian.org/HowToGetABacktrace";.
6. If the input format is SVG, run the commands
"rsvg-convert yourinput.svg > rsvg.png" and
"inkscape yourinput.svg --export-png=inkscape.png", and include
the output files in your bug report.
--
JBR with qualifications in linguistics, experience as a Debian
sysadmin, and probably no clue about this particular package
Reply to: