Opened 5 years ago

Closed 5 years ago

#2332 closed enhancement (fixed)

Better documenting of boolean options

Reported by: burek Owned by:
Priority: wish Component: documentation
Version: unspecified Keywords:
Cc: Blocked By:
Blocking: Reproduced by developer: yes
Analyzed by developer: yes

Description

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

Change History (4)

comment:1 follow-up: Changed 5 years ago by cehoyos

  • Resolution set to invalid
  • Status changed from new to closed

Please send patches to ffmpeg-devel, they usually typically more attention there.

comment:2 in reply to: ↑ description ; follow-up: Changed 5 years ago by saste

  • Resolution invalid deleted
  • Status changed from closed to reopened

Replying to 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.

comment:3 in reply to: ↑ 1 Changed 5 years ago by michael

Replying to cehoyos:

Please send patches to ffmpeg-devel, they usually typically more attention there.

Theres no patch here so nothing that could have been sent to ffmpeg-devel

comment:4 in reply to: ↑ 2 Changed 5 years ago by saste

  • Analyzed by developer set
  • Reproduced by developer set
  • Resolution set to fixed
  • Status changed from reopened to closed

Replying to saste:

Replying to burek:

[...]

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.

Partially fixed in:

commit f185a040b0d5f6766c8016cc84b415d414d38246
Author: Stefano Sabatini <stefasab@gmail.com>
Date:   Sun Mar 10 11:51:00 2013 +0100

    doc/ffplay,ffmpeg: mention the corresponding negated option for -stats
    
    This helps lazy users who didn't read the part about boolean options, in
    case they grep for "-nostats".
    
    -stdin and -stats are the only booleans option enabled by default. This
    is a partial fix for Trac ticket #2332, a complete overhaul of boolean
    options documentation is probably overkill.
Note: See TracTickets for help on using tickets.