← 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: Patch Queue Manager
  • Date: 2012-03-15 11:06:07 UTC
  • mfrom: (6504.1.2 trunk)
  • Revision ID: pqm@pqm.ubuntu.com-20120315110607-bbulg6wegrhwnavm
(vila) Release 2.6b1 (Vincent Ladeuil)

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-2010 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
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
 
21
21
  * add command aliases
22
22
"""
23
23
 
24
 
import os
25
 
import sys
 
24
from __future__ import absolute_import
 
25
 
26
26
import textwrap
27
27
import time
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
 
56
57
def man_escape(string):
57
58
    """Escapes strings for man page compatibility"""
58
59
    result = string.replace("\\","\\\\")
59
 
    result = result.replace("`","\\`")
60
 
    result = result.replace("'","\\'")
 
60
    result = result.replace("`","\\'")
 
61
    result = result.replace("'","\\*(Aq")
61
62
    result = result.replace("-","\\-")
62
63
    return result
63
64
 
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
 
    doc = cmd.help()
 
112
    doc = bzrlib.help_topics.help_as_plain_text(cmd.help())
 
113
 
 
114
    # A dot at the beginning of a line is interpreted as a macro.
 
115
    # Simply join lines that begin with a dot with the previous
 
116
    # line to work around this.
 
117
    doc = doc.replace("\n.", ".")
107
118
 
108
119
    option_str = ""
109
120
    options = cmd.options()
111
122
        option_str = "\nOptions:\n"
112
123
        for option_name, option in sorted(options.items()):
113
124
            for name, short_name, argname, help in option.iter_switches():
 
125
                if option.is_hidden(name):
 
126
                    continue
114
127
                l = '    --' + name
115
128
                if argname is not None:
116
129
                    l += ' ' + argname
117
130
                if short_name:
118
 
                    assert len(short_name) == 1
119
131
                    l += ', -' + short_name
120
 
                l += (30 - len(l)) * ' ' + help
121
 
                # TODO: Split help over multiple lines with
122
 
                # correct indenting and wrapping.
 
132
                l += (30 - len(l)) * ' ' + (help or '')
123
133
                wrapped = textwrap.fill(l, initial_indent='',
124
 
                                        subsequent_indent=30*' ')
 
134
                    subsequent_indent=30*' ',
 
135
                    break_long_words=False,
 
136
                    )
125
137
                option_str = option_str + wrapped + '\n'       
126
138
 
127
139
    aliases_str = ""
133
145
        aliases_str += ', '.join(cmd.aliases)
134
146
        aliases_str += '\n'
135
147
 
136
 
    return subsection_header + option_str + aliases_str + "\n" + doc + "\n"
 
148
    see_also_str = ""
 
149
    see_also = cmd.get_see_also()
 
150
    if see_also:
 
151
        see_also_str += '\nSee also: '
 
152
        see_also_str += ', '.join(see_also)
 
153
        see_also_str += '\n'
 
154
 
 
155
    return subsection_header + option_str + aliases_str + see_also_str + "\n" + doc + "\n"
 
156
 
 
157
 
 
158
def format_alias(params, alias, cmd_name):
 
159
    help = '.SS "bzr %s"\n' % alias
 
160
    help += 'Alias for "%s", see "bzr %s".\n' % (cmd_name, cmd_name)
 
161
    return help
137
162
 
138
163
 
139
164
man_preamble = """\
140
 
Man page for Bazaar (%(bzrcmd)s)
 
165
.\\\"Man page for Bazaar (%(bzrcmd)s)
141
166
.\\\"
142
167
.\\\" Large parts of this file are autogenerated from the output of
143
168
.\\\"     \"%(bzrcmd)s help commands\"
145
170
.\\\"
146
171
.\\\" Generation time: %(timestamp)s
147
172
.\\\"
 
173
 
 
174
.ie \\n(.g .ds Aq \\(aq
 
175
.el .ds Aq '
148
176
"""
149
177
 
150
178
 
151
179
man_head = """\
152
180
.TH bzr 1 "%(datestamp)s" "%(version)s" "Bazaar"
153
181
.SH "NAME"
154
 
Bazaar (%(bzrcmd)s) - next-generation distributed version control
 
182
%(bzrcmd)s - Bazaar next-generation distributed version control
155
183
.SH "SYNOPSIS"
156
184
.B "%(bzrcmd)s"
157
185
.I "command"
166
194
.B "help"
167
195
.I "command"
168
196
.SH "DESCRIPTION"
169
 
Bazaar (or %(bzrcmd)s) is a project of Canonical to develop an open source
170
 
distributed version control system that is powerful, friendly, and scalable.
171
 
Version control means a system that keeps track of previous revisions
172
 
of software source code or similar information and helps people work on it in teams.
 
197
 
 
198
Bazaar (or %(bzrcmd)s) is a distributed version control system that is powerful, 
 
199
friendly, and scalable.  Bazaar is a project of Canonical Ltd and part of 
 
200
the GNU Project to develop a free operating system.
 
201
 
 
202
Bazaar keeps track of changes to software source code (or similar information);
 
203
lets you explore who changed it, when, and why; merges concurrent changes; and
 
204
helps people work together in a team.
173
205
"""
174
206
 
175
207
man_foot = """\
178
210
.I "BZRPATH"
179
211
Path where
180
212
.B "%(bzrcmd)s"
181
 
is to look for external command.
 
213
is to look for shell plugin external commands.
182
214
.TP
183
215
.I "BZR_EMAIL"
184
216
E-Mail address of the user. Overrides default user config.
185
217
.TP
186
218
.I "EMAIL"
187
 
E-Mail address of the user. Overriddes default user config.
 
219
E-Mail address of the user. Overrides default user config.
188
220
.TP
189
221
.I "BZR_EDITOR"
190
222
Editor for editing commit messages
200
232
.SH "FILES"
201
233
.TP
202
234
.I "~/.bazaar/bazaar.conf"
203
 
Contains the users default configuration. The section
 
235
Contains the user's default configuration. The section
204
236
.B [DEFAULT]
205
237
is used to define general configuration that will be applied everywhere.
206
238
The section
221
253
.br
222
254
log10 = log --short -r -10..-1
223
255
.SH "SEE ALSO"
224
 
.UR http://www.bazaar-vcs.org/
225
 
.BR http://www.bazaar-vcs.org/
 
256
.UR http://bazaar.canonical.com/
 
257
.BR http://bazaar.canonical.com/
226
258
"""
227
259