Documentation, design document?

Hi Christian,
Thanks for documenting your experience with Redshift. I fully agree with you that the user experience could be greatly improved. I have not had much time to work on documentation myself, but I've tried to encourage others who might be interested in working on this. The man page was contributed in this way, but unfortunately not much else has come about. If anyone decides to work on this I'll gladly include it in the Redshift package and/or put it up on the web page.
-Jon

Ok. I've checked out https://code.launchpad.net/~jonls/redshift/trunk
(and converted to Git to use familiar tools); right now I'm trying to
build the latest version with the debian/ subdir from the 1.6 Debian
package, fails with:

...

make[1]: Entering directory `/home/chrisnox/rr/trunk'
dh_auto_configure -- --enable-randr --enable-vidmode --enable-gnome-clock
make[1]: Leaving directory `/home/chrisnox/rr/trunk'
   dh_auto_build
   dh_auto_test
 fakeroot -u debian/rules binary
dh binary --with autotools_dev
   dh_testroot
   dh_prep
   dh_installdirs
   dh_auto_install
   dh_install
cp: cannot stat `debian/tmp/usr/bin/redshift': No such file or directory
dh_install: cp -a debian/tmp/usr/bin/redshift
debian/redshift//usr/bin/ returned exit code 1
make: *** [binary] Error 2
dpkg-buildpackage: error: fakeroot -u debian/rules binary gave error
exit status 2

I guess I'll just forget about the deb for now; next thing I wonder
is, debian/rules configures it with --enable-randr --enable-vidmode
--enable-gnome-clock, and I guess the gnome-clock is related to that
/apps/panel/applets/clock_screen0/prefs/cities setting, is this
correct? What I'm mainly wondering is, which various ways to figure
out the location does it currently have? And which are compiled in
conditionally?

Christian.

2011/9/22 Christian Jaeger <email address hidden>:
> cp: cannot stat `debian/tmp/usr/bin/redshift': No such file or directory
>

Ah, running ./bootstrap fixes this.

2011/9/22 Christian J. <email address hidden>:
> Question #172031 on Redshift changed:
> I guess I'll just forget about the deb for now; next thing I wonder
> is, debian/rules configures it with --enable-randr --enable-vidmode
> --enable-gnome-clock, and I guess the gnome-clock is related to that
> /apps/panel/applets/clock_screen0/prefs/cities setting, is this
> correct? What I'm mainly wondering is, which various ways to figure
> out the location does it currently have? And which are compiled in
> conditionally?

I believe ./configure --help should show more about what parts of the
program that can be conditionally compiled. Some quick notes on the
rationale behind certain redshift features: There are basically two
groups of features: "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 as you correctly mention.
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.
I hope this makes sense,
-Jon

Reopen.

Perfect, thanks, . I've added your explanation to the DESIGN document
that I've started. I've pushed my git branch to github for now:
git://github.com/pflanze/redshift.git

I expect to be able to convert the Git repo back to Bazaar and then
push it to my new account at launchpad, but I haven't looked into that
yet.

While looking at the following:

$ redshift
Location not specified for city.
Initialization of gnome-clock failed.
Trying next provider...
Latitude and longitude must be set.

I've had two ideas: (1) prefix the messages with the name of the
'component'; like (not sure this is right):

$ redshift
gnome-clock: Location not specified for city.
gnome-clock: Initialization of gnome-clock failed.
Trying next provider...
Latitude and longitude must be set.

and (2) maybe have a verbose flag--actually I see that -v is already
parsed and set, so this point is kinda moot, just maybe add more
messages where it makes sense.

I'm going to try --enable-geoclue now (but I guess on Debian stable
that's the older buggy stuff).

Christian.

2011/9/22 Christian Jaeger <email address hidden>:
> git://github.com/pflanze/redshift.git

actually that was a rather useless URL, here's the web UI:
https://github.com/pflanze/redshift

I wrote:
> I'm going to try --enable-geoclue now (but I guess on Debian stable
> that's the older buggy stuff).

Well, the version of geoclue I have here simply doesn't seem to know
any way to find my location, the bundled README lists the available
options and all of them are GPS, which I don't have.

Here's the output of redshift:

[
$ redshift
Trying location provider `geoclue'...

** (process:21365): WARNING **: Metadata for error domain
"geoclue-error-quark" already registered

Started Geoclue provider `Geoclue Master'.
Using provider `geoclue'.
Could not get location: Geoclue master client has no usable Position providers.
Unable to get location from provider.
]

Note that it stopped looking for alternatives, even though it didn't
try the gnome clock applet yet. That could be considered a bug maybe?
(Giving coordinates on the commandline still overrides geoclue, so
that's the way for a user to get out of the geoclue tarpit, but for
using gnome clock with a binary that has geoclue in it, the user would
have to list the provider explicitely.)

I'm now mostly done, I've answered most questions I had and written
docs about then; these things are open:

- I haven't fixed translations; I forgot how to use the po stuff
(never actually used it in an own project), if you tell me how I'll
give it a go.

- Maybe the DESIGN document should be formatted as a manpage, so it
would be more easily available to users? (Debian would probably still
bundle the file in the /usr/share/doc/redshift/ directory, but who is
looking there? Well I frequently do, but then..?)

- redshift doesn't flush stdout (and/or stderr), thus when running
something like:

  redshift -v 2>&1|log-timestamp

it buffers messages for a long time.

I've pushed my code to Github (URL above), and imported it to
launchpad: https://code.launchpad.net/~chrjae/redshift/trunk
NOTE: this includes the .gitignore file I've added. Can you exclude
the two patches touching .gitignore when picking my changes, or would
you prefer if I reimport without that file?

You should check what I've written; for example I haven't really
verified whether my claim that redshift doesn't update from geoclue
after startup is correct.

I haven't thought about what would be good for the web presence. I'd
say a central place would be better than multiple blog pages, but I
think the current version is already quite user friendly now (at least
I think it would have solved my questions) so there's maybe no need
for a change.

(I still don't know whether redshift will actually change back to day
now, I'll see tomorrow morning.)

Christian.

> these things are open:

Ah, and:

- I've removed almost the whole help text from the redshift program
(and tell the user to read the man page instead), to avoid having two
places with the same docs. I guess this is a bit a rough solution; I'm
rarely using the help text of programs, but maybe some people do. A
solution would be to convert the manpage to text at compile time and
automatically include it in the program, but I don't know how to do
that cleanly (esp. since translations are involved, too; although, if
we rely on translations being found, we should also be able to rely on
the manpages to be found? Then calling the man page automatically at
runtime would be ok?)

Christian.

I wrote:
> - I haven't fixed translations; I forgot how to use the po stuff..

I've found "make update-po". I've run it (and committed the changes),
and fixed the German translation.

> - redshift doesn't flush stdout (and/or stderr),

Done, by using setvbuf.

> I've pushed my code to Github (URL above), and imported it to
> launchpad: https://code.launchpad.net/~chrjae/redshift/trunk
> NOTE: this includes the .gitignore file I've added. Can you exclude

I've removed the .gitignore patches now (and pushed with --force);
also I've fixed the patch that said transition happens in 10 minutes
(changed it to "about 50 minutes", I guess that might depend on the
latitude and time of year? I haven't looked at the calculation, but I
appreciate how precise it seems to be). Also, I've moved the two
patches changing the help text to the end, and have pushed a new
branch "pu" (for "proposed updates") that doesn't contain these; I
intend to work on "master" and put on "pu" what I think is ready to be
merged.

I want to add an import for the "pu" branch, too, but somehow I just
can't find where to find that functionality on launchpad anymore.

> - I've removed almost the whole help text from the redshift program
> (and tell the user to read the man page instead), to avoid having two
> places with the same docs.

I still don't know what do do for that. I realize:

- there are currently no translations for the manpage
- using gettext might be nice for handling translations (text
dissected in smaller parts, using existing infrastructure)
- so maybe the way to go is to generate the manpage from the help
text? I might write a Perl script to do that. But maybe there are
better solutions.

Christian.

2011/9/25 Christian J. <email address hidden>:
> I want to add an import for the "pu" branch, too, but somehow I just
> can't find where to find that functionality on launchpad anymore.
>

I got it imported now thanks to help from wgrant on the launchpad IRC
channel (in case anyone's interested):

Launchpad only gained support for importing non-master git branches a
couple of weeks ago, and the UI isn't exactly obvious yet.
[Go to] code.launchpad.net/myproject
Click the "Code" tab at the top.
you should see an 'Import a branch' link on the right.
Until we have a special UI for this, you can import a non-master
branch by adding ',branch=somebranchname' to the end of the git URL.
Imports from GitHub work better over git:// than https://.

2011/9/25 Christian Jaeger <email address hidden>:
>> - I've removed almost the whole help text from the redshift program
>> (and tell the user to read the man page instead), to avoid having two
>> places with the same docs.
>
> I still don't know what do do for that. I realize:
>
> - there are currently no translations for the manpage
> - using gettext might be nice for handling translations (text
> dissected in smaller parts, using existing infrastructure)
> - so maybe the way to go is to generate the manpage from the help
> text? I might write a Perl script to do that. But maybe there are
> better solutions.
>

I've partically implemented a solution and pushed it to Github master
(will automatically be synched into my Launchpad trunk in a couple
hours). I'm relying on the C preprocessor, which makes it rather easy,
except that the expansion targeted to the man page still needs to be
post-processed a little by a script, which I haven't written yet; the
script needs to do:

- remove quotes from string arguments (and merge them like C does),
and turn special markers into real line feeds, remove empty lines and
file position markers
- process %s in format strings; for that, know the values of the
macros that are used in the help text (how? Should be easy to do using
gcc -E and trivial files only containing the macro in question).
- process _( ) (gettext), for this: look up the actual translation (I
don't currently know how to do this)

Of course I'm stupid to implement all of this just to avoid having to
keep half a page of documentation in sync. But maybe you'll find it
neat and it was fun to do so far.

Christian.

Here's the commit in question:
https://github.com/pflanze/redshift/commit/c90a9fed606fe5357b42ad395592895110b416e4

2011/9/26 Christian J. <email address hidden>:
> Question #172031 on Redshift changed:
> https://answers.launchpad.net/redshift/+question/172031
>
> Christian J. gave more information on the question:
> Here's the commit in question:
> https://github.com/pflanze/redshift/commit/c90a9fed606fe5357b42ad395592895110b416e4

Awesome. I'll merge the DESIGN and HACKING documents soon.
-Jon

Thanks for fixing up the man page for redshift, Christian's commit looks much more helpful than the current state of affairs (version 1.7 is the latest packaged in Debian).

There are a few questions that Christian started with that I'd still like to see answered:

* The LAT:LON format is yet undocumented. Does it use WEST and EAST or negative/positive numbers? If the latter, which way is negative? Can it handle degrees, minutes, and seconds? I've made some educated guesses (see below), but it'd be nice if it was actually specified in the man page.

* It'd be great to have an example in the man page on how to google for your coordinates and input them. Something like,

    If you type the name of your city followed by the word "coordinates" into Google's search box, Google will show your city's latitude and longitude in this format:

    40.7142° N, 74.0064° W

    You can use those numbers in redshift like so: redshift -l 40.7142:-74.0064

    Note that redshift currently gets confused if you enter coordinates with a suffix like N or W. Instead, north and east are assumed and you must use a negative number if you wish to specify south or west. Also, redshift cannot handle a comma between the numbers, you must use a colon instead. There is no way yet to specify coordinates in degree-minute-second format, so you must use decimal degrees. Don't even think of entering the degree sign.

* It would be nice to have some more details about how redshift works. Something that talks about the sinusoid and why timezone isn't enough to specify daylight hours.

Also, I'd like to ask a question:

* Could redshift use the coordinate data from another free software package, such as sunclock, so that at least major cities can be specified by name on the command line? http://www.arvernes.com/wiki/index.php/Sunclock

Here is a sample of the data in /usr/share/sunclock/Sunclockrc

addcity 3|Aachen|50.784|6.053|MET-1METDST,M3.5.0,M10.5.0
addcity 3|Aberdeen|57.207|-2.209|GMT0BST,M3.5.0,M10.5.0
addcity 3|Abilene|32.451|-99.731|CST6CDT
addcity 3|Akron|41.083|-81.512|EST5EDT
addcity 3|Albany|42.650|-73.750|EST5EDT
addcity 3|Albuquerque|35.084|-106.651|MST7MDT
addcity 3|Alice^_Springs|-23.808|133.901|CST-9:30
addcity 3|Allentown|40.603|-75.468|EST5EDT
addcity 3|Altoona|40.515|-78.401|EST5EDT
addcity 3|Amarillo|35.208|-101.834|CST6CDT
addcity 3|Amsterdam|52.367|4.900|MET-1METDST,M3.5.0,M10.5.0