Opened 3 years ago

Last modified 5 weeks ago

#7740 reopened enhancement

Missing '-'prefix in documentation of ffmpeg options

Reported by: Ulf Zibis Owned by:
Priority: wish Component: documentation
Version: unspecified Keywords:
Cc: Blocked By:
Blocking: Reproduced by developer: no
Analyzed by developer: no

Description

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 '-')".

Change History (13)

comment:1 by Carl Eugen Hoyos, 3 years ago

Resolution: invalid
Status: newclosed

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.

comment:2 by llogan, 3 years ago

Priority: normalwish
Resolution: invalid
Status: closedreopened
Type: defectenhancement

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.

comment:3 by Ulf Zibis, 15 months ago

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.

comment:4 by Nicolas George, 15 months ago

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.

comment:5 by Ulf Zibis, 15 months ago

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.

comment:6 by Nicolas George, 15 months ago

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

comment:7 by Ulf Zibis, 15 months ago

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

comment:8 by Stefano Sabatini, 8 weeks ago

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.

comment:9 by Ulf Zibis, 7 weeks ago

Summary: Missing '-'prefix on ffmpeg optionsMissing '-'prefix in documentation of ffmpeg options

comment:10 by Ulf Zibis, 7 weeks ago

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 -

Last edited 7 weeks ago by Ulf Zibis (previous) (diff)

comment:11 by Michael Koch, 7 weeks ago

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

comment:12 by Gyan, 7 weeks ago

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.

in reply to:  10 comment:13 by Stefano Sabatini, 5 weeks ago

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).

Note: See TracTickets for help on using tickets.