← 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: John Arbash Meinel
  • Author(s): Mark Hammond
  • Date: 2008-09-09 17:02:21 UTC
  • mto: This revision was merged to the branch mainline in revision 3697.
  • Revision ID: john@arbash-meinel.com-20080909170221-svim3jw2mrz0amp3
An updated transparent icon for bzr.

Show diffs side-by-side

added added

removed removed

Lines of Context:
tools/doc_generate/autodoc_man.py
1
 
# Copyright (C) 2005-2010 Canonical Ltd
 
1
# Copyright 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
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., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
 
15
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  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
 
from __future__ import absolute_import
25
 
 
26
 
PLUGINS_TO_DOCUMENT = ["launchpad"]
27
 
 
 
24
import os
 
25
import sys
28
26
import textwrap
29
27
import time
30
28
 
33
31
import bzrlib.help_topics
34
32
import bzrlib.commands
35
33
 
36
 
from bzrlib.plugin import load_plugins
37
 
load_plugins()
38
 
 
39
34
 
40
35
def get_filename(options):
41
36
    """Provides name of manpage"""
56
51
    outfile.write(man_escape(man_head % params))
57
52
    outfile.write(man_escape(getcommand_list(params)))
58
53
    outfile.write(man_escape(getcommand_help(params)))
59
 
    outfile.write("".join(environment_variables()))
60
54
    outfile.write(man_escape(man_foot % params))
61
55
 
62
56
 
63
57
def man_escape(string):
64
58
    """Escapes strings for man page compatibility"""
65
59
    result = string.replace("\\","\\\\")
66
 
    result = result.replace("`","\\'")
67
 
    result = result.replace("'","\\*(Aq")
 
60
    result = result.replace("`","\\`")
 
61
    result = result.replace("'","\\'")
68
62
    result = result.replace("-","\\-")
69
63
    return result
70
64
 
72
66
def command_name_list():
73
67
    """Builds a list of command names from bzrlib"""
74
68
    command_names = bzrlib.commands.builtin_command_names()
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
78
 
            cmd_object.plugin_name() in PLUGINS_TO_DOCUMENT):
79
 
            command_names.append(cmdname)
80
69
    command_names.sort()
81
70
    return command_names
82
71
 
103
92
def getcommand_help(params):
104
93
    """Shows individual options for a bzr command"""
105
94
    output='.SH "COMMAND REFERENCE"\n'
106
 
    formatted = {}
107
95
    for cmd_name in command_name_list():
108
96
        cmd_object = bzrlib.commands.get_cmd_object(cmd_name)
109
97
        if cmd_object.hidden:
110
98
            continue
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)
114
 
    for cmd_name in sorted(formatted):
115
 
        output += formatted[cmd_name]
 
99
        output = output + format_command(params, cmd_object)
116
100
    return output
117
101
 
118
102
 
119
 
def format_command(params, cmd):
 
103
def format_command (params, cmd):
120
104
    """Provides long help for each public command"""
121
105
    subsection_header = '.SS "%s"\n' % (cmd._usage())
122
106
    doc = "%s\n" % (cmd.__doc__)
123
107
    doc = bzrlib.help_topics.help_as_plain_text(cmd.help())
124
108
 
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
 
 
130
109
    option_str = ""
131
110
    options = cmd.options()
132
111
    if options:
139
118
                if argname is not None:
140
119
                    l += ' ' + argname
141
120
                if short_name:
 
121
                    assert len(short_name) == 1
142
122
                    l += ', -' + short_name
143
123
                l += (30 - len(l)) * ' ' + (help or '')
144
124
                wrapped = textwrap.fill(l, initial_indent='',
145
 
                    subsequent_indent=30*' ',
146
 
                    break_long_words=False,
147
 
                    )
148
 
                option_str += wrapped + '\n'
 
125
                                        subsequent_indent=30*' ')
 
126
                option_str = option_str + wrapped + '\n'       
149
127
 
150
128
    aliases_str = ""
151
129
    if cmd.aliases:
166
144
    return subsection_header + option_str + aliases_str + see_also_str + "\n" + doc + "\n"
167
145
 
168
146
 
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
 
 
175
 
def environment_variables():
176
 
    yield ".SH \"ENVIRONMENT\"\n"
177
 
 
178
 
    from bzrlib.help_topics import known_env_variables
179
 
    for k, desc in known_env_variables:
180
 
        yield ".TP\n"
181
 
        yield ".I \"%s\"\n" % k
182
 
        yield man_escape(desc) + "\n"
183
 
 
184
 
 
185
147
man_preamble = """\
186
 
.\\\"Man page for Bazaar (%(bzrcmd)s)
 
148
Man page for Bazaar (%(bzrcmd)s)
187
149
.\\\"
188
150
.\\\" Large parts of this file are autogenerated from the output of
189
151
.\\\"     \"%(bzrcmd)s help commands\"
190
152
.\\\"     \"%(bzrcmd)s help <cmd>\"
191
153
.\\\"
192
 
 
193
 
.ie \\n(.g .ds Aq \\(aq
194
 
.el .ds Aq '
 
154
.\\\" Generation time: %(timestamp)s
 
155
.\\\"
195
156
"""
196
157
 
197
158
 
198
159
man_head = """\
199
160
.TH bzr 1 "%(datestamp)s" "%(version)s" "Bazaar"
200
161
.SH "NAME"
201
 
%(bzrcmd)s - Bazaar next-generation distributed version control
 
162
Bazaar (%(bzrcmd)s) - next-generation distributed version control
202
163
.SH "SYNOPSIS"
203
164
.B "%(bzrcmd)s"
204
165
.I "command"
213
174
.B "help"
214
175
.I "command"
215
176
.SH "DESCRIPTION"
216
 
 
217
 
Bazaar (or %(bzrcmd)s) is a distributed version control system that is powerful, 
218
 
friendly, and scalable.  Bazaar is a project of Canonical Ltd and part of 
219
 
the GNU Project to develop a free operating system.
220
 
 
221
 
Bazaar keeps track of changes to software source code (or similar information);
222
 
lets you explore who changed it, when, and why; merges concurrent changes; and
223
 
helps people work together in a team.
 
177
Bazaar (or %(bzrcmd)s) is a project of Canonical to develop an open source
 
178
distributed version control system that is powerful, friendly, and scalable.
 
179
Version control means a system that keeps track of previous revisions
 
180
of software source code or similar information and helps people work on it in teams.
224
181
"""
225
182
 
226
183
man_foot = """\
 
184
.SH "ENVIRONMENT"
 
185
.TP
 
186
.I "BZRPATH"
 
187
Path where
 
188
.B "%(bzrcmd)s"
 
189
is to look for shell plugin external commands.
 
190
.TP
 
191
.I "BZR_EMAIL"
 
192
E-Mail address of the user. Overrides default user config.
 
193
.TP
 
194
.I "EMAIL"
 
195
E-Mail address of the user. Overrides default user config.
 
196
.TP
 
197
.I "BZR_EDITOR"
 
198
Editor for editing commit messages
 
199
.TP
 
200
.I "EDITOR"
 
201
Editor for editing commit messages
 
202
.TP
 
203
.I "BZR_PLUGIN_PATH"
 
204
Paths where bzr should look for plugins
 
205
.TP
 
206
.I "BZR_HOME"
 
207
Home directory for bzr
227
208
.SH "FILES"
228
209
.TP
229
210
.I "~/.bazaar/bazaar.conf"
248
229
.br
249
230
log10 = log --short -r -10..-1
250
231
.SH "SEE ALSO"
251
 
.UR http://bazaar.canonical.com/
252
 
.BR http://bazaar.canonical.com/
 
232
.UR http://www.bazaar-vcs.org/
 
233
.BR http://www.bazaar-vcs.org/
253
234
"""
254
235