aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorMattias Andrée <maandree@member.fsf.org>2016-01-05 20:29:12 +0100
committerMattias Andrée <maandree@member.fsf.org>2016-01-05 20:29:12 +0100
commit5fc891fa4214cdeb7f01be274198711c716b29cd (patch)
treec0196d6029dc7a640347c8ef729c4e23edadab96
parentm (diff)
downloadlibred-5fc891fa4214cdeb7f01be274198711c716b29cd.tar.gz
libred-5fc891fa4214cdeb7f01be274198711c716b29cd.tar.bz2
libred-5fc891fa4214cdeb7f01be274198711c716b29cd.tar.xz
m + texinfo manual
Signed-off-by: Mattias Andrée <maandree@member.fsf.org>
-rw-r--r--Makefile.in5
-rw-r--r--doc/info/chap/constants.texinfo47
-rw-r--r--doc/info/chap/functions.texinfo155
-rw-r--r--doc/info/chap/macros.texinfo49
-rw-r--r--doc/info/chap/overview.texinfo6
-rw-r--r--doc/info/chap/variables.texinfo15
-rw-r--r--doc/info/content.texinfo8
-rw-r--r--doc/man/libred.h.08
-rw-r--r--doc/man/libred_get_colour.32
-rw-r--r--doc/man/libred_solar_elevation.32
10 files changed, 288 insertions, 9 deletions
diff --git a/Makefile.in b/Makefile.in
index b34fcf6..00b0881 100644
--- a/Makefile.in
+++ b/Makefile.in
@@ -60,7 +60,8 @@ _TEXINFO_DIRLEVELS = 2
_INFOPARTS = 0
_HAVE_TEXINFO_MANUAL = yes
_HTML_FILES = Free-Software-Needs-Free-Documentation.html GNU-Free-Documentation-License.html \
- GNU-General-Public-License.html index.html Overview.html
+ GNU-General-Public-License.html index.html Overview.html Functions.html \
+ Constants.html Macros.html Variables.html
# Used by mk/man.mk
_MAN_PAGE_SECTIONS = 0 3 7
@@ -76,7 +77,7 @@ _COPYING = COPYING
___EVERYTHING_INFO = autohaltd titlepage-data content hardcopy-copying \
appx/fdl appx/free-software-needs-free-documentation appx/gpl \
reusable/macros reusable/paper reusable/titlepage \
- chap/overview
+ chap/overview chap/variables chap/macros chap/functions chap/constants
_EVERYTHING = $(__EVERYTHING_ALL_COMMON) DEPENDENCIES INSTALL NEWS \
$(foreach F,$(___EVERYTHING_INFO),doc/info/$(F).texinfo) \
src/10deg src/blackbody.c src/libred.h src/macros.h \
diff --git a/doc/info/chap/constants.texinfo b/doc/info/chap/constants.texinfo
new file mode 100644
index 0000000..e5e09ac
--- /dev/null
+++ b/doc/info/chap/constants.texinfo
@@ -0,0 +1,47 @@
+@node Constants
+@chapter Constants
+
+@file{<libred.h>} defines a number of symbolic constants
+suitable for using a @code{#if} preprocessing directives.
+
+@table @code
+@item LIBRED_SOLAR_APPARENT_RADIUS
+The approximate apparent size of the Sun in degrees.
+This value should be about 0.5(3).
+
+@item LIBRED_SOLAR_ELEVATION_SUNSET_SUNRISE
+The Sun's elevation at sunset and sunrise, measured in
+degrees. This value will always be 0.0.
+
+@item LIBRED_SOLAR_ELEVATION_CIVIL_DUSK_DAWN
+The Sun's elevation at civil dusk and civil dawn, measured
+in degrees. This value will always be @math{-6.0}.
+
+@item LIBRED_SOLAR_ELEVATION_NAUTICAL_DUSK_DAWN
+The Sun's elevation at nautical dusk and nautical dawn,
+measured in degrees. This value will always be @math{-12.0}.
+
+@item LIBRED_SOLAR_ELEVATION_ASTRONOMICAL_DUSK_DAWN
+The Sun's elevation at astronomical dusk and astronomical
+dawn, measured in degrees. This value will always be @math{-18.0}.
+
+@item 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
+@code{libred_get_colour}, as higher values shall be
+unnoticeable. Currently, this value is 40@tie{}000.
+
+@item 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 @code{libred_get_colour}
+failing and setting @code{errno} to @code{EDOM}. Currently
+this value 1000, hypothetical changes will be very small.
+
+@item LIBRED_DELTA_TEMPERATURE
+The temperatures differences between sequential colour
+temperatures in the colour temperatures look up table.
+Currently this value is 100.
+@end table
+
diff --git a/doc/info/chap/functions.texinfo b/doc/info/chap/functions.texinfo
new file mode 100644
index 0000000..d3236ec
--- /dev/null
+++ b/doc/info/chap/functions.texinfo
@@ -0,0 +1,155 @@
+@node Functions
+@chapter Functions
+
+@file{<libred.h>} defines a small number of functions.
+@example
+int libred_check_timetravel(void);
+double libred_solar_elevation(double latitude, double longitude);
+int libred_init_colour(void);
+void libred_term_colour(void);
+int libred_get_colour(long int temp, double* r, double* g, double* b);
+@end example
+
+@code{libred_check_timetravel} exits the process if @command{libred}
+is not compiled to support the current time, which is the case if it
+was compiled without @option{-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. Upon successful
+completion, without time incompatibility, the function returns 0.
+Upon failure, that is,it is unable to read the clock, the function
+returns @math{-1}. The function may fail for any reason specified for
+@code{clock_gettime}, and set the value of errno to the same values.
+It is recommended to call this function at the beginning of the program.
+
+@example
+#include <libred.h>
+#include <stdio.h>
+int main()
+@{
+ if (libred_check_timetravel())
+ return perror(""), 1;
+
+ /* @xrm{}Use @xtt{}libred_solar_elevation@xrm{} to your heart's contempt.@xtt{} */
+
+ return 0;
+@}
+@end example
+
+@code{libred_solar_elevation} calculates the Sun's elevation as apparent
+from a select geographical position. Namely from latitude degrees north
+of GPS's equator and longitude degrees east of GPS's prime meridian.
+The function is only explicitly defined for values between @math{-90} and
+@math{+90} for latitude and values between @math{-180} and @math{+180} for
+and longitude. Other values may or may not work, no error is thrown if used.
+Upon successful completion, the function sets 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 @code{errno} an a non-zero value. The function may fail for
+any reason specified for @code{clock_gettime}, and set the value of
+@code{errno} to the same values. @code{errno} is always set to 0 on success.
+
+@example
+#include <libred.h>
+#include <stdio.h>
+#include <stdlib.h>
+int main(int argc, char* argv[])
+@{
+ double elevation, latitude, longitude;
+
+ if (libred_check_timetravel())
+ return perror(""), 1;
+
+ if (argc < 3) return 2;
+ latitude = atof(argv[1]);
+ longitude = atof(argv[2]);
+
+ elevation = libred_solar_elevation(latitude, longitude);
+ return errno || printf("Elevation: %lf\n", elevation) < 0;
+@}
+@end example
+
+@code{libred_init_colour} open a file descriptor, without returning it,
+to the colour temperature lookup table, and stores the file descriptor to
+@code{libred_fd}. It is necessary to call this function before the first
+call to @code{libred_get_colour}. Upon successful completion, the
+function returns 0. On failure, the function returns @math{-1} and sets
+@code{errno} appropriately. The function may fail for any reason specified
+for @code{open}, and set the value of @code{errno} to the same values.
+@code{errno} is always set to 0 on success. It is possible that the
+behaviour is changed to loading the colour temperature lookup table rather
+than just open a file descriptor to it.
+
+@code{libred_term_colour} deallocates all resources acquired by
+@code{libred_init_colour}. It is highly recommended to call this function
+before calling an @code{exec}-function. If you want to use
+@code{libred_get_colour} again after a call to this function has been
+made, you must first call @code{libred_init_colour}.
+
+@example
+#include <libred.h>
+#include <stdio.h>
+int main(int argc, char* argv[])
+@{
+ if (libred_init_colour())
+ return perror(""), 1;
+
+ /* @xrm{}Use @xtt{}libred_get_colour@xrm{} to your heart's contempt.@xtt{} */
+
+ libred_term_colour();
+ return 0;
+@}
+@end example
+
+@code{libred_get_colour} gets or interpolates the colour temperature for
+@code{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 @code{*r}, @code{*g}, and @code{*b}, respectively.
+Upon successful completion, the function returns 0. On failure, the
+function returns @math{-1} and sets @code{errno} appropriately.
+The function may fail if:
+@table @code
+@item EOVERFLOW
+The colour temperature lookup table is smaller than it should be.
+@item EDOM
+If @code{temp} is less than @code{LIBRED_LOWEST_TEMPERATURE} (which is 1000.)
+@end table
+@noindent
+The function may also fail for any reason specified for @code{pread}, and
+set the value of @code{errno} to the same values.
+
+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 @code{*r}, @code{*g}, and @code{*b} all
+will be 1.0 if @code{temp} is 6500.
+
+You must call @code{libred_init_colour} before the first use of
+@code{libred_get_colour}, and you should call @code{libred_term_colour}
+after the last use of @code{libred_get_colour}.
+
+@example
+#include <libred.h>
+#include <stdio.h>
+#include <stdlib.h>
+int main(int argc, char* argv[])
+@{
+ long int temp;
+ double r, g, b;
+
+ if (argc < 2) return 2;
+ temp = atol(argv[1]);
+
+ if (libred_init_colour())
+ return perror(""), 1;
+
+ if (libred_get_colour(temp, &r, &g, &b));
+ return perror(""), libred_term_colour(), 1;
+
+ libred_term_colour();
+
+ return printf("Red: %lf\n"
+ "Green: %lf\n"
+ "Blue: %lf\n",
+ r, g, b) < 0;
+@}
+@end example
+
diff --git a/doc/info/chap/macros.texinfo b/doc/info/chap/macros.texinfo
new file mode 100644
index 0000000..2d4a947
--- /dev/null
+++ b/doc/info/chap/macros.texinfo
@@ -0,0 +1,49 @@
+@node Macros
+@chapter Macros
+
+@file{<libred.h>} defines a small set of macros
+suitable for using a @code{#if} preprocessing directives.
+
+@table @code
+@item LIBRED_IS_TWILIGHT(const double)
+Evaluates to 1 if the given expression is between @math{-18.0}
+and 0.0 (this is, between
+@code{LIBRED_SOLAR_ELEVATION_ASTRONOMICAL_DUSK_DAWN} and
+@code{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.
+
+@item LIBRED_IS_CIVIL_TWILIGHT(const double)
+Evaluates to 1 if the given expression is between @math{-6.0}
+and 0.0 (this is, between
+@code{LIBRED_SOLAR_ELEVATION_CIVIL_DUSK_DAWN} and
+@code{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.
+
+@item LIBRED_IS_NAUTICAL_TWILIGHT(const double)
+Evaluates to 1 if the given expression is between @math{-12.0}
+and @math{-6.0} (this is, between
+@code{LIBRED_SOLAR_ELEVATION_NAUTICAL_DUSK_DAWN} and
+@code{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.
+
+@item LIBRED_IS_ASTRONOMICAL_TWILIGHT(const double)
+Evaluates to 1 if the given expression is between @math{-18.0}
+and @math{-12.0} (this is, between
+@code{LIBRED_SOLAR_ELEVATION_ASTRONOMICAL_DUSK_DAWN} and
+@code{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.
+@end table
+
diff --git a/doc/info/chap/overview.texinfo b/doc/info/chap/overview.texinfo
index 3571e63..34f0f71 100644
--- a/doc/info/chap/overview.texinfo
+++ b/doc/info/chap/overview.texinfo
@@ -5,3 +5,9 @@
the Sun's apparent elevation, and colour temperatures, the
colour of blackbodies.
+To use @command{libred}, include the header file
+@file{<libred.h>}, and link with @option{-lred}. The
+@command{libred} package includes a @command{librarian}
+file and a @command{pkgconfig} file, both named
+@command{libred}.
+
diff --git a/doc/info/chap/variables.texinfo b/doc/info/chap/variables.texinfo
new file mode 100644
index 0000000..aa44f19
--- /dev/null
+++ b/doc/info/chap/variables.texinfo
@@ -0,0 +1,15 @@
+@node Variables
+@chapter Variables
+
+@file{<libred.h>} defines the variable
+@example
+extern int libred_fd
+@end example
+@indent
+which is either @code{-1} or the file descriptor the
+library uses to access the colour temperature lookup
+table. The header also defines @code{LIBRED_HAVE_FD}.
+It is possible that @code{libred_fd} is removed in a
+future version. If it is, @code{LIBRED_HAVE_FD} will
+be removed too.
+
diff --git a/doc/info/content.texinfo b/doc/info/content.texinfo
index 8ff128d..25719b2 100644
--- a/doc/info/content.texinfo
+++ b/doc/info/content.texinfo
@@ -9,6 +9,10 @@
@menu
* Overview:: Brief overview of @command{libred}.
+* Constants:: Symbolic constants in @file{<libred.h>}.
+* Macros:: Macros in @file{<libred.h>}.
+* Functions:: Functions in @file{<libred.h>}.
+* Variables:: External variables in @file{<libred.h>}.
* Free Software Needs Free Documentation:: Why free documentation is important.
* GNU General Public License:: Copying and sharing @command{libred}.
@@ -18,6 +22,10 @@
@include chap/overview.texinfo
+@include chap/constants.texinfo
+@include chap/macros.texinfo
+@include chap/functions.texinfo
+@include chap/variables.texinfo
@include appx/free-software-needs-free-documentation.texinfo
diff --git a/doc/man/libred.h.0 b/doc/man/libred.h.0
index 30ef848..e837cb9 100644
--- a/doc/man/libred.h.0
+++ b/doc/man/libred.h.0
@@ -71,7 +71,7 @@ between
.B LIBRED_SOLAR_ELEVATION_ASTRONOMICAL_DUSK_DAWN
and
.BR LIBRED_SOLAR_ELEVATION_SUNSET_SUNRISE ),
-inclusively, other wise, this macro evaluates to 0. The input should be the
+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.
@@ -82,7 +82,7 @@ between
.B LIBRED_SOLAR_ELEVATION_CIVIL_DUSK_DAWN
and
.BR LIBRED_SOLAR_ELEVATION_SUNSET_SUNRISE ),
-inclusively, other wise, this macro evaluates to 0. The input should be the
+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.
@@ -93,7 +93,7 @@ between
.B LIBRED_SOLAR_ELEVATION_NAUTICAL_DUSK_DAWN
and
.BR LIBRED_SOLAR_ELEVATION_CIVIL_DUSK_DAWN ),
-inclusively, other wise, this macro evaluates to 0. The input should be the
+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.
@@ -104,7 +104,7 @@ between
.B LIBRED_SOLAR_ELEVATION_ASTRONOMICAL_DUSK_DAWN
and
.BR LIBRED_SOLAR_ELEVATION_NAUTICAL_DUSK_DAWN ),
-inclusively, other wise, this macro evaluates to 0. The input should be the
+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.
diff --git a/doc/man/libred_get_colour.3 b/doc/man/libred_get_colour.3
index 5220067..c2a951a 100644
--- a/doc/man/libred_get_colour.3
+++ b/doc/man/libred_get_colour.3
@@ -63,8 +63,6 @@ The function may also fail for any reason specified for
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
diff --git a/doc/man/libred_solar_elevation.3 b/doc/man/libred_solar_elevation.3
index b87124a..05a4100 100644
--- a/doc/man/libred_solar_elevation.3
+++ b/doc/man/libred_solar_elevation.3
@@ -22,7 +22,7 @@ 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, not error is thrown if used.
+Other values may or may not work, no error is thrown if used.
.SH "RETURN VALUE"
Upon successful completion, the function sets
.B errno