Commit 738b375608c4a414a6b663a335daaff281b7305b

Stefan Sperling 2020-01-28T19:14:30

add gotweb(8) man page and move README info there; discussed with tracey

diff --git a/README b/README
index 1cb5da5..5061408 100644
--- a/README
+++ b/README
@@ -46,6 +46,7 @@ Man page files in the Got source tree can be viewed with 'man -l':
 
 EXAMPLES in got.1 contains a quick-start guide for OpenBSD developers.
 
+
 Game of Trees Web (Gotweb) is a CGI program which displays repository data
 and is designed to work with httpd(8) and slowcgi(8).
 
@@ -59,32 +60,13 @@ This will create the following files:
   the CGI program /var/www/cgi-bin/gotweb/gotweb
   helper programs from the libexec directory in /var/www/cgi-bin/gotweb/libexec
   several template files in /var/www/cgi-bin/gw_tmpl/
-  html, css, and image files in /var/www/htdocs/gotweb/gotweb/
+  html, css, and image files in /var/www/htdocs/gotweb/
   the directory /var/www/tmp/
   man pages (only installed if building sources from a Got release tarball)
 
-Example configuration for httpd.conf:
-
-  types { include "/usr/share/misc/mime.types" }
-  server "localhost" {
-  	listen on * port 80
-  	root "/htdocs/gotweb"
-  	location "/cgi-bin/*" {
-  		root "/"
-  		fastcgi
-  	}
-  	location "/*" {
-  		directory index "index.html"
-  	}
-  }
-
-httpd(8) and slowcgi(8) should be enabled and started:
-
-  # rcctl enable httpd slowcgi
-  # rcctl start httpd slowcgi
-
-Gotweb's run-time behaviour can be configured in the gotweb.conf file:
+Documentation is available in manual pages:
 
+ $ man -l gotweb/gotweb.8
  $ man -l gotweb/gotweb.conf.5
 
 
diff --git a/gotweb/Makefile b/gotweb/Makefile
index 3a1ae06..392a732 100644
--- a/gotweb/Makefile
+++ b/gotweb/Makefile
@@ -12,7 +12,7 @@ SRCS =		gotweb.c parse.y blame.c commit_graph.c delta.c diff.c \
 		privsep.c reference.c repository.c sha1.c worktree.c \
 		inflate.c buf.c rcsutil.c diff3.c lockfile.c \
 		deflate.c object_create.c delta_cache.c
-MAN =		${PROG}.conf.5
+MAN =		${PROG}.conf.5 ${PROG}.8
 
 CPPFLAGS +=	-I${.CURDIR}/../include -I${.CURDIR}/../lib -I${.CURDIR} \
 		-I${KCGIBASE}/include
diff --git a/gotweb/gotweb.8 b/gotweb/gotweb.8
new file mode 100644
index 0000000..c3edaa0
--- /dev/null
+++ b/gotweb/gotweb.8
@@ -0,0 +1,150 @@
+.\"
+.\" Copyright (c) 2020 Stefan Sperling
+.\"
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\"
+.Dd $Mdocdate$
+.Dt GOTWEB 8
+.Os
+.Sh NAME
+.Nm gotweb
+.Nd Game of Trees Git repository server for web browsers
+.Sh SYNOPSIS
+.Nm
+.Sh DESCRIPTION
+.Nm
+provides a simple web interface for read-only access to Git repositories,
+allowing repository contents to be viewed with a web browser.
+.Pp
+.Nm
+is a CGI program based on
+.Xr got 1
+and
+.Xr kcgi 3
+which is intended to run in a
+.Xr chroot 2
+environment in
+.Pa /var/www .
+The program has been designed to work out of the box with
+the
+.Xr httpd 8
+web server in conjunction with
+.Xr slowcgi 8 .
+.Pp
+Enabling
+.Nm
+requires the following steps:
+.Bl -enum
+.It
+The
+.Xr httpd.conf 5
+configuration file must be adjusted to run
+.Nm
+as a CGI program with
+.Xr slowcgi 8 .
+The
+.Sx EXAMPLES
+section below contains an appropriate configuration file sample.
+.It
+httpd(8) and slowcgi(8) must be enabled and started:
+.Bd -literal -offset indent
+  # rcctl enable httpd slowcgi
+  # rcctl start httpd slowcgi
+.Ed
+.It
+Optionally, the run-time behaviour of
+.Nm
+can be configured via the
+.Xr gotweb.conf 5
+configuration file.
+.It
+Git repositories must be created at a suitable location inside the
+web server's
+.Xr chroot 2
+environment.
+These repositories should
+.Em not
+be writable by the user ID of the
+.Xr httpd 8
+server.
+The default location for repositories published by
+.Nm
+is
+.Pa /var/www/got/public .
+.It
+Git repositories served by
+.Nm
+should be kept up-to-date with a mechanism such as
+.Xr git-fetch 1
+or
+.Xr rsync 1 ,
+scheduled by
+.Xr cron 8 .
+.El
+.Sh FILES
+.Bl -tag -width /var/www/got/public/ -compact
+.It Pa /var/www/got/public/
+Default location for Git repositories served by
+.Nm .
+This location can be adjusted in the
+.Xr gotweb.conf 5
+configuration file.
+.It Pa /var/www/cgi-bin/gotweb/gotweb
+The
+.Nm
+CGI program, statically linked for use in a
+.Xr chroot 2
+environment.
+.It Pa /var/www/cgi-bin/gotweb/gw_tmpl/
+Directory for template files used by
+.Nm .
+.It Pa /var/www/cgi-bin/gotweb/libexec/
+Directory containing statically linked
+.Xr got 1
+helper programs which are run by
+.Nm
+to read Git repositories.
+.It Pa /var/www/htdocs/gotweb/
+Directory containing HTML, CSS, and image files used by
+.Nm .
+.It Pa /var/www/tmp/
+Directory for temporary files created by
+.Nm .
+.El
+.Sh EXAMPLES
+Example configuration for httpd.conf:
+.Bd -literal -offset indent
+
+  types { include "/usr/share/misc/mime.types" }
+  server "gotweb.example.com" {
+  	listen on * port 80
+  	root "/htdocs/gotweb"
+  	location "/cgi-bin/*" {
+  		root "/"
+  		fastcgi
+  	}
+  	location "/*" {
+  		directory index "index.html"
+  	}
+  }
+.Ed
+.Sh SEE ALSO
+.Xr got 1 ,
+.Xr kcgi 3 ,
+.Xr git-repository 5 ,
+.Xr gotweb.conf 5 ,
+.Xr httpd 8 ,
+.Xr slowcgi 8
+.Sh AUTHORS
+.An Tracey Emery Aq Mt tracey@traceyemery.net
+.An Stefan Sperling Aq Mt stsp@openbsd.org