From cde1926a3c65830bceed5e8e76cd94e81b19386c Mon Sep 17 00:00:00 2001
From: Tom Ryder <tom@sanctum.geek.nz>
Date: Fri, 26 Aug 2016 12:13:03 +1200
Subject: Put dotfiles manuals into their own section

This probably contains a few mistakes
---
 man/man1/apf.1df | 65 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 65 insertions(+)
 create mode 100644 man/man1/apf.1df

(limited to 'man/man1/apf.1df')

diff --git a/man/man1/apf.1df b/man/man1/apf.1df
new file mode 100644
index 00000000..6f8804e0
--- /dev/null
+++ b/man/man1/apf.1df
@@ -0,0 +1,65 @@
+.TH APF 1df "August 2016" "Manual page for apf"
+.SH NAME
+.B apf
+\- add arguments to a command from a file
+.SH SYNOPSIS
+.B apf
+foorc
+foo --bar baz
+.SH DESCRIPTION
+Add newline-delimited arguments read from a file to a command's arguments
+(before any given ones) before running it. This is intended as a quick way of
+implementing *rc files for interactive shell calls to programs that don't
+support such files, without having to use broken environment variables like GNU
+grep(1)'s GREP_OPTIONS.
+.P
+This enables you to use arguments with shell metacharacters and spaces in them
+that you do not want expanded. The only exception is that you cannot have
+newlines in any of the arguments. This was done to keep POSIX sh(1)
+compatibility.
+.P
+For example, given this simple program in our $PATH, printargs:
+.P
+    $ cat /usr/bin/printargs
+    #!/bin/sh
+    printf '%s\\n' "$@"
+.P
+Which just prints its arguments:
+.P
+    $ printargs a b c
+    a
+    b
+    c
+.P
+We could do this:
+.P
+    $ printf '%s\\n' -f --flag --option '? foo bar *' > "$HOME"/.printargsrc
+.P
+    $ apf "$HOME"/.printargsrc printargs a b c
+    -f
+    --flag
+    --option
+    ? foo bar *
+    a
+    b
+    c
+.P
+We could then make a permanent wrapper script in two line:
+.P
+    $ cat >~/.local/bin/printargs
+    #!/bin/sh
+    exec apf "$HOME"/.printargsrc /usr/bin/printargs
+    ^D
+    $ chmod +x ~/.local/bin/printargs
+.P
+Or just a shell function, if it's needed interactively:
+.P
+    $ printargs() { apf "$HOME"/.printargsrc printargs "$@" ; }
+.P
+It's not considered an error if the file doesn't exist or is empty. If it's a
+directory or otherwise not byte-readable, an error will be printed to stderr,
+but execution of the called program will continue anyway. Blank lines or lines
+beginning with # are also ignored. Both leading and trailing whitespace is
+preserved.
+.SH AUTHOR
+Tom Ryder <tom@sanctum.geek.nz>
-- 
cgit v1.2.3