[FFmpeg-trac] #2332(documentation:reopened): Better documenting of boolean options

[FFmpeg]

#2332: Better documenting of boolean options
-------------------------------------+-------------------------------------
             Reporter:  burek        |                    Owner:
                 Type:  enhancement  |                   Status:  reopened
             Priority:  wish         |                Component:
              Version:  unspecified  |  documentation
             Keywords:               |               Resolution:
             Blocking:               |               Blocked By:
Analyzed by developer:  0            |  Reproduced by developer:  0
-------------------------------------+-------------------------------------
Changes (by saste):

 * status:  closed => reopened
 * resolution:  invalid =>


Comment:

 Replying to [ticket:2332 burek]:
 > The online documentation http://www.ffmpeg.org/ffmpeg.html has
 description for "boolean options" which says:
 >  ''Options which do not take arguments are boolean options, and set the
 corresponding value to true. They can be set to false by prefixing with
 "no" the option name, for example using "-nofoo" in the command line will
 set to false the boolean option with name "foo".''
 > Now, the only problem is that all the boolean options in the
 documentation are not clearly marked as boolean, so the only way to
 conclude which options will support the "-nofoo" pattern is to see which
 options do not take any arguments. But that is also not enough since there
 are a lot of options which don't take any arguments, but are not boolean,
 like -formats, -codecs, -vn, etc.
 >
 > The suggestion is to do one of either 2 things:
 >
 > 1) clearly mark each boolean option as '''boolean''' like:
 >  '''‘-stats (global, boolean)’'''
 >  Print encoding progress/statistics. On by default.
 >
 > 2) couple each boolean option with its "-nofoo" couple, like:
 >  '''‘-stats, -nostats (global)’'''
 >  Print encoding progress/statistics. On by default.
 >
 > This will help users who get to the docs page and use CTRL+F to just
 find the option they are interested in, without reading the documentation
 page like a book, from the beginning to the end (hence, they usually skip
 the intro part that explains the "-nofoo" logic).

 Most boolean options are off by default, so it is clear that selecting
 -foo will enable it. For the few options which are on by default, we may
 mention that -nofoo will disable the options, like it is done for example
 with -stdin. This seems easier, requires less doc churnup and addresses
 the problem for a lazy user grepping for -nostats.

-- 
Ticket URL: <https://ffmpeg.org/trac/ffmpeg/ticket/2332#comment:2>
FFmpeg <http://ffmpeg.org>
FFmpeg issue tracker