← 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: John Arbash Meinel
  • Date: 2009-02-19 20:55:17 UTC
  • mto: (0.22.4 experimental)
  • mto: This revision was merged to the branch mainline in revision 4280.
  • Revision ID: john@arbash-meinel.com-20090219205517-drw89424koe6h1da
Play around a bit.

1) Empty texts are no-op inserted, to avoid ever trying to match against their text.
2) If we find a new file-id and the compressor is more than half full, we go
ahead and start a new compressor.

Show diffs side-by-side

added added

removed removed

Lines of Context:
bzrlib/doc_generate/autodoc_man.py
1
 
# Copyright (C) 2005-2010 Canonical Ltd
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.
7
 
#
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.
12
 
#
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
15
 
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
16
 
 
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
 
 
24
 
import os
25
 
import sys
26
 
import textwrap
27
 
import time
28
 
 
29
 
import bzrlib
30
 
import bzrlib.help
31
 
import bzrlib.help_topics
32
 
import bzrlib.commands
33
 
 
34
 
 
35
 
def get_filename(options):
36
 
    """Provides name of manpage"""
37
 
    return "%s.1" % (options.bzr_name)
38
 
 
39
 
 
40
 
def infogen(options, outfile):
41
 
    """Assembles a man page"""
42
 
    t = time.time()
43
 
    tt = time.gmtime(t)
44
 
    params = \
45
 
           { "bzrcmd": options.bzr_name,
46
 
             "datestamp": time.strftime("%Y-%m-%d",tt),
47
 
             "timestamp": time.strftime("%Y-%m-%d %H:%M:%S +0000",tt),
48
 
             "version": bzrlib.__version__,
49
 
             }
50
 
    outfile.write(man_preamble % params)
51
 
    outfile.write(man_escape(man_head % params))
52
 
    outfile.write(man_escape(getcommand_list(params)))
53
 
    outfile.write(man_escape(getcommand_help(params)))
54
 
    outfile.write(man_escape(man_foot % params))
55
 
 
56
 
 
57
 
def man_escape(string):
58
 
    """Escapes strings for man page compatibility"""
59
 
    result = string.replace("\\","\\\\")
60
 
    result = result.replace("`","\\`")
61
 
    result = result.replace("'","\\'")
62
 
    result = result.replace("-","\\-")
63
 
    return result
64
 
 
65
 
 
66
 
def command_name_list():
67
 
    """Builds a list of command names from bzrlib"""
68
 
    command_names = bzrlib.commands.builtin_command_names()
69
 
    command_names.sort()
70
 
    return command_names
71
 
 
72
 
 
73
 
def getcommand_list (params):
74
 
    """Builds summary help for command names in manpage format"""
75
 
    bzrcmd = params["bzrcmd"]
76
 
    output = '.SH "COMMAND OVERVIEW"\n'
77
 
    for cmd_name in command_name_list():
78
 
        cmd_object = bzrlib.commands.get_cmd_object(cmd_name)
79
 
        if cmd_object.hidden:
80
 
            continue
81
 
        cmd_help = cmd_object.help()
82
 
        if cmd_help:
83
 
            firstline = cmd_help.split('\n', 1)[0]
84
 
            usage = cmd_object._usage()
85
 
            tmp = '.TP\n.B "%s"\n%s\n' % (usage, firstline)
86
 
            output = output + tmp
87
 
        else:
88
 
            raise RuntimeError, "Command '%s' has no help text" % (cmd_name)
89
 
    return output
90
 
 
91
 
 
92
 
def getcommand_help(params):
93
 
    """Shows individual options for a bzr command"""
94
 
    output='.SH "COMMAND REFERENCE"\n'
95
 
    formatted = {}
96
 
    for cmd_name in command_name_list():
97
 
        cmd_object = bzrlib.commands.get_cmd_object(cmd_name)
98
 
        if cmd_object.hidden:
99
 
            continue
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]
105
 
    return output
106
 
 
107
 
 
108
 
def format_command (params, cmd):
109
 
    """Provides long help for each public command"""
110
 
    subsection_header = '.SS "%s"\n' % (cmd._usage())
111
 
    doc = "%s\n" % (cmd.__doc__)
112
 
    doc = bzrlib.help_topics.help_as_plain_text(cmd.help())
113
 
 
114
 
    option_str = ""
115
 
    options = cmd.options()
116
 
    if options:
117
 
        option_str = "\nOptions:\n"
118
 
        for option_name, option in sorted(options.items()):
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
157
 
 
158
 
 
159
 
man_preamble = """\
160
 
.\\\"Man page for Bazaar (%(bzrcmd)s)
161
 
.\\\"
162
 
.\\\" Large parts of this file are autogenerated from the output of
163
 
.\\\"     \"%(bzrcmd)s help commands\"
164
 
.\\\"     \"%(bzrcmd)s help <cmd>\"
165
 
.\\\"
166
 
.\\\" Generation time: %(timestamp)s
167
 
.\\\"
168
 
"""
169
 
 
170
 
 
171
 
man_head = """\
172
 
.TH bzr 1 "%(datestamp)s" "%(version)s" "Bazaar"
173
 
.SH "NAME"
174
 
%(bzrcmd)s - Bazaar next-generation distributed version control
175
 
.SH "SYNOPSIS"
176
 
.B "%(bzrcmd)s"
177
 
.I "command"
178
 
[
179
 
.I "command_options"
180
 
]
181
 
.br
182
 
.B "%(bzrcmd)s"
183
 
.B "help"
184
 
.br
185
 
.B "%(bzrcmd)s"
186
 
.B "help"
187
 
.I "command"
188
 
.SH "DESCRIPTION"
189
 
Bazaar (or %(bzrcmd)s) is a project of Canonical to develop an free
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.
193
 
"""
194
 
 
195
 
man_foot = """\
196
 
.SH "ENVIRONMENT"
197
 
.TP
198
 
.I "BZRPATH"
199
 
Path where
200
 
.B "%(bzrcmd)s"
201
 
is to look for shell plugin external commands.
202
 
.TP
203
 
.I "BZR_EMAIL"
204
 
E-Mail address of the user. Overrides default user config.
205
 
.TP
206
 
.I "EMAIL"
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
220
 
.SH "FILES"
221
 
.TP
222
 
.I "~/.bazaar/bazaar.conf"
223
 
Contains the user's default configuration. The section
224
 
.B [DEFAULT]
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
243
 
.SH "SEE ALSO"
244
 
.UR http://bazaar.canonical.com/
245
 
.BR http://bazaar.canonical.com/
246
 
"""
247