man pages: add EXAMPLES

hacky, but works. Better would be to make a separate docs/examples dir
with only the examples in them, separated by command.

Or, putting these different sections; DESCRIPTION, EXAMPLES and NOTES
into the --help doc, but separately of course, so that they can be aptly
formatted for different media (html, --help, man).

setup.py

@@ -347,6 +347,12 @@ class build_man(Command):
         'extract': ('mount', ),
     }
 
+    rst_prelude = textwrap.dedent("""
+    .. role:: ref(title)
+
+    .. |project_name| replace:: Borg
+    """)
+
     def initialize_options(self):
         pass
 
@@ -379,14 +385,12 @@ class build_man(Command):
                 continue
 
             man_title = 'borg-' + command.replace(' ', '-')
-            print('building man page %-40s' % (man_title + '(1)'), end='\r', file=sys.stderr)
+            print('building man page', man_title + '(1)', file=sys.stderr)
 
             if self.generate_level(command + ' ', parser, Archiver):
                 continue
 
-            doc = io.StringIO()
-            write = self.printer(doc)
-
+            doc, write = self.new_doc()
             self.write_man_header(write, man_title, parser.description)
 
             self.write_heading(write, 'SYNOPSIS')
@@ -402,14 +406,15 @@ class build_man(Command):
             write()
             self.write_options(write, parser)
 
+            self.write_examples(write, command)
+
             self.write_see_also(write, man_title)
 
             self.gen_man_page(man_title, doc.getvalue())
 
         # Generate the borg-common(1) man page with the common options.
         if 'create' in choices:
-            doc = io.StringIO()
-            write = self.printer(doc)
+            doc, write = self.new_doc()
             man_title = 'borg-common'
             self.write_man_header(write, man_title, 'Common options of Borg commands')
 
@@ -424,16 +429,21 @@ class build_man(Command):
 
     def build_topic_pages(self, Archiver):
         for topic, text in Archiver.helptext.items():
-            doc = io.StringIO()
-            write = self.printer(doc)
+            doc, write = self.new_doc()
             man_title = 'borg-' + topic
-            print('building man page %-40s' % (man_title + '(1)'), end='\r', file=sys.stderr)
+            print('building man page', man_title + '(1)', file=sys.stderr)
 
             self.write_man_header(write, man_title, 'Details regarding ' + topic)
             self.write_heading(write, 'DESCRIPTION')
             write(text)
             self.gen_man_page(man_title, doc.getvalue())
 
+    def new_doc(self):
+        doc = io.StringIO(self.rst_prelude)
+        doc.read()
+        write = self.printer(doc)
+        return doc, write
+
     def printer(self, fd):
         def write(*args, **kwargs):
             print(*args, file=fd, **kwargs)
@@ -457,6 +467,22 @@ class build_man(Command):
         write(':Manual group: borg backup tool')
         write()
 
+    def write_examples(self, write, command):
+        with open('docs/usage.rst') as fd:
+            usage = fd.read()
+            usage_include = '.. include:: usage/%s.rst.inc' % command
+            begin = usage.find(usage_include)
+            end = usage.find('.. include', begin + 1)
+            examples = usage[begin:end]
+            examples = examples.replace(usage_include, '')
+            examples = examples.replace('Examples\n~~~~~~~~', '')
+            examples = examples.replace('Miscellaneous Help\n------------------', '')
+            examples = re.sub('^(~+)$', lambda matches: '+' * len(matches.group(0)), examples, flags=re.MULTILINE)
+            examples = examples.strip()
+        if examples:
+            self.write_heading(write, 'EXAMPLES', '-')
+            write(examples)
+
     def write_see_also(self, write, man_title):
         see_also = self.see_also.get(man_title.replace('borg-', ''), ())
         see_also = ['`borg-%s(1)`' % s for s in see_also]