cvs2svn_lib/man_writer.py

   1 # (Be in -*- python -*- mode.)
   2 #
   3 # ====================================================================
   4 # Copyright (c) 2009 CollabNet.  All rights reserved.
   5 #
   6 # This software is licensed as described in the file COPYING, which
   7 # you should have received as part of this distribution.  The terms
   8 # are also available at http://subversion.tigris.org/license-1.html.
   9 # If newer versions of this license are posted there, you may use a
  10 # newer version instead, at your option.
  11 #
  12 # This software consists of voluntary contributions made by many
  13 # individuals.  For exact contribution history, see the revision
  14 # history and logs, available at http://cvs2svn.tigris.org/.
  15 # ====================================================================
  16
  17 """This module contains the ManWriter class for outputting manpages."""
  18
  19
  20 import datetime
  21 import optparse
  22 import re
  23
  24
  25 whitespace_re = re.compile(r'\s+')
  26
  27 def wrap(s, width=70):
  28   # Convert all whitespace substrings to single spaces:
  29   s = whitespace_re.sub(' ', s)
  30   s = s.strip()
  31   retval = []
  32   while s:
  33     if len(s) <= width:
  34       retval.append(s)
  35       break
  36     i = s.rfind(' ', 0, width + 1)
  37     if i == -1:
  38       # There were no spaces within the first width+1 characters; break
  39       # at the next space after width:
  40       i = s.find(' ', width + 1)
  41       if i == -1:
  42         # There were no spaces in s at all.
  43         retval.append(s)
  44         break
  45
  46     retval.append(s[:i].rstrip())
  47     s = s[i+1:].lstrip()
  48
  49   for (i,line) in enumerate(retval):
  50     if line.startswith('\'') or line.startswith('.'):
  51       # These are roff control characters and have to be escaped:
  52       retval[i] = '\\' + line
  53
  54   return '\n'.join(retval)
  55
  56
  57 class ManOption(optparse.Option):
  58   """An optparse.Option that holds an explicit string for the man page."""
  59
  60   def __init__(self, *args, **kw):
  61     self.man_help = kw.pop('man_help')
  62     optparse.Option.__init__(self, *args, **kw)
  63
  64
  65 class ManWriter(object):
  66   def __init__(
  67         self,
  68         parser,
  69         section=None, date=None, source=None, manual=None,
  70         short_desc=None, synopsis=None, long_desc=None,
  71         files=None, authors=None, see_also=None,
  72         ):
  73     self.parser = parser
  74     self.section = section
  75     self.date = date
  76     self.source = source
  77     self.manual = manual
  78     self.short_desc = short_desc
  79     self.synopsis = synopsis
  80     self.long_desc = long_desc
  81     self.files = files
  82     self.authors = authors
  83     self.see_also = see_also
  84
  85   def write_title(self, f):
  86     f.write('.\\" Process this file with\n')
  87     f.write(
  88         '.\\" groff -man -Tascii %s.%s\n' % (
  89             self.parser.get_prog_name(),
  90             self.section,
  91             )
  92         )
  93     f.write(
  94         '.TH %s "%s" "%s" "%s" "%s"\n' % (
  95             self.parser.get_prog_name().upper(),
  96             self.section,
  97             self.date.strftime('%b %d, %Y'),
  98             self.source,
  99             self.manual,
 100             )
 101         )
 102
 103   def write_name(self, f):
 104     f.write('.SH "NAME"\n')
 105     f.write(
 106         '%s \- %s\n' % (
 107             self.parser.get_prog_name(),
 108             self.short_desc,
 109             )
 110         )
 111
 112   def write_synopsis(self, f):
 113     f.write('.SH "SYNOPSIS"\n')
 114     f.write(self.synopsis)
 115
 116   def write_description(self, f):
 117     f.write('.SH "DESCRIPTION"\n')
 118     f.write(self.long_desc)
 119
 120   def _get_option_strings(self, option):
 121     """Return a list of option strings formatted with their metavariables.
 122
 123     This method is very similar to
 124     optparse.HelpFormatter.format_option_strings().
 125
 126     """
 127
 128     if option.takes_value():
 129       metavar = (option.metavar or option.dest).lower()
 130       short_opts = [
 131           '\\fB%s\\fR \\fI%s\\fR' % (opt, metavar)
 132           for opt in option._short_opts
 133           ]
 134       long_opts = [
 135           '\\fB%s\\fR=\\fI%s\\fR' % (opt, metavar)
 136           for opt in option._long_opts
 137           ]
 138     else:
 139       short_opts = [
 140           '\\fB%s\\fR' % (opt,)
 141           for opt in option._short_opts
 142           ]
 143       long_opts = [
 144           '\\fB%s\\fR' % (opt,)
 145           for opt in option._long_opts
 146           ]
 147
 148     return short_opts + long_opts
 149
 150   def _write_option(self, f, option):
 151     man_help = getattr(option, 'man_help', option.help)
 152
 153     if man_help is not optparse.SUPPRESS_HELP:
 154       man_help = wrap(man_help)
 155       f.write('.IP "%s"\n' % (', '.join(self._get_option_strings(option)),))
 156       f.write('%s\n' % (man_help,))
 157
 158   def _write_container_help(self, f, container):
 159     for option in container.option_list:
 160       if option.help is not optparse.SUPPRESS_HELP:
 161         self._write_option(f, option)
 162
 163   def write_options(self, f):
 164     f.write('.SH "OPTIONS"\n')
 165     if self.parser.option_list:
 166       (self._write_container_help(f, self.parser))
 167     for group in self.parser.option_groups:
 168       f.write('.SH "%s"\n' % (group.title.upper(),))
 169       if group.description:
 170         f.write(self.format_description(group.description) + '\n')
 171       self._write_container_help(f, group)
 172
 173   def write_files(self, f):
 174     f.write('.SH "FILES"\n')
 175     f.write(self.files)
 176
 177   def write_authors(self, f):
 178     f.write('.SH "AUTHORS"\n')
 179     f.write("Main authors are:\n")
 180     for author in self.authors:
 181       f.write(".br\n")
 182       f.write(author + "\n")
 183     f.write(".PP\n")
 184     f.write(
 185       "Manpage was written for the Debian GNU/Linux system by\n"
 186       "Laszlo 'GCS' Boszormenyi <gcs@lsc.hu> (but may be used by others).\n")
 187
 188   def write_see_also(self, f):
 189     f.write('.SH "SEE ALSO"\n')
 190     f.write(', '.join([
 191           '%s(%s)' % (name, section,)
 192           for (name, section,) in self.see_also
 193           ]) + '\n')
 194
 195   def write_manpage(self, f):
 196     self.write_title(f)
 197     self.write_name(f)
 198     self.write_synopsis(f)
 199     self.write_description(f)
 200     self.write_options(f)
 201     self.write_files(f)
 202     self.write_authors(f)
 203     self.write_see_also(f)
 204
 205