m + texinfo manual

Signed-off-by: Mattias Andrée <maandree@member.fsf.org>

1 files changed, 155 insertions, 0 deletions

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
+