Revamp documentation, add manpages

6 files changed, 151 insertions, 19 deletions

diff --git a/.gitignore b/.gitignore
index 913367e..76ea7d6 100644
--- a/.gitignore
+++ b/.gitignore
@@ -2,3 +2,4 @@ pcu-mincore
 pcu-fadvise
 *.tar.gz
 GIT-VERSION-FILE
+*.1
diff --git a/INSTALL b/INSTALL
new file mode 100644
index 0000000..011e178
--- /dev/null
+++ b/INSTALL
@@ -0,0 +1,37 @@
+Installing page cache utilities
+===============================
+
+Dependencies
+------------
+
+These utilities are dependent on the posix_fadvise and mincore syscalls.
+
+pcu-fadvise needs a kernel that supports the posix_fadvise(2) syscall and C
+library support.  For GNU/Linux systems, this means you'll need a kernel
+newer than 2.5.60 and the GNU C library 2.2 or later.
+
+pcu-mincore should work on most somewhat-modern UNIX/UNIX-like kernels that
+support the mincore(2) system call.  While the mincore(2) system call is not
+specified by current versions of POSIX, it is fairly common.
+
+Standard build tools such as a C compiler, GNU make, install are required.
+
+If you wish to build and install the manpages, you'll also need the txt2man
+utility available here: http://mvertes.free.fr/download/
+The documentation is otherwise viewable in plain text form.
+
+Instructions
+------------
+
+To install executables into your home directory in ~/bin:
+
+  $ make
+  $ make install
+
+To install executables globally in /usr/local/bin:
+
+  $ make ; # as yourself
+  # make install prefix=/usr/local/bin ; # as root
+
+All pcu-* executables are relocatable and have no dependencies outside
+of the system C library and kernel support for the syscalls they need.
diff --git a/Makefile b/Makefile
index 1c410c2..64b0154 100644
--- a/Makefile
+++ b/Makefile
@@ -5,6 +5,13 @@ prefix = $(HOME)
 bindir = $(prefix)/bin
 mandir = $(prefix)/share/man
 INSTALL = install
+TXT2MAN = txt2man
+STRIP ?= strip
+GIT-VERSION-FILE: .FORCE-GIT-VERSION-FILE
+        @./GIT-VERSION-GEN
+-include GIT-VERSION-FILE
+
+DISTNAME = pcu-$(GIT_VERSION)
 
 # overridable from command-line
 CFLAGS = -g -O2 -Wall -D_LARGEFILE64_SOURCE -D_FILE_OFFSET_BITS=64
@@ -28,17 +35,31 @@ install: $(PCU_BIN)
         $(INSTALL) -d -m 755 '$(DESTDIR)$(bindir)'
         $(INSTALL) $^ '$(DESTDIR)$(bindir)'
 
-GIT-VERSION-FILE: .FORCE-GIT-VERSION-FILE
-        @./GIT-VERSION-GEN
--include GIT-VERSION-FILE
+strip: $(PCU_BIN)
+        $(STRIP) $(STRIP_OPTS) $(PCU_BIN)
+
+install-strip: strip
+        $(MAKE) install
+
+%.1: %.1.txt
+        $(TXT2MAN) -r 'pcu $(GIT_VERSION)' \
+          -v 'Page Cache Utilities Reference Manual' \
+          -t $(basename $@) -s 1 < $< > $@+
+        mv $@+ $@
+
+man1 := $(addsuffix .1,$(PCU_BIN))
+man: $(man1)
+install-man: install-man1
+install-man1: $(man1)
+        $(INSTALL) -d -m 755 '$(DESTDIR)$(mandir)/man1'
+        $(INSTALL) $^ '$(DESTDIR)$(mandir)/man1'
 
-DISTNAME = pcu-$(GIT_VERSION)
 dist: GIT-VERSION-FILE
         git archive --format=tar --prefix=$(DISTNAME)/ HEAD^{tree} \
                 | gzip -9 > $(DISTNAME).tar.gz+
         mv $(DISTNAME).tar.gz+ $(DISTNAME).tar.gz
 clean:
-        $(RM) $(PCU_BIN) $(DISTNAME).tar.gz*
-        $(RM) GIT-VERSION-FILE
+        $(RM) $(PCU_BIN) $(DISTNAME).tar.gz* GIT-VERSION-FILE
+        $(RM) $(man1)
 
-.PHONY: .FORCE-GIT-VERSION-FILE
+.PHONY: .FORCE-GIT-VERSION-FILE install install-man man
diff --git a/README b/README
index 3e73b72..4ce7335 100644
--- a/README
+++ b/README
@@ -1,15 +1,10 @@
-command-line utils for viewing/managing the Linux page cache
+page cache utilities
+====================
 
-pcu-mincore - shows the pages in the page cache for given files
+This package contains command-line utilities for viewing/managing the
+kernel page cache.
 
-        pcu-mincore <files>
+* pcu-fadvise - runs posix_fadvise(2) on given files
+* pcu-mincore - shows the pages in the page cache for given files
 
-
-pcu-fadvise - runs posix_fadvise(2) on a given file
-
-        pcu-fadvise [-a advice] [-o offset] [-l length] <files>
-
-        advice can be one of:
-          normal, sequential, random, noreuse, willneed, dontneed
-
-See posix_fadvise(2) and mincore(2) manpages for more details.
+See manpages for the individual commands for more details.
diff --git a/pcu-fadvise.1.txt b/pcu-fadvise.1.txt
new file mode 100644
index 0000000..e7f26a9
--- /dev/null
+++ b/pcu-fadvise.1.txt
@@ -0,0 +1,44 @@
+NAME
+  pcu-fadvise - predeclare an access pattern on given files
+SYNOPSIS
+  pcu-fadvise [-a advice] [-o offset] [-l length] FILE...
+DESCRIPTION
+  A command-line interface to the posix_fadvise(2) syscall to tell
+  the kernel to optimize access patterns for specified files.
+OPTIONS
+  -a advice
+
+  File access pattern advice.
+  The advice must be one of the following:
+
+    normal
+    sequential
+    random
+    noreuse
+    willneed
+    dontneed
+
+  The default advice is normal.
+
+  -o offset
+
+  Apply advice only to the given byte offset.
+  This offset rounded down to the previous page offset.
+  The default offset is zero (beginning of the file)
+
+  -l length
+
+  Apply advice only to the given length in bytes.
+  This length is rounded up next page offset.
+  The default is to scan the entire file.
+
+OUTPUT
+  Errors only.
+ENVIRONMENT
+  none
+SEE ALSO
+  posix_fadvise(2), pcu(7)
+BUGS
+  None known. Email the author if you find any.
+AUTHOR
+  Eric Wong <normalperson@yhbt.net>
diff --git a/pcu-mincore.1.txt b/pcu-mincore.1.txt
new file mode 100644
index 0000000..e095621
--- /dev/null
+++ b/pcu-mincore.1.txt
@@ -0,0 +1,34 @@
+NAME
+  pcu-mincore - shows cache status for given files
+SYNOPSIS
+  pcu-mincore [-o offset] [-l length] FILE...
+DESCRIPTION
+  A command-line interface to the mincore(2) syscall to inspect
+  whether or not certain pages belonging to a file are cached in
+  resident memory.
+OPTIONS
+  -o offset
+
+  Scan only pages on or after the given offset.
+  This offset is rounded down to the previous page offset.
+  The default offset is zero (beginning of the file)
+
+  -l length
+
+  Check only the given length in bytes.
+  This length is rounded up next page offset.
+  The default is to scan the entire file.
+OUTPUT
+  One line for every page scanned in the following format:
+
+  <filename>: <offset> <incore>
+
+  offset is a hexadecimal number for a given range of PAGE_SIZE bytes.
+  incore is a boolean value indicating whether or not the page beginning
+  at a particular offset is cached in resident memory or not.
+SEE ALSO
+  mincore(2), pcu(7)
+BUGS
+  None known. Email the author if you find any.
+AUTHOR
+  Eric Wong <normalperson@yhbt.net>