python setup.py build_man

1 files changed, 35 insertions, 9 deletions

diff --git a/docs/man/borg-patterns.1 b/docs/man/borg-patterns.1
index b4c71a172..0b36bccf5 100644
--- a/docs/man/borg-patterns.1
+++ b/docs/man/borg-patterns.1
@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-PATTERNS 1 "2017-12-30" "" "borg backup tool"
+.TH BORG-PATTERNS 1 "2018-03-29" "" "borg backup tool"
 .SH NAME
 borg-patterns \- Details regarding patterns
 .
@@ -32,6 +32,15 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 ..
 .SH DESCRIPTION
 .sp
+The path/filenames used as input for the pattern matching start from the
+currently active recursion root. You usually give the recursion root(s)
+when invoking borg and these can be either relative or absolute paths.
+.sp
+So, when you give \fIrelative/\fP as root, the paths going into the matcher
+will look like \fIrelative/.../file.ext\fP\&. When you give \fI/absolute/\fP as root,
+they will look like \fI/absolute/.../file.ext\fP\&. This is meant when we talk
+about "full path" below.
+.sp
 File patterns support these styles: fnmatch, shell, regular expressions,
 path prefixes and path full\-matches. By default, fnmatch is used for
 \fB\-\-exclude\fP patterns and shell\-style is used for the experimental \fB\-\-pattern\fP
@@ -52,8 +61,8 @@ matching any character not specified. For the purpose of these patterns,
 the path separator (\(aq\(aq for Windows and \(aq/\(aq on other systems) is not
 treated specially. Wrap meta\-characters in brackets for a literal
 match (i.e. \fI[?]\fP to match the literal character \fI?\fP). For a path
-to match a pattern, it must completely match from start to end, or
-must match from the start to just before a path separator. Except
+to match a pattern, the full path must match, or it must match
+from the start of the full path to just before a path separator. Except
 for the root path, paths will never end in the path separator when
 matching is attempted.  Thus, if a given pattern ends in a path
 separator, a \(aq*\(aq is appended before matching is attempted.
@@ -67,7 +76,7 @@ exception of any path separator.
 .TP
 .B Regular expressions, selector \fIre:\fP
 Regular expressions similar to those found in Perl are supported. Unlike
-shell patterns regular expressions are not required to match the complete
+shell patterns regular expressions are not required to match the full
 path and any substring match is sufficient. It is strongly recommended to
 anchor patterns to the start (\(aq^\(aq), to the end (\(aq$\(aq) or both. Path
 separators (\(aq\(aq for Windows and \(aq/\(aq on other systems) in paths are
@@ -77,13 +86,13 @@ the re module\fP\&.
 .TP
 .B Path prefix, selector \fIpp:\fP
 This pattern style is useful to match whole sub\-directories. The pattern
-\fIpp:/data/bar\fP matches \fI/data/bar\fP and everything therein.
+\fIpp:root/somedir\fP matches \fIroot/somedir\fP and everything therein.
 .TP
 .B Path full\-match, selector \fIpf:\fP
-This pattern style is useful to match whole paths.
+This pattern style is (only) useful to match full paths.
 This is kind of a pseudo pattern as it can not have any variable or
-unspecified parts \- the full, precise path must be given.
-\fIpf:/data/foo.txt\fP matches \fI/data/foo.txt\fP only.
+unspecified parts \- the full path must be given.
+\fIpf:root/file.ext\fP matches \fIroot/file.txt\fP only.
 .sp
 Implementation note: this is implemented via very time\-efficient O(1)
 hashtable lookups (this means you can have huge amounts of such patterns
@@ -175,7 +184,24 @@ Patterns (\fB\-\-pattern\fP) and excludes (\fB\-\-exclude\fP) from the command l
 considered first (in the order of appearance). Then patterns from \fB\-\-patterns\-from\fP
 are added. Exclusion patterns from \fB\-\-exclude\-from\fP files are appended last.
 .sp
-An example \fB\-\-patterns\-from\fP file could look like that:
+Examples:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+# backup pics, but not the ones from 2018, except the good ones:
+# note: using = is essential to avoid cmdline argument parsing issues.
+borg create \-\-pattern=+pics/2018/good \-\-pattern=\-pics/2018 repo::arch pics
+
+# use a file with patterns:
+borg create \-\-patterns\-from patterns.lst repo::arch
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The patterns.lst file could look like that:
 .INDENT 0.0
 .INDENT 3.5
 .sp