1
# Copyright (C) 2005-2010 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
24
from __future__ import absolute_import
26
PLUGINS_TO_DOCUMENT = ["launchpad"]
33
import bzrlib.help_topics
34
import bzrlib.commands
36
from bzrlib.plugin import load_plugins
40
def get_filename(options):
41
"""Provides name of manpage"""
42
return "%s.1" % (options.bzr_name)
45
def infogen(options, outfile):
46
"""Assembles a man page"""
50
{ "bzrcmd": options.bzr_name,
51
"datestamp": time.strftime("%Y-%m-%d",tt),
52
"timestamp": time.strftime("%Y-%m-%d %H:%M:%S +0000",tt),
53
"version": bzrlib.__version__,
55
outfile.write(man_preamble % params)
56
outfile.write(man_escape(man_head % params))
57
outfile.write(man_escape(getcommand_list(params)))
58
outfile.write(man_escape(getcommand_help(params)))
59
outfile.write("".join(environment_variables()))
60
outfile.write(man_escape(man_foot % params))
63
def man_escape(string):
64
"""Escapes strings for man page compatibility"""
65
result = string.replace("\\","\\\\")
66
result = result.replace("`","\\'")
67
result = result.replace("'","\\*(Aq")
68
result = result.replace("-","\\-")
72
def command_name_list():
73
"""Builds a list of command names from bzrlib"""
74
command_names = bzrlib.commands.builtin_command_names()
75
for cmdname in bzrlib.commands.plugin_command_names():
76
cmd_object = bzrlib.commands.get_cmd_object(cmdname)
77
if (PLUGINS_TO_DOCUMENT is None or
78
cmd_object.plugin_name() in PLUGINS_TO_DOCUMENT):
79
command_names.append(cmdname)
84
def getcommand_list (params):
85
"""Builds summary help for command names in manpage format"""
86
bzrcmd = params["bzrcmd"]
87
output = '.SH "COMMAND OVERVIEW"\n'
88
for cmd_name in command_name_list():
89
cmd_object = bzrlib.commands.get_cmd_object(cmd_name)
92
cmd_help = cmd_object.help()
94
firstline = cmd_help.split('\n', 1)[0]
95
usage = cmd_object._usage()
96
tmp = '.TP\n.B "%s"\n%s\n' % (usage, firstline)
99
raise RuntimeError, "Command '%s' has no help text" % (cmd_name)
103
def getcommand_help(params):
104
"""Shows individual options for a bzr command"""
105
output='.SH "COMMAND REFERENCE"\n'
107
for cmd_name in command_name_list():
108
cmd_object = bzrlib.commands.get_cmd_object(cmd_name)
109
if cmd_object.hidden:
111
formatted[cmd_name] = format_command(params, cmd_object)
112
for alias in cmd_object.aliases:
113
formatted[alias] = format_alias(params, alias, cmd_name)
114
for cmd_name in sorted(formatted):
115
output += formatted[cmd_name]
119
def format_command(params, cmd):
120
"""Provides long help for each public command"""
121
subsection_header = '.SS "%s"\n' % (cmd._usage())
122
doc = "%s\n" % (cmd.__doc__)
123
doc = bzrlib.help_topics.help_as_plain_text(cmd.help())
125
# A dot at the beginning of a line is interpreted as a macro.
126
# Simply join lines that begin with a dot with the previous
127
# line to work around this.
128
doc = doc.replace("\n.", ".")
131
options = cmd.options()
133
option_str = "\nOptions:\n"
134
for option_name, option in sorted(options.items()):
135
for name, short_name, argname, help in option.iter_switches():
136
if option.is_hidden(name):
139
if argname is not None:
142
l += ', -' + short_name
143
l += (30 - len(l)) * ' ' + (help or '')
144
wrapped = textwrap.fill(l, initial_indent='',
145
subsequent_indent=30*' ',
146
break_long_words=False,
148
option_str += wrapped + '\n'
152
if len(cmd.aliases) > 1:
153
aliases_str += '\nAliases: '
155
aliases_str += '\nAlias: '
156
aliases_str += ', '.join(cmd.aliases)
160
see_also = cmd.get_see_also()
162
see_also_str += '\nSee also: '
163
see_also_str += ', '.join(see_also)
166
return subsection_header + option_str + aliases_str + see_also_str + "\n" + doc + "\n"
169
def format_alias(params, alias, cmd_name):
170
help = '.SS "bzr %s"\n' % alias
171
help += 'Alias for "%s", see "bzr %s".\n' % (cmd_name, cmd_name)
175
def environment_variables():
176
yield ".SH \"ENVIRONMENT\"\n"
178
from bzrlib.help_topics import known_env_variables
179
for k, desc in known_env_variables:
181
yield ".I \"%s\"\n" % k
182
yield man_escape(desc) + "\n"
186
.\\\"Man page for Bazaar (%(bzrcmd)s)
188
.\\\" Large parts of this file are autogenerated from the output of
189
.\\\" \"%(bzrcmd)s help commands\"
190
.\\\" \"%(bzrcmd)s help <cmd>\"
193
.ie \\n(.g .ds Aq \\(aq
199
.TH bzr 1 "%(datestamp)s" "%(version)s" "Bazaar"
201
%(bzrcmd)s - Bazaar next-generation distributed version control
217
Bazaar (or %(bzrcmd)s) is a distributed version control system that is powerful,
218
friendly, and scalable. Bazaar is a project of Canonical Ltd and part of
219
the GNU Project to develop a free operating system.
221
Bazaar keeps track of changes to software source code (or similar information);
222
lets you explore who changed it, when, and why; merges concurrent changes; and
223
helps people work together in a team.
229
.I "~/.bazaar/bazaar.conf"
230
Contains the user's default configuration. The section
232
is used to define general configuration that will be applied everywhere.
235
can be used to create command aliases for
236
commonly used options.
238
A typical config file might look something like:
243
email=John Doe <jdoe@isp.com>
247
commit = commit --strict
249
log10 = log --short -r -10..-1
251
.UR http://bazaar.canonical.com/
252
.BR http://bazaar.canonical.com/
added
removed
bzrlib/doc_generate/autodoc_man.py
