Clean up

Signed-off-by: Mattias Andrée <maandree@kth.se>

7 files changed, 401 insertions, 0 deletions

diff --git a/man/libred.7 b/man/libred.7
new file mode 100644
index 0000000..a5a6f36
--- /dev/null
+++ b/man/libred.7
@@ -0,0 +1,15 @@
+.TH LIBRED 7 LIBRED
+.SH NAME
+libred \- Solar elevation and blackbody colour calculation
+.SH DESCRIPTION
+.B libred
+is a C library for calculating the Sun's apparent elevation
+and colours temperatures.
+.SH "FUTURE DIRECTIONS"
+None.
+.SH "SEE ALSO"
+.BR libred.h (0),
+.BR solar-python (7),
+.BR redshift (1),
+.BR blueshift (1),
+.BR libgamma (7)
diff --git a/man/libred.h.0 b/man/libred.h.0
new file mode 100644
index 0000000..95a5144
--- /dev/null
+++ b/man/libred.h.0
@@ -0,0 +1,152 @@
+.\" -*- nroff -*-
+.TH LIBRED.H 0 LIBRED "" "Library Headers"
+.SH NAME
+libred.h \- Solar elevation and blackbody colour calculation
+.SH SYNOPSIS
+.nf
+#include <libred.h>
+.fi
+.PP
+Link with
+.IR -lred .
+.SH DESCRIPTION
+The
+.I <libred.h>
+header defines macros, symbolic constants, and functions for
+calculating solar elevations and blackbody colours. All macros
+and symbolic constants in this header are suitable for use in
+.B #if
+preprocessing directives.
+.PP
+This header defines the follow symbolic constants:
+.TP
+.B LIBRED_SOLAR_APPARENT_RADIUS
+The approximate apparent size of the Sun in degrees. This
+value should be about 0.5(3).
+.TP
+.B LIBRED_SOLAR_ELEVATION_SUNSET_SUNRISE
+The Sun's elevation at sunset and sunrise, measured in degrees.
+This value will always be 0.0.
+.TP
+.B LIBRED_SOLAR_ELEVATION_CIVIL_DUSK_DAWN
+The Sun's elevation at civil dusk and civil dawn, measured in
+degrees. This value will always be -6.0.
+.TP
+.B LIBRED_SOLAR_ELEVATION_NAUTICAL_DUSK_DAWN
+The Sun's elevation at nautical dusk and nautical dawn, measured
+in degrees. This value will always be -12.0.
+.TP
+.B LIBRED_SOLAR_ELEVATION_ASTRONOMICAL_DUSK_DAWN
+The Sun's elevation at astronomical dusk and astronomical dawn,
+measured in degrees. This value will always be -18.0.
+.TP
+.B LIBRED_HIGHEST_TEMPERATURE
+The highest temperature, in kelvins, for which there is a colour
+temperature in the table of colour temperature. Any temperature
+above this is automatically truncated by
+.BR libred_get_colour (3),
+as higher values shall be unnoticeable. Currently, this value
+is 40\ 000.
+.TP
+.B LIBRED_LOWEST_TEMPERATURE
+The lowest temperature, in kelvins, for which there is a colour
+temperature in the table of colour temperature. Any temperature
+below this results in
+.BR libred_get_colour (3)
+failing and setting
+.B errno
+to
+.BR EDOM .
+Currently this value 1000, hypothetical changes will be very small.
+.TP
+.B LIBRED_DELTA_TEMPERATURE
+The temperatures differences between sequential colour temperatures
+in the colour temperatures look up table. Currently this value is 100.
+.PP
+This header defines the follow macros:
+.TP
+.BR LIBRED_IS_TWILIGHT "(const double)"
+Evaluates to 1 if the given expression is between -18.0 and 0.0 (this is,
+between
+.B LIBRED_SOLAR_ELEVATION_ASTRONOMICAL_DUSK_DAWN
+and
+.BR LIBRED_SOLAR_ELEVATION_SUNSET_SUNRISE ),
+inclusively, otherwise, this macro evaluates to 0. The input should be the
+Sun's apparent elevation, and the macro evaluates to 1 if it is currently
+twilight. The given expression is evaluted either once or twice, therefore,
+it must not have side-effects.
+.TP
+.BR LIBRED_IS_CIVIL_TWILIGHT "(const double)"
+Evaluates to 1 if the given expression is between -6.0 and 0.0 (this is,
+between
+.B LIBRED_SOLAR_ELEVATION_CIVIL_DUSK_DAWN
+and
+.BR LIBRED_SOLAR_ELEVATION_SUNSET_SUNRISE ),
+inclusively, otherwise, this macro evaluates to 0. The input should be the
+Sun's apparent elevation, and the macro evaluates to 1 if it is currently
+civil twilight. The given expression is evaluted either once or twice,
+therefore, it must not have side-effects.
+.TP
+.BR LIBRED_IS_NAUTICAL_TWILIGHT "(const double)"
+Evaluates to 1 if the given expression is between -12.0 and -6.0 (this is,
+between
+.B LIBRED_SOLAR_ELEVATION_NAUTICAL_DUSK_DAWN
+and
+.BR LIBRED_SOLAR_ELEVATION_CIVIL_DUSK_DAWN ),
+inclusively, otherwise, this macro evaluates to 0. The input should be the
+Sun's apparent elevation, and the macro evaluates to 1 if it is currently
+nautical twilight. The given expression is evaluted either once or twice,
+therefore, it must not have side-effects.
+.TP
+.BR LIBRED_IS_ASTRONOMICAL_TWILIGHT "(const double)"
+Evaluates to 1 if the given expression is between -18.0 and -12.0 (this is,
+between
+.B LIBRED_SOLAR_ELEVATION_ASTRONOMICAL_DUSK_DAWN
+and
+.BR LIBRED_SOLAR_ELEVATION_NAUTICAL_DUSK_DAWN ),
+inclusively, otherwise, this macro evaluates to 0. The input should be the
+Sun's apparent elevation, and the macro evaluates to 1 if it is currently
+astronomical twilight. The given expression is evaluted either once or twice,
+therefore, it must not have side-effects.
+.PP
+Note that the intervals are closed, and hence their boundaries overlap.
+This is intentional. If it is not twilight it is either daytime or night.
+It is night only if the Sun's apparent elevation is negative.
+.PP
+This header defines the following functions:
+.TP
+*
+.BR libred_solar_elevation (3)
+.TP
+*
+.BR libred_check_timetravel (3)
+.TP
+*
+.BR libred_init_colour (3)
+.TP
+*
+.BR libred_term_colour (3)
+.TP
+*
+.BR libred_get_colour (3)
+.PP
+This header may define
+.B extern int libred_fd
+iff it does it also defines the macro
+.BR LIBRED_HAVE_FD .
+If it does, you want to keep this file descriptor open when you daemonise
+your process. It is set by
+.BR libred_init_colour (3)
+and unset by
+.BR libred_term_colour (3).
+It value is negative (more precisely it is -1) if no file descriptor has
+been opened.
+.SH "FUTURE DIRECTIONS"
+None.
+.SH "SEE ALSO"
+.BR libred (7),
+.BR libred_solar_elevation (3),
+.BR libred_check_timetravel (3),
+.BR libred_init_colour (3),
+.BR libred_term_colour (3),
+.BR libred_get_colour (3)
diff --git a/man/libred_check_timetravel.3 b/man/libred_check_timetravel.3
new file mode 100644
index 0000000..1d34d39
--- /dev/null
+++ b/man/libred_check_timetravel.3
@@ -0,0 +1,38 @@
+.TH LIBRED_CHECK_TIMETRAVEL 3 LIBRED
+.SH NAME
+libred_check_timetravel \- Exit the process if the clock is too far in the past
+.SH SYNOPSIS
+.nf
+#include <libred.h>
+
+int \fBlibred_check_timetravel\fP(void);
+.fi
+.PP
+Link with
+.IR -lred .
+.SH DESCRIPTION
+.B libred_check_timetravel
+exits the process if
+.B libred
+is not compiled to support the current time, which is the case
+if it was compiled without
+.I \-DTIMETRAVELLER
+and the clock is before year 2000.5 in the Julian calendar. Before
+exiting, the function will print an informative error message to
+standard error.
+.SH "RETURN VALUE"
+Upon successful completion, without time incompatibility, the function
+returns 0. Upon failure, that is, it is unable to read the clock, the
+function returns -1.
+.SH ERRORS
+The function may fail for any reason specified for
+.BR clock_gettime (3),
+and set the value of
+.B errno
+to the same values.
+.SH "FUTURE DIRECTIONS"
+None.
+.SH "SEE ALSO"
+.BR libred.h (0),
+.BR libred (7),
+.BR libred_solar_elevation (3)
diff --git a/man/libred_get_colour.3 b/man/libred_get_colour.3
new file mode 100644
index 0000000..fd32eb3
--- /dev/null
+++ b/man/libred_get_colour.3
@@ -0,0 +1,74 @@
+.TH LIBRED_GET_COLOUR 3 LIBRED
+.SH NAME
+libred_get_colour \- Calculate a colour temperature
+.SH SYNOPSIS
+.nf
+#include <libred.h>
+
+int \fBlibred_get_colour\fP(long int \fItemp\fP, double* \fIr\fP, double* \fIg\fP, double* \fIb\fP);
+.fi
+.PP
+Link with
+.IR -lred .
+.SH DESCRIPTION
+.B libred_get_colour
+gets or interpolates the colour temperature for
+.I temp
+kelvins, and returns the colour temperature in sRGB. The values,
+between 0.0 and 1.0, for the "red", green, and blue channels
+are stored in
+.IR *r ,
+.IR *g ,
+and
+.IR *b ,
+respectively.
+.PP
+At least one of the values will be 1.0, none will be greater than
+1.0, and none will be less than 0.0. It is guaranteed (unless the
+resources file has been modified) that
+.IR *r ,
+.IR *g ,
+and
+.I *b
+all will be 1.0 if
+.I temp
+is 6500.
+.PP
+You must call
+.BR libred_init_colour (3)
+before the first use of this function,
+and you should call
+.BR libred_term_colour (3)
+after the last use of this function.
+.SH "RETURN VALUE"
+Upon successful completion, the function returns 0. On failure,
+the function returns -1 and sets
+.B errno
+appropriately.
+.SH ERRORS
+The function may fail if:
+.TP
+.B EOVERFLOW
+The colour temperature lookup table is smaller than it should be.
+.TP
+.B EDOM
+If
+.I temp
+is less than
+.B LIBRED_LOWEST_TEMPERATURE
+(which is 1000.)
+.PP
+The function may also fail for any reason specified for
+.BR pread (3),
+and set the value of
+.B errno
+to the same values.
+.SH "FUTURE DIRECTIONS"
+It is possible that the behaviour is changed to loading the
+colour temperature lookup table rather than just open a
+file descriptor to it.
+.SH "SEE ALSO"
+.BR libred.h (0),
+.BR libred (7),
+.BR libred_init_colour (3),
+.BR libred_term_colour (3)
diff --git a/man/libred_init_colour.3 b/man/libred_init_colour.3
new file mode 100644
index 0000000..9463245
--- /dev/null
+++ b/man/libred_init_colour.3
@@ -0,0 +1,41 @@
+.TH LIBRED_INIT_COLOUR 3 LIBRED
+.SH NAME
+libred_init_colour \- Prepare for use of libred_get_colour(3)
+.SH SYNOPSIS
+.nf
+#include <libred.h>
+
+int \fBlibred_init_colour\fP(void);
+.fi
+.PP
+Link with
+.IR -lred .
+.SH DESCRIPTION
+.B libred_init_colour
+open a file descriptor, without returning it, to the colour
+temperature lookup table, and stores the file descriptor to
+.BR libred_fd .
+It is necessary to call this function before the first call to
+.BR libred_get_colour (3).
+.SH "RETURN VALUE"
+Upon successful completion, the function returns 0. On failure,
+the function returns -1 and sets
+.B errno
+appropriately.
+.SH ERRORS
+The function may fail for any reason specified for
+.BR open (3),
+and set the value of
+.B errno
+to the same values.
+.B errno
+is always set to 0 on success.
+.SH "FUTURE DIRECTIONS"
+It is possible that the behaviour is changed to loading the
+colour temperature lookup table rather than just open a
+file descriptor to it.
+.SH "SEE ALSO"
+.BR libred.h (0),
+.BR libred (7),
+.BR libred_get_colour (3),
+.BR libred_term_colour (3)
diff --git a/man/libred_solar_elevation.3 b/man/libred_solar_elevation.3
new file mode 100644
index 0000000..7fd499f
--- /dev/null
+++ b/man/libred_solar_elevation.3
@@ -0,0 +1,48 @@
+.TH LIBRED_SOLAR_ELEVATION 3 LIBRED
+.SH NAME
+libred_solar_elevation \- Calculate the Sun's apparent elevation
+.SH SYNOPSIS
+.nf
+#include <libred.h>
+
+double \fBlibred_solar_elevation\fP(double \fIlatitude\fP, double \fIlongitude\fP);
+.fi
+.PP
+Link with
+.IR -lred .
+.SH DESCRIPTION
+.B libred_solar_elevation
+calculates the Sun's  elevation as apparent from a select geographical position.
+Namely from
+.I latitude
+degrees north of GPS's equator and
+.I longitude
+degrees east of GPS's prime meridian. The function is only explicitly defined for
+values between -90 and +90 for
+.I latitude
+and values between -180 and +180 for and
+.IR longitude .
+Other values may or may not work, no error is thrown if used.
+.SH "RETURN VALUE"
+Upon successful completion, the function sets
+.B errno
+to 0 and returns the Sun's current apparent elevation, measured in
+degrees above the horizon. On failure, the function returns an
+arbitrary value (happens to always be 0.0) and sets
+.B errno
+an a non-zero value.
+.SH ERRORS
+The function may fail for any reason specified for
+.BR clock_gettime (3),
+and set the value of
+.B errno
+to the same values.
+.B errno
+is always set to 0 on success.
+.SH "FUTURE DIRECTIONS"
+None.
+.SH "SEE ALSO"
+.BR libred.h (0),
+.BR libred (7),
+.BR libred_check_timetravel (3),
+.BR libred_init_colour (3)
diff --git a/man/libred_term_colour.3 b/man/libred_term_colour.3
new file mode 100644
index 0000000..6d327c2
--- /dev/null
+++ b/man/libred_term_colour.3
@@ -0,0 +1,33 @@
+.TH LIBRED_TERM_COLOUR 3 LIBRED
+.SH NAME
+libred_term_colour \- Deallocate resources required by libred_get_colour(3)
+.SH SYNOPSIS
+.nf
+#include <libred.h>
+
+void \fBlibred_term_colour\fP(void);
+.fi
+.PP
+Link with
+.IR -lred .
+.SH DESCRIPTION
+.B libred_term_colour
+deallocates all resources acquired by
+.BR libred_init_colour (3).
+It is highly recommended to call this function before calling an
+.BR exec (3)-function.
+If you want to use
+.BR libred_get_colour (3)
+again after a call to this function has been made, you must first call
+.BR libred_init_colour (3).
+.SH "RETURN VALUE"
+None.
+.SH ERRORS
+None.
+.SH "FUTURE DIRECTIONS"
+None.
+.SH "SEE ALSO"
+.BR libred.h (0),
+.BR libred (7),
+.BR libred_get_colour (3),
+.BR libred_init_colour (3)