← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to bzrlib/doc_generate/autodoc_man.py

  • Committer: Robert Collins
  • Date: 2009-09-07 03:08:30 UTC
  • mto: This revision was merged to the branch mainline in revision 4690.
  • Revision ID: robertc@robertcollins.net-20090907030830-rf59kt28d550eauj
Milestones language tightning, internal consistency.

Show diffs side-by-side

added added

removed removed

Lines of Context:
bzrlib/doc_generate/autodoc_man.py
1
 
# Copyright 2005 Canonical Ltd.
 
1
# Copyright (C) 2005 Canonical Ltd
2
2
 
3
3
# This program is free software; you can redistribute it and/or modify
4
4
# it under the terms of the GNU General Public License as published by
5
5
# the Free Software Foundation; either version 2 of the License, or
6
6
# (at your option) any later version.
7
 
 
 
7
#
8
8
# This program is distributed in the hope that it will be useful,
9
9
# but WITHOUT ANY WARRANTY; without even the implied warranty of
10
10
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
11
11
# GNU General Public License for more details.
12
 
 
 
12
#
13
13
# You should have received a copy of the GNU General Public License
14
14
# along with this program; if not, write to the Free Software
15
 
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 
15
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
16
16
 
17
17
"""man.py - create man page from built-in bzr help and static text
18
18
 
28
28
 
29
29
import bzrlib
30
30
import bzrlib.help
 
31
import bzrlib.help_topics
31
32
import bzrlib.commands
32
33
 
33
34
 
80
81
        cmd_help = cmd_object.help()
81
82
        if cmd_help:
82
83
            firstline = cmd_help.split('\n', 1)[0]
83
 
            usage = bzrlib.help.command_usage(cmd_object)
 
84
            usage = cmd_object._usage()
84
85
            tmp = '.TP\n.B "%s"\n%s\n' % (usage, firstline)
85
86
            output = output + tmp
86
87
        else:
91
92
def getcommand_help(params):
92
93
    """Shows individual options for a bzr command"""
93
94
    output='.SH "COMMAND REFERENCE"\n'
 
95
    formatted = {}
94
96
    for cmd_name in command_name_list():
95
97
        cmd_object = bzrlib.commands.get_cmd_object(cmd_name)
96
98
        if cmd_object.hidden:
97
99
            continue
98
 
        output = output + format_command(params, cmd_object)
 
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]
99
105
    return output
100
106
 
101
107
 
102
108
def format_command (params, cmd):
103
109
    """Provides long help for each public command"""
104
 
    subsection_header = '.SS "%s"\n' % (bzrlib.help.command_usage(cmd))
 
110
    subsection_header = '.SS "%s"\n' % (cmd._usage())
105
111
    doc = "%s\n" % (cmd.__doc__)
106
 
    docsplit = cmd.__doc__.split('\n')
107
 
    doc = '\n'.join([docsplit[0]] + [line[4:] for line in docsplit[1:]])
 
112
    doc = bzrlib.help_topics.help_as_plain_text(cmd.help())
 
113
 
108
114
    option_str = ""
109
115
    options = cmd.options()
110
116
    if options:
111
117
        option_str = "\nOptions:\n"
112
118
        for option_name, option in sorted(options.items()):
113
 
            l = '    --' + option_name
114
 
            if option.type is not None:
115
 
                l += ' ' + option.argname.upper()
116
 
            short_name = option.short_name()
117
 
            if short_name:
118
 
                assert len(short_name) == 1
119
 
                l += ', -' + short_name
120
 
            l += (30 - len(l)) * ' ' + option.help
121
 
            # TODO: Split help over multiple lines with
122
 
            # correct indenting and wrapping.
123
 
            wrapped = textwrap.fill(l, initial_indent='',
124
 
                                    subsequent_indent=30*' ')
125
 
            option_str = option_str + wrapped + '\n'       
126
 
    return subsection_header + option_str + "\n" + doc + "\n"
 
119
            for name, short_name, argname, help in option.iter_switches():
 
120
                if option.is_hidden(name):
 
121
                    continue
 
122
                l = '    --' + name
 
123
                if argname is not None:
 
124
                    l += ' ' + argname
 
125
                if short_name:
 
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,
 
131
                    )
 
132
                option_str = option_str + wrapped + '\n'       
 
133
 
 
134
    aliases_str = ""
 
135
    if cmd.aliases:
 
136
        if len(cmd.aliases) > 1:
 
137
            aliases_str += '\nAliases: '
 
138
        else:
 
139
            aliases_str += '\nAlias: '
 
140
        aliases_str += ', '.join(cmd.aliases)
 
141
        aliases_str += '\n'
 
142
 
 
143
    see_also_str = ""
 
144
    see_also = cmd.get_see_also()
 
145
    if see_also:
 
146
        see_also_str += '\nSee also: '
 
147
        see_also_str += ', '.join(see_also)
 
148
        see_also_str += '\n'
 
149
 
 
150
    return subsection_header + option_str + aliases_str + see_also_str + "\n" + doc + "\n"
 
151
 
 
152
 
 
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)
 
156
    return help
127
157
 
128
158
 
129
159
man_preamble = """\
130
 
Man page for %(bzrcmd)s (bazaar-ng)
 
160
.\\\"Man page for Bazaar (%(bzrcmd)s)
131
161
.\\\"
132
162
.\\\" Large parts of this file are autogenerated from the output of
133
163
.\\\"     \"%(bzrcmd)s help commands\"
139
169
 
140
170
 
141
171
man_head = """\
142
 
.TH bzr 1 "%(datestamp)s" "%(version)s" "bazaar-ng"
 
172
.TH bzr 1 "%(datestamp)s" "%(version)s" "Bazaar"
143
173
.SH "NAME"
144
 
%(bzrcmd)s - bazaar-ng next-generation distributed version control
 
174
Bazaar (%(bzrcmd)s) - next-generation distributed version control
145
175
.SH "SYNOPSIS"
146
176
.B "%(bzrcmd)s"
147
177
.I "command"
156
186
.B "help"
157
187
.I "command"
158
188
.SH "DESCRIPTION"
159
 
bazaar-ng (or
160
 
.B "%(bzrcmd)s"
161
 
) 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.
162
 
.SS "Warning"
163
 
bazaar-ng is at an early stage of development, and the design is still changing from week to week. This man page here may be inconsistent with itself, with other documentation or with the code, and sometimes refer to features that are planned but not yet written. Comments are still very welcome; please send them to bazaar-ng@lists.canonical.com.
 
189
Bazaar (or %(bzrcmd)s) is a project of Canonical to develop an open source
 
190
distributed version control system that is powerful, friendly, and scalable.
 
191
Version control means a system that keeps track of previous revisions
 
192
of software source code or similar information and helps people work on it in teams.
164
193
"""
165
194
 
166
195
man_foot = """\
169
198
.I "BZRPATH"
170
199
Path where
171
200
.B "%(bzrcmd)s"
172
 
is to look for external command.
 
201
is to look for shell plugin external commands.
173
202
.TP
174
 
.I "BZREMAIL"
 
203
.I "BZR_EMAIL"
175
204
E-Mail address of the user. Overrides default user config.
176
205
.TP
177
206
.I "EMAIL"
178
 
E-Mail address of the user. Overriddes default user config.
 
207
E-Mail address of the user. Overrides default user config.
 
208
.TP
 
209
.I "BZR_EDITOR"
 
210
Editor for editing commit messages
 
211
.TP
 
212
.I "EDITOR"
 
213
Editor for editing commit messages
 
214
.TP
 
215
.I "BZR_PLUGIN_PATH"
 
216
Paths where bzr should look for plugins
 
217
.TP
 
218
.I "BZR_HOME"
 
219
Home directory for bzr
179
220
.SH "FILES"
180
221
.TP
181
 
.I "~/.bazaar/bazaar.conf/"
182
 
Contains the default user config. Only one section, [DEFAULT] is allowed. A 
183
 
typical default config file may be similiar to:
184
 
.br
185
 
.br
 
222
.I "~/.bazaar/bazaar.conf"
 
223
Contains the user's default configuration. The section
186
224
.B [DEFAULT]
187
 
.br
188
 
.B email=John Doe <jdoe@isp.com>
 
225
is used to define general configuration that will be applied everywhere.
 
226
The section
 
227
.B [ALIASES]
 
228
can be used to create command aliases for
 
229
commonly used options.
 
230
 
 
231
A typical config file might look something like:
 
232
 
 
233
.br
 
234
[DEFAULT]
 
235
.br
 
236
email=John Doe <jdoe@isp.com>
 
237
.br
 
238
[ALIASES]
 
239
.br
 
240
commit = commit --strict
 
241
.br
 
242
log10 = log --short -r -10..-1
189
243
.SH "SEE ALSO"
190
 
.UR http://bazaar.canonical.com/
191
 
.BR http://bazaar.canonical.com/,
192
 
.UR http://www.bazaar-ng.org/
193
 
.BR http://www.bazaar-ng.org/
 
244
.UR http://www.bazaar-vcs.org/
 
245
.BR http://www.bazaar-vcs.org/
194
246
"""
195
247