~bzr-pqm/bzr/bzr.dev

4988.10.3 by John Arbash Meinel
Merge bzr.dev 5007, resolve conflict, update NEWS
1
# Copyright (C) 2005-2010 Canonical Ltd
635 by Martin Pool
- manpage generator by Hans Ulrich Niedermann
2
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.
1887.1.1 by Adeodato Simó
Do not separate paragraphs in the copyright statement with blank lines,
7
#
635 by Martin Pool
- manpage generator by Hans Ulrich Niedermann
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.
1887.1.1 by Adeodato Simó
Do not separate paragraphs in the copyright statement with blank lines,
12
#
635 by Martin Pool
- manpage generator by Hans Ulrich Niedermann
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
4183.7.1 by Sabin Iacob
update FSF mailing address
15
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
635 by Martin Pool
- manpage generator by Hans Ulrich Niedermann
16
1551.3.11 by Aaron Bentley
Merge from Robert
17
"""man.py - create man page from built-in bzr help and static text
18
19
TODO:
20
  * use usage information instead of simple "bzr foo" in COMMAND OVERVIEW
21
  * add command aliases
22
"""
23
6379.6.7 by Jelmer Vernooij
Move importing from future until after doc string, otherwise the doc string will disappear.
24
from __future__ import absolute_import
25
6498.4.1 by Jelmer Vernooij
Document launchpad plugin commands in manual page.
26
PLUGINS_TO_DOCUMENT = ["launchpad"]
27
1551.3.11 by Aaron Bentley
Merge from Robert
28
import textwrap
635 by Martin Pool
- manpage generator by Hans Ulrich Niedermann
29
import time
1551.3.11 by Aaron Bentley
Merge from Robert
30
31
import bzrlib
32
import bzrlib.help
2666.1.3 by Ian Clatworthy
Fix man page to show plain text, not reStructuredText
33
import bzrlib.help_topics
1551.3.11 by Aaron Bentley
Merge from Robert
34
import bzrlib.commands
35
6498.4.1 by Jelmer Vernooij
Document launchpad plugin commands in manual page.
36
from bzrlib.plugin import load_plugins
37
load_plugins()
38
1551.3.11 by Aaron Bentley
Merge from Robert
39
40
def get_filename(options):
41
    """Provides name of manpage"""
42
    return "%s.1" % (options.bzr_name)
43
44
45
def infogen(options, outfile):
46
    """Assembles a man page"""
47
    t = time.time()
48
    tt = time.gmtime(t)
49
    params = \
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__,
54
             }
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)))
6503.2.2 by Jelmer Vernooij
Generate ENVIRONMENT section in manpage from environment variable list in bzrlib.help_topics.
59
    outfile.write("".join(environment_variables()))
1551.3.11 by Aaron Bentley
Merge from Robert
60
    outfile.write(man_escape(man_foot % params))
1185.74.4 by James Blackwell
Give long help with command on man page
61
1185.75.1 by Hans Ulrich Niedermann
Start implementing general doc generation plan:
62
635 by Martin Pool
- manpage generator by Hans Ulrich Niedermann
63
def man_escape(string):
1551.3.11 by Aaron Bentley
Merge from Robert
64
    """Escapes strings for man page compatibility"""
635 by Martin Pool
- manpage generator by Hans Ulrich Niedermann
65
    result = string.replace("\\","\\\\")
6498.2.2 by Jelmer Vernooij
Fix accent grave generation.
66
    result = result.replace("`","\\'")
6498.2.1 by Jelmer Vernooij
Properly format apostrophes in manual page.
67
    result = result.replace("'","\\*(Aq")
635 by Martin Pool
- manpage generator by Hans Ulrich Niedermann
68
    result = result.replace("-","\\-")
69
    return result
1185.75.1 by Hans Ulrich Niedermann
Start implementing general doc generation plan:
70
71
1551.3.11 by Aaron Bentley
Merge from Robert
72
def command_name_list():
73
    """Builds a list of command names from bzrlib"""
74
    command_names = bzrlib.commands.builtin_command_names()
6498.4.1 by Jelmer Vernooij
Document launchpad plugin commands in manual page.
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
6498.4.3 by Jelmer Vernooij
Use Command.plugin_name().
78
            cmd_object.plugin_name() in PLUGINS_TO_DOCUMENT):
6498.4.1 by Jelmer Vernooij
Document launchpad plugin commands in manual page.
79
            command_names.append(cmdname)
1551.3.11 by Aaron Bentley
Merge from Robert
80
    command_names.sort()
81
    return command_names
82
83
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)
90
        if cmd_object.hidden:
91
            continue
92
        cmd_help = cmd_object.help()
93
        if cmd_help:
94
            firstline = cmd_help.split('\n', 1)[0]
2432.1.33 by Robert Collins
Fix tests broken by deprecation of help.command_usage.
95
            usage = cmd_object._usage()
1551.3.11 by Aaron Bentley
Merge from Robert
96
            tmp = '.TP\n.B "%s"\n%s\n' % (usage, firstline)
97
            output = output + tmp
1185.75.1 by Hans Ulrich Niedermann
Start implementing general doc generation plan:
98
        else:
1551.3.11 by Aaron Bentley
Merge from Robert
99
            raise RuntimeError, "Command '%s' has no help text" % (cmd_name)
100
    return output
101
102
103
def getcommand_help(params):
104
    """Shows individual options for a bzr command"""
105
    output='.SH "COMMAND REFERENCE"\n'
4056.4.1 by James Westby
Explicitly list aliases in the manpage as commands that can be executed.
106
    formatted = {}
1551.3.11 by Aaron Bentley
Merge from Robert
107
    for cmd_name in command_name_list():
108
        cmd_object = bzrlib.commands.get_cmd_object(cmd_name)
109
        if cmd_object.hidden:
110
            continue
4056.4.1 by James Westby
Explicitly list aliases in the manpage as commands that can be executed.
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)
4056.4.2 by James Westby
Tweaks from review by Ian.
114
    for cmd_name in sorted(formatted):
115
        output += formatted[cmd_name]
1551.3.11 by Aaron Bentley
Merge from Robert
116
    return output
117
118
6498.4.3 by Jelmer Vernooij
Use Command.plugin_name().
119
def format_command(params, cmd):
1551.3.11 by Aaron Bentley
Merge from Robert
120
    """Provides long help for each public command"""
2432.1.33 by Robert Collins
Fix tests broken by deprecation of help.command_usage.
121
    subsection_header = '.SS "%s"\n' % (cmd._usage())
1551.3.11 by Aaron Bentley
Merge from Robert
122
    doc = "%s\n" % (cmd.__doc__)
2666.1.3 by Ian Clatworthy
Fix man page to show plain text, not reStructuredText
123
    doc = bzrlib.help_topics.help_as_plain_text(cmd.help())
1861.3.2 by Alexander Belchenko
bzr.1 man page: show aliases for commands; fixed description of bazaar.conf
124
6503.1.1 by Jelmer Vernooij
Prevent lines starting with a dot to accidentally be interpreted as a roff macro.
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.", ".")
129
1551.3.11 by Aaron Bentley
Merge from Robert
130
    option_str = ""
131
    options = cmd.options()
132
    if options:
133
        option_str = "\nOptions:\n"
134
        for option_name, option in sorted(options.items()):
1857.1.14 by Aaron Bentley
Fix man page generation
135
            for name, short_name, argname, help in option.iter_switches():
1551.18.12 by Aaron Bentley
Man page doesn't list hidden options (#131667)
136
                if option.is_hidden(name):
137
                    continue
1857.1.14 by Aaron Bentley
Fix man page generation
138
                l = '    --' + name
139
                if argname is not None:
140
                    l += ' ' + argname
141
                if short_name:
142
                    l += ', -' + short_name
2309.3.1 by bialix at ukr
Fix for selftest of man generator with instaled plugin 'htmllog' (no help for plugin's log formatter)
143
                l += (30 - len(l)) * ' ' + (help or '')
1857.1.14 by Aaron Bentley
Fix man page generation
144
                wrapped = textwrap.fill(l, initial_indent='',
4070.11.2 by Martin Pool
Ask textwrap not to break long words or on hyphens
145
                    subsequent_indent=30*' ',
146
                    break_long_words=False,
4070.11.5 by Martin Pool
textwrap break_on_hyphens option is not available in python2.5
147
                    )
6498.4.3 by Jelmer Vernooij
Use Command.plugin_name().
148
                option_str += wrapped + '\n'
1861.3.2 by Alexander Belchenko
bzr.1 man page: show aliases for commands; fixed description of bazaar.conf
149
150
    aliases_str = ""
151
    if cmd.aliases:
152
        if len(cmd.aliases) > 1:
153
            aliases_str += '\nAliases: '
154
        else:
155
            aliases_str += '\nAlias: '
156
        aliases_str += ', '.join(cmd.aliases)
157
        aliases_str += '\n'
158
2425.2.4 by Robert Collins
Update the doc_generate logic to include see-also help topics.
159
    see_also_str = ""
160
    see_also = cmd.get_see_also()
161
    if see_also:
162
        see_also_str += '\nSee also: '
163
        see_also_str += ', '.join(see_also)
164
        see_also_str += '\n'
165
166
    return subsection_header + option_str + aliases_str + see_also_str + "\n" + doc + "\n"
1185.75.1 by Hans Ulrich Niedermann
Start implementing general doc generation plan:
167
168
4056.4.1 by James Westby
Explicitly list aliases in the manpage as commands that can be executed.
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)
172
    return help
173
174
6503.2.2 by Jelmer Vernooij
Generate ENVIRONMENT section in manpage from environment variable list in bzrlib.help_topics.
175
def environment_variables():
176
    yield ".SH \"ENVIRONMENT\"\n"
177
178
    from bzrlib.help_topics import known_env_variables
6503.2.4 by Jelmer Vernooij
Use tuples for known env variables list.
179
    for k, desc in known_env_variables:
6503.2.2 by Jelmer Vernooij
Generate ENVIRONMENT section in manpage from environment variable list in bzrlib.help_topics.
180
        yield ".TP\n"
181
        yield ".I \"%s\"\n" % k
182
        yield man_escape(desc) + "\n"
183
184
635 by Martin Pool
- manpage generator by Hans Ulrich Niedermann
185
man_preamble = """\
3709.2.1 by David Futcher
Make the first line of the manpage preamble a comment again (#242106)
186
.\\\"Man page for Bazaar (%(bzrcmd)s)
635 by Martin Pool
- manpage generator by Hans Ulrich Niedermann
187
.\\\"
188
.\\\" Large parts of this file are autogenerated from the output of
189
.\\\"     \"%(bzrcmd)s help commands\"
190
.\\\"     \"%(bzrcmd)s help <cmd>\"
191
.\\\"
192
.\\\" Generation time: %(timestamp)s
193
.\\\"
6498.2.1 by Jelmer Vernooij
Properly format apostrophes in manual page.
194
195
.ie \\n(.g .ds Aq \\(aq
196
.el .ds Aq '
635 by Martin Pool
- manpage generator by Hans Ulrich Niedermann
197
"""
198
1551.3.11 by Aaron Bentley
Merge from Robert
199
635 by Martin Pool
- manpage generator by Hans Ulrich Niedermann
200
man_head = """\
1861.2.8 by Alexander Belchenko
More branding: bazaar-ng -> Bazaar; bazaar-ng.org -> bazaar-vcs.org
201
.TH bzr 1 "%(datestamp)s" "%(version)s" "Bazaar"
635 by Martin Pool
- manpage generator by Hans Ulrich Niedermann
202
.SH "NAME"
4785.1.1 by John Ferlito
lexgrog doesn't like having "Bazaar (bzr)" as the nae of the command page
203
%(bzrcmd)s - Bazaar next-generation distributed version control
635 by Martin Pool
- manpage generator by Hans Ulrich Niedermann
204
.SH "SYNOPSIS"
205
.B "%(bzrcmd)s"
206
.I "command"
207
[
208
.I "command_options"
209
]
210
.br
211
.B "%(bzrcmd)s"
212
.B "help"
213
.br
214
.B "%(bzrcmd)s"
215
.B "help"
216
.I "command"
217
.SH "DESCRIPTION"
6015.8.1 by Martin Pool
Mention GNU and improve phrasing of the start of the man page.
218
219
Bazaar (or %(bzrcmd)s) is a distributed version control system that is powerful, 
220
friendly, and scalable.  Bazaar is a project of Canonical Ltd and part of 
221
the GNU Project to develop a free operating system.
222
223
Bazaar keeps track of changes to software source code (or similar information);
224
lets you explore who changed it, when, and why; merges concurrent changes; and
225
helps people work together in a team.
635 by Martin Pool
- manpage generator by Hans Ulrich Niedermann
226
"""
227
228
man_foot = """\
229
.SH "FILES"
230
.TP
1861.3.2 by Alexander Belchenko
bzr.1 man page: show aliases for commands; fixed description of bazaar.conf
231
.I "~/.bazaar/bazaar.conf"
2374.1.1 by Ian Clatworthy
Help and man page fixes
232
Contains the user's default configuration. The section
1551.3.11 by Aaron Bentley
Merge from Robert
233
.B [DEFAULT]
1861.2.14 by Alexander Belchenko
generate_docs (man/rstx): fixed description of configuration file
234
is used to define general configuration that will be applied everywhere.
235
The section
236
.B [ALIASES]
237
can be used to create command aliases for
238
commonly used options.
239
240
A typical config file might look something like:
241
242
.br
243
[DEFAULT]
244
.br
245
email=John Doe <jdoe@isp.com>
246
.br
247
[ALIASES]
248
.br
249
commit = commit --strict
250
.br
251
log10 = log --short -r -10..-1
635 by Martin Pool
- manpage generator by Hans Ulrich Niedermann
252
.SH "SEE ALSO"
5050.47.1 by Martin Pool
Backport fix for bad url in bzr help
253
.UR http://bazaar.canonical.com/
254
.BR http://bazaar.canonical.com/
635 by Martin Pool
- manpage generator by Hans Ulrich Niedermann
255
"""
256