Commits

Jakub Wilk committed c3de5cf

Provide a manual page.

  • Participants
  • Parent commits 2bb02c3

Comments (0)

Files changed (7)

+syntax: glob
+
+doc/*.pod
+doc/*.1

File debian/changelog

   * Don't expect third-party Python 2.X modules to be byte-compiled if the
     corresponding Python version is not installed.
   * Print symlink target when reporting broken symlink.
+  * Provide a manual page.
 
- -- Jakub Wilk <jwilk@debian.org>  Fri, 14 Sep 2012 15:00:12 +0200
+ -- Jakub Wilk <jwilk@debian.org>  Fri, 14 Sep 2012 17:21:51 +0200
 
 adequate (0.2) unstable; urgency=low
 

File debian/rules

 	dh_prep
 	dh_installdirs
 	dh_install
+	dh_installman doc/*.1
 	dh_perl
 	dh_installdocs
 	dh_installchangelogs

File doc/Makefile

+version = $(word 2,$(shell cd .. && dpkg-parsechangelog | grep ^Version:))
+
+.PHONY: all
+all: adequate.1
+
+tags.desc: ../adequate
+	../private/update-tags
+
+adequate.pod: tags.desc ../adequate
+	../private/generate-manpage > $(@)
+
+%.1: %.pod
+	pod2man --utf8 -c '' -r "$(*) $(version)" $(<) $(@)
+
+.PHONY: clean
+clean:
+	rm -f *.pod *.1
+
+# vim:ts=4 sw=4 noet

File doc/tags.desc

+Tag: bin-or-sbin-binary-requires-usr-lib-library
+Description: This package ships a binary in /bin or /sbin that requires a
+ library in /usr/lib.  This will make impossible to use this binary before /usr
+ is mounted.
+
+Tag: broken-symlink
+Description: This package ships a symlink which points to a non-existent file.
+
+Tag: missing-copyright-file
+Description: The copyright file for this package is missing.  This often
+ happens if /usr/share/doc/<pkg>/ was a real directory in a previous version of
+ the package, but it's now a symlink; dpkg never replaces directory
+ with a symlink to a directory.
+References:
+ Debian Policy §12.5
+ Debian Policy §6.6
+
+Tag: obsolete-conffile
+Description: The current version of this package no longer ships a conffile
+ (that used to be included in the past).  However, the conffile hasn't been
+ removed on upgrade.
+References:
+ http://wiki.debian.org/DpkgConffileHandling
+ dpkg-maintscript-helper(1)
+
+Tag: py-file-not-bytecompiled
+Description: This package ships Python modules that are not byte-compiled.
+References:
+ Debian Python Policy §2.6
+
+Tag: pyshared-file-not-bytecompiled
+Description: This package ships Python modules that are not byte-compiled.
+References:
+ Debian Python Policy §2.6
+

File private/generate-manpage

+#!/usr/bin/python3
+
+import io
+import os
+import re
+import subprocess as ipc
+import sys
+
+import apt_pkg
+
+def podify_reference(s):
+    s = s.strip()
+    s = re.sub(r'^([a-z]+://\S+)$', r'<I<\1>>', s)
+    s = re.sub(r'^(.*)\((\d+)\)$', r'B<\1>(\2)', s)
+    return s
+
+def podify_synopsis(s):
+    if s.startswith(' '):
+        s = s.lstrip()
+        s = re.sub(r'<(.+?)>', r'I<\1>', s)
+        s = re.sub(r'^(\S+)', r'B<\1>', s)
+        s += '\n'
+    return s
+
+def podify_description(s):
+    s = re.sub(r'^\s+', '', s, flags=re.MULTILINE)
+    s = re.sub(r'<(.+?)>', r'I<\1>', s)
+    return s
+
+def podselect(filename, regexp):
+    child = ipc.Popen(['podselect', '-section', regexp, filename], stdout=ipc.PIPE)
+    stdout, stderr = child.communicate()
+    return stdout.decode('ASCII')
+
+def main():
+    sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='UTF-8')
+    base = os.path.join(os.path.dirname(__file__), os.pardir)
+    desc_fn = os.path.join(base, 'doc', 'tags.desc')
+    code_fn = os.path.join(base, 'adequate')
+    print('=encoding UTF-8')
+    print()
+    fragment = podselect(filename=code_fn, regexp='^NAME$')
+    print(fragment)
+    fragment = podselect(filename=code_fn, regexp='^SYNOPSIS$')
+    for line in fragment.splitlines():
+        line = podify_synopsis(line)
+        print(line)
+    print('=head1 TAGS')
+    print()
+    print('=over 4')
+    print()
+    with open(desc_fn, 'rt', encoding='UTF-8') as file:
+        for section in apt_pkg.TagFile(file):
+            tag = section['tag']
+            print('=item B<{tag}>'.format(tag=tag))
+            print()
+            try:
+                description = section['description']
+            except LookupError:
+                pass
+            else:
+                description = podify_description(description)
+                print(description)
+                print()
+            try:
+                references = section['references']
+            except LookupError:
+                pass
+            else:
+                references = ', '.join(podify_reference(s) for s in references.splitlines())
+                print('References: {refs}.'.format(refs=references))
+                print()
+    print('=back')
+
+if __name__ == '__main__':
+    main()
+
+# vim:ts=4 sw=4 et

File private/update-tags

+#!/usr/bin/python3
+
+import argparse
+import os
+import re
+import sys
+
+import apt_pkg
+
+tag_re = re.compile(r"^\s*tag\s+[$]\w+,\s+'(\S+)'")
+
+required_fields = {'Tag', 'Description'}
+known_fields = required_fields | {'References'}
+
+def main():
+    base = os.path.join(os.path.dirname(__file__), os.pardir)
+    desc_fn = os.path.join(base, 'doc', 'tags.desc')
+    code_fn = os.path.join(base, 'adequate')
+    tags = {}
+    with open(desc_fn, 'rt', encoding='UTF-8') as file:
+        for section in apt_pkg.TagFile(file):
+            tag = section['tag']
+            tags[tag] = section
+            for field in required_fields:
+                if field not in section:
+                    print('W: {tag}: required field {field} is missing'.format(tag=tag, field=field), file=sys.stderr)
+            for field in section.keys():
+                if field not in known_fields:
+                    print('W: {tag}: unknown field {field}'.format(tag=tag, field=field), file=sys.stderr)
+    with open(code_fn, 'rt', encoding='UTF-8') as file:
+        for line in file:
+            match = tag_re.match(line)
+            if match:
+                tag = match.group(1)
+                if tag in tags:
+                    continue
+                tags[tag] = 'Tag: {tag}\n'.format(tag=tag)
+    with open(desc_fn + '+', 'wt', encoding='UTF-8') as file:
+        for tag, section in sorted(tags.items()):
+            print(section, file=file)
+    os.rename(desc_fn + '+', desc_fn)
+
+if __name__ == '__main__':
+    main()
+
+# vim:ts=4 sw=4 et