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.

Author: g-branden-robinson

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