man: rewrite helper script in python to avoid `help2man` as that tends to mangle things

9 files changed, 170 insertions, 57 deletions

diff --git a/Makefile b/Makefile
index 75bdda08..717352d5 100644
--- a/Makefile
+++ b/Makefile
@@ -1,6 +1,6 @@
 # Copyright 2005-2008 Gentoo Foundation
 # Distributed under the terms of the GNU General Public License v2
-# $Header: /var/cvsroot/gentoo-projects/portage-utils/Makefile,v 1.75 2013/09/29 17:52:39 vapier Exp $
+# $Header: /var/cvsroot/gentoo-projects/portage-utils/Makefile,v 1.76 2013/09/29 22:12:51 vapier Exp $
 ####################################################################
 
 check_gcc=$(shell if $(CC) $(1) -S -o /dev/null -xc /dev/null > /dev/null 2>&1; \
@@ -119,7 +119,7 @@ install: all
 	)
 
 man: q
-	cd man && ./mkman.sh
+	./man/mkman.py
 
 symlinks: all
 	./q --install
diff --git a/man/include/qfile-01-owners.include b/man/include/qfile-01-owners.include
index b82c479f..c9ce378b 100644
--- a/man/include/qfile-01-owners.include
+++ b/man/include/qfile-01-owners.include
@@ -1,4 +1,4 @@
-[Finding files owners]
+.SH "FINDING FILES OWNERS"
 .PP
 This is the default behavior of \fBqfile\fP.  It will list the packages which
 own the files (or directories, or symlinks, or anything else Portage can 
diff --git a/man/include/qfile-02-orphans.include b/man/include/qfile-02-orphans.include
index 0b7d4634..ca237966 100644
--- a/man/include/qfile-02-orphans.include
+++ b/man/include/qfile-02-orphans.include
@@ -1,4 +1,4 @@
-[Finding orphan files]
+.SH "FINDING ORPHAN FILES"
 .PP
 \fBqfile\fP can also, with the \fB\-\-orphans\fP option, find files which are 
 not owned by any package.  This behavior is the opposite of the usual file 
diff --git a/man/include/qfile-03-ROOT.include b/man/include/qfile-03-ROOT.include
index 835f9603..61d965d0 100644
--- a/man/include/qfile-03-ROOT.include
+++ b/man/include/qfile-03-ROOT.include
@@ -1,4 +1,4 @@
-[Handling of the ROOT variable]
+.SH "$ROOT HANDLING"
 .PP
 By setting the \fIROOT\fP environment variable, you can force \fBqfile\fP to
 work in the sytem of your choice. This example shows queries for owner of 
diff --git a/man/include/qfile-04-from.include b/man/include/qfile-04-from.include
index 47c20d45..47652bb4 100644
--- a/man/include/qfile-04-from.include
+++ b/man/include/qfile-04-from.include
@@ -1,4 +1,4 @@
-[Reading arguments from a file (or stdin)]
+.SH "READING ARGUMENTS FROM A FILE/STDIN"
 .PP
 When you try to launch \fBqfile\fP with a large number of arguments, you may
 hit the following shell error:
diff --git a/man/include/qfile-05-collisions.include b/man/include/qfile-05-collisions.include
index adaf8fa3..dcf0e49c 100644
--- a/man/include/qfile-05-collisions.include
+++ b/man/include/qfile-05-collisions.include
@@ -1,4 +1,4 @@
-[Searching for files collisions]
+.SH "SEARCHING FOR FILE COLLISIONS"
 .PP
 A last option of \fBqfile\fP is \fB\-\-exclude\fP (\fB\-x\fP), which will makes
 it skip one particular package when doing its files owners search.  This option
diff --git a/man/include/qfile-99-authors.include b/man/include/qfile-99-authors.include
index 1daf476a..df3dc399 100644
--- a/man/include/qfile-99-authors.include
+++ b/man/include/qfile-99-authors.include
@@ -1,4 +1,4 @@
-[Additional Contributors]
-.TP
+.SH "ADDITIONAL CONTRIBUTORS"
+.nf
 TGL degrenier[at]easyconnect.fr
-.TP
+.fi
diff --git a/man/mkman.py b/man/mkman.py
new file mode 100755
index 00000000..cd0fa7a3
--- /dev/null
+++ b/man/mkman.py
@@ -0,0 +1,160 @@
+#!/usr/bin/python
+
+"""Generate man pages for the q applets"""
+
+from __future__ import print_function
+
+import datetime
+import functools
+import glob
+import locale
+import multiprocessing
+import os
+import re
+import subprocess
+import sys
+
+
+MKMAN_DIR = os.path.realpath(os.path.join(__file__, '..'))
+FRAGS_DIR = os.path.join(MKMAN_DIR, 'include')
+
+TOPDIR = os.path.join(MKMAN_DIR, '..')
+Q = os.path.join(TOPDIR, 'q')
+
+
+def FindApplets():
+    """Return a list of all supported applets"""
+    applets = os.path.join(TOPDIR, 'applets.sh')
+    return subprocess.check_output([applets]).splitlines()
+
+
+COMMON_AUTHORS = [
+    'Ned Ludd <solar@gentoo.org>',
+    'Mike Frysinger <vapier@gentoo.org>',
+]
+TEMPLATE = r""".TH %(applet)s "1" "%(date)s" "Gentoo Foundation" "%(applet)s"
+.SH NAME
+%(applet)s \- %(short_desc)s
+.SH SYNOPSIS
+.B %(applet)s
+\fI%(usage)s\fR
+.SH DESCRIPTION
+%(description)s
+.SH OPTIONS
+%(options)s
+%(extra_sections)s
+.SH "REPORTING BUGS"
+Please report bugs via http://bugs.gentoo.org/
+.br
+Product: Portage Development; Component: Tools
+.SH AUTHORS
+.nf
+%(authors)s
+.fi
+.SH "SEE ALSO"
+%(see_also)s
+"""
+
+def MkMan(applets, applet, output):
+    """Generate a man page for |applet| and write it to |output|"""
+    print('%-10s: generating %s' % (applet, output))
+
+    # Extract the main use string and description:
+    # Usage: q <applet> <args>  : invoke a portage utility applet
+    ahelp = subprocess.check_output([Q, applet, '--help'])
+    lines = ahelp.splitlines()
+    m = re.search(r'^Usage: %s (.*) : (.*)' % applet, ahelp)
+    usage = m.group(1)
+    short_desc = m.group(2)
+
+    authors = COMMON_AUTHORS
+    see_also = sorted(['.BR %s (1)' % x for x in applets if x != applet])
+
+    description = ''
+    desc_file = os.path.join(FRAGS_DIR, '%s.desc' % applet)
+    if os.path.exists(desc_file):
+        description = open(desc_file).read().rstrip()
+
+    # Extract all the options
+    options = []
+    for line, i in zip(lines, xrange(len(lines))):
+        if not line.startswith('Options: '):
+            continue
+
+        for option in [x.strip().split() for x in lines[i + 1:]]:
+            flags = [option[0].rstrip(',')]
+            option.pop(0)
+            if option[0][0] == '-':
+                flags += [option[0].rstrip(',')]
+                option.pop(0)
+
+            if option[0] == '<arg>':
+                flags = [r'\fB%s\fR \fI<arg>\fR' % x for x in flags]
+                option.pop(0)
+            else:
+                flags = [r'\fB%s\fR' % x for x in flags]
+
+            assert option[0] == '*', 'help line for %s is broken: %r' % (applet, option)
+            option.pop(0)
+
+            options += [
+                '.TP',
+                ', '.join(flags).replace('-', r'\-'),
+                ' '.join(option),
+            ]
+        break
+
+    # Handle applets that have applets
+    extra_sections = []
+    if 'Currently defined applets:' in ahelp:
+        alines = lines[lines.index('Currently defined applets:') + 1:]
+        alines = alines[:alines.index('')]
+        extra_sections += (
+            ['.SH APPLETS', '.nf',
+             '.B This applet also has sub applets:'] +
+            alines +
+            ['.fi']
+        )
+
+    # Handle any fragments this applet has available
+    for frag in sorted(glob.glob(os.path.join(FRAGS_DIR, '%s-*.include' % applet))):
+        with open(frag) as f:
+            extra_sections += [x.rstrip() for x in f.readlines()]
+
+    data = {
+        'applet': applet,
+        'date': datetime.datetime.now().strftime('%b %Y'),
+        'short_desc': short_desc,
+        'usage': usage,
+        'description': description,
+        'options': '\n'.join(options),
+        'extra_sections': '\n'.join(extra_sections),
+        'authors': '\n'.join(authors),
+        'see_also': ',\n'.join(see_also),
+        'rcsid': '',
+    }
+    with open(output, 'w') as f:
+        f.write(TEMPLATE % data)
+
+
+def _MkMan(applets, applet):
+    """Trampoline to MkMan for multiprocessing pickle"""
+    output = os.path.join(MKMAN_DIR, '%s.1' % applet)
+    MkMan(applets, applet, output)
+
+
+def main(argv):
+    os.environ['NOCOLOR'] = '1'
+
+    if not argv:
+        argv = FindApplets()
+    # Support file completion like "qfile.1" or "./qdepends.1"
+    applets = [os.path.basename(x).split('.', 1)[0] for x in argv]
+
+    p = multiprocessing.Pool()
+    functor = functools.partial(_MkMan, applets)
+    p.map(functor, applets)
+
+
+if __name__ == '__main__':
+    sys.exit(main(sys.argv[1:]))
diff --git a/man/mkman.sh b/man/mkman.sh
deleted file mode 100755
index b9f0d805..00000000
--- a/man/mkman.sh
+++ /dev/null
@@ -1,47 +0,0 @@
-#!/bin/bash
-set -e
-
-export NOCOLOR=1
-cd "${0%/*}"
-
-[[ $# -eq 0 ]] && set -- $(../applets.sh)
-
-for applet in "$@" ; do
-	man="${applet}.1"
-	echo "creating ${man}"
-
-	help2man -N -S "Gentoo Foundation" -m ${applet} -s 1 \
-		$(printf ' -I %s' include/${applet}-*.include) \
-		-n "$(../q ${applet} --help | sed -n '/^Usage/{s|^.* : ||p;q;}')" \
-		-o ${man} "../q ${applet}"
-	[[ $? == 0 ]] || continue
-
-	sed \
-		-e "s/PORTAGE-UTILS-CVS:/${applet}/g" \
-		-e "s/portage-utils-cvs:/${applet}/g" \
-		-e '/\.SH SYNOPSIS/,/\.SH/s/ : .*\\fR$/\\fR/' \
-		-e '/\.SH DESCRIPTION/,/\.SH/s|^\(Options:.*\)\\fR\(.*\)|\1\2\\fR|' \
-		${man} | \
-		awk '{
-			if ($1 == "<arg>") {
-				line = line " " $1
-				$1 = ""
-			}
-			if (line)
-				print line
-			line = $0
-		}
-		END { print line }
-		' | \
-		sed -e 's:^ *[*] ::' > ${man}~
-	mv ${man}~ ${man}
-
-	head -n $(($(wc -l < ${man})-1)) ${man} \
-		| tr '@' '\n' > ${man}~ && mv ${man}~ ${man}
-
-	sed -e s/'compiled on'/'@@@@@@@@@@@@@@'/ ${man} |
-		cut -d @ -f 1 | \
-		grep -v 'DO NOT MODIFY THIS FILE' \
-		> ${man}~
-	mv ${man}~ ${man}
-done