19
19
Help topics are meant to be help for items that aren't commands, but will
20
20
help bzr become fully learnable without referring to a tutorial.
22
Limited formatting of help text is permitted to make the text useful
23
both within the reference manual (reStructuredText) and on the screen.
24
The help text should be reStructuredText with formatting kept to a
25
minimum and, in particular, no headings. The onscreen renderer applies
26
the following simple rules before rendering the text:
28
1. A '::' appearing on the end of a line is replaced with ':'.
29
2. Lines starting with a ':' have it stripped.
31
These rules mean that literal blocks and field lists respectively can
32
be used in the help text, producing sensible input to a manual while
33
rendering on the screen naturally.
23
36
from bzrlib import registry
39
# Section identifiers (map topics to the right place in the manual)
40
SECT_COMMAND = "command"
41
SECT_CONCEPT = "concept"
42
SECT_HIDDEN = "hidden"
44
SECT_PLUGIN = "plugin"
26
47
class HelpTopicRegistry(registry.Registry):
27
48
"""A Registry customized for handling help topics."""
29
def register(self, topic, detail, summary):
50
def register(self, topic, detail, summary, section=SECT_LIST):
30
51
"""Register a new help topic.
32
53
:param topic: Name of documentation entry
33
54
:param detail: Function or string object providing detailed
34
55
documentation for topic. Function interface is detail(topic).
35
56
This should return a text string of the detailed information.
57
See the module documentation for details on help text formatting.
36
58
:param summary: String providing single-line documentation for topic.
59
:param section: Section in reference manual - see SECT_* identifiers.
38
# The detail is stored as the 'object' and the
39
super(HelpTopicRegistry, self).register(topic, detail, info=summary)
61
# The detail is stored as the 'object' and the metadata as the info
62
info=(summary,section)
63
super(HelpTopicRegistry, self).register(topic, detail, info=info)
41
def register_lazy(self, topic, module_name, member_name, summary):
65
def register_lazy(self, topic, module_name, member_name, summary,
42
67
"""Register a new help topic, and import the details on demand.
44
69
:param topic: Name of documentation entry
45
70
:param module_name: The module to find the detailed help.
46
71
:param member_name: The member of the module to use for detailed help.
47
72
:param summary: String providing single-line documentation for topic.
73
:param section: Section in reference manual - see SECT_* identifiers.
75
# The detail is stored as the 'object' and the metadata as the info
76
info=(summary,section)
49
77
super(HelpTopicRegistry, self).register_lazy(topic, module_name,
50
member_name, info=summary)
78
member_name, info=info)
52
80
def get_detail(self, topic):
53
81
"""Get the detailed help on a given topic."""
83
131
def _help_on_revisionspec(name):
84
"""Write the summary help for all documented topics to outfile."""
132
"""Generate the help for revision specs."""
85
134
import bzrlib.revisionspec
88
out.append("\nRevision prefix specifier:"
89
"\n--------------------------\n")
137
out.append("Revision Identifiers\n")
138
out.append("A revision, or a range bound, can be one of the following.\n")
140
details.append("\nFurther details are given below.\n")
142
# The help text is indented 4 spaces - this re cleans that up below
143
indent_re = re.compile(r'^ ', re.MULTILINE)
91
144
for i in bzrlib.revisionspec.SPEC_TYPES:
93
146
if doc == bzrlib.revisionspec.RevisionSpec.help_txt:
95
while (doc[-2:] == '\n\n' or doc[-1:] == ' '):
98
out.append(" %s %s\n\n" % (i.prefix, doc))
150
# Extract out the top line summary from the body and
151
# clean-up the unwanted whitespace
152
summary,doc = doc.split("\n", 1)
153
#doc = indent_re.sub('', doc)
154
while (doc[-2:] == '\n\n' or doc[-1:] == ' '):
157
# Note: The leading : here are HACKs to get reStructuredText
158
# 'field' formatting - we know that the prefix ends in a ':'.
159
out.append(":%s\n\t%s" % (i.prefix, summary))
160
details.append(":%s\n%s" % (i.prefix, doc))
162
return '\n'.join(out + details)
103
165
def _help_on_transport(name):
178
240
"""Global Options
180
242
These options may be used with any command, and may appear in front of any
181
command. (e.g. "bzr --quiet help").
183
--quiet Suppress informational output; only print errors and warnings
184
--version Print the version number
186
--no-aliases Do not process command aliases when running this command
243
command. (e.g. "bzr --profile help").
245
--version Print the version number. Must be supplied before the command.
246
--no-aliases Do not process command aliases when running this command.
187
247
--builtin Use the built-in version of a command, not the plugin version.
188
This does not suppress other plugin effects
189
--no-plugins Do not process any plugins
248
This does not suppress other plugin effects.
249
--no-plugins Do not process any plugins.
191
-Derror Instead of normal error handling, always print a traceback on
193
--profile Profile execution using the hotshot profiler
194
--lsprof Profile execution using the lsprof profiler
251
--profile Profile execution using the hotshot profiler.
252
--lsprof Profile execution using the lsprof profiler.
195
253
--lsprof-file Profile execution using the lsprof profiler, and write the
196
254
results to a specified file. If the filename ends with ".txt",
197
text format will be used. If the filename ends with
198
".callgrind", output will be formatted for use with KCacheGrind.
199
Otherwise, the output will be a pickle.
255
text format will be used. If the filename either starts with
256
"callgrind.out" or end with ".callgrind", the output will be
257
formatted for use with KCacheGrind. Otherwise, the output
201
260
See doc/developers/profiling.txt for more information on profiling.
203
Note: --version must be supplied before any command.
261
A number of debug flags are also available to assist troubleshooting and
264
-Derror Instead of normal error handling, always print a traceback on
266
-Devil Capture call sites that do expensive or badly-scaling
268
-Dhooks Trace hook execution.
269
-Dhpss Trace smart protocol requests and responses.
270
-Dindex Trace major index operations.
271
-Dlock Trace when lockdir locks are taken or released.
274
_standard_options = \
277
Standard options are legal for all commands.
279
--help, -h Show help message.
280
--verbose, -v Display more information.
281
--quiet, -q Only display errors and warnings.
283
Unlike global options, standard options can be used in aliases.
365
446
this will update the tree to match the branch.
453
A branch consists of the state of a project, including all of its
454
history. All branches have a repository associated (which is where the
455
branch history is stored), but multiple branches may share the same
456
repository (a shared repository). Branches can be copied and merged.
460
init Make a directory into a versioned branch.
461
branch Create a new copy of a branch.
462
merge Perform a three-way merge.
466
_standalone_trees = \
469
A standalone tree is a working tree with an associated repository. It
470
is an independently usable branch, with no dependencies on any other.
471
Creating a standalone tree (via bzr init) is the quickest way to put
472
an existing project under version control.
476
init Make a directory into a versioned branch.
368
480
_status_flags = \
371
483
Status flags are used to summarise changes to the working tree in a concise
372
manner. They are in the form:
484
manner. They are in the form::
374
488
where the columns' meanings are as follows.
376
Column 1: versioning / renames
490
Column 1 - versioning/renames::
378
493
- File unversioned
381
496
C File has conflicts
382
497
P Entry for a pending merge (not a file)
499
Column 2 - contents::
387
503
K File kind changed
391
508
* The execute bit was changed
513
"""Environment Variables
515
================ =================================================================
516
BZRPATH Path where bzr is to look for shell plugin external commands.
517
BZR_EMAIL E-Mail address of the user. Overrides EMAIL.
518
EMAIL E-Mail address of the user.
519
BZR_EDITOR Editor for editing commit messages. Overrides EDITOR.
520
EDITOR Editor for editing commit messages.
521
BZR_PLUGIN_PATH Paths where bzr should look for plugins.
522
BZR_HOME Directory holding .bazaar config dir. Overrides HOME.
523
BZR_HOME (Win32) Directory holding bazaar config dir. Overrides APPDATA and HOME.
524
================ =================================================================
531
:On Linux: ~/.bazaar/bazaar.conf
532
:On Windows: C:\\Documents and Settings\\username\\Application Data\\bazaar\\2.0\\bazaar.conf
534
Contains the user's default configuration. The section ``[DEFAULT]`` is
535
used to define general configuration that will be applied everywhere.
536
The section ``[ALIASES]`` can be used to create command aliases for
537
commonly used options.
539
A typical config file might look something like::
542
email=John Doe <jdoe@isp.com>
545
commit = commit --strict
546
log10 = log --short -r -10..-1
550
# Register help topics
395
551
topic_registry.register("revisionspec", _help_on_revisionspec,
396
552
"Explain how to use --revision")
397
topic_registry.register('basic', _basic_help, "Basic commands")
398
topic_registry.register('topics', _help_on_topics, "Topics list")
553
topic_registry.register('basic', _basic_help, "Basic commands", SECT_HIDDEN)
554
topic_registry.register('topics', _help_on_topics, "Topics list", SECT_HIDDEN)
399
555
def get_format_topic(topic):
400
556
from bzrlib import bzrdir
401
return bzrdir.format_registry.help_topic(topic)
557
return "Storage Formats\n\n" + bzrdir.format_registry.help_topic(topic)
402
558
topic_registry.register('formats', get_format_topic, 'Directory formats')
559
topic_registry.register('standard-options', _standard_options,
560
'Options that can be used with any command')
403
561
topic_registry.register('global-options', _global_options,
404
'Options that can be used with any command')
405
topic_registry.register('checkouts', _checkouts,
406
'Information on what a checkout is')
562
'Options that control how Bazaar runs')
407
563
topic_registry.register('urlspec', _help_on_transport,
408
564
"Supported transport protocols")
409
565
topic_registry.register('status-flags', _status_flags,
410
566
"Help on status flags")
411
567
def get_bugs_topic(topic):
412
568
from bzrlib import bugtracker
413
return bugtracker.tracker_registry.help_topic(topic)
569
return "Bug Trackers\n\n" + bugtracker.tracker_registry.help_topic(topic)
414
570
topic_registry.register('bugs', get_bugs_topic, 'Bug tracker support')
571
topic_registry.register('env-variables', _env_variables,
572
'Environment variable names and values')
573
topic_registry.register('files', _files,
574
'Information on configuration and log files')
577
# Register concept topics.
578
# Note that we might choose to remove these from the online help in the
579
# future or implement them via loading content from files. In the meantime,
580
# please keep them concise.
581
topic_registry.register('branches', _branches,
582
'Information on what a branch is', SECT_CONCEPT)
583
topic_registry.register('checkouts', _checkouts,
584
'Information on what a checkout is', SECT_CONCEPT)
415
585
topic_registry.register('repositories', _repositories,
416
'Basic information on shared repositories.')
586
'Basic information on shared repositories.',
588
topic_registry.register('standalone-trees', _standalone_trees,
589
'Information on what a standalone tree is',
417
591
topic_registry.register('working-trees', _working_trees,
418
'Information on working trees')
592
'Information on working trees', SECT_CONCEPT)
421
595
class HelpTopicIndex(object):
added
removed
bzrlib/help_topics.py
