Typos in the command line option page for V 6

[ronsavage]

I'm referring to this page: http://imagemagick.org/script/command-line-options.php:

Several items have a '}}' rather than a '}' at the end, or perhaps are missing a '{' somewhere:

-brightness-contrast brightness{xcontrast}{%}}

-contrast-stretch black-point{xwhite-point}{%}}

-linear-stretch black-point{xwhite-point}{%}}

-mean-shift widthxheight{+distance{%}}

[fmw42]

The extra braces are for optional arguments.

But I would agree that they are unbalanced as

Code: Select all

-contrast-stretch black-point{xwhite-point}{%}}

should most likely be

Code: Select all

-contrast-stretch black-point{xwhite-point}{%}

but could be

Code: Select all

-contrast-stretch black-point{{xwhite-point{%}}

But I would leave the decision to remove or add a brace to the IM developers.

[ronsavage]

OK.

When you say 'optional arguments', what's the difference between using [xyz] and {xyz}?

[fmw42]

The braces are not used. They are there in the documentation just to show what arguments are optional.

For example:

Code: Select all

-contrast-stretch black-point

-contrast-stretch black-pointxwhite-point

-contrast-stretch black-pointxwhite-point%

-contrast-stretch black-pointxwhite-point%

-contrast-stretch black-point%xwhite-point%

IM will use both as percent even if it see only one percent.

The "x" separates the two arguments. Often it can be replace with ","

[fmw42]

Parentheses are (...)
Brackets are [...]
Braces are {...}

It seems that the documentation is inconsistent in the use of brackets and braces to both mean optional arguments. I am not sure when the braces were intruduced. It used to be always brackets.

[ronsavage]

Ahhh. I got auto-logged-off, and lost my long reply. Not happy.

Thanx for the clarification. I agree it's inconsistent, and I'd say regrettable.

And I do understand '[]' and '{}' do not actually appear on the command line.

The reason I'm studying this page is that I'm writing a Perl module which parses IM command lines.

Although this might seem pointless, it's to build a data structure that other Perl modules, e.g. Imager, can use to provide some support, however limited, for users who prototype using 'convert'. More here: https://rt.cpan.org/Ticket/Display.html?id=91883.

So, I've written code which parses that doc page, and outputs the corresponding BNF for use by Marpa::R2. It's not finished of course. Will it work? I hope so.

[fmw42]

I believe that the documentation will be fixed on this issue. The IM developer will do that or he can direct me to do it.

[ronsavage]

Great news!

[ronsavage]

Also, probably a good time to unify 'index(s)' and 'indexes'.

[ronsavage]

Also, I think {+-} generally means we must make a mandatory choice of either '+' or '-', whereas with a case like '-bias value{%}' (and if not that option, then elsewhere), the intention is that '%' is optional.

[ronsavage]

And, for '-rotate degrees{<}{>}', should that read [<>], meaning choose only one, or neither?

[ronsavage]

And likewise for '-delay ticksxticks-per-second {<} {>}'?

[snibgo]

IM's language has gradually evolved over the years, and isn't easily defined in BNF. (But good luck with it!) Some aspects are rather vague, and IM will accept syntax that it shouldn't.

With "-rotate", IM v6 currently accepts < or > or both (in either order) or neither. Using both is somewhat pointless and seems to give the expected result: the image is never rotated.

[ronsavage]

That's good to know, even if it increases my confusion level .

I do have a number of other observations, which I'll relate shortly.

[fmw42]

Also, I think {+-} generally means we must make a mandatory choice of either '+' or '-', whereas with a case like '-bias value{%}' (and if not that option, then elsewhere), the intention is that '%' is optional.

That is correct as far as I know.