3
# Copyright (C) 2005 by Hans Ulrich Niedermann
4
# Portions Copyright (C) 2005 by Canonical Ltd
1
# Copyright (C) 2005-2010 Canonical Ltd
6
3
# This program is free software; you can redistribute it and/or modify
7
4
# it under the terms of the GNU General Public License as published by
8
5
# the Free Software Foundation; either version 2 of the License, or
9
6
# (at your option) any later version.
11
8
# This program is distributed in the hope that it will be useful,
12
9
# but WITHOUT ANY WARRANTY; without even the implied warranty of
13
10
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14
11
# GNU General Public License for more details.
16
13
# You should have received a copy of the GNU General Public License
17
14
# along with this program; if not, write to the Free Software
18
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
20
#<<< code taken from bzr (C) Canonical
25
version_info = sys.version_info
26
except AttributeError:
27
version_info = 1, 5 # 1.5 or older
30
REINVOKE = "__BZR_REINVOKE"
33
if version_info < NEED_VERS:
34
if not os.environ.has_key(REINVOKE):
35
# mutating os.environ doesn't work in old Pythons
36
os.putenv(REINVOKE, "1")
37
for python in 'python2.4', 'python2.3':
39
os.execvp(python, [python] + sys.argv)
42
print >>sys.stderr, "bzr-man.py: error: cannot find a suitable python interpreter"
43
print >>sys.stderr, " (need %d.%d or later)" % NEED_VERS
45
if hasattr(os, "unsetenv"):
48
import bzrlib, bzrlib.help
50
#>>> code taken from bzr (C) Canonical
15
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
17
"""man.py - create man page from built-in bzr help and static text
20
* use usage information instead of simple "bzr foo" in COMMAND OVERVIEW
31
import bzrlib.help_topics
32
import bzrlib.commands
35
def get_filename(options):
36
"""Provides name of manpage"""
37
return "%s.1" % (options.bzr_name)
40
def infogen(options, outfile):
41
"""Assembles a man page"""
45
{ "bzrcmd": options.bzr_name,
46
"datestamp": time.strftime("%Y-%m-%d",tt),
47
"timestamp": time.strftime("%Y-%m-%d %H:%M:%S +0000",tt),
48
"version": bzrlib.__version__,
50
outfile.write(man_preamble % params)
51
outfile.write(man_escape(man_head % params))
52
outfile.write(man_escape(getcommand_list(params)))
53
outfile.write(man_escape(getcommand_help(params)))
54
outfile.write(man_escape(man_foot % params))
58
57
def man_escape(string):
58
"""Escapes strings for man page compatibility"""
59
59
result = string.replace("\\","\\\\")
60
60
result = result.replace("`","\\`")
61
61
result = result.replace("'","\\'")
68
def parse_line(self, line):
72
class CommandListParser(Parser):
74
"""Parser for output of "bzr help commands".
76
The parsed content can then be used to
77
- write a "COMMAND OVERVIEW" section into a man page
78
- provide a list of all commands
81
def __init__(self,params):
83
self.command_usage = []
84
self.all_commands = []
85
self.usage_exp = re.compile("([a-z0-9-]+).*")
86
self.descr_exp = re.compile(" ([A-Z].*)\s*")
92
def parse_line(self, line):
93
m = self.usage_exp.match(line)
97
self.command_usage.append((self.command,self.usage,self.descr))
98
self.all_commands.append(self.command)
100
self.command = m.groups()[0]
102
raise Error, "matching usage line in state %d" % state
105
m = self.descr_exp.match(line)
108
self.descr = m.groups()[0]
110
raise Error, "matching descr line in state %d" % state
113
raise Error, "Cannot parse this line"
118
self.command_usage.append((self.command,self.usage,self.descr))
119
self.all_commands.append(self.command)
121
raise Error, "ending parse in state %d" % state
123
def write_to_manpage(self, outfile):
124
bzrcmd = self.params["bzrcmd"]
125
outfile.write('.SH "COMMAND OVERVIEW"\n')
126
for (command,usage,descr) in self.command_usage:
127
outfile.write('.TP\n.B "%s %s"\n%s\n\n' % (bzrcmd, usage, descr))
132
def __init__(self, parser):
135
def write(self, data):
138
for line in data.split('\n'):
139
self.parser.parse_line(line)
142
def write_command_details(params, command, usage, descr, outfile):
143
x = ('.SS "%s %s"\n.B "%s"\n.PP\n.B "Usage:"\n%s %s\n\n' %
149
outfile.write(man_escape(x))
66
def command_name_list():
67
"""Builds a list of command names from bzrlib"""
68
command_names = bzrlib.commands.builtin_command_names()
73
def getcommand_list (params):
74
"""Builds summary help for command names in manpage format"""
75
bzrcmd = params["bzrcmd"]
76
output = '.SH "COMMAND OVERVIEW"\n'
77
for cmd_name in command_name_list():
78
cmd_object = bzrlib.commands.get_cmd_object(cmd_name)
81
cmd_help = cmd_object.help()
83
firstline = cmd_help.split('\n', 1)[0]
84
usage = cmd_object._usage()
85
tmp = '.TP\n.B "%s"\n%s\n' % (usage, firstline)
88
raise RuntimeError, "Command '%s' has no help text" % (cmd_name)
92
def getcommand_help(params):
93
"""Shows individual options for a bzr command"""
94
output='.SH "COMMAND REFERENCE"\n'
96
for cmd_name in command_name_list():
97
cmd_object = bzrlib.commands.get_cmd_object(cmd_name)
100
formatted[cmd_name] = format_command(params, cmd_object)
101
for alias in cmd_object.aliases:
102
formatted[alias] = format_alias(params, alias, cmd_name)
103
for cmd_name in sorted(formatted):
104
output += formatted[cmd_name]
108
def format_command (params, cmd):
109
"""Provides long help for each public command"""
110
subsection_header = '.SS "%s"\n' % (cmd._usage())
111
doc = "%s\n" % (cmd.__doc__)
112
doc = bzrlib.help_topics.help_as_plain_text(cmd.help())
115
options = cmd.options()
117
option_str = "\nOptions:\n"
118
for option_name, option in sorted(options.items()):
119
for name, short_name, argname, help in option.iter_switches():
120
if option.is_hidden(name):
123
if argname is not None:
126
l += ', -' + short_name
127
l += (30 - len(l)) * ' ' + (help or '')
128
wrapped = textwrap.fill(l, initial_indent='',
129
subsequent_indent=30*' ',
130
break_long_words=False,
132
option_str = option_str + wrapped + '\n'
136
if len(cmd.aliases) > 1:
137
aliases_str += '\nAliases: '
139
aliases_str += '\nAlias: '
140
aliases_str += ', '.join(cmd.aliases)
144
see_also = cmd.get_see_also()
146
see_also_str += '\nSee also: '
147
see_also_str += ', '.join(see_also)
150
return subsection_header + option_str + aliases_str + see_also_str + "\n" + doc + "\n"
153
def format_alias(params, alias, cmd_name):
154
help = '.SS "bzr %s"\n' % alias
155
help += 'Alias for "%s", see "bzr %s".\n' % (cmd_name, cmd_name)
152
159
man_preamble = """\
153
.\\\" Man page for %(bzrcmd)s (bazaar-ng)
160
.\\\"Man page for Bazaar (%(bzrcmd)s)
155
162
.\\\" Large parts of this file are autogenerated from the output of
156
163
.\\\" \"%(bzrcmd)s help commands\"
196
is to look for external command.
201
is to look for shell plugin external commands.
200
E-Mail address of the user. Overrides
201
.I "~/.bzr.conf/email" and
204
.I "John Doe <john@example.com>"
204
E-Mail address of the user. Overrides default user config.
208
E-Mail address of the user. Overridden by the content of the file
209
.I "~/.bzr.conf/email"
210
and of the environment variable
207
E-Mail address of the user. Overrides default user config.
210
Editor for editing commit messages
213
Editor for editing commit messages
216
Paths where bzr should look for plugins
219
Home directory for bzr
216
Directory where all the user\'s settings are stored.
218
.I "~/.bzr.conf/email"
219
Stores name and email address of the user. Overrides content of
221
environment variable. Example content:
222
.I "John Doe <john@example.com>"
222
.I "~/.bazaar/bazaar.conf"
223
Contains the user's default configuration. The section
225
is used to define general configuration that will be applied everywhere.
228
can be used to create command aliases for
229
commonly used options.
231
A typical config file might look something like:
236
email=John Doe <jdoe@isp.com>
240
commit = commit --strict
242
log10 = log --short -r -10..-1
225
.UR http://www.bazaar-ng.org/
226
.BR http://www.bazaar-ng.org/,
227
.UR http://www.bazaar-ng.org/doc/
228
.BR http://www.bazaar-ng.org/doc/
244
.UR http://bazaar.canonical.com/
245
.BR http://bazaar.canonical.com/
236
"datestamp": time.strftime("%Y-%m-%d",tt),
237
"timestamp": time.strftime("%Y-%m-%d %H:%M:%S +0000",tt),
238
"version": bzrlib.__version__,
241
clp = CommandListParser(params)
242
bzrlib.help.help("commands", outfile=HelpReader(clp))
246
if len(sys.argv) == 2:
247
filename = sys.argv[1]
251
outfile = open(filename,"w")
253
outfile.write(man_preamble % params)
254
outfile.write(man_escape(man_head % params))
255
clp.write_to_manpage(outfile)
258
# This doesn't do more than the summary so far.
259
#outfile.write('.SH "DETAILED COMMAND DESCRIPTION"\n')
260
#for (command,usage,descr) in clp.command_usage:
261
# write_command_details(params, command, usage, descr, outfile = outfile)
263
outfile.write(man_escape(man_foot % params))
266
if __name__ == '__main__':