← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to bzrinfogen/big_man.py

- Pulling generated docs into one place, though whether bash completion is
  documents is arguable....

- Bash completion generator. [Hans Ulrich Niedermann]

Show diffs side-by-side

added added

removed removed

Lines of Context:
bzrinfogen/big_man.py
1
1
#!/usr/bin/python
2
2
 
3
 
# Marked portions Copyright (C) 2005 by Hans Ulrich Niedermann
4
 
# Unmarked portions (C) 2005 Canonical Ltd.
 
3
# Copyright 2005 Canonical Ltd.
5
4
 
6
5
# This program is free software; you can redistribute it and/or modify
7
6
# it under the terms of the GNU General Public License as published by
17
16
# along with this program; if not, write to the Free Software
18
17
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
19
18
 
 
19
"""big_man.py - create man page from built-in bzr help and static text
 
20
 
 
21
TODO:
 
22
  * use usage information instead of simple "bzr foo" in COMMAND OVERVIEW
 
23
  * add command aliases
 
24
"""
 
25
 
20
26
import os, sys
21
27
import bzrlib, bzrlib.help, bzrlib.commands
22
 
#<<< Begin (C) Hans Ulrich Niedermann
 
28
import textwrap
23
29
import time
24
 
import re
25
 
 
26
 
def main():
 
30
 
 
31
 
 
32
def get_filename(options):
 
33
    return "%s.1" % (options.bzr_name)
 
34
 
 
35
 
 
36
def infogen(options, outfile):
27
37
    t = time.time()
28
38
    tt = time.gmtime(t)
29
39
    params = \
30
 
           { "bzrcmd": "bzr",
 
40
           { "bzrcmd": options.bzr_name,
31
41
             "datestamp": time.strftime("%Y-%m-%d",tt),
32
42
             "timestamp": time.strftime("%Y-%m-%d %H:%M:%S +0000",tt),
33
43
             "version": bzrlib.__version__,
34
44
             }
35
45
 
36
 
    filename = "bzr.1"
37
 
    if len(sys.argv) == 2:
38
 
        filename = sys.argv[1]
39
 
    if filename == "-":
40
 
        outfile = sys.stdout
41
 
    else:
42
 
        outfile = open(filename,"w")
43
 
 
44
46
    outfile.write(man_preamble % params)
45
47
    outfile.write(man_escape(man_head % params))
46
 
#<<< End (C) Hans Ulrich Niedermann
47
 
    outfile.write(man_escape(getcommand_help()))
48
 
#<<< Begin (C) Hans Ulrich Niedermann
 
48
 
 
49
    outfile.write(man_escape(getcommand_list(params)))
 
50
    outfile.write(man_escape(getcommand_help(params)))
 
51
 
49
52
    outfile.write(man_escape(man_foot % params))
50
53
 
 
54
 
51
55
def man_escape(string):
52
56
    result = string.replace("\\","\\\\")
53
57
    result = result.replace("`","\\`")
54
58
    result = result.replace("'","\\'")
55
59
    result = result.replace("-","\\-")
56
60
    return result
57
 
#<<< End (C) Hans Ulrich Niedermann
58
 
 
59
 
def format_command (cmd):
60
 
    cmdusage = '.TP\n.B %s\n.PP\n' % (bzrlib.help.command_usage(cmd))
61
 
    doc = "%s\n.PP\n.PP\n" % (cmd.__doc__)
62
 
    return cmdusage + doc
63
 
 
64
 
def getcommand_help():
65
 
    output=""
 
61
 
 
62
 
 
63
def command_name_list():
66
64
    command_names = bzrlib.commands.builtin_command_names()
67
65
    command_names.sort()
68
 
    for cmd_name in  command_names:
69
 
        desc = bzrlib.commands.get_cmd_object(cmd_name)
70
 
        output = output + format_command(desc)
 
66
    return command_names
 
67
 
 
68
 
 
69
def getcommand_list (params):
 
70
    bzrcmd = params["bzrcmd"]
 
71
    output = '.SH "COMMAND OVERVIEW"\n'
 
72
    for cmd_name in command_name_list():
 
73
        cmd_object = bzrlib.commands.get_cmd_object(cmd_name)
 
74
        if cmd_object.hidden:
 
75
            continue
 
76
        cmd_help = cmd_object.help()
 
77
        if cmd_help:
 
78
            firstline = cmd_help.split('\n', 1)[0]
 
79
            tmp = '.TP\n.B "%s %s"\n%s\n' % (bzrcmd, cmd_name,
 
80
                                                        firstline)
 
81
            output = output + tmp
 
82
        else:
 
83
            raise RuntimeError, "Command '%s' has no help text" % (cmd_name)
 
84
    return output
 
85
 
 
86
 
 
87
def format_command (params, cmd):
 
88
    subsection_header = '.SS "%s %s"\n' % (params["bzrcmd"], cmd.name())
 
89
    cmdusage = '.TP\n.B "Usage: %s"\n.PP\n' % (bzrlib.help.command_usage(cmd))
 
90
    doc = "%s\n" % (cmd.__doc__)
 
91
    option_str = ""
 
92
    options = cmd.options()
 
93
    # option walk code stolen from bzrlib/help.py
 
94
    if options:
 
95
        option_str = "\nOptions:\n"
 
96
        for option_name, option in sorted(options.items()):
 
97
            l = '    --' + option_name
 
98
            if option.type is not None:
 
99
                l += ' ' + option.argname.upper()
 
100
            short_name = option.short_name()
 
101
            if short_name:
 
102
                assert len(short_name) == 1
 
103
                l += ', -' + short_name
 
104
            l += (30 - len(l)) * ' ' + option.help
 
105
            # TODO: split help over multiple lines with correct indenting and 
 
106
            # wrapping
 
107
            wrapped = textwrap.fill(l, initial_indent='',
 
108
                                    subsequent_indent=30*' ')
 
109
            option_str = option_str + wrapped + '\n'       
 
110
    return subsection_header + cmdusage + doc + option_str
 
111
 
 
112
 
 
113
def getcommand_help(params):
 
114
    output='.SH "COMMAND REFERENCE"\n'
 
115
    for cmd_name in command_name_list():
 
116
        cmd_object = bzrlib.commands.get_cmd_object(cmd_name)
 
117
        if cmd_object.hidden:
 
118
            continue
 
119
        output = output + format_command(params, cmd_object)
71
120
    return output
72
121
 
73
122
 
94
143
) is a project of Canonical Ltd. 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.
95
144
.SS "Warning"
96
145
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.
 
146
 
 
147
.SH "USAGE"
 
148
Commands for a number of common use cases.
 
149
 
 
150
.SS "Create a branch"
 
151
    $ cd my-project
 
152
    $ %(bzrcmd)s init
 
153
 
 
154
.SS "Add files to be versioned"
 
155
    $ cd my-project
 
156
    $ %(bzrcmd)s add hello-world.c Makefile
 
157
 
 
158
.SS "Review local changes"
 
159
    $ cd my-project
 
160
    $ %(bzrcmd)s status
 
161
    $ %(bzrcmd)s diff
 
162
 
 
163
.SS "Commit changes to branch"
 
164
    $ cd my-project
 
165
    $ %(bzrcmd)s commit -m \"initial import of files\"
 
166
 
 
167
.SS "Branching off an existing branch"
 
168
    $ %(bzrcmd)s branch http://other.com/project-foo
 
169
    $ cd project-foo
 
170
 
 
171
    $ %(bzrcmd)s branch http://other.com/project-foo foo-by-other
 
172
    $ cd foo-by-other
 
173
    
 
174
    $ %(bzrcmd)s branch foo-by-other foo-with-my-changes
 
175
    $ cd foo-with-my-changes
 
176
 
 
177
.SS "Following upstream changes"
 
178
If you have not modified anything in your local branch:
 
179
    $ cd foo-by-other
 
180
    $ %(bzrcmd)s pull
 
181
 
 
182
If you have modified and committed things in your local branch:
 
183
    $ cd foo-with-my-changes
 
184
    $ %(bzrcmd)s merge
 
185
 
 
186
.SS "Publishing your changes"
 
187
Publishing your branch for the first time:
 
188
    $ cd foo-with-my-changes
 
189
    $ %(bzrcmd)s push sftp://user@host/public_html/foo-with-my-changes
 
190
 
 
191
Publishing your branch subsequently is easier as %(bzrcmd)s remembers the push location:
 
192
    $ cd foo-with-my-changes
 
193
    $ %(bzrcmd)s push
 
194
    
97
195
"""
98
196
 
 
197
 
99
198
man_foot = """\
100
199
.SH "EXAMPLES"
101
200
See
141
240
  check_signatures=check-available
142
241
  create_signatures=when-required
143
242
 
 
243
.TP
 
244
.I "~/.bazaar/branches.conf"
 
245
Override settings for a specific branch in this file. The sections in this file are named after the locations of the branch, and the settings in that section look just like the ones in the
 
246
.B DEFAULT
 
247
section of the
 
248
.I "~/.bazaar/bazaar.conf"
 
249
file. Example:
 
250
 
 
251
  [/home/john/src/boofar.dev-john]
 
252
  email="John Doe <john@boofar.example.com>
 
253
 
 
254
  [http://erk.example.com/boo]
 
255
  check_signatures=always
 
256
 
144
257
.SH "SEE ALSO"
145
258
.UR http://www.bazaar-ng.org/
146
259
.BR http://www.bazaar-ng.org/,
150
263
.BR http://bazaar.canonical.com/BzrDocumentation
151
264
"""
152
265
 
153
 
#<<< Begin (C) Hans Ulrich Niedermann
 
266
 
154
267
man_preamble = """\
155
268
.\\\" Man page for %(bzrcmd)s (bazaar-ng)
156
269
.\\\"
161
274
.\\\" Generation time: %(timestamp)s
162
275
.\\\"
163
276
"""
164
 
 
165
 
if __name__ == '__main__':
166
 
    main()
167
 
#<<< End (C) Hans Ulrich Niedermann