[FFmpeg-trac] #7740(documentation:reopened): Missing '-'prefix in documentation of ffmpeg options

[FFmpeg]

#7740: Missing '-'prefix in documentation of ffmpeg options
-------------------------------------+-------------------------------------
             Reporter:  Ulf Zibis    |                    Owner:  (none)
                 Type:  enhancement  |                   Status:  reopened
             Priority:  wish         |                Component:
                                     |  documentation
              Version:  unspecified  |               Resolution:
             Keywords:               |               Blocked By:
             Blocking:               |  Reproduced by developer:  0
Analyzed by developer:  0            |
-------------------------------------+-------------------------------------
Comment (by Stefano Sabatini):

 Replying to [comment:10 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 with'''out''' 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).
-- 
Ticket URL: <https://trac.ffmpeg.org/ticket/7740#comment:13>
FFmpeg <https://ffmpeg.org>
FFmpeg issue tracker