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.
This commit is contained in:
Jon Lund Steffensen
@@ -0,0 +1,95 @@
|
||||
This is a document describing how redshift works. It might be useful
|
||||
if the normal docs don't answer a question, or when you want to hack
|
||||
on the code.
|
||||
|
||||
|
||||
Programs
|
||||
========
|
||||
|
||||
redshift
|
||||
--------
|
||||
|
||||
redshift is a program written in C that tries to figure out the user's
|
||||
location during startup, and then goes into a loop setting the display
|
||||
gamma according to the time of day every couple seconds or minutes
|
||||
(details?).
|
||||
|
||||
On systems that support signals, it reacts to the SIGUSR1 signal by
|
||||
switching to day/night immediately, and when receiving SIGINT or
|
||||
SIGTERM, it restores the screen gamma (to 6500K).
|
||||
|
||||
Redshift knows short and long transitions, short transitions being
|
||||
used at start and when reacting to signals. Short transitions take
|
||||
about 10 seconds; long transitions about 50 minutes.
|
||||
|
||||
Once running, redshift currently doesn't check location providers
|
||||
again.
|
||||
|
||||
|
||||
gtk-redshift
|
||||
------------
|
||||
|
||||
gtk-redshift is a small program written in Python that shows a status
|
||||
icon (what is an appindicator versus a GTK status icon?) (does it
|
||||
change the icon according to internal program state of redshift?
|
||||
doesn't seem so) and run an instance of the "redshift" program, and
|
||||
will send it SIGUSR1 each time the user clicks the icon.
|
||||
|
||||
|
||||
Alternative Features
|
||||
====================
|
||||
|
||||
Redshift interacts with the rest of the system in two ways: reading
|
||||
the location, and setting the gamma. Both can be done in different
|
||||
ways, and so for both areas there are configure options to
|
||||
enable/disable compilation of the various methods. ./configure --help
|
||||
shows more about what parts of the program that can be conditionally
|
||||
compiled.
|
||||
|
||||
NOTE: some features have to be disabled explicitely, like
|
||||
--disable-gnome-clock to prevent the gnome-clock code from being built
|
||||
in.
|
||||
|
||||
The two groups of features shall be called: "location providers" and
|
||||
"adjustment methods".
|
||||
|
||||
These are probably not the best names for these things but at least
|
||||
I've been mostly consistent with the naming throughout the source code
|
||||
(I hope).
|
||||
|
||||
First adjustment methods: There is "randr" which is the preferred
|
||||
because it has some features that are lacking in "vidmode" (IIRC it
|
||||
has to do with multiple monitors). Both are APIs in the X server that
|
||||
allow for manipulation of gamma ramps, which is what Redshift uses to
|
||||
change the screen color temperature. There's also "wingdi" which is
|
||||
for the Windows version.
|
||||
|
||||
Then there are location providers: "manual", "gnome-clock" and
|
||||
"geoclue". Some time ago there was only one way to specify the
|
||||
location which had to be done manually with the argument "-l LAT:LON".
|
||||
Then later, automatic "location providers" were added and the syntax
|
||||
had to be changed to "-l PROVIDER:OPTIONS" where OPTIONS are arguments
|
||||
specific to the provider. But to make people less confused about the
|
||||
change I decided to still support the "-l LAT:LON" syntax, so if the
|
||||
PROVIDER is a number, the whole thing is parsed as LAT:LON. You could
|
||||
run redshift with "-l manual:lat=55:lon=12" and get the same effect as
|
||||
"-l 55:12".
|
||||
|
||||
So there are currently two automatic location providers "gnome-clock"
|
||||
and "geoclue". From the beginning I was looking for a way to get the
|
||||
location automatically (from e.g. GPS) and Geoclue seemed like a good
|
||||
idea, but upon closer investigation it turned out to be horribly
|
||||
unstable. At this time GNOME had a clock applet which was present by
|
||||
default (at least in Ubuntu) that allowed the user to set a home town.
|
||||
This setting was registered in the gconf key
|
||||
/apps/panel/applets/clock_screen*/prefs/cities.
|
||||
The idea was to use this information until Geoclue had become more
|
||||
stable. To me, it always was a hack. Now that the Clock applet has
|
||||
gone (at least in Ubuntu) the "gnome-clock" makes little sense and
|
||||
causes a lot of trouble, so I really want to get rid of it as soon as
|
||||
possible. The problem is that Geoclue is still problematic for some
|
||||
people.
|
||||
|
||||
Lastly, there's the support for configuration files for which there's
|
||||
no real documentation, but all the options that can be set on the
|
||||
command line can also be set in the config file.
|
||||
@@ -0,0 +1,3 @@
|
||||
- verbose flag is (currently) only held in redshift.c; thus, write all
|
||||
verbose messages there
|
||||
|
||||
+73
-14
@@ -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.
|
||||
|
||||
@@ -117,6 +117,10 @@ location_geoclue_print_help(FILE *f)
|
||||
fputs(_(" name=N\tName of Geoclue provider (or `default')\n"
|
||||
" path=N\tPath of Geoclue provider (or `default')\n"), f);
|
||||
fputs("\n", f);
|
||||
fputs(_("NOTE: currently redshift doesn't recheck geoclue once started,\n"
|
||||
"which means it has to be restarted to take notice after travel.\n"),
|
||||
f);
|
||||
fputs("\n", f);
|
||||
}
|
||||
|
||||
int
|
||||
|
||||
@@ -156,7 +156,9 @@ location_gnome_clock_init(location_gnome_clock_state_t *state)
|
||||
char *lat_str = strstr(current_city, "latitude=\"");
|
||||
char *lon_str = strstr(current_city, "longitude=\"");
|
||||
if (lat_str == NULL || lon_str == NULL) {
|
||||
fputs(_("Location not specified for city.\n"), stderr);
|
||||
fprintf(stderr,
|
||||
_("Location not specified for city `%s'.\n"),
|
||||
current_city);
|
||||
g_free(current_city);
|
||||
return -1;
|
||||
}
|
||||
|
||||
@@ -70,6 +70,9 @@ location_manual_print_help(FILE *f)
|
||||
fputs(_(" lat=N\t\tLatitude\n"
|
||||
" lon=N\t\tLongitude\n"), f);
|
||||
fputs("\n", f);
|
||||
fputs(_("Both values are expected to be floating point numbers,\n"
|
||||
"negative values representing west / south, respectively.\n"), f);
|
||||
fputs("\n", f);
|
||||
}
|
||||
|
||||
int
|
||||
|
||||
+6
-1
@@ -930,6 +930,9 @@ main(int argc, char *argv[])
|
||||
location_providers[i].name != NULL; i++) {
|
||||
const location_provider_t *p =
|
||||
&location_providers[i];
|
||||
fprintf(stderr,
|
||||
_("Trying location provider `%s'...\n"),
|
||||
p->name);
|
||||
r = provider_try_start(p, &location_state,
|
||||
&config_state, NULL);
|
||||
if (r < 0) {
|
||||
@@ -966,6 +969,8 @@ main(int argc, char *argv[])
|
||||
if (verbose) {
|
||||
/* TRANSLATORS: Append degree symbols if possible. */
|
||||
printf(_("Location: %f, %f\n"), lat, lon);
|
||||
printf(_("Temperatures: %dK at day, %dK at night\n"),
|
||||
temp_day, temp_night);
|
||||
}
|
||||
|
||||
/* Latitude */
|
||||
@@ -1314,7 +1319,7 @@ main(int argc, char *argv[])
|
||||
}
|
||||
}
|
||||
|
||||
/* Sleep for a while */
|
||||
/* Sleep for 5 seconds or 0.1 second. */
|
||||
#ifndef _WIN32
|
||||
if (short_trans) usleep(100000);
|
||||
else usleep(5000000);
|
||||
|
||||
Reference in New Issue
Block a user