← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to tools/doc_generate/autodoc_man.py

  • Committer: Canonical.com Patch Queue Manager
  • Date: 2009-03-24 05:12:24 UTC
  • mfrom: (4189.1.1 integration)
  • Revision ID: pqm@pqm.ubuntu.com-20090324051224-rneg6bkbzjyd85rl
(mbp) merge update to FSF address

Show diffs side-by-side

added added

removed removed

Lines of Context:
tools/doc_generate/autodoc_man.py
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
                    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'       
 
132
 
 
133
    aliases_str = ""
 
134
    if cmd.aliases:
 
135
        if len(cmd.aliases) > 1:
 
136
            aliases_str += '\nAliases: '
 
137
        else:
 
138
            aliases_str += '\nAlias: '
 
139
        aliases_str += ', '.join(cmd.aliases)
 
140
        aliases_str += '\n'
 
141
 
 
142
    see_also_str = ""
 
143
    see_also = cmd.get_see_also()
 
144
    if see_also:
 
145
        see_also_str += '\nSee also: '
 
146
        see_also_str += ', '.join(see_also)
 
147
        see_also_str += '\n'
 
148
 
 
149
    return subsection_header + option_str + aliases_str + see_also_str + "\n" + doc + "\n"
 
150
 
 
151
 
 
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)
 
155
    return help
127
156
 
128
157
 
129
158
man_preamble = """\
130
 
Man page for %(bzrcmd)s (bazaar-ng)
 
159
.\\\"Man page for Bazaar (%(bzrcmd)s)
131
160
.\\\"
132
161
.\\\" Large parts of this file are autogenerated from the output of
133
162
.\\\"     \"%(bzrcmd)s help commands\"
139
168
 
140
169
 
141
170
man_head = """\
142
 
.TH bzr 1 "%(datestamp)s" "%(version)s" "bazaar-ng"
 
171
.TH bzr 1 "%(datestamp)s" "%(version)s" "Bazaar"
143
172
.SH "NAME"
144
 
%(bzrcmd)s - bazaar-ng next-generation distributed version control
 
173
Bazaar (%(bzrcmd)s) - next-generation distributed version control
145
174
.SH "SYNOPSIS"
146
175
.B "%(bzrcmd)s"
147
176
.I "command"
156
185
.B "help"
157
186
.I "command"
158
187
.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.
 
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.
162
192
"""
163
193
 
164
194
man_foot = """\
167
197
.I "BZRPATH"
168
198
Path where
169
199
.B "%(bzrcmd)s"
170
 
is to look for external command.
 
200
is to look for shell plugin external commands.
171
201
.TP
172
 
.I "BZREMAIL"
 
202
.I "BZR_EMAIL"
173
203
E-Mail address of the user. Overrides default user config.
174
204
.TP
175
205
.I "EMAIL"
176
 
E-Mail address of the user. Overriddes default user config.
 
206
E-Mail address of the user. Overrides default user config.
 
207
.TP
 
208
.I "BZR_EDITOR"
 
209
Editor for editing commit messages
 
210
.TP
 
211
.I "EDITOR"
 
212
Editor for editing commit messages
 
213
.TP
 
214
.I "BZR_PLUGIN_PATH"
 
215
Paths where bzr should look for plugins
 
216
.TP
 
217
.I "BZR_HOME"
 
218
Home directory for bzr
177
219
.SH "FILES"
178
220
.TP
179
 
.I "~/.bazaar/bazaar.conf/"
180
 
Contains the default user config. Only one section, [DEFAULT] is allowed. A 
181
 
typical default config file may be similiar to:
182
 
.br
183
 
.br
 
221
.I "~/.bazaar/bazaar.conf"
 
222
Contains the user's default configuration. The section
184
223
.B [DEFAULT]
185
 
.br
186
 
.B email=John Doe <jdoe@isp.com>
 
224
is used to define general configuration that will be applied everywhere.
 
225
The section
 
226
.B [ALIASES]
 
227
can be used to create command aliases for
 
228
commonly used options.
 
229
 
 
230
A typical config file might look something like:
 
231
 
 
232
.br
 
233
[DEFAULT]
 
234
.br
 
235
email=John Doe <jdoe@isp.com>
 
236
.br
 
237
[ALIASES]
 
238
.br
 
239
commit = commit --strict
 
240
.br
 
241
log10 = log --short -r -10..-1
187
242
.SH "SEE ALSO"
188
243
.UR http://www.bazaar-vcs.org/
189
244
.BR http://www.bazaar-vcs.org/