commit 51bb0201a1ab9cb50ba33d997b43d66b8a2c1b4d
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sat Sep 14 11:07:51 2024 -0500
Commit: Fabian Greffrath <fabian@greffrath.com>
CommitDate: Wed Jul 2 08:24:12 2025 +0200
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 | 28 ++++++++++++++++++++--------
1 file changed, 20 insertions(+), 8 deletions(-)
diff --git a/man/docgen b/man/docgen
index 3e8548d3..6c1761a7 100755
--- a/man/docgen
+++ b/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")