1551.3.11
by Aaron Bentley
Merge from Robert |
1 |
# Copyright 2005 Canonical Ltd.
|
635
by Martin Pool
- manpage generator by Hans Ulrich Niedermann |
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.
|
|
1887.1.1
by Adeodato Simó
Do not separate paragraphs in the copyright statement with blank lines, |
7 |
#
|
635
by Martin Pool
- manpage generator by Hans Ulrich Niedermann |
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.
|
|
1887.1.1
by Adeodato Simó
Do not separate paragraphs in the copyright statement with blank lines, |
12 |
#
|
635
by Martin Pool
- manpage generator by Hans Ulrich Niedermann |
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., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
|
|
16 |
||
1551.3.11
by Aaron Bentley
Merge from Robert |
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 |
|
635
by Martin Pool
- manpage generator by Hans Ulrich Niedermann |
27 |
import time |
1551.3.11
by Aaron Bentley
Merge from Robert |
28 |
|
29 |
import bzrlib |
|
30 |
import bzrlib.help |
|
31 |
import bzrlib.commands |
|
32 |
||
33 |
||
34 |
def get_filename(options): |
|
35 |
"""Provides name of manpage"""
|
|
36 |
return "%s.1" % (options.bzr_name) |
|
37 |
||
38 |
||
39 |
def infogen(options, outfile): |
|
40 |
"""Assembles a man page"""
|
|
41 |
t = time.time() |
|
42 |
tt = time.gmtime(t) |
|
43 |
params = \ |
|
44 |
{ "bzrcmd": options.bzr_name, |
|
45 |
"datestamp": time.strftime("%Y-%m-%d",tt), |
|
46 |
"timestamp": time.strftime("%Y-%m-%d %H:%M:%S +0000",tt), |
|
47 |
"version": bzrlib.__version__, |
|
48 |
}
|
|
49 |
outfile.write(man_preamble % params) |
|
50 |
outfile.write(man_escape(man_head % params)) |
|
51 |
outfile.write(man_escape(getcommand_list(params))) |
|
52 |
outfile.write(man_escape(getcommand_help(params))) |
|
53 |
outfile.write(man_escape(man_foot % params)) |
|
1185.74.4
by James Blackwell
Give long help with command on man page |
54 |
|
1185.75.1
by Hans Ulrich Niedermann
Start implementing general doc generation plan: |
55 |
|
635
by Martin Pool
- manpage generator by Hans Ulrich Niedermann |
56 |
def man_escape(string): |
1551.3.11
by Aaron Bentley
Merge from Robert |
57 |
"""Escapes strings for man page compatibility"""
|
635
by Martin Pool
- manpage generator by Hans Ulrich Niedermann |
58 |
result = string.replace("\\","\\\\") |
59 |
result = result.replace("`","\\`") |
|
60 |
result = result.replace("'","\\'") |
|
61 |
result = result.replace("-","\\-") |
|
62 |
return result |
|
1185.75.1
by Hans Ulrich Niedermann
Start implementing general doc generation plan: |
63 |
|
64 |
||
1551.3.11
by Aaron Bentley
Merge from Robert |
65 |
def command_name_list(): |
66 |
"""Builds a list of command names from bzrlib"""
|
|
67 |
command_names = bzrlib.commands.builtin_command_names() |
|
68 |
command_names.sort() |
|
69 |
return command_names |
|
70 |
||
71 |
||
72 |
def getcommand_list (params): |
|
73 |
"""Builds summary help for command names in manpage format"""
|
|
74 |
bzrcmd = params["bzrcmd"] |
|
75 |
output = '.SH "COMMAND OVERVIEW"\n' |
|
76 |
for cmd_name in command_name_list(): |
|
77 |
cmd_object = bzrlib.commands.get_cmd_object(cmd_name) |
|
78 |
if cmd_object.hidden: |
|
79 |
continue
|
|
80 |
cmd_help = cmd_object.help() |
|
81 |
if cmd_help: |
|
82 |
firstline = cmd_help.split('\n', 1)[0] |
|
83 |
usage = bzrlib.help.command_usage(cmd_object) |
|
84 |
tmp = '.TP\n.B "%s"\n%s\n' % (usage, firstline) |
|
85 |
output = output + tmp |
|
1185.75.1
by Hans Ulrich Niedermann
Start implementing general doc generation plan: |
86 |
else: |
1551.3.11
by Aaron Bentley
Merge from Robert |
87 |
raise RuntimeError, "Command '%s' has no help text" % (cmd_name) |
88 |
return output |
|
89 |
||
90 |
||
91 |
def getcommand_help(params): |
|
92 |
"""Shows individual options for a bzr command"""
|
|
93 |
output='.SH "COMMAND REFERENCE"\n' |
|
94 |
for cmd_name in command_name_list(): |
|
95 |
cmd_object = bzrlib.commands.get_cmd_object(cmd_name) |
|
96 |
if cmd_object.hidden: |
|
97 |
continue
|
|
98 |
output = output + format_command(params, cmd_object) |
|
99 |
return output |
|
100 |
||
101 |
||
102 |
def format_command (params, cmd): |
|
103 |
"""Provides long help for each public command"""
|
|
104 |
subsection_header = '.SS "%s"\n' % (bzrlib.help.command_usage(cmd)) |
|
105 |
doc = "%s\n" % (cmd.__doc__) |
|
1861.2.13
by Alexander Belchenko
generate_docs (man/rstx): get help with .help() method, otherwise help for merge incomplete |
106 |
doc = cmd.help() |
1861.3.2
by Alexander Belchenko
bzr.1 man page: show aliases for commands; fixed description of bazaar.conf |
107 |
|
1551.3.11
by Aaron Bentley
Merge from Robert |
108 |
option_str = "" |
109 |
options = cmd.options() |
|
110 |
if options: |
|
111 |
option_str = "\nOptions:\n" |
|
112 |
for option_name, option in sorted(options.items()): |
|
1857.1.14
by Aaron Bentley
Fix man page generation |
113 |
for name, short_name, argname, help in option.iter_switches(): |
114 |
l = ' --' + name |
|
115 |
if argname is not None: |
|
116 |
l += ' ' + argname |
|
117 |
if short_name: |
|
118 |
assert len(short_name) == 1 |
|
119 |
l += ', -' + short_name |
|
120 |
l += (30 - len(l)) * ' ' + 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' |
|
1861.3.2
by Alexander Belchenko
bzr.1 man page: show aliases for commands; fixed description of bazaar.conf |
126 |
|
127 |
aliases_str = "" |
|
128 |
if cmd.aliases: |
|
129 |
if len(cmd.aliases) > 1: |
|
130 |
aliases_str += '\nAliases: ' |
|
131 |
else: |
|
132 |
aliases_str += '\nAlias: ' |
|
133 |
aliases_str += ', '.join(cmd.aliases) |
|
134 |
aliases_str += '\n' |
|
135 |
||
136 |
return subsection_header + option_str + aliases_str + "\n" + doc + "\n" |
|
1185.75.1
by Hans Ulrich Niedermann
Start implementing general doc generation plan: |
137 |
|
138 |
||
635
by Martin Pool
- manpage generator by Hans Ulrich Niedermann |
139 |
man_preamble = """\ |
1861.2.8
by Alexander Belchenko
More branding: bazaar-ng -> Bazaar; bazaar-ng.org -> bazaar-vcs.org |
140 |
Man page for Bazaar (%(bzrcmd)s) |
635
by Martin Pool
- manpage generator by Hans Ulrich Niedermann |
141 |
.\\\" |
142 |
.\\\" Large parts of this file are autogenerated from the output of |
|
143 |
.\\\" \"%(bzrcmd)s help commands\" |
|
144 |
.\\\" \"%(bzrcmd)s help <cmd>\" |
|
145 |
.\\\" |
|
146 |
.\\\" Generation time: %(timestamp)s |
|
147 |
.\\\" |
|
148 |
"""
|
|
149 |
||
1551.3.11
by Aaron Bentley
Merge from Robert |
150 |
|
635
by Martin Pool
- manpage generator by Hans Ulrich Niedermann |
151 |
man_head = """\ |
1861.2.8
by Alexander Belchenko
More branding: bazaar-ng -> Bazaar; bazaar-ng.org -> bazaar-vcs.org |
152 |
.TH bzr 1 "%(datestamp)s" "%(version)s" "Bazaar" |
635
by Martin Pool
- manpage generator by Hans Ulrich Niedermann |
153 |
.SH "NAME"
|
1861.2.8
by Alexander Belchenko
More branding: bazaar-ng -> Bazaar; bazaar-ng.org -> bazaar-vcs.org |
154 |
Bazaar (%(bzrcmd)s) - next-generation distributed version control |
635
by Martin Pool
- manpage generator by Hans Ulrich Niedermann |
155 |
.SH "SYNOPSIS"
|
156 |
.B "%(bzrcmd)s" |
|
157 |
.I "command"
|
|
158 |
[
|
|
159 |
.I "command_options"
|
|
160 |
]
|
|
161 |
.br
|
|
162 |
.B "%(bzrcmd)s" |
|
163 |
.B "help"
|
|
164 |
.br
|
|
165 |
.B "%(bzrcmd)s" |
|
166 |
.B "help"
|
|
167 |
.I "command"
|
|
168 |
.SH "DESCRIPTION"
|
|
1861.2.13
by Alexander Belchenko
generate_docs (man/rstx): get help with .help() method, otherwise help for merge incomplete |
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.
|
|
635
by Martin Pool
- manpage generator by Hans Ulrich Niedermann |
173 |
"""
|
174 |
||
175 |
man_foot = """\ |
|
176 |
.SH "ENVIRONMENT"
|
|
177 |
.TP
|
|
178 |
.I "BZRPATH"
|
|
179 |
Path where
|
|
180 |
.B "%(bzrcmd)s" |
|
181 |
is to look for external command.
|
|
182 |
.TP
|
|
1861.4.1
by Matthieu Moy
BZREMAIL renamed to BZR_EMAIL. |
183 |
.I "BZR_EMAIL"
|
1551.3.11
by Aaron Bentley
Merge from Robert |
184 |
E-Mail address of the user. Overrides default user config.
|
635
by Martin Pool
- manpage generator by Hans Ulrich Niedermann |
185 |
.TP
|
186 |
.I "EMAIL"
|
|
2221.3.1
by Alexander Belchenko
Bugfix #76603: fix typo in bzr manpage text |
187 |
E-Mail address of the user. Overrides default user config.
|
1861.3.4
by Alexander Belchenko
more environment variables for man page |
188 |
.TP
|
189 |
.I "BZR_EDITOR"
|
|
190 |
Editor for editing commit messages
|
|
191 |
.TP
|
|
192 |
.I "EDITOR"
|
|
193 |
Editor for editing commit messages
|
|
194 |
.TP
|
|
195 |
.I "BZR_PLUGIN_PATH"
|
|
196 |
Paths where bzr should look for plugins
|
|
197 |
.TP
|
|
198 |
.I "BZR_HOME"
|
|
199 |
Home directory for bzr
|
|
635
by Martin Pool
- manpage generator by Hans Ulrich Niedermann |
200 |
.SH "FILES"
|
201 |
.TP
|
|
1861.3.2
by Alexander Belchenko
bzr.1 man page: show aliases for commands; fixed description of bazaar.conf |
202 |
.I "~/.bazaar/bazaar.conf"
|
1861.2.14
by Alexander Belchenko
generate_docs (man/rstx): fixed description of configuration file |
203 |
Contains the users default configuration. The section
|
1551.3.11
by Aaron Bentley
Merge from Robert |
204 |
.B [DEFAULT]
|
1861.2.14
by Alexander Belchenko
generate_docs (man/rstx): fixed description of configuration file |
205 |
is used to define general configuration that will be applied everywhere.
|
206 |
The section
|
|
207 |
.B [ALIASES]
|
|
208 |
can be used to create command aliases for
|
|
209 |
commonly used options.
|
|
210 |
||
211 |
A typical config file might look something like:
|
|
212 |
||
213 |
.br
|
|
214 |
[DEFAULT]
|
|
215 |
.br
|
|
216 |
email=John Doe <jdoe@isp.com>
|
|
217 |
.br
|
|
218 |
[ALIASES]
|
|
219 |
.br
|
|
220 |
commit = commit --strict
|
|
221 |
.br
|
|
222 |
log10 = log --short -r -10..-1
|
|
635
by Martin Pool
- manpage generator by Hans Ulrich Niedermann |
223 |
.SH "SEE ALSO"
|
1662.1.18
by Martin Pool
Fix up urls and warnings in auto-generated documentation |
224 |
.UR http://www.bazaar-vcs.org/
|
225 |
.BR http://www.bazaar-vcs.org/
|
|
635
by Martin Pool
- manpage generator by Hans Ulrich Niedermann |
226 |
"""
|
227 |