From 5fdffde89ad7a24001b8aa49c243fbbcd6fedbbf Mon Sep 17 00:00:00 2001 From: Mattias Andrée Date: Wed, 28 May 2014 06:17:08 +0200 Subject: info: errors MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Mattias Andrée --- Makefile | 27 +++++++++++++++++-------- info/libgamma-error-extract | 41 ++++++++++++++++++++++++++++++++++++++ info/libgamma.texinfo | 48 +++++++++++++++++++++++++++++++++++++++++++++ info/texise | 32 ++++++++++++++++++++++++++++++ 4 files changed, 140 insertions(+), 8 deletions(-) create mode 100755 info/libgamma-error-extract create mode 100755 info/texise 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 . + +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 }'' 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 . + +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) + -- cgit v1.2.3-70-g09d2