Overhaul and simplify program usage and documentation in README

- Use version from configure script
- Simplify usage text for accessibility, only one command at a time
- Simplify terminology, we have commands and options to commands

Signed-off-by: Joachim Nilsson <troglobit@gmail.com>

README.md

@@ -27,8 +27,8 @@ Introduction
 * Possibility to set a minimum brightness value
 
 Let's get started with a few examples, for details, see below for the
-full description of the different operating modes, value conversion and
-how to operate different controllers.
+full description of the different commands, options and how to access
+different controllers.
 
 
 Examples
@@ -77,85 +77,61 @@ Verify by reading back the max brightness, you should get a value of 1:
 Usage
 -----
 
-Light has 5 different criteria on flags to use: operation modes, value
-mode, target, field and controller mode.  Flags from these different
-modes can never be used in conjunction, i.e. you cannot get and set a
-value at the same time, that requires different invocations.
+### Commands
 
-**Note:** like most UNIX applications, light only print errors if you
-  are using it incorrectly. If something goes wrong, and you can't
-  figure out why, try setting the verbosity flag with -v:
+* `-G`: Get (read) brightness/data from controllers/files
+* `-S VAL`: Set (write)brightness/data to controllers/files
+* `-A VAL`: Like `-S`, but adds the given value
+* `-U VAL`: Like `-S`, but subtracts the given value
+* `-O`: Save the current brightness for later use (usually used on shutdown)
+* `-I`: Restore the previously saved brightness (usually used on boot)
+* `-L`: List available controllers, see below `-k` option as well
+
+Without any options (below) the commands operate on the brightness of an
+automatically selected controller.  Values are given in percent, unless
+the below `r` option is also given.
+
+**Note:** like most UNIX applications, light only gives output on
+  errors.  If something goes wrong try the verbosity option `-v VAL`:
 
 * 0: No debug output
 * 1: Errors
 * 2: Errors, warnings
 * 3: Errors, warnings, notices
 
+### Options
 
-### Operation modes
-
-The operation modes describe **what** you want to do.
-
-* -G: Which **reads/gets** brightness/data from controllers/files
-* -S: Which **writes/sets** brightness/data to controllers/files
-* -A: Which does like -S but instead **adds** the value
-* -U: Which does like -S but instead '**subtracts** the value
-* -O: Save the current brightness for later use (usually used on shutdown)
-* -I: Restore the previously saved brightness (usually used on boot)
-* -L: List the available controllers
-
-When used by themselves operate on the brightness of a controller that
-is selected automatically. S, A and U needs another argument -- except
-for the main 4 criteria -- which is the value to set/add/subtract.  This
-can be specified either in percent or in raw values, but remember to
-specify the value mode (read below) if you want to write raw values.
-
-
-### Value modes
-
-The value mode specify in what unit you want to read or write values
-in. The default one (if not specified) is in percent, the other one is
-raw mode and should always be used when you need very precise values (or
-only have a controller with a very small amount of brightness levels).
-
-* -p: Percent
-* -r: Raw mode
-
-Remember, this is the unit that will be used when you set, get, add or
-subtract brightness values.
-
-
-### Target
-
-You can choose which target to act on:
-
-* -l: Act on screen backlight
-* -k: Act on keyboard backlight and LEDs
-
+Values may be given, or presented, in percent or raw mode.  Raw mode is
+the format specific to the controller.  The default is in percent, but
+raw mode may be required for precise control, or when the steps are very
+few, e.g. for most keyboard backlight controllers.
 
-### Field
+* `-p`: Percent, default
+* `-r`: Raw mode
 
-As you can not only handle the **brightness** of controllers, you may
-also specify a field to read/write from/to:
+By default the screen is the active target for all commands, use `-k` to
+select the keyboard instead.  In either case you may need to select a
+different controller, see below.
 
-* -b: Current brightness of selected controller
-* -m: Maximum brightness of selected controller
-* -c: Minimum brightness (cap) of selected controller
+* `-l`: Act on screen backlight, default
+* `-k`: Act on keyboard backlight and LEDs
 
-The minimum brightness is a feature implemented as some controllers make
-the screen go pitch black at 0%, if you have a controller like that, it
-is recommended to set this value (in percent or raw mode).  These values
-are saved in raw mode though, so if you specify it in percent it might
-not be too accurate depending on your controller.
+By default commands act on the brightness property, which is read+write.
+The maximum brightness is a read-only property.  The minimum brightness
+cap is a feature implemented to protect against setting brightness too
+low, since some controllers make the screen go pitch black at 0%.  For
+controllers like that it is recommended to set this value.
 
+* `-b`: Current brightness of selected controller, default
+* `-m`: Max. brightness of selected controller
+* `-c`: Min. brightness (cap) of selected controller (recommend raw mode)
 
-### Controller modes
+Controller is automatically done to select the controller with maximum
+precision.  It can however also be done manually and we recommend the
+`-L` and `-Lk` commands to list available controllers:
 
-Finally, you can either use the built-in controller selection to get the
-controller with the maximum precision, or you can specify one manually
-with the -s flag. The -a flag will force automatic mode and is
-default. Use -L to get a list of controllers to use with the -s flag (to
-specify which controller to use).
+* `-a`: Automatic controller selection
+* `-s ARG`: Manual controller selection
 
 **Note:** Without the `-s` flag on _every_ command light will default
   to automatic controller selection.

src/light.c

@@ -239,48 +239,45 @@ LIGHT_BOOL light_parseArguments(int argc, char** argv)
 }
 
 void light_printVersion(){
-  printf("Light %u.%u (%s)\n", LIGHT_VER_MAJOR, LIGHT_VER_MINOR, LIGHT_VER_TYPE);
-  printf("Copyright (C) %u %s\n", LIGHT_YEAR, LIGHT_AUTHOR);
-  printf("This is free software, see the source for copying conditions.  There is NO\n");
-  printf("warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE\n\n");
+  printf("v%s\n", VERSION);
 }
 
 void light_printHelp(){
-  printf("Usage: light <options> <value>\n");
-  printf("<value> has to be either integral(raw mode) or decimal(percent mode) depending on the specified value mode.\n");
-  printf("<options> can be any of the following:\n\n");
-
-  printf("Operations (can not be used in conjunction):\n");
-  printf("  -H -h:\tPrints this help and exits\n");
-  printf("  -V:\t\tPrints version info and exits\n");
-  printf("  -G:\t\tGet value (default)\n");
-  printf("  -S:\t\tSet value\n");
-  printf("  -A:\t\tAdd value\n");
-  printf("  -U:\t\tSubtract value\n");
-  printf("  -L:\t\tList controllers\n");
-  printf("  -I:\t\tRestore brightness\n");
-  printf("  -O:\t\tSave brightness\n\n");
-
-  printf("Targets (can not be used in conjunction):\n");
-  printf("  -l:\t\tAct on screen backlight (default)\n");
-  printf("  -k:\t\tAct on keyboard backlight\n\n");
-
-  printf("Fields (can not be used in conjunction):\n");
-  printf("  -b:\t\tBrightness (default)\n  \t\tUsed with [GSAU]\n\n");
-  printf("  -m:\t\tMaximum brightness\n  \t\tUsed with [G]\n\n");
-  printf("  -c:\t\tMinimum cap\n  \t\tUsed with [GS]\n");
-  printf("  \t\tG returns null if no minimum cap is set.\n\n");
-
-  printf("Controller selection (can not be used in conjunction):\n");
-  printf("  -a:\t\tSelects controller automatically (default).\n");
-  printf("  -s:\t\tSpecify controller to use. (needs argument)\n\n");
-
-  printf("Value modes (can not be used in conjunction):\n");
-  printf("  -p:\t\tInterpret <value> as, and output values in, percent. (default)\n");
-  printf("  -r:\t\tInterpret <value> as, and output values in, raw mode.\n\n");
-
-  printf("Other:\n");
-  printf("  -v:\t\tSets the verbosity level, (needs argument).\n  \t\t0: Only outputs read values.\n  \t\t1: Read values, Errors.\n  \t\t2: Read values, Errors, Warnings.\n  \t\t3: Read values, Errors, Warnings, Notices.\n\n");
+	printf("Usage:\n"
+	       "  light [OPTIONS] <COMMAND> [VALUE]\n"
+	       "\n"
+	       "Commands:\n"
+	       "  -A VAL  Add value\n"
+	       "  -G      Get (read) value, default command\n"
+	       "  -H, -h  Show this help and exit\n"
+	       "  -I      Restore brightness\n"
+	       "  -L      List available controllers\n"
+	       "  -O      Save brightness\n"
+	       "  -S VAL  Set (write) value\n"
+	       "  -U VAL  Subtract value\n"
+	       "  -V      Show program version and exit\n"
+	       "\n"
+	       "Options:\n"
+	       "  -a      Automatic controller selection, default\n"
+	       "  -b      Brightness, default\n"
+	       "  -c      Act on minimum cap, only possible to read and set\n"
+	       "  -k      Act on keyboard backlight\n"
+	       "  -l      Act on screen backlight, default\n"
+	       "  -m      Maximum brightness, only possible to read\n"
+	       "  -p      Interpret input, and output, values in percent, default\n"
+	       "  -r      Interpret input, and outpot, values in raw mode\n"
+	       "  -s ARG  Specify controller to use, use -L and -Lk to list available\n"
+	       "  -v ARG  Verbosity level:\n"
+	       "            0: Values only, default\n"
+	       "            1: Values, Errors.\n"
+	       "            2: Values, Errors, Warnings.\n"
+	       "            3: Values, Errors, Warnings, Notices.\n"
+	       "\n");
+
+	printf("Copyright (C) %s  %s\n", LIGHT_YEAR, LIGHT_AUTHOR);
+	printf("This is free software, see the source for copying conditions.  There is NO\n"
+	       "warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE\n"
+	       "\n");
 }
 
 LIGHT_BOOL light_initialize(int argc, char** argv)

src/light.h

@@ -1,25 +1,22 @@
-#ifndef LIGHT_H
-#define LIGHT_H
+#ifndef LIGHT_H_
+#define LIGHT_H_
 
+#include "config.h"
 #include "helpers.h"
 
 #include <sys/types.h>
 #include <dirent.h>
 #include <linux/limits.h>
 
-#define LIGHT_VER_MAJOR 0
-#define LIGHT_VER_MINOR 10
-#define LIGHT_VER_TYPE "beta"
-#define LIGHT_YEAR 2014
+#define LIGHT_YEAR   "2012-2018"
 #define LIGHT_AUTHOR "Fredrik Haikarainen"
 
-#define ASSERT_SET(t,v) \
-  if(v)\
-  {\
-    fprintf(stderr, t" arguments can not be used in conjunction.\n");\
-    return FALSE;\
-  }\
-  v = TRUE;
+#define ASSERT_SET(t,v)							\
+	if (v) {							\
+		fprintf(stderr, t" arguments cannot be used in conjunction.\n"); \
+		return FALSE;						\
+	}								\
+	v = TRUE;
 
 #define ASSERT_OPSET() ASSERT_SET("Operation", opSet)
 #define ASSERT_TARGETSET() ASSERT_SET("Target", targetSet)
@@ -138,4 +135,4 @@ LIGHT_BOOL light_saveBrightness(char const *controller, unsigned long v);
 
 LIGHT_BOOL light_restoreBrightness(char const *controller);
 
-#endif /* LIGHT_H */
+#endif /* LIGHT_H_ */