add libred_solar_elevation.3

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

1 files changed, 65 insertions, 0 deletions

diff --git a/doc/man/libred_solar_elevation.3 b/doc/man/libred_solar_elevation.3
new file mode 100644
index 0000000..b87124a
--- /dev/null
+++ b/doc/man/libred_solar_elevation.3
@@ -0,0 +1,65 @@
+.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, not 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)
+.SH LICENSE
+Copyright \(co 2016  Mattias Andrée
+.br
+License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+.br
+There is NO WARRANTY, to the extent permitted by law.
+.PP
+Copying and distribution of this manual, with or without modification,
+are permitted in any medium without royalty provided the copyright
+notice and this notice are preserved.  This file is offered as-is,
+without any warranty.
+.SH BUGS
+Please report bugs to <https://github.com/maandree/libred/issues>
+or to <maandree@member.fsf.org>.
+