Add man pages

Signed-off-by: Mattias Andrée <maandree@kth.se>

12 files changed, 344 insertions, 2 deletions

diff --git a/Makefile b/Makefile
index f0f17e9..f699cc3 100644
--- a/Makefile
+++ b/Makefile
@@ -20,6 +20,17 @@ OBJ =\
 HDR =\
 	libparsepsf.h
 
+MAN0 =\
+	libparsepsf.h.0
+
+MAN3 =\
+	libparsepsf_destroy_font.3\
+	libparsepsf_get_glyph.3\
+	libparsepsf_parse_font.3
+
+MAN7 =\
+	libparsepsf.7
+
 
 all: libparsepsf.a libparsepsf.$(LIBEXT) demo
 $(OBJ): $(HDR)
@@ -45,12 +56,18 @@ demo: demo.o libparsepsf.a
 install: libparsepsf.a
 	mkdir -p -- "$(DESTDIR)$(PREFIX)/lib"
 	mkdir -p -- "$(DESTDIR)$(PREFIX)/include"
+	mkdir -p -- "$(DESTDIR)$(MANPREFIX)/man0"
+	mkdir -p -- "$(DESTDIR)$(MANPREFIX)/man3"
+	mkdir -p -- "$(DESTDIR)$(MANPREFIX)/man7"
 	cp -- libparsepsf.a "$(DESTDIR)$(PREFIX)/lib"
 	cp -- libparsepsf.$(LIBEXT) "$(DESTDIR)$(PREFIX)/lib/libparsepsf.$(LIBMINOREXT)"
 	$(FIX_INSTALL_NAME) "$(DESTDIR)$(PREFIX)/lib/libparsepsf.$(LIBMINOREXT)"
 	ln -sf -- "libparsepsf.$(LIBMINOREXT)" "$(DESTDIR)$(PREFIX)/lib/libparsepsf.$(LIBMAJOREXT)"
 	ln -sf -- "libparsepsf.$(LIBMAJOREXT)" "$(DESTDIR)$(PREFIX)/lib/libparsepsf.$(LIBEXT)"
 	cp -- libparsepsf.h "$(DESTDIR)$(PREFIX)/include"
+	cp -P -- $(MAN0) "$(DESTDIR)$(MANPREFIX)/man0"
+	cp -P -- $(MAN3) "$(DESTDIR)$(MANPREFIX)/man3"
+	cp -P -- $(MAN7) "$(DESTDIR)$(MANPREFIX)/man7"
 
 uninstall:
 	-rm -f -- "$(DESTDIR)$(PREFIX)/lib/libparsepsf.a"
@@ -58,6 +75,9 @@ uninstall:
 	-rm -f -- "$(DESTDIR)$(PREFIX)/lib/libparsepsf.$(LIBMAJOREXT)"
 	-rm -f -- "$(DESTDIR)$(PREFIX)/lib/libparsepsf.$(LIBMINOREXT)"
 	-rm -f -- "$(DESTDIR)$(PREFIX)/include/libparsepsf.h"
+	-cd -- "$(DESTDIR)$(MANPREFIX)/man0" && rm -f -- $(MAN0)
+	-cd -- "$(DESTDIR)$(MANPREFIX)/man3" && rm -f -- $(MAN3)
+	-cd -- "$(DESTDIR)$(MANPREFIX)/man7" && rm -f -- $(MAN7)
 
 clean:
 	-rm -f -- *.o *.lo *.su *.a *.so *.so.* demo
diff --git a/README b/README
index 96de825..f4295db 100644
--- a/README
+++ b/README
@@ -1 +1,12 @@
-libparsepsf is a C library for interpreting PSF (PC Screen Font) files.
+NAME
+	libparsepsf - Library for interpreting PSF (PC Screen Font) files.
+
+DESCRIPTION
+	libparsepsf is a C library for interpreting PSF (PC Screen Font) files.
+	It can be used to examine the contents of a font file, and look up
+	glyphs to use a for a text. It is not rendering text, instead
+	the user is given enough information to implement it's own rendering;
+	nor is the library capable of creating PSF files.
+
+SEE ALSO
+	None
diff --git a/libparsepsf.7 b/libparsepsf.7
new file mode 100644
index 0000000..32b8e66
--- /dev/null
+++ b/libparsepsf.7
@@ -0,0 +1,15 @@
+.TH LIBPARSEPSF 7 LIBPARSEPSF
+.SH NAME
+libparsepsf \- Library for interpreting PSF (PC Screen Font) files.
+.SH DESCRIPTION
+.B libparsepsf
+is a C library for interpreting PSF (PC Screen Font) files.
+It can be used to examine the contents of a font file, and look up
+glyphs to use a for a text. It is not rendering text, instead
+the user is given enough information to implement it's own rendering;
+nor is the library capable of creating PSF files.
+.SH SEE ALSO
+.BR libparsepsf.h (0),
+.BR libparsepsf_parse_font (3),
+.BR libparsepsf_get_glyph (3),
+.BR libparsepsf_destroy_font (3)
diff --git a/libparsepsf.h b/libparsepsf.h
index 74b229b..8e98789 100644
--- a/libparsepsf.h
+++ b/libparsepsf.h
@@ -60,7 +60,7 @@ struct libparsepsf_font {
 	/**
 	 * Glyph trie, maps from byte sequences to glyph indices;
 	 * you can use `libparsepsf_get_glyph` to search it
-	 * (enumeration has to be done manually); not that an
+	 * (enumeration has to be done manually); note that an
 	 * entry can be multiple characters wide, for example
 	 * to deal with context dependent glyphs and grapheme
 	 * clusters
diff --git a/libparsepsf.h.0 b/libparsepsf.h.0
new file mode 100644
index 0000000..b3193eb
--- /dev/null
+++ b/libparsepsf.h.0
@@ -0,0 +1,39 @@
+.TH LIBPARSEPSF.H 0 LIBPARSEPSF
+.SH NAME
+libparsepsf.h \- Header file for interpreting PSF (PC Screen Font) files.
+.SH SYNOPSIS
+.nf
+#include <libparsepsf.h>
+.fi
+.PP
+Link with
+.IR -lparsepsf .
+.SH DESCRIPTION
+The
+.B <libparsepsf.h>
+header defines structures and functions for interpreting PSF
+(PC Screen Font) files.
+.PP
+This header defines the following functions:
+.TP
+.BR libparsepsf_parse_font (3)
+Parse a PSF file.
+.TP
+.BR libparsepsf_get_glyph (3)
+Get glyph to use at a position in a text string.
+.TP
+.BR libparsepsf_destroy_font (3)
+Deallocate a parsed PSF file.
+.PP
+This header defines the following structures:
+.TP
+.B struct libparsepsf_font
+Structure containing all font information.
+.TP
+.B struct libparsepsf_unimap
+Node for byte-sequence-to-glyph mapping trie.
+.SH SEE ALSO
+.BR libparsepsf (7),
+.BR libparsepsf_parse_font (3),
+.BR libparsepsf_get_glyph (3),
+.BR libparsepsf_destroy_font (3)
diff --git a/libparsepsf_destroy_font.3 b/libparsepsf_destroy_font.3
new file mode 100644
index 0000000..8763e3c
--- /dev/null
+++ b/libparsepsf_destroy_font.3
@@ -0,0 +1,26 @@
+.TH LIBPARSEPSF_DESTROY_FONT 3 LIBPARSEPSF
+.SH NAME
+libparsepsf_destroy_font \- Deallocate a parsed PSF files
+.SH SYNOPSIS
+.nf
+#include <libparsepsf.h>
+
+void libparsepsf_destroy_font(struct libparsepsf_font *\fIfont\fP);
+.fi
+.PP
+Link with
+.IR -lparsepsf .
+.SH DESCRIPTION
+The
+.B libparsepsf_destroy_font
+function deallocates the contents of
+.IR *font ,
+without deallocating the memory that the pointer
+itself points to directly (only memory pointed
+to by nested pointers).
+.SH RETURN VALUE
+None.
+.SH ERRORS
+None.
+.SH SEE ALSO
+.BR libparsepsf_parse_font (3)
diff --git a/libparsepsf_font.3 b/libparsepsf_font.3
new file mode 120000
index 0000000..21a36bb
--- /dev/null
+++ b/libparsepsf_font.3
@@ -0,0 +1 @@
+struct_libparsepsf_font.3
\ No newline at end of file
diff --git a/libparsepsf_get_glyph.3 b/libparsepsf_get_glyph.3
new file mode 100644
index 0000000..bb2c481
--- /dev/null
+++ b/libparsepsf_get_glyph.3
@@ -0,0 +1,94 @@
+.TH LIBPARSEPSF_GET_GLYPH 3 LIBPARSEPSF
+.SH NAME
+libparsepsf_get_glyph \- Get glyph to use in a position in a text
+.SH SYNOPSIS
+.nf
+#include <libparsepsf.h>
+
+size_t libparsepsf_get_glyph(struct libparsepsf_font *\fIfont\fP, const char *\fIc\fP, size_t *\fIremp\fP, const char **\fInext_cp\fP);
+.fi
+.PP
+Link with
+.IR -lparsepsf .
+.SH DESCRIPTION
+The
+.B libparsepsf_get_glyph
+function gets the next glyph to print for a line of text.
+.PP
+.I font
+be a parsed font: created with
+.BR libparsepsf_parse_font (3).
+.PP
+.I c
+shall be the current position in the text, and either
+.I remp
+shall be
+.I NULL
+or
+.I *remp
+shall be the number of bytes remaining in the text.
+.PP
+Upon successful completion, the number of bytes
+read from
+.I c
+will be subtracted from
+.IR *remp
+(unless
+.I remp
+is
+.IR NULL ),
+and, unless
+.I next_cp
+is
+.I NULL,
+.I *next_cp
+will be set to
+.I &c[n]
+where
+.I n
+is the number of bytes in the byte-sequence for the
+returned glyph.
+.PP
+If and only if
+.I remp
+is
+.IR NULL ,
+the
+.B libparsepsf_get_glyph
+function will assume the text ends at the first NUL byte.
+.PP
+.I *remp
+and
+.I *next_cp
+are only updated if the function returns a non-zero value.
+.SH RETURN VALUE
+The
+.B libparsepsf_get_glyph
+function returned a glyph index, plus 1, upon successful
+completion, or 0 if the end of the text has been reached
+or if there is no glyph for the current position. On
+failure the function returns 0 and sets
+.I errno
+appropriately to indicate the error.
+.SH ERRORS
+The
+.B libparsepsf_get_glyph
+function may fail if:
+.TP
+.B EILSEQ
+If
+.I font->map
+is
+.I NULL
+and an illegal byte sequence was found.
+.SH NOTE
+A sequence of multiple characters can be rendered as a
+single glyph, therefore it is important that the entire
+text line has been loaded and there all characters on
+the line in prior positions have been mapped.
+.PP
+The
+.B libparsepsf_get_glyph
+function does not treat <newline> especially.
+.SH SEE ALSO
+.BR libparsepsf_parse_font (3)
diff --git a/libparsepsf_parse_font.3 b/libparsepsf_parse_font.3
new file mode 100644
index 0000000..7fe22b8
--- /dev/null
+++ b/libparsepsf_parse_font.3
@@ -0,0 +1,133 @@
+.TH LIBPARSEPSF_PARSE_FONT 3 LIBPARSEPSF
+.SH NAME
+libparsepsf_parse_font \- Parse the contents of a PSF file
+.SH SYNOPSIS
+.nf
+#include <libparsepsf.h>
+
+struct libparsepsf_unimap {
+        struct libparsepsf_unimap *\fInonterminal\fP[256];
+        size_t \fIterminal\fP[256];
+};
+
+struct libparsepsf_font {
+        size_t \fInum_glyphs\fP;
+        size_t \fIheight\fP;
+        size_t \fIwidth\fP;
+        uint8_t *\fIglyph_data\fP;
+        struct libparsepsf_unimap *\fImap\fP;
+};
+
+int libparsepsf_parse_font(const void *\fIdata\fP, size_t \fIsize\fP, struct libparsepsf_font *\fIfontp\fP, uint32_t *\fIunrecognised_versionp\fP);
+.fi
+.PP
+Link with
+.IR -lparsepsf .
+.SH DESCRIPTION
+The
+.B libparsepsf_parse_font
+parses the contents of a PSF (PC Screen Font) file,
+and output the information in the file, in
+.IR *fontp
+upon successful completion, which should be deallocated
+using the
+.BR libparsepsf_destroy_font (3)
+function when it is no longer needed. On failure
+.IR *fontp
+is set so that
+.BR libparsepsf_destroy_font (3)
+can be called without any side-effects.
+.PP
+.I data
+shall contain the content contents of the entire
+font file, and
+.I size
+shall be set to the number of bytes in the font file.
+.PP
+.I *unrecognised_versionp
+is normally set to 0, however, if the minor format
+version used by the font file is not recognised,
+.I *unrecognised_versionp
+will be set to that number.
+.I *unrecognised_versionp
+being set to a non-zero number, does not indicate
+failure as it is assumed that backwards-compatibility
+exists within major format versions.
+.PP
+No argument may be
+.IR NULL .
+.PP
+.I fontp->num_glyph
+will be set to the number of glyphs in the font,
+.I fontp->width
+will be set to the bit-width of each glyph in the font,
+.I fontp->height
+will be set to the bit-height of each glyph in the font,
+.I fontp->glyph_data
+will contain the glyphs in the font, and
+.I fontp->map
+will either be set to
+.I NULL
+or a trie that maps byte sequences to glyph indices.
+.PP
+If
+.I fontp->map
+is
+.IR NULL ,
+unicode character points map directly (identity mapping)
+to glyph indices; and UTF-8 the assumed encoding; otherwise
+.I fontp->map
+maps byte sequences (from an unspecified encoding, usually
+UTF-8) to glyph indices.
+.I fontp->map
+can be searched using the
+.BR libparsepsf_get_glyph (3)
+function, but enumeration must be done manually. Note that
+an entry can be multiple characters wide, for example to
+deal with context dependent glyphs and grapheme clusters.
+In each node in the trie,
+.IR nonterminal[b] ,
+for a byte
+.IR b ,
+maps either to
+.I NULL
+if there is no glyph for a continuation on the current
+byte sequence, or to a trie-node for the byte in the
+byte sequence. Regardless of the value of
+.IR nonterminal[b] ,
+.I terminal[b] ,
+may map either to 0, if there is no glyph for the current
+byte sequence, or the glyph index, plus 1, for the current
+byte sequence.
+.PP
+.I fontp->glyph_data
+is a ordered array of glyph, where is glyph is oriented in
+row-major and most-significant-bit-first order, but each
+row is also right-padded to a multiple of 8 bits, meaning
+that the bit 0x80 in the first byte for a glyph represents
+the left-most, top-most bit in the, and 0x40 in the same
+byte represents the bit directly right to it. Bit on means
+ink on, bit off means ink off. For a glyph index
+.IR i ,
+.I &fontp->glyph_data[i*(fontp->height*(fontp->width/8+(fontp->width%8>0)))]
+maps to the start of the glyph with that index.
+.SH RETURN VALUE
+The
+.B libparsepsf_parse_font
+function returns 0 upon successful completion.
+On failure, -1 is returned and
+.I errno
+is set appropriately to indicate the error.
+.SH ERRORS
+The
+.B libparsepsf_parse_font
+function may fail if:
+.TP
+.B ENOMEM
+The function failed to allocate enough memory.
+.TP
+.B EBFONT
+The font file is corrupt or unsupported.
+.SH SEE ALSO
+.BR libparsepsf_destroy_font (3),
+.BR libparsepsf_get_glyph (3)
diff --git a/libparsepsf_unimap.3 b/libparsepsf_unimap.3
new file mode 120000
index 0000000..21a36bb
--- /dev/null
+++ b/libparsepsf_unimap.3
@@ -0,0 +1 @@
+struct_libparsepsf_font.3
\ No newline at end of file
diff --git a/struct_libparsepsf_font.3 b/struct_libparsepsf_font.3
new file mode 120000
index 0000000..14403d3
--- /dev/null
+++ b/struct_libparsepsf_font.3
@@ -0,0 +1 @@
+libparsepsf_parse_font.3
\ No newline at end of file
diff --git a/struct_libparsepsf_unimap.3 b/struct_libparsepsf_unimap.3
new file mode 120000
index 0000000..21a36bb
--- /dev/null
+++ b/struct_libparsepsf_unimap.3
@@ -0,0 +1 @@
+struct_libparsepsf_font.3
\ No newline at end of file