1 # (Be in -*- python -*- mode.)
3 # ====================================================================
4 # Copyright (c) 2009 CollabNet. All rights reserved.
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.
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 # ====================================================================
17 """This module contains the ManWriter class for outputting manpages."""
25 whitespace_re
= re
.compile(r
'\s+')
27 def wrap(s
, width
=70):
28 # Convert all whitespace substrings to single spaces:
29 s
= whitespace_re
.sub(' ', s
)
36 i
= s
.rfind(' ', 0, width
+ 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)
42 # There were no spaces in s at all.
46 retval
.append(s
[:i
].rstrip())
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
54 return '\n'.join(retval
)
57 class ManOption(optparse
.Option
):
58 """An optparse.Option that holds an explicit string for the man page."""
60 def __init__(self
, *args
, **kw
):
61 self
.man_help
= kw
.pop('man_help')
62 optparse
.Option
.__init
__(self
, *args
, **kw
)
65 class ManWriter(object):
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,
74 self
.section
= section
78 self
.short_desc
= short_desc
79 self
.synopsis
= synopsis
80 self
.long_desc
= long_desc
82 self
.authors
= authors
83 self
.see_also
= see_also
85 def write_title(self
, f
):
86 f
.write('.\\" Process this file with\n')
88 '.\\" groff -man -Tascii %s.%s\n' % (
89 self
.parser
.get_prog_name(),
94 '.TH %s "%s" "%s" "%s" "%s"\n' % (
95 self
.parser
.get_prog_name().upper(),
97 self
.date
.strftime('%b %d, %Y'),
103 def write_name(self
, f
):
104 f
.write('.SH "NAME"\n')
107 self
.parser
.get_prog_name(),
112 def write_synopsis(self
, f
):
113 f
.write('.SH "SYNOPSIS"\n')
114 f
.write(self
.synopsis
)
116 def write_description(self
, f
):
117 f
.write('.SH "DESCRIPTION"\n')
118 f
.write(self
.long_desc
)
120 def _get_option_strings(self
, option
):
121 """Return a list of option strings formatted with their metavariables.
123 This method is very similar to
124 optparse.HelpFormatter.format_option_strings().
128 if option
.takes_value():
129 metavar
= (option
.metavar
or option
.dest
).lower()
131 '\\fB%s\\fR \\fI%s\\fR' % (opt
, metavar
)
132 for opt
in option
._short
_opts
135 '\\fB%s\\fR=\\fI%s\\fR' % (opt
, metavar
)
136 for opt
in option
._long
_opts
140 '\\fB%s\\fR' % (opt
,)
141 for opt
in option
._short
_opts
144 '\\fB%s\\fR' % (opt
,)
145 for opt
in option
._long
_opts
148 return short_opts
+ long_opts
150 def _write_option(self
, f
, option
):
151 man_help
= getattr(option
, 'man_help', option
.help)
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
,))
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
)
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
)
173 def write_files(self
, f
):
174 f
.write('.SH "FILES"\n')
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
:
182 f
.write(author
+ "\n")
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")
188 def write_see_also(self
, f
):
189 f
.write('.SH "SEE ALSO"\n')
191 '%s(%s)' % (name
, section
,)
192 for (name
, section
,) in self
.see_also
195 def write_manpage(self
, f
):
198 self
.write_synopsis(f
)
199 self
.write_description(f
)
200 self
.write_options(f
)
202 self
.write_authors(f
)
203 self
.write_see_also(f
)