# Copyright (C) 2005-2010 Canonical Ltd
# This program is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation; either version 2 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program; if not, write to the Free Software
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
"""man.py - create man page from built-in bzr help and static text
TODO:
* use usage information instead of simple "bzr foo" in COMMAND OVERVIEW
* add command aliases
"""
import os
import sys
import textwrap
import time
import bzrlib
import bzrlib.help
import bzrlib.help_topics
import bzrlib.commands
def get_filename(options):
"""Provides name of manpage"""
return "%s.1" % (options.bzr_name)
def infogen(options, outfile):
"""Assembles a man page"""
t = time.time()
tt = time.gmtime(t)
params = \
{ "bzrcmd": options.bzr_name,
"datestamp": time.strftime("%Y-%m-%d",tt),
"timestamp": time.strftime("%Y-%m-%d %H:%M:%S +0000",tt),
"version": bzrlib.__version__,
}
outfile.write(man_preamble % params)
outfile.write(man_escape(man_head % params))
outfile.write(man_escape(getcommand_list(params)))
outfile.write(man_escape(getcommand_help(params)))
outfile.write(man_escape(man_foot % params))
def man_escape(string):
"""Escapes strings for man page compatibility"""
result = string.replace("\\","\\\\")
result = result.replace("`","\\`")
result = result.replace("'","\\'")
result = result.replace("-","\\-")
return result
def command_name_list():
"""Builds a list of command names from bzrlib"""
command_names = bzrlib.commands.builtin_command_names()
command_names.sort()
return command_names
def getcommand_list (params):
"""Builds summary help for command names in manpage format"""
bzrcmd = params["bzrcmd"]
output = '.SH "COMMAND OVERVIEW"\n'
for cmd_name in command_name_list():
cmd_object = bzrlib.commands.get_cmd_object(cmd_name)
if cmd_object.hidden:
continue
cmd_help = cmd_object.help()
if cmd_help:
firstline = cmd_help.split('\n', 1)[0]
usage = cmd_object._usage()
tmp = '.TP\n.B "%s"\n%s\n' % (usage, firstline)
output = output + tmp
else:
raise RuntimeError, "Command '%s' has no help text" % (cmd_name)
return output
def getcommand_help(params):
"""Shows individual options for a bzr command"""
output='.SH "COMMAND REFERENCE"\n'
formatted = {}
for cmd_name in command_name_list():
cmd_object = bzrlib.commands.get_cmd_object(cmd_name)
if cmd_object.hidden:
continue
formatted[cmd_name] = format_command(params, cmd_object)
for alias in cmd_object.aliases:
formatted[alias] = format_alias(params, alias, cmd_name)
for cmd_name in sorted(formatted):
output += formatted[cmd_name]
return output
def format_command (params, cmd):
"""Provides long help for each public command"""
subsection_header = '.SS "%s"\n' % (cmd._usage())
doc = "%s\n" % (cmd.__doc__)
doc = bzrlib.help_topics.help_as_plain_text(cmd.help())
option_str = ""
options = cmd.options()
if options:
option_str = "\nOptions:\n"
for option_name, option in sorted(options.items()):
for name, short_name, argname, help in option.iter_switches():
if option.is_hidden(name):
continue
l = ' --' + name
if argname is not None:
l += ' ' + argname
if short_name:
l += ', -' + short_name
l += (30 - len(l)) * ' ' + (help or '')
wrapped = textwrap.fill(l, initial_indent='',
subsequent_indent=30*' ',
break_long_words=False,
)
option_str = option_str + wrapped + '\n'
aliases_str = ""
if cmd.aliases:
if len(cmd.aliases) > 1:
aliases_str += '\nAliases: '
else:
aliases_str += '\nAlias: '
aliases_str += ', '.join(cmd.aliases)
aliases_str += '\n'
see_also_str = ""
see_also = cmd.get_see_also()
if see_also:
see_also_str += '\nSee also: '
see_also_str += ', '.join(see_also)
see_also_str += '\n'
return subsection_header + option_str + aliases_str + see_also_str + "\n" + doc + "\n"
def format_alias(params, alias, cmd_name):
help = '.SS "bzr %s"\n' % alias
help += 'Alias for "%s", see "bzr %s".\n' % (cmd_name, cmd_name)
return help
man_preamble = """\
.\\\"Man page for Bazaar (%(bzrcmd)s)
.\\\"
.\\\" Large parts of this file are autogenerated from the output of
.\\\" \"%(bzrcmd)s help commands\"
.\\\" \"%(bzrcmd)s help <cmd>\"
.\\\"
.\\\" Generation time: %(timestamp)s
.\\\"
"""
man_head = """\
.TH bzr 1 "%(datestamp)s" "%(version)s" "Bazaar"
.SH "NAME"
%(bzrcmd)s - Bazaar next-generation distributed version control
.SH "SYNOPSIS"
.B "%(bzrcmd)s"
.I "command"
[
.I "command_options"
]
.br
.B "%(bzrcmd)s"
.B "help"
.br
.B "%(bzrcmd)s"
.B "help"
.I "command"
.SH "DESCRIPTION"
Bazaar (or %(bzrcmd)s) is a project of Canonical to develop an open source
distributed version control system that is powerful, friendly, and scalable.
Version control means a system that keeps track of previous revisions
of software source code or similar information and helps people work on it in teams.
"""
man_foot = """\
.SH "ENVIRONMENT"
.TP
.I "BZRPATH"
Path where
.B "%(bzrcmd)s"
is to look for shell plugin external commands.
.TP
.I "BZR_EMAIL"
E-Mail address of the user. Overrides default user config.
.TP
.I "EMAIL"
E-Mail address of the user. Overrides default user config.
.TP
.I "BZR_EDITOR"
Editor for editing commit messages
.TP
.I "EDITOR"
Editor for editing commit messages
.TP
.I "BZR_PLUGIN_PATH"
Paths where bzr should look for plugins
.TP
.I "BZR_HOME"
Home directory for bzr
.SH "FILES"
.TP
.I "~/.bazaar/bazaar.conf"
Contains the user's default configuration. The section
.B [DEFAULT]
is used to define general configuration that will be applied everywhere.
The section
.B [ALIASES]
can be used to create command aliases for
commonly used options.
A typical config file might look something like:
.br
[DEFAULT]
.br
email=John Doe <jdoe@isp.com>
.br
[ALIASES]
.br
commit = commit --strict
.br
log10 = log --short -r -10..-1
.SH "SEE ALSO"
.UR http://www.bazaar.canonical.com/
.BR http://www.bazaar.canonical.com/
"""
|