What is the correct index position of the Convert command's options of GraphicsMagick

Question

I am confused about the covert command of GraphicsMagick.

According to the documentation (http://www.graphicsmagick.org/convert.html), the synopsis of convert command is:

convert [ options ... ] input_file output_file 

According to the above synopsis, I can execute the convert command in the following way:

Example 1:

gm convert -strip -scale x400 inputFile.jpg outputFile.jpg

The above command is executed successfully. Now, I ran the the same command with different index position of the options.

Example 2:

gm convert inputFile.jpg -strip -scale x400 outputFile.jpg

The above example executed successfully. The above example's index position of the options are different, does not match against the synopsis.

My question is, which example is correct?

Answer 1

I fear the answer is partly philosophical, partly folklore, partly opinion and partly flexibility of GraphicsMagick and partly rigidity of manpages. Let me explain...

To understand the answer, you need to differentiate between settings and operators. @KurtPfeifle did a great job here which, for the sake of completeness, I will summarise as follows:

• Some parameters are settings - they set and retain their value till the end of the command or till changed. For example, -size sets the size of all canvases created after it is set on the commandline. Until the point it is first set, the default canvas size is 1x1, after it is set it remains till the end of the command.

• Some parameters are operators - they generally perform some image processing, such as thresholding or converting to greyscale. These ones operate on all images currently in the image list.

Maybe an example will help. First, we use the -size setting:

gm convert -background none xc:red -size 5x5 xc:lime xc:blue -size 10x10 xc:magenta +append setting.png

Initially, the default size was 1x1, so the red canvas comes out at 1x1. Then I changed the setting and it remained at 5x5 for the lime and blue canvases till I changed it to 10x10 for the magenta one. Those were settings and they set things up for the images yet to come.

Now, I do a similar thing with the -colorspace operator:

gm convert xc:red xc:lime xc:blue -colorspace gray +append operator.png

And you see that the -colorspace operator has changed all the images that were already in the image list, i.e. they process images that have previously been added to the list.

If you like, you could simplify things and say "settings apply to all that is to come, and operators apply to all that has gone". Although I am sure there are counter-examples.

The order of the commandline options was rationalised a few years back and GraphicsMagick permits some flexibility to retain some backward compatibility. That is probably the best explanation of your actual question.

So, in general, you should declare settings as soon as posssible on the commandline and apply operators at the point that makes most sense depending on what images are currently in your list.

Another reason is that it would be very cumbersome, to the point of unintelligibility, if all the GraphicsMagick combinations and permutations were put in a conventional manpage. Can you imagine:

gm convert [[[operators|settings]|[settings|operators]] image] [[settings|operators]|[operators]] ...