info: errors

Signed-off-by: Mattias Andrée <maandree@operamail.com>

4 files changed, 140 insertions, 8 deletions

diff --git a/Makefile b/Makefile
index 8870cfe..377d98e 100644
--- a/Makefile
+++ b/Makefile
@@ -28,6 +28,9 @@ LICENSEDIR ?= $(DATADIR)/licenses
 # The name of the package as it should be installed.
 PKGNAME ?= libgamma
 
+# General-preprocess command. (https://github.com/maandree/gpp)
+GPP ?= gpp
+
 
 # Enabled warnings.
 WARN = -Wall -Wextra -pedantic -Wdouble-promotion -Wformat=2 -Winit-self       \
@@ -53,8 +56,11 @@ LIBS_C =
 # Object files for the library.
 LIBOBJ = libgamma-facade libgamma-method libgamma-error gamma-helper edid
 
+# Header files for the library are parsed for the info manual.
+HEADERS_INFO = libgamma-error libgamma-facade libgamma-method
+
 # Header files for the library, as installed.
-HEADERS = libgamma libgamma-config libgamma-error libgamma-facade libgamma-method
+HEADERS = libgamma libgamma-config $(HEADERS_INFO)
 
 # Object files for the test.
 TESTOBJ = test
@@ -134,29 +140,34 @@ obj/%.o: test/%.c
 .PHONY: doc
 doc: info pdf dvi ps
 
+obj/libgamma.texinfo: info/libgamma.texinfo $(foreach H,$(HEADERS_INFO),src/$(H).h)
+	mkdir -p obj
+	$(GPP) --symbol '£' --input $< --output $@
+
+obj/%.texinfo: info/%.texinfo
+	mkdir -p obj
+	cp $< $@
+
 .PHONY: info
 info: libgamma.info
-%.info: info/%.texinfo info/fdl.texinfo
+%.info: obj/%.texinfo obj/fdl.texinfo
 	makeinfo $<
 
 .PHONY: pdf
 pdf: libgamma.pdf
-%.pdf: info/%.texinfo info/fdl.texinfo
-	mkdir -p obj
+%.pdf: obj/%.texinfo obj/fdl.texinfo
 	cd obj ; yes X | texi2pdf ../$<
 	mv obj/$@ $@
 
 .PHONY: dvi
 dvi: libgamma.dvi
-%.dvi: info/%.texinfo info/fdl.texinfo
-	mkdir -p obj
+%.dvi: obj/%.texinfo obj/fdl.texinfo
 	cd obj ; yes X | $(TEXI2DVI) ../$<
 	mv obj/$@ $@
 
 .PHONY: ps
 ps: libgamma.ps
-%.ps: info/%.texinfo info/fdl.texinfo
-	mkdir -p obj
+%.ps: obj/%.texinfo obj/fdl.texinfo
 	cd obj ; yes X | texi2pdf --ps ../$<
 	mv obj/$@ $@
 
diff --git a/info/libgamma-error-extract b/info/libgamma-error-extract
new file mode 100755
index 0000000..3f4aa1f
--- /dev/null
+++ b/info/libgamma-error-extract
@@ -0,0 +1,41 @@
+#!/usr/bin/env python3
+# -*- python -*-
+
+# libgamma — Display server abstraction layer for gamma ramp adjustments
+# Copyright © 2014  Mattias Andrée (maandree@member.fsf.org)
+# 
+# This library is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+# 
+# This library is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+# 
+# You should have received a copy of the GNU General Public License
+# along with this library.  If not, see <http://www.gnu.org/licenses/>.
+
+import sys
+import os
+
+with open(os.path.dirname(sys.argv[0]) + '/../src/libgamma-error.h', 'rb') as file:
+    data = file.read()
+data = data.decode('utf-8', 'error')
+
+if sys.argv[1] == '--list':
+    defs = [line for line in data.split('\n') if line.startswith('#define') and not line.endswith('_H')]
+    defs = [line.split(' ')[1] for line in defs if 'LIBGAMMA_ERROR_MIN' not in line]
+    print('\n'.join(defs))
+
+else:
+    i = data.find('\n#define ' + sys.argv[1])
+    data = data[:i]
+    i = data.rfind('\n */')
+    data = data[:i]
+    i = data.rfind('/**\n')
+    data = data[i + len('/**\n'):]
+    data = [line[3:] for line in data.split('\n')]
+    print('\n'.join(data))
+
diff --git a/info/libgamma.texinfo b/info/libgamma.texinfo
index 1869145..2a7ea57 100644
--- a/info/libgamma.texinfo
+++ b/info/libgamma.texinfo
@@ -29,6 +29,9 @@ Texts. A copy of the license is included in the section entitled
 @end quotation
 @end copying
 
+£>set -u
+£>cd info
+
 @ifnottex
 @node Top
 @top libgamma -- Display server abstraction layer for gamma ramp adjustments
@@ -382,6 +385,10 @@ and for the freedom of all.
 @node API
 @chapter API
 
+@menu
+* Errors::                          Error codes and how to handle errors.
+@end menu
+
 To use @command{libgamma} add ``@code{#include <libgamma.h>}''
 to and C file or C header file that requires anything
 from @command{libgamma}. @file{libgamma.h} is the only
@@ -446,6 +453,47 @@ You may also want to add checks for update to
 
 
 
+@node Errors
+@section Errors
+
+Many @command{libgamma} functions will return
+@command{libgamma} specific error codes rather
+than setting @code{errno} and return @code{-1}.
+However @code{errno} may have been set, but
+should in such case be ignored unless
+@code{LIBGAMMA_ERRNO_SET} has been returned.
+Other functions do set @code{errno} and return
+@code{-1}. Other functions may store the error
+code. In this case @code{LIBGAMMA_ERRNO_SET}
+cannot be stored but the value that @code{errno}
+had when an error occured can be stored instead
+of a @command{libgamma} specific error codes.
+@code{errno} values are allows positive whereas
+@command{libgamma} specific error codes are
+allows negative. On success zero is returned
+or stored.
+
+If @code{LIBGAMMA_DEVICE_REQUIRE_GROUP} is returned
+the ID of the required group is stored in
+@code{libgamma_group_gid} and the name of that
+group is stored in @code{libgamma_group_name}.
+@code{NULL} is stored if the name of the group
+cannto be determined. @file{libgamma.h} give
+you access to these variables, they are defined
+as @code{gid_t} and @code{const char*} types
+respectively.
+
+@command{libgamma} defines the following error codes
+that its functions may return:
+@table @code
+£>for err in $(libgamma-error-extract --list); do
+@item £{err}
+£>libgamma-error-extract $err | texise
+£>done
+@end table
+
+
+
 @node GNU Free Documentation License
 @appendix GNU Free Documentation License
 @include fdl.texinfo
diff --git a/info/texise b/info/texise
new file mode 100755
index 0000000..c778777
--- /dev/null
+++ b/info/texise
@@ -0,0 +1,32 @@
+#!/usr/bin/env python3
+# -*- python -*-
+
+# libgamma — Display server abstraction layer for gamma ramp adjustments
+# Copyright © 2014  Mattias Andrée (maandree@member.fsf.org)
+# 
+# This library is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+# 
+# This library is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+# 
+# You should have received a copy of the GNU General Public License
+# along with this library.  If not, see <http://www.gnu.org/licenses/>.
+
+import sys
+
+data = sys.stdin.read()[:-1]
+
+n = 0
+while '`' in data:
+    i = data.find('`')
+    replacement = '@code{' if n % 2 == 0 else '}'
+    data = data[:i] + replacement + data[i + 1:]
+    n += 1
+
+print(data)
+