man/docgen (manpage_output): Add special cases

...to handle command-line options with complex argument structures
(where "complex" means "anything but the most trivial case").  This
causes them to format idiomatically, with parameters in italics,
literals in bold, and "synopsis language", like brackets denoting
optional parameters, in roman.

This approach is necessary for idiomatic man page rendering because in
the language interpreted by this script, there is no way to mark up such
distinctions in code comments.  Such a mini-language would have to be
designed, and that way lies perlpod(1) and similar efforts.

man/docgen

@@ -241,14 +241,26 @@ class Parameter:
             return ""
 
     def manpage_output(self):
-        result = self.name
-
         if self.args:
-            result += " " + self.args
-
-        result = '\\fB' + result + '\\fR'
-
-        result += "\n"
+            # Special cases -- GBR is not proud.
+            if self.args == "[<x> <y> | <xy>]":
+                result = ".BR " + self.name + " \\~\\c\n" \
+                    + ".RI [ x\~y | xy ]\n"
+            elif self.args == "<WxH>":
+                result = ".BI " + self.name + "\\~ W x H\n"
+            elif self.args == "<x> <y>":
+                result = ".BI " + self.name + "\\~ \"x y\"\n"
+            elif self.args == "<files>":
+                result = ".BI " + self.name + "\\~ \"file\\~\c\n" \
+                    + "\\&.\\|.\\|.\n"
+            elif self.args == "<save-num> <demo-name>":
+                result = ".BI " + self.name \
+                    + "\\~ \"save-num demo-name\"\n"
+            else:
+                self.args = re.sub(r'[<>]', '', self.args)
+                result = ".BI " + self.name + "\\~ " + self.args + "\n"
+        else:
+            result = ".B " + self.name + "\n"
 
         if self.platform:
             result += "[%s only] " % self.platform
@@ -536,7 +548,7 @@ def usage():
     print("         (matches the given tag name in the source file)")
     print("   -s :  Package name, e.g. Chocolate Doom (for substitution)")
     print("   -z :  Package short-name, e.g. Chocolate (for substitution)")
-    print("   -v :  Package version e.g. 7.0 (for substitution)")
+    print("   -v :  Package version, e.g. 7.0 (for substitution)")
     print("   -n :  Program name, e.g. chocolate (for substitution)")
     print("   -M :  Markdown output")
     print("   -m :  Manpage output")