DOCS/man: replace legacy option syntax usage

[na-na-hi]

They are replaced by --option=value.

[kasper93]

Why? How --v is better than -v?

[sfan5]

The "Legacy option syntax" section (here) only talks about -option value, not -flag.
While I value consistency I think the single letter flags are an exception and -v -v is much more aesthetically pleasing than --v --v

[na-na-hi]

The "Legacy option syntax" section (here) only talks about -option value, not -flag.

Flag options are normal options which take values in essence: they're equivalent to --flag=yes. In fact most flag options are already documented as --flag=<yes|no>.

Since they are no different from options which take values, this description in the documentation also takes effect on flag options, which says such usage should be avoided:

This is mostly for compatibility with MPlayer. Using these should be avoided. Their semantics can change any time in the future.

[kasper93]

Single letter flags (like -v) should use single dash. We can even make it into documentation or restrict it in the code. I agree longer flags should use --.

I strongly disagree on making --v standard and recommended use.

[Dudemanguy]

Single letter flags are pretty standard across any program. If you find the wording of the legacy option section in the documentation too ambiguous, I would suggest rewording that instead.

[na-na-hi]

Single letter flags (like -v) should use single dash. We can even make it into documentation or restrict it in the code.

MPlayer uses single dash for all options, while mpv prefers double dash. Treating single letter flags differently has no ground in MPlayer/mpv convention and history. Besides, these options already accept double dashes, so restricting it in the code creates backwards incompatibility.

Also what about non flag single-letter options like --o? Should it use single or double dash? Treating them differently only causes confusion.

I strongly disagree on making --v standard and recommended use.

I can make an explicit exception for that and document it. Is this good enough for you?

[kasper93]

MPlayer uses single dash for all options, while mpv prefers double dash. Treating single letter flags differently has no ground in MPlayer/mpv convention and history.

We are not in the void. Single letter flags are common like @Dudemanguy said. --verbose, -v is one of the common way to do it.

so restricting it in the code creates backwards incompatibility.

Of course, we cannot introduce breaking change like that. But we should not recommend that either imho. I would go even further and add depreciation warning about inconsistent use of - and --.

I can make an explicit exception for that and document it. Is this good enough for you?

No need for explicit exception. I think we should make it clear that all single-letter flags should be prefixed with single-dash - and all longer options should be prefixed with double-dash --. Maybe I'm missing some context, but it is obvious to me and frankly I wasn't aware we can do --v up until now.

Either way, I don't mind as long as -v still works.

[na-na-hi]

Reverted the --v change.

I think we should make it clear that all single-letter flags should be prefixed with single-dash - and all longer options should be prefixed with double-dash --.

I don't think such preference is necessary.

Maybe I'm missing some context, but it is obvious to me and frankly I wasn't aware we can do --v up until now.

This has been already used in the documentation, dating back to 2014:

mpv/DOCS/man/input.rst

Line 1649 in 4fe6793

``--v`` option, and is also what is used for ``--msg-level``.

mpv/DOCS/man/options.rst

Line 7291 in 4fe6793

in verbose mode, i.e. ``--v``. In general we can't print errors, because

mpv/DOCS/man/mpv.rst

Line 1444 in 4fe6793

of ``--v`` options passed to the command line.

[N-R-K]

I don't think such preference is necessary.

It's not a preference. It's the de facto standard.

[na-na-hi]

It's the de facto standard.

Doesn't matter. FFmpeg and gcc for example use single dash for long options, which doesn't conform to the "standard". There is no obligation for mpv to use single dash for single-letter options either. In all situations mentioned, the history and convention of individual programs take preference over everything else.

See b85983a for example: this commit from 2014 explicitly changes the --o documentation to use the new double dash syntax, despite being a single letter option. This clearly shows that the double dash syntax is the preferred style for most of the documentation since the beginning of the history of mpv.

[N-R-K]

FFmpeg and gcc for example use single dash for long options, which doesn't conform to the "standard".

I wasn't talking about long options, which don't have any standard (neither POSIX nor de facto). Some programs use double dash some use single.

But short options are very widely supported and expected with a single dash. So far I haven't seen any actual reason to document a syntax that's both unconventional and worse to type.

[...] since the beginning of the history of mpv

Arbitrary choices made in the past without any actual reasoning behind it isn't really a convincing argument.

There's a 1k line document in this repo documenting all the interface changes each release. If "it was done this way before" was a valid argument by itself then you wouldn't be able to change anything at all aside from fixing bugs.

[na-na-hi]

I wasn't talking about long options, which don't have any standard (neither POSIX nor de facto).

The GNU getopt_long is the de facto standard, and most independent commandline parsers for other languages follow the same semantics. getopt_long doesn't require that long options are longer than a single letter; in fact, its documentation explicitly says that programs don't need to support short options at all.

But short options are very widely supported and expected with a single dash.

The reality says otherwise. Lots of GNU coreutils don't implement -h at all: it doesn't even do anything. Instead, they demand you to type --help. So here is your "convention": utilities have no obligation to make the commandline easier to type.

Arbitrary choices made in the past without any actual reasoning behind it isn't really a convincing argument.

So are arbitrary standards. If we strictly follow the POSIX standard and convention, we can't have long options at all.

If "it was done this way before" was a valid argument by itself then you wouldn't be able to change anything at all aside from fixing bugs.

I wanted to make --v the preferred way (which is a change from the current option documentation) but lots of comments rejected the --v change for the same reason.