Add various documentation updates: DESIGN and HACKING document, and various small comments int the source (Christian Jaeger).

Update man page with information on configuration file.

1 files changed, 73 insertions, 14 deletions

diff --git a/redshift.1 b/redshift.1
index 13c4452..85b245c 100644
--- a/redshift.1
+++ b/redshift.1
@@ -1,20 +1,26 @@
-.TH REDSHIFT: "1" "August 2010" "redshift" "User Commands"
+.TH REDSHIFT: "1" "October 2011" "redshift" "User Commands"
 .SH NAME
 redshift \- Set color temperature of display according to time of day.
 .SH SYNOPSIS
 .B redshift
-\fI-l LAT:LON -t DAY:NIGHT \fR[\fIOPTIONS\fR...]
+\fI[-l LAT:LON | -l PROVIDER:OPTIONS] [-t DAY:NIGHT] \fR[\fIOPTIONS\fR...]
 .SH DESCRIPTION
 .B redshift
 adjusts the color temperature of your screen according to your
-surroundings. This may help your eyes hurt less if you are working in
-front of the screen at night.
+surroundings. This may help your eyes hurt less or reduce the risk for
+delayed sleep phase syndrome if you are working in front of the screen
+at night.
 
 The color temperature is set according to the position of the sun. A
 different color temperature is set during night and daytime. During
 twilight and early morning, the color temperature transitions smoothly
 from night to daytime temperature to allow your eyes to slowly
-adapt.
+adapt over a period of about an hour. At night the color temperature
+should be set to match the lamps in your room. This is typically a low
+temperature at around 3000K\-4000K (default is 3700K). During the day,
+the color temperature should match the light from outside, typically
+around 5500K\-6500K (default is 5500K). The light has a higher
+temperature on an overcast day.
 .SH OPTIONS
 .TP
 \fB\-h\fR
@@ -26,8 +32,8 @@ Verbose output
 \fB\-V\fR
 Show program version
 .TP
-\fB\-b\fR N
-Screen brightness to apply (max is 1.0)
+\fB\-b\fR DAY:NIGHT
+Screen brightness to apply (between 0.1 and 1.0)
 .TP
 \fB\-c\fR FILE
 Load settings from specified configuration file
@@ -36,9 +42,11 @@ Load settings from specified configuration file
 Additional gamma correction to apply
 .TP
 \fB\-l\fR LAT:LON
-Your current location
+Your current location, in degrees, given as floating point numbers,
+towards north and east, with negative numbers representing south and
+west, respectively.
 .TP
-\fB\-l\fR PROVIDER
+\fB\-l\fR PROVIDER[:OPTIONS]
 Select provider for automatic location updates
 (Type `list' to see available providers)
 .TP
@@ -48,6 +56,7 @@ Method to use to set color temperature
 .TP
 \fB\-o\fR
 One shot mode (do not continously adjust color temperature)
+.TP
 \fB\-O\fR TEMP
 One shot manual mode (set color temperature)
 .TP
@@ -66,14 +75,64 @@ color temperature to a value higher than this results in
 more blue light, and setting a lower value will result in
 more red light.
 
-Default values:
+Default temperature values:
 .IP
-Daytime temperature: 5500K
-Night temperature: 3700K
+Daytime: 5500K, night: 3700K
+.SH CONFIGURATION FILE
+A configuration file with the name `redshift.conf' can optionally be
+placed in `~/.config/'. The file has standard INI format. General
+program options are placed under the `redshift' header, while options
+for location providers and adjustment methods are placed under a
+header with the name of that provider or method. General options are:
+.TP
+\fBtemp-day\fR = integer
+Daytime temperature
+.TP
+\fBtemp-night\fR = integer
+Night temperature
+.TP
+\fBtransition\fR = 0 or 1
+Disable or enable transitions
+.TP
+\fBbrightness-day\fR = 0.1\-1.0
+Screen brightness at daytime
+.TP
+\fBbrightness-night\fR = 0.1\-1.0
+Screen brightness at night
+.TP
+\fBgamma\fR = R:G:B
+Gamma adjustment to apply
+.TP
+\fBadjustment-method\fR = name
+Select adjustment method. Options for the adjustment method can be
+given under the configuration file heading of the same name.
+.TP
+\fBlocation-provider\fR = name
+Select location provider. Options for the location provider can be
+given under the configuration file heading of the same name.
+.PP
+Options for location providers and adjustment methods can be found in
+the help output of the providers and methods.
 .SH EXAMPLE
 Example for Copenhagen, Denmark:
 .IP
-$ redshift -l 55.7:12.6 -t 5700:3600 -g 0.8 -m vidmode -v
+\fB$\fR redshift -l 55.7:12.6 -t 5700:3600 -g 0.8 -m vidmode -v
+.PP
+An example configuration file with the same effect as the above
+command line:
+.IP
+.nf
+[\fBredshift\fR]
+temp-day=5700
+temp-night=3600
+gamma=0.8
+adjustment-method=vidmode
+location-provider=manual
+
+[\fBmanual\fR]
+lat=55.7
+lon=12.6
+.fi
 .SH AUTHOR
 .B redshift
 was written by Jon Lund Steffensen <jonlst@gmail.com>.
@@ -85,6 +144,6 @@ License, version 3.
 .SH BUGS
 Please report bugs to <https://bugs.launchpad.net/redshift>
 .SH KNOWN ISSUES
-Redshift won’t affect the color of your cursor when your graphics driver
+Redshift won't affect the color of your cursor when your graphics driver
 is configured to use hardware cursors. Some graphics drivers have an
 option to disable hardware cursors in xorg.conf.