1
# Copyright 2005 Canonical Ltd.
3
# This program is free software; you can redistribute it and/or modify
4
# it under the terms of the GNU General Public License as published by
5
# the Free Software Foundation; either version 2 of the License, or
6
# (at your option) any later version.
8
# This program is distributed in the hope that it will be useful,
9
# but WITHOUT ANY WARRANTY; without even the implied warranty of
10
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
11
# GNU General Public License for more details.
13
# You should have received a copy of the GNU General Public License
14
# along with this program; if not, write to the Free Software
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))
57
def man_escape(string):
58
"""Escapes strings for man page compatibility"""
59
result = string.replace("\\","\\\\")
60
result = result.replace("`","\\`")
61
result = result.replace("'","\\'")
62
result = result.replace("-","\\-")
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
assert len(short_name) == 1
127
l += ', -' + short_name
128
l += (30 - len(l)) * ' ' + (help or '')
129
wrapped = textwrap.fill(l, initial_indent='',
130
subsequent_indent=30*' ')
131
option_str = option_str + wrapped + '\n'
135
if len(cmd.aliases) > 1:
136
aliases_str += '\nAliases: '
138
aliases_str += '\nAlias: '
139
aliases_str += ', '.join(cmd.aliases)
143
see_also = cmd.get_see_also()
145
see_also_str += '\nSee also: '
146
see_also_str += ', '.join(see_also)
149
return subsection_header + option_str + aliases_str + see_also_str + "\n" + doc + "\n"
152
def format_alias(params, alias, cmd_name):
153
help = '.SS "bzr %s"\n' % alias
154
help += 'Alias for "%s", see "bzr %s".\n' % (cmd_name, cmd_name)
159
.\\\"Man page for Bazaar (%(bzrcmd)s)
161
.\\\" Large parts of this file are autogenerated from the output of
162
.\\\" \"%(bzrcmd)s help commands\"
163
.\\\" \"%(bzrcmd)s help <cmd>\"
165
.\\\" Generation time: %(timestamp)s
171
.TH bzr 1 "%(datestamp)s" "%(version)s" "Bazaar"
173
Bazaar (%(bzrcmd)s) - next-generation distributed version control
188
Bazaar (or %(bzrcmd)s) is a project of Canonical to develop an open source
189
distributed version control system that is powerful, friendly, and scalable.
190
Version control means a system that keeps track of previous revisions
191
of software source code or similar information and helps people work on it in teams.
200
is to look for shell plugin external commands.
203
E-Mail address of the user. Overrides default user config.
206
E-Mail address of the user. Overrides default user config.
209
Editor for editing commit messages
212
Editor for editing commit messages
215
Paths where bzr should look for plugins
218
Home directory for bzr
221
.I "~/.bazaar/bazaar.conf"
222
Contains the user's default configuration. The section
224
is used to define general configuration that will be applied everywhere.
227
can be used to create command aliases for
228
commonly used options.
230
A typical config file might look something like:
235
email=John Doe <jdoe@isp.com>
239
commit = commit --strict
241
log10 = log --short -r -10..-1
243
.UR http://www.bazaar-vcs.org/
244
.BR http://www.bazaar-vcs.org/
added
removed
tools/doc_generate/autodoc_man.py
