[gentoo-portage-dev] [PATCH 2/2] man/make.conf.5: Document globbing for INSTALL_MASK.

[Michael Orlitzky]

The INSTALL_MASK variable has long supported shell glob patterns, but
these were not mentioned in the man page. In fact there are two
different behaviors -- one for globs that the shell can expand, and
one for "bare globs" like "*.pdf". Both of these are now documented in
the man page.

In addition, a warning and example have been added to the man page
regarding spaces within filenames (patterns).
---
 man/make.conf.5 | 44 ++++++++++++++++++++++++++++++++++++--------
 1 file changed, 36 insertions(+), 8 deletions(-)

diff --git a/man/make.conf.5 b/man/make.conf.5
index a7417f3..13b8042 100644
--- a/man/make.conf.5
+++ b/man/make.conf.5
@@ -699,14 +699,42 @@ These variables are used by network clients such as \fBwget\fR(1) and
 \fBrsync\fR(1). They are only required if you use a
 proxy server for internet access.
 .TP
-\fBINSTALL_MASK\fR = \fI[space delimited list of file names]\fR
-Use this variable if you want to selectively prevent certain files from being
-copied into your file system tree.  This does not work on symlinks, but only on
-actual files.  Useful if you wish to filter out files like HACKING.gz and
-TODO.gz. The \fBINSTALL_MASK\fR is processed just before a package is merged.
-Also supported is a \fBPKG_INSTALL_MASK\fR variable that behaves exactly like
-\fBINSTALL_MASK\fR except that it is processed just before creation of a binary
-package.
+\fBINSTALL_MASK\fR = \fI[space delimited list of filename patterns (globs)]\fR
+Use this variable if you want to selectively prevent certain files
+from being copied into your file system tree.  This does not work on
+symlinks, but only on actual files. Useful if you wish to filter out
+files like HACKING.gz and TODO.gz.
+
+Patterns are matched against both the absolute path and the bare
+filename of each file (or directory) to be installed.
+
+The \fBINSTALL_MASK\fR is processed just before a package is merged.
+Also supported is a \fBPKG_INSTALL_MASK\fR variable that behaves
+exactly like \fBINSTALL_MASK\fR except that it is processed just
+before creation of a binary package.
+
+\fB***warning***\fR
+.br
+This does not place nice with filenames containing spaces. If you
+supply a pattern with a space in it, that single pattern will be
+interpreted as two separate patterns.
+
+.I Examples:
+
+.nf
+# Prevent individual files from being installed.
+INSTALL_MASK="/usr/bin/zless /usr/bin/zzxorcat"
+
+# Prevent all PDF files from being installed.
+INSTALL_MASK="*.pdf"
+
+# Block PDF files one level beneath /usr/share/doc.
+INSTALL_MASK="/usr/share/doc/*/*.pdf"
+
+# Watch out! This will be interpreted as two patterns, and
+# prevent both "README" AND all PDF files from being installed.
+INSTALL_MASK="README\\ *.pdf"
+.fi
 .TP
 .B LDFLAGS
 A list of flags to pass to the compiler when the linker will be called. See
-- 
2.3.6