Add man page for the gvpr library

diff --git a/lib/gvpr/Makefile.am b/lib/gvpr/Makefile.am
index edfe22771240642322264ac6435680e98626677c..702bb07df3d81cfdc4ae34375eea9e212165d096 100644 (file)
--- a/lib/gvpr/Makefile.am
+++ b/lib/gvpr/Makefile.am
@@ -25,6 +25,8 @@ noinst_HEADERS = actions.h compile.h gprstate.h parse.h queue.h trieFA.h trie.c
 noinst_LTLIBRARIES = libgvpr_C.la
 lib_LTLIBRARIES = libgvpr.la
 pkgconfig_DATA = libgvpr.pc
+man_MANS = libgvpr.3
+pdf_DATA = libgvpr.3.pdf
 
 libgvpr_C_la_SOURCES = actions.c compile.c gvpr.c gprstate.c parse.c queue.c 
 $(libgvpr_C_la_OBJECTS): gdefs.h
@@ -33,6 +35,9 @@ libgvpr_C_la_DEPENDENCIES = \
        $(top_builddir)/lib/common/libcommon_C.la \
        $(top_builddir)/lib/ingraphs/libingraphs_C.la
 
+libgvpr.3.pdf: $(srcdir)/libgvpr.3
+       - @GROFF@ -Tps -man $(srcdir)/libgvpr.3 | @PS2PDF@ - - >libgvpr.3.pdf
+
 
 libgvpr_la_LDFLAGS = -version-info $(GVPR_VERSION) -no-undefined
 libgvpr_la_SOURCES = $(libgvpr_C_la_SOURCES)

diff --git a/lib/gvpr/libgvpr.3 b/lib/gvpr/libgvpr.3
new file mode 100644 (file)
index 0000000..1c63b5c
--- /dev/null
+++ b/lib/gvpr/libgvpr.3
@@ -0,0 +1,70 @@
+.TH LIBGVPR 3 "15 OCTOBER 2013"
+.SH NAME
+\fBlibgvpr\fR \- library for graph filtering
+.SH SYNOPSIS
+.ta .75i 1.5i 2.25i 3i 3.75i 4.5i 5.25i 6i
+.PP
+.nf
+\f5
+#include <graphviz/gvpr.h>
+
+
+  /* If set, gvpr calls exit() on errors */
+#define GV_USE_EXIT 1
+  /* If set, gvpr stores output graphs in gvpropts */
+#define GV_USE_OUTGRAPH 2
+
+typedef ssize_t (*gvprwr) (void*, const char *buf, size_t nbyte, void*);
+
+typedef struct {
+    Agraph_t** ingraphs;      /* NULL-terminated array of input graphs */
+    int n_outgraphs;          /* if GV_USE_OUTGRAPH set, output graphs */
+    Agraph_t** outgraphs;
+    gvprwr out;               /* write function for stdout */
+    gvprwr err;               /* write function for stderr */
+    int flags;
+} gvpropts;
+
+extern int gvpr (int argc, char *argv[], gvpropts* opts);
+
+\fP
+.fi
+.SH DESCRIPTION
+The \fBgvpr\fP library allows an application to perform general-purpose
+graph manipulation and filtering based on an awk-like language. (For a more
+complete description of this language, see gvpr(1).) 
+.P
+The library has a single entry point: the \fIgvpr()\fP function. This provides a
+standard \fIargc/argv\fP interface, along with a structure to support
+in-core graphs, application print functions, along with additional options.
+.P
+When called, \fIgvpr()\fP processes any flags provided in the \fIargv\fP array, and compiles
+the \fBgvpr\fP program to be run (provided either via the \fI-f\fP flag or as an item
+in \fIargv\fP). It then runs the program on each input graph. If \fIopt->ingraphs\fP is
+non-NULL, this is taken as a NULL-terminated array of in-core graphs to be used as input.
+Otherwise, the unprocessed elements of \fIargv\fP are taken to be the names of files containing
+graphs to be processed. (If none remain, \fBgvpr\fP will read from stdin.)
+.P
+Normally, \fBgvpr\fP writes any output graph to stdout. However, if 
+the flag \fIGV_USE_OUTGRAPH\fP is set in \fIopts->flags\fP, the output graphs will be stored in
+an array pointed to be \fIopts->outgraphs\fP and the count will be stored in \fIopts->n_outgraphs\fP.
+In this case, the application must call \fIagclose()\fP on each output graph when it is done with
+it.
+.P
+The application can override the default write functions for stdout and stderr using the
+\fIout\fP and \fIerr\fP fields in \fIopts\fP. When called by \fBgvpr\fP, the second argument
+will point to a buffer of characters to be written, while the third argument provides the
+number of characters. The function should return the number of bytes actually written.
+.SH RETURN VALUES
+Normally, \fBgvpr\fP returns 0 on success and non-zero if an error occurs. Any relevant
+error message will have been written to stderr or the application's \fIopts->err\fP function will
+have been called. If, however, \fIGV_USE_EXIT\fP is set in \fIopts->flags\fP, \fBgvpr\fP will call
+exit(3) in case of an error.
+.SH SEE ALSO
+.BR gvpr (1),
+.BR awk (1),
+.BR cgraph (3)
+
+.SH AUTHORS
+Emden Gansner (erg@research.att.com).
+