Consistent order of options and operation

[herrkami]

According to the man page, the order of options, operation, and value is

brightnessctl [options] [operation] [value...]

Contrary to this, brightnessctl s 10%- -e 4 -n 100 works on my setup while brightnessctl -e 4 -n 100 s +10% does not. brightnessctl -e 4 -n 100 s 10% neither works.

Therefore, either the man page seems to be misleading or wrong, or the arguments are not being parsed correctly. (Unless the bug is in my head of course.)

Be it as it may, it would be great if the man page also included some examples with options. So far, we only have six examples that illustrate how values are being parsed and formatted.

Im using version 0.5.1-3.

[TheTrueWhiteOwl]

If you want to pass values into those options the man page makes it quite clear that they must be in the form --min-value=100 or --exponent=4. Are you sure the example you said works is actually working as intended?

When I run this: brightnessctl s 10%- -e 4 -n 100 the 100 is ignored and the -n is interpreted simply as the default value, i.e. --min-value=1

What you seem to want (or at least what I want) is to allow options to be passed in with the syntax you mistakenly used.

[herrkami]

Hey @TheTrueWhiteOwl, thanks for your reply and sorry for the delay.

If you want to pass values into those options the man page makes it quite clear that they must be in the form --min-value=100 or --exponent=4

Assuming I am using the correct version, then neither of this is stated clearly. I find parts of it confusing and even wrong in some cases. Let me try to explain it more explicitly:

1. s, set VALUE means that VALUE can follow either s or set. Both will execute the same set-operation. This is fine and in line with how ,-separations are usually used in man pages.
   However, if I understand you correctly, then -n and -e are actually not the same as -min-value=VALUE and --exponent=K. The first act like boolean switches while the latter allow for setting the respective parameters. If this is the case, it needs to be stated explicitly imo.
2. Same context: According to the man page, -n allows for [setting the] minimum brightness when using delta values. According to your reply, however, -n does actually not allow for setting the minimum brightness. Instead, it allows for turning on minimum brightness limiting (to 1) for delta updates.
3. If option values generally need to be parsed in the format --OPTION=OPTION_VALUE, then what's -d and -c?
4. None of the six man page examples illustrates how the available options are to be used. Perhaps, it would be cool to add one at least.

BRIGHTNESSCTL(1)        brightnessctl       BRIGHTNESSCTL(1)

NAME
       brightnessctl - read and control device brightness

SYNOPSIS
       brightnessctl [options] [operation] [value...]

OPTIONS
       -h, --help
           Print this help.

       -l, --list
           List devices with available brightness controls.

       -q, --quiet
           Suppress output.

       -p, --pretend
           Do not perform write operations.

       -m, --machine-readable
           Produce machine-readable output.

       -n, --min-value=VALUE
           Set  minimum  brightness when using delta values,
           defaults to 1.

       -e, --exponent=K
           Changes percentage scaling curve  to  exponential
           (linear by default). Default exponent is 4.

           Percentage  equation:  %  = [VALUE]^[K] * [MAX] *
           100^-[K].

           The exponential curve may  make  the  adjustments
           perceptually equal.

       -s, --save
           Save state in a temporary file.

       -r, --restore
           Restore previously-saved state.

       -d, --device=DEVICE
           Specify device name (can be a wildcard).

       -c, --class=CLASS
           Specify device class.

       -v, --version
           Print version and exit.

OPERATIONS
       i, info
           Get device info.

       g, get
           Get the current brightness of the device.

       m, max
           Get the maximum brightness of the device.

       s, set VALUE
           Set the brightness of the device.

   VALUES
       You may specify VALUE for the set command in absolute
       or  relative form, and as a value or a delta from the
       current value. For example:

       brightnessctl set 500
           Sets brightness to 500.

       brightnessctl set 50%
           Sets brightness to 50% of the maximum.

       brightnessctl set 50-
           Subtracts 50 from the current brightness.

       brightnessctl set +10
           Adds 10 to the current brightness.

       brightnessctl set 50%-
           Subtracts 50% of the  maximum  from  the  current
           brightness.

       brightnessctl set +10%
           Adds  10%  of  the maximum to the current bright‐
           ness.

AUTHORS
       Maintained by Mykyta Holubakha, who  is  assisted  by
       other  open source contributors. For more information
       about brightnessctl development, visit:

       https://github.com/Hummer12007/brightnessctl

brightnessctl           24th Jan 2018       BRIGHTNESSCTL(1)