Missing '-'prefix in documentation of ffmpeg options

[Ulf Zibis]

Summary of the bug:
Given a ffmpeg command line from somewhere.
If one wants to find the documentation of a given option he may search on the web site with "-option". To succeed this search, it would be helpful to list the options with a '-' prefixed. Also if studying the documentation, it would be helpful as saving the '-' in the list of options is very uncommon with Linux documentation on commands.
The statement "by specifying -option value" is quite difficult to find on such huge web pages and presupposes some avoidable thinking on what it may mean.
So _at least_ please add "(prefix the listed options with '-')".

[Carl Eugen Hoyos]

I don’t think this is a valid ticket but feel free to send a patch - made with git format-patch - to the development mailing list if you know what you want to change.

[llogan]

It is inconsistent in the manual. Sometimes the - prefix is there and sometimes it isn't. We should make it consistent and add it where it is missing.

[Ulf Zibis]

According the mentioned consistency variants I would vote for adding - where it is missing, to serve the browsers find facility, using "-option_name". Otherwise all occurrences of "option_name" (which can be a very common word) are found.

[Cigaes]

This is a valid argument. On the other hand, the dash is not part of the option name, it is only an artifact of the command-line tools. An application based on FFmpeg's libraries will have the options without the dashes.

[Ulf Zibis]

Yes, but most users use the command line tool and most given exsamles refer to it.
Library users could be hinted by a general explaining advice.

[Cigaes]

The reference documentation is not for “most users”, it needs to be correct.

[Ulf Zibis]

But for real correctness, the given examples then should be reformatted to C syntax.

[Stefano Sabatini]

After checking this, I confirm there is ambiguity in how the options are formatted. While it is correct to use - in ffmpeg tools documentation as it is already done, for libraries/components we should stick to the same convention, and I agree with Nicolas that being this documentation generic we should use the form without the -.

I think it still makes sense to use some ffmpeg commandline to show usage of the tools, even if this does not completely stick with the scope of the specific manual (libavcodec, muxers, demuxers etc.) because this is useful to test the usage of the option.

[Ulf Zibis]

Stefano, I do not really understand your statement. You say:

we should stick to the same convention

(which I understand as "with the -")

And then you say:

we should use the form without the -

[Michael Koch]

In my opinion it's better to list all options with "-" prefix, because without the prefix there might be too many results when you search for an option in ffmpeg-all.html

Michael

[Gyan]

The command line tool is used by a lot more folks of varying savvy than C API but more importantly, the dash prefix aids search, as Michael mentioned. Alternatively, we can have a separate TOC page with only lists of linked option names - we'll need to add anchors for this.

[Stefano Sabatini]

Replying to Ulf Zibis:

Stefano, I do not really understand your statement. You say:

we should stick to the same convention

(which I understand as "with the -")

And then you say:

we should use the form without the -

If you see the codec options manual, the doc sometimes uses the -foo format, in other cases it uses the foo format (e.g.: ffmpeg-codecs.1), in some cases, both formats are shown (e.g. b (-b)), probably to aid search.

An argument in favor of the foo format is that while the -foo option helps with ffmpeg tools, in general you don't know how the options are parsed, for example many applications just pass the options to other tools as configuration (e.g. foo=1,bar=2), therefore using the -foo in the *reference* might be confusing. Also in general you can use some slightly more advanced search expression (e.g. \<b\> which works with man pages).

For sure we should stick to the same format for all options to avoid confusion and aid new entries addition.

Possible choices:

1. we only use foo (simpler and less confusing since it doesn't assume a parsing format), slightly harder but not impossible to search
2. we only use -foo, simpler search but confusing in case you use the options in a consuming tool
3. we mention both formats, this is more verbose but might address both use cases

Also in many cases we reference an fftool command, which is IMHO fine although technically out of scope in a reference because it enables the reader to try an option/param effect with minimum effort without having to write/compile/debug custom code using the API (the main side-effect being that in case we change the command syntax it would be very hard to spot that the command is no more valid, but in practice this doesn't happen very often).