~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to bzrlib/help_topics.py

  • Committer: Aaron Bentley
  • Date: 2007-08-13 14:00:59 UTC
  • mto: (2681.5.3 bzr-mail)
  • mto: This revision was merged to the branch mainline in revision 2736.
  • Revision ID: abentley@panoramicfeedback.com-20070813140059-04k01bfueilqvg10
Update text, fix whitespace issues

Show diffs side-by-side

added added

removed removed

Lines of Context:
1
 
# Copyright (C) 2006-2011 Canonical Ltd
 
1
# Copyright (C) 2006 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
"""A collection of extra help information for using bzr.
18
18
 
33
33
rendering on the screen naturally.
34
34
"""
35
35
 
36
 
from __future__ import absolute_import
37
 
 
38
 
import bzrlib
39
 
from bzrlib import (
40
 
    config,
41
 
    osutils,
42
 
    registry,
43
 
    i18n,
44
 
    )
 
36
from bzrlib import registry
45
37
 
46
38
 
47
39
# Section identifiers (map topics to the right place in the manual)
67
59
        :param section: Section in reference manual - see SECT_* identifiers.
68
60
        """
69
61
        # The detail is stored as the 'object' and the metadata as the info
70
 
        info = (summary, section)
 
62
        info=(summary,section)
71
63
        super(HelpTopicRegistry, self).register(topic, detail, info=info)
72
64
 
73
65
    def register_lazy(self, topic, module_name, member_name, summary,
81
73
        :param section: Section in reference manual - see SECT_* identifiers.
82
74
        """
83
75
        # The detail is stored as the 'object' and the metadata as the info
84
 
        info = (summary, section)
 
76
        info=(summary,section)
85
77
        super(HelpTopicRegistry, self).register_lazy(topic, module_name,
86
78
                                                     member_name, info=info)
87
79
 
128
120
 
129
121
    topics = topic_registry.keys()
130
122
    lmax = max(len(topic) for topic in topics)
131
 
 
 
123
        
132
124
    out = []
133
125
    for topic in topics:
134
126
        summary = topic_registry.get_summary(topic)
136
128
    return ''.join(out)
137
129
 
138
130
 
139
 
def _load_from_file(topic_name):
140
 
    """Load help from a file.
141
 
 
142
 
    Topics are expected to be txt files in bzrlib.help_topics.
143
 
    """
144
 
    resource_name = osutils.pathjoin("en", "%s.txt" % (topic_name,))
145
 
    return osutils.resource_string('bzrlib.help_topics', resource_name)
146
 
 
147
 
 
148
131
def _help_on_revisionspec(name):
149
132
    """Generate the help for revision specs."""
150
133
    import re
151
134
    import bzrlib.revisionspec
152
135
 
153
136
    out = []
154
 
    out.append(
155
 
"""Revision Identifiers
156
 
 
157
 
A revision identifier refers to a specific state of a branch's history.  It
158
 
can be expressed in several ways.  It can begin with a keyword to
159
 
unambiguously specify a given lookup type; some examples are 'last:1',
160
 
'before:yesterday' and 'submit:'.
161
 
 
162
 
Alternately, it can be given without a keyword, in which case it will be
163
 
checked as a revision number, a tag, a revision id, a date specification, or a
164
 
branch specification, in that order.  For example, 'date:today' could be
165
 
written as simply 'today', though if you have a tag called 'today' that will
166
 
be found first.
167
 
 
168
 
If 'REV1' and 'REV2' are revision identifiers, then 'REV1..REV2' denotes a
169
 
revision range. Examples: '3647..3649', 'date:yesterday..-1' and
170
 
'branch:/path/to/branch1/..branch:/branch2' (note that there are no quotes or
171
 
spaces around the '..').
172
 
 
173
 
Ranges are interpreted differently by different commands. To the "log" command,
174
 
a range is a sequence of log messages, but to the "diff" command, the range
175
 
denotes a change between revisions (and not a sequence of changes).  In
176
 
addition, "log" considers a closed range whereas "diff" and "merge" consider it
177
 
to be open-ended, that is, they include one end but not the other.  For example:
178
 
"bzr log -r 3647..3649" shows the messages of revisions 3647, 3648 and 3649,
179
 
while "bzr diff -r 3647..3649" includes the changes done in revisions 3648 and
180
 
3649, but not 3647.
181
 
 
182
 
The keywords used as revision selection methods are the following:
183
 
""")
 
137
    out.append("Revision Identifiers\n")
 
138
    out.append("A revision, or a range bound, can be one of the following.\n")
184
139
    details = []
185
 
    details.append("\nIn addition, plugins can provide other keywords.")
186
 
    details.append("\nA detailed description of each keyword is given below.\n")
 
140
    details.append("\nFurther details are given below.\n")
187
141
 
188
142
    # The help text is indented 4 spaces - this re cleans that up below
189
143
    indent_re = re.compile(r'^    ', re.MULTILINE)
190
 
    for prefix, i in bzrlib.revisionspec.revspec_registry.iteritems():
 
144
    for i in bzrlib.revisionspec.SPEC_TYPES:
191
145
        doc = i.help_txt
192
146
        if doc == bzrlib.revisionspec.RevisionSpec.help_txt:
193
147
            summary = "N/A"
199
153
            #doc = indent_re.sub('', doc)
200
154
            while (doc[-2:] == '\n\n' or doc[-1:] == ' '):
201
155
                doc = doc[:-1]
202
 
 
 
156
        
203
157
        # Note: The leading : here are HACKs to get reStructuredText
204
158
        # 'field' formatting - we know that the prefix ends in a ':'.
205
159
        out.append(":%s\n\t%s" % (i.prefix, summary))
215
169
    import textwrap
216
170
 
217
171
    def add_string(proto, help, maxl, prefix_width=20):
218
 
       help_lines = textwrap.wrap(help, maxl - prefix_width,
219
 
            break_long_words=False)
 
172
       help_lines = textwrap.wrap(help, maxl - prefix_width)
220
173
       line_with_indent = '\n' + ' ' * prefix_width
221
174
       help_text = line_with_indent.join(help_lines)
222
175
       return "%-20s%s\n" % (proto, help_text)
253
206
        out += "\nSupported modifiers::\n\n  " + \
254
207
            '  '.join(decl)
255
208
 
256
 
    out += """\
257
 
\nBazaar supports all of the standard parts within the URL::
258
 
 
259
 
  <protocol>://[user[:password]@]host[:port]/[path]
260
 
 
261
 
allowing URLs such as::
262
 
 
263
 
  http://bzruser:BadPass@bzr.example.com:8080/bzr/trunk
264
 
 
265
 
For bzr+ssh:// and sftp:// URLs, Bazaar also supports paths that begin
266
 
with '~' as meaning that the rest of the path should be interpreted
267
 
relative to the remote user's home directory.  For example if the user
268
 
``remote`` has a  home directory of ``/home/remote`` on the server
269
 
shell.example.com, then::
270
 
 
271
 
  bzr+ssh://remote@shell.example.com/~/myproject/trunk
272
 
 
273
 
would refer to ``/home/remote/myproject/trunk``.
274
 
 
275
 
Many commands that accept URLs also accept location aliases too.
276
 
See :doc:`location-alias-help` and :doc:`url-special-chars-help`.
277
 
"""
278
 
 
279
209
    return out
280
210
 
281
211
 
282
212
_basic_help = \
283
 
"""Bazaar %s -- a free distributed version-control tool
284
 
http://bazaar.canonical.com/
 
213
"""Bazaar -- a free distributed version-control tool
 
214
http://bazaar-vcs.org/
285
215
 
286
216
Basic commands:
287
217
  bzr init           makes this directory a versioned branch
296
226
 
297
227
  bzr merge          pull in changes from another branch
298
228
  bzr commit         save some or all changes
299
 
  bzr send           send changes via email
300
229
 
301
230
  bzr log            show history of changes
302
231
  bzr check          validate storage
304
233
  bzr help init      more help on e.g. init command
305
234
  bzr help commands  list all commands
306
235
  bzr help topics    list all help topics
307
 
""" % bzrlib.__version__
 
236
"""
308
237
 
309
238
 
310
239
_global_options = \
311
240
"""Global Options
312
241
 
313
242
These options may be used with any command, and may appear in front of any
314
 
command.  (e.g. ``bzr --profile help``).
315
 
 
316
 
--version      Print the version number. Must be supplied before the command.
317
 
--no-aliases   Do not process command aliases when running this command.
 
243
command.  (e.g. "bzr --quiet help").
 
244
 
 
245
--quiet        Suppress informational output; only print errors and warnings
 
246
--version      Print the version number
 
247
 
 
248
--no-aliases   Do not process command aliases when running this command
318
249
--builtin      Use the built-in version of a command, not the plugin version.
319
 
               This does not suppress other plugin effects.
320
 
--no-plugins   Do not process any plugins.
321
 
--no-l10n      Do not translate messages.
322
 
--concurrency  Number of processes that can be run concurrently (selftest).
 
250
               This does not suppress other plugin effects
 
251
--no-plugins   Do not process any plugins
323
252
 
324
 
--profile      Profile execution using the hotshot profiler.
325
 
--lsprof       Profile execution using the lsprof profiler.
 
253
-Derror        Instead of normal error handling, always print a traceback on
 
254
               error.
 
255
--profile      Profile execution using the hotshot profiler
 
256
--lsprof       Profile execution using the lsprof profiler
326
257
--lsprof-file  Profile execution using the lsprof profiler, and write the
327
258
               results to a specified file.  If the filename ends with ".txt",
328
259
               text format will be used.  If the filename either starts with
329
260
               "callgrind.out" or end with ".callgrind", the output will be
330
261
               formatted for use with KCacheGrind. Otherwise, the output
331
262
               will be a pickle.
332
 
--coverage     Generate line coverage report in the specified directory.
333
 
 
334
 
-Oname=value   Override the ``name`` config option setting it to ``value`` for
335
 
               the duration of the command.  This can be used multiple times if
336
 
               several options need to be overridden.
337
 
 
338
 
See http://doc.bazaar.canonical.com/developers/profiling.html for more
339
 
information on profiling.
340
 
 
341
 
A number of debug flags are also available to assist troubleshooting and
342
 
development.  See :doc:`debug-flags-help`.
343
 
"""
344
 
 
345
 
_standard_options = \
346
 
"""Standard Options
347
 
 
348
 
Standard options are legal for all commands.
349
 
 
350
 
--help, -h     Show help message.
351
 
--verbose, -v  Display more information.
352
 
--quiet, -q    Only display errors and warnings.
353
 
 
354
 
Unlike global options, standard options can be used in aliases.
355
 
"""
356
 
 
 
263
 
 
264
See doc/developers/profiling.txt for more information on profiling.
 
265
 
 
266
Note: --version must be supplied before any command.
 
267
"""
357
268
 
358
269
_checkouts = \
359
270
"""Checkouts
397
308
Lightweight checkouts work best when you have fast reliable access to the
398
309
master branch. This means that if the master branch is on the same disk or LAN
399
310
a lightweight checkout will be faster than a heavyweight one for any commands
400
 
that modify the revision history (as only one copy of the branch needs to
401
 
be updated). Heavyweight checkouts will generally be faster for any command
402
 
that uses the history but does not change it, but if the master branch is on
403
 
the same disk then there won't be a noticeable difference.
 
311
that modify the revision history (as only one copy branch needs to be updated).
 
312
Heavyweight checkouts will generally be faster for any command that uses the
 
313
history but does not change it, but if the master branch is on the same disk
 
314
then there wont be a noticeable difference.
404
315
 
405
316
Another possible use for a checkout is to use it with a treeless repository
406
317
containing your branches, where you maintain only one working tree by
407
 
switching the master branch that the checkout points to when you want to
 
318
switching the master branch that the checkout points to when you want to 
408
319
work on a different branch.
409
320
 
410
321
Obviously to commit on a checkout you need to be able to write to the master
413
324
end. Checkouts also work on the local file system, so that all that matters is
414
325
file permissions.
415
326
 
416
 
You can change the master of a checkout by using the "switch" command (see
417
 
"help switch").  This will change the location that the commits are sent to.
418
 
The "bind" command can also be used to turn a normal branch into a heavy
419
 
checkout. If you would like to convert your heavy checkout into a normal
420
 
branch so that every commit is local, you can use the "unbind" command. To see
421
 
whether or not a branch is bound or not you can use the "info" command. If the
422
 
branch is bound it will tell you the location of the bound branch.
 
327
You can change the master of a checkout by using the "bind" command (see "help
 
328
bind"). This will change the location that the commits are sent to. The bind
 
329
command can also be used to turn a branch into a heavy checkout. If you
 
330
would like to convert your heavy checkout into a normal branch so that every
 
331
commit is local, you can use the "unbind" command.
423
332
 
424
333
Related commands::
425
334
 
427
336
              checkout
428
337
  update      Pull any changes in the master branch in to your checkout
429
338
  commit      Make a commit that is sent to the master branch. If you have
430
 
              a heavy checkout then the --local option will commit to the
 
339
              a heavy checkout then the --local option will commit to the 
431
340
              checkout without sending the commit to the master
432
 
  switch      Change the master branch that the commits in the checkout will
 
341
  bind        Change the master branch that the commits in the checkout will
433
342
              be sent to
434
 
  bind        Turn a standalone branch into a heavy checkout so that any
435
 
              commits will be sent to the master branch
436
343
  unbind      Turn a heavy checkout into a standalone branch so that any
437
344
              commits are only made locally
438
 
  info        Displays whether a branch is bound or unbound. If the branch is
439
 
              bound, then it will also display the location of the bound branch
440
345
"""
441
346
 
442
347
_repositories = \
447
352
 
448
353
Repositories are a form of database. Bzr will usually maintain this for
449
354
good performance automatically, but in some situations (e.g. when doing
450
 
very many commits in a short time period) you may want to ask bzr to
 
355
very many commits in a short time period) you may want to ask bzr to 
451
356
optimise the database indices. This can be done by the 'bzr pack' command.
452
357
 
453
358
By default just running 'bzr init' will create a repository within the new
519
424
 
520
425
  checkout     Create a working tree when a branch does not have one.
521
426
  remove-tree  Removes the working tree from a branch when it is safe to do so.
522
 
  update       When a working tree is out of sync with its associated branch
 
427
  update       When a working tree is out of sync with it's associated branch
523
428
               this will update the tree to match the branch.
524
429
"""
525
430
 
526
 
 
527
 
_branches = \
528
 
"""Branches
529
 
 
530
 
A branch consists of the state of a project, including all of its
531
 
history. All branches have a repository associated (which is where the
532
 
branch history is stored), but multiple branches may share the same
533
 
repository (a shared repository). Branches can be copied and merged.
534
 
 
535
 
In addition, one branch may be bound to another one.  Binding to another
536
 
branch indicates that commits which happen in this branch must also 
537
 
happen in the other branch.  Bazaar ensures consistency by not allowing 
538
 
commits when the two branches are out of date.  In order for a commit 
539
 
to succeed, it may be necessary to update the current branch using 
540
 
``bzr update``.
541
 
 
542
 
Related commands::
543
 
 
544
 
  init    Change a directory into a versioned branch.
545
 
  branch  Create a new branch that is a copy of an existing branch.
546
 
  merge   Perform a three-way merge.
547
 
  bind    Bind a branch to another one.
548
 
"""
549
 
 
550
 
 
551
 
_standalone_trees = \
552
 
"""Standalone Trees
553
 
 
554
 
A standalone tree is a working tree with an associated repository. It
555
 
is an independently usable branch, with no dependencies on any other.
556
 
Creating a standalone tree (via bzr init) is the quickest way to put
557
 
an existing project under version control.
558
 
 
559
 
Related Commands::
560
 
 
561
 
  init    Make a directory into a versioned branch.
562
 
"""
563
 
 
564
 
 
565
431
_status_flags = \
566
432
"""Status Flags
567
433
 
578
444
  - File unversioned
579
445
  R File renamed
580
446
  ? File unknown
581
 
  X File nonexistent (and unknown to bzr)
582
447
  C File has conflicts
583
448
  P Entry for a pending merge (not a file)
584
449
 
595
460
"""
596
461
 
597
462
 
598
 
known_env_variables = [
599
 
    ("BZRPATH", "Path where bzr is to look for shell plugin external commands."),
600
 
    ("BZR_EMAIL", "E-Mail address of the user. Overrides EMAIL."),
601
 
    ("EMAIL", "E-Mail address of the user."),
602
 
    ("BZR_EDITOR", "Editor for editing commit messages. Overrides EDITOR."),
603
 
    ("EDITOR", "Editor for editing commit messages."),
604
 
    ("BZR_PLUGIN_PATH", "Paths where bzr should look for plugins."),
605
 
    ("BZR_DISABLE_PLUGINS", "Plugins that bzr should not load."),
606
 
    ("BZR_PLUGINS_AT", "Plugins to load from a directory not in BZR_PLUGIN_PATH."),
607
 
    ("BZR_HOME", "Directory holding .bazaar config dir. Overrides HOME."),
608
 
    ("BZR_HOME (Win32)", "Directory holding bazaar config dir. Overrides APPDATA and HOME."),
609
 
    ("BZR_REMOTE_PATH", "Full name of remote 'bzr' command (for bzr+ssh:// URLs)."),
610
 
    ("BZR_SSH", "Path to SSH client, or one of paramiko, openssh, sshcorp, plink or lsh."),
611
 
    ("BZR_LOG", "Location of .bzr.log (use '/dev/null' to suppress log)."),
612
 
    ("BZR_LOG (Win32)", "Location of .bzr.log (use 'NUL' to suppress log)."),
613
 
    ("BZR_COLUMNS", "Override implicit terminal width."),
614
 
    ("BZR_CONCURRENCY", "Number of processes that can be run concurrently (selftest)"),
615
 
    ("BZR_PROGRESS_BAR", "Override the progress display. Values are 'none' or 'text'."),
616
 
    ("BZR_PDB", "Control whether to launch a debugger on error."),
617
 
    ("BZR_SIGQUIT_PDB", "Control whether SIGQUIT behaves normally or invokes a breakin debugger."),
618
 
    ("BZR_TEXTUI_INPUT", "Force console input mode for prompts to line-based (instead of char-based)."),
619
 
    ]
620
 
 
621
 
def _env_variables(topic):
622
 
    import textwrap
623
 
    ret = ["Environment Variables\n\n"]
624
 
    max_key_len = max([len(k[0]) for k in known_env_variables])
625
 
    desc_len = (80 - max_key_len - 2)
626
 
    ret.append("=" * max_key_len + " " + "=" * desc_len + "\n")
627
 
    for k, desc in known_env_variables:
628
 
        ret.append(k + (max_key_len + 1 - len(k)) * " ")
629
 
        ret.append("\n".join(textwrap.wrap(
630
 
            desc, width=desc_len, subsequent_indent=" " * (max_key_len + 1))))
631
 
        ret.append("\n")
632
 
    ret += "=" * max_key_len + " " + "=" * desc_len + "\n"
633
 
    return "".join(ret)
 
463
_env_variables = \
 
464
"""Environment Variables
 
465
 
 
466
================ =================================================================
 
467
BZRPATH          Path where bzr is to look for shell plugin external commands.
 
468
BZR_EMAIL        E-Mail address of the user. Overrides EMAIL.
 
469
EMAIL            E-Mail address of the user.
 
470
BZR_EDITOR       Editor for editing commit messages. Overrides EDITOR.
 
471
EDITOR           Editor for editing commit messages.
 
472
BZR_PLUGIN_PATH  Paths where bzr should look for plugins.
 
473
BZR_HOME         Directory holding .bazaar config dir. Overrides HOME.
 
474
BZR_HOME (Win32) Directory holding bazaar config dir. Overrides APPDATA and HOME.
 
475
================ =================================================================
 
476
"""
 
477
 
634
478
 
635
479
_files = \
636
480
r"""Files
637
481
 
638
 
:On Unix:   ~/.bazaar/bazaar.conf
 
482
:On Linux:   ~/.bazaar/bazaar.conf
639
483
:On Windows: C:\\Documents and Settings\\username\\Application Data\\bazaar\\2.0\\bazaar.conf
640
484
 
641
485
Contains the user's default configuration. The section ``[DEFAULT]`` is
653
497
  log10 = log --short -r -10..-1
654
498
"""
655
499
 
656
 
_criss_cross = \
657
 
"""Criss-Cross
658
 
 
659
 
A criss-cross in the branch history can cause the default merge technique
660
 
to emit more conflicts than would normally be expected.
661
 
 
662
 
In complex merge cases, ``bzr merge --lca`` or ``bzr merge --weave`` may give
663
 
better results.  You may wish to ``bzr revert`` the working tree and merge
664
 
again.  Alternatively, use ``bzr remerge`` on particular conflicted files.
665
 
 
666
 
Criss-crosses occur in a branch's history if two branches merge the same thing
667
 
and then merge one another, or if two branches merge one another at the same
668
 
time.  They can be avoided by having each branch only merge from or into a
669
 
designated central branch (a "star topology").
670
 
 
671
 
Criss-crosses cause problems because of the way merge works.  Bazaar's default
672
 
merge is a three-way merger; in order to merge OTHER into THIS, it must
673
 
find a basis for comparison, BASE.  Using BASE, it can determine whether
674
 
differences between THIS and OTHER are due to one side adding lines, or
675
 
from another side removing lines.
676
 
 
677
 
Criss-crosses mean there is no good choice for a base.  Selecting the recent
678
 
merge points could cause one side's changes to be silently discarded.
679
 
Selecting older merge points (which Bazaar does) mean that extra conflicts
680
 
are emitted.
681
 
 
682
 
The ``weave`` merge type is not affected by this problem because it uses
683
 
line-origin detection instead of a basis revision to determine the cause of
684
 
differences.
685
 
"""
686
 
 
687
 
_branches_out_of_sync = """Branches Out of Sync
688
 
 
689
 
When reconfiguring a checkout, tree or branch into a lightweight checkout,
690
 
a local branch must be destroyed.  (For checkouts, this is the local branch
691
 
that serves primarily as a cache.)  If the branch-to-be-destroyed does not
692
 
have the same last revision as the new reference branch for the lightweight
693
 
checkout, data could be lost, so Bazaar refuses.
694
 
 
695
 
How you deal with this depends on *why* the branches are out of sync.
696
 
 
697
 
If you have a checkout and have done local commits, you can get back in sync
698
 
by running "bzr update" (and possibly "bzr commit").
699
 
 
700
 
If you have a branch and the remote branch is out-of-date, you can push
701
 
the local changes using "bzr push".  If the local branch is out of date, you
702
 
can do "bzr pull".  If both branches have had changes, you can merge, commit
703
 
and then push your changes.  If you decide that some of the changes aren't
704
 
useful, you can "push --overwrite" or "pull --overwrite" instead.
705
 
"""
706
 
 
707
 
 
708
 
_storage_formats = \
709
 
"""Storage Formats
710
 
 
711
 
To ensure that older clients do not access data incorrectly,
712
 
Bazaar's policy is to introduce a new storage format whenever
713
 
new features requiring new metadata are added. New storage
714
 
formats may also be introduced to improve performance and
715
 
scalability.
716
 
 
717
 
The newest format, 2a, is highly recommended. If your
718
 
project is not using 2a, then you should suggest to the
719
 
project owner to upgrade.
720
 
 
721
 
 
722
 
.. note::
723
 
 
724
 
   Some of the older formats have two variants:
725
 
   a plain one and a rich-root one. The latter include an additional
726
 
   field about the root of the tree. There is no performance cost
727
 
   for using a rich-root format but you cannot easily merge changes
728
 
   from a rich-root format into a plain format. As a consequence,
729
 
   moving a project to a rich-root format takes some co-ordination
730
 
   in that all contributors need to upgrade their repositories
731
 
   around the same time. 2a and all future formats will be
732
 
   implicitly rich-root.
733
 
 
734
 
See :doc:`current-formats-help` for the complete list of
735
 
currently supported formats. See :doc:`other-formats-help` for
736
 
descriptions of any available experimental and deprecated formats.
737
 
"""
738
 
 
739
 
 
740
 
# Register help topics
 
500
 
741
501
topic_registry.register("revisionspec", _help_on_revisionspec,
742
502
                        "Explain how to use --revision")
743
503
topic_registry.register('basic', _basic_help, "Basic commands", SECT_HIDDEN)
744
504
topic_registry.register('topics', _help_on_topics, "Topics list", SECT_HIDDEN)
745
 
def get_current_formats_topic(topic):
746
 
    from bzrlib import controldir
747
 
    return "Current Storage Formats\n\n" + \
748
 
        controldir.format_registry.help_topic(topic)
749
 
def get_other_formats_topic(topic):
750
 
    from bzrlib import controldir
751
 
    return "Other Storage Formats\n\n" + \
752
 
        controldir.format_registry.help_topic(topic)
753
 
topic_registry.register('current-formats', get_current_formats_topic,
754
 
    'Current storage formats')
755
 
topic_registry.register('other-formats', get_other_formats_topic,
756
 
    'Experimental and deprecated storage formats')
757
 
topic_registry.register('standard-options', _standard_options,
 
505
def get_format_topic(topic):
 
506
    from bzrlib import bzrdir
 
507
    return "Storage Formats\n\n" + bzrdir.format_registry.help_topic(topic)
 
508
topic_registry.register('formats', get_format_topic, 'Directory formats')
 
509
topic_registry.register('global-options', _global_options,
758
510
                        'Options that can be used with any command')
759
 
topic_registry.register('global-options', _global_options,
760
 
                    'Options that control how Bazaar runs')
 
511
topic_registry.register('checkouts', _checkouts,
 
512
                        'Information on what a checkout is', SECT_CONCEPT)
761
513
topic_registry.register('urlspec', _help_on_transport,
762
514
                        "Supported transport protocols")
763
515
topic_registry.register('status-flags', _status_flags,
764
516
                        "Help on status flags")
765
517
def get_bugs_topic(topic):
766
518
    from bzrlib import bugtracker
767
 
    return ("Bug Tracker Settings\n\n" +
768
 
        bugtracker.tracker_registry.help_topic(topic))
769
 
topic_registry.register('bugs', get_bugs_topic, 'Bug tracker settings')
 
519
    return "Bug Trackers\n\n" + bugtracker.tracker_registry.help_topic(topic)
 
520
topic_registry.register('bugs', get_bugs_topic, 'Bug tracker support')
 
521
topic_registry.register('repositories', _repositories,
 
522
                        'Basic information on shared repositories.',
 
523
                        SECT_CONCEPT)
 
524
topic_registry.register('working-trees', _working_trees,
 
525
                        'Information on working trees', SECT_CONCEPT)
770
526
topic_registry.register('env-variables', _env_variables,
771
527
                        'Environment variable names and values')
772
528
topic_registry.register('files', _files,
773
529
                        'Information on configuration and log files')
774
 
topic_registry.register_lazy('hooks', 'bzrlib.hooks', 'hooks_help_text',
775
 
                        'Points at which custom processing can be added')
776
 
topic_registry.register_lazy('location-alias', 'bzrlib.directory_service',
777
 
                        'AliasDirectory.help_text',
778
 
                        'Aliases for remembered locations')
779
 
 
780
 
# Load some of the help topics from files. Note that topics which reproduce API
781
 
# details will tend to skew (quickly usually!) so please seek other solutions
782
 
# for such things.
783
 
topic_registry.register('authentication', _load_from_file,
784
 
                        'Information on configuring authentication')
785
 
topic_registry.register('configuration', _load_from_file,
786
 
                        'Details on the configuration settings available')
787
 
topic_registry.register('conflict-types', _load_from_file,
788
 
                        'Types of conflicts and what to do about them')
789
 
topic_registry.register('debug-flags', _load_from_file,
790
 
                        'Options to show or record debug information')
791
 
topic_registry.register('log-formats', _load_from_file,
792
 
                        'Details on the logging formats available')
793
 
topic_registry.register('url-special-chars', _load_from_file,
794
 
                        'Special character handling in URLs')
795
 
 
796
 
 
797
 
# Register concept topics.
798
 
# Note that we might choose to remove these from the online help in the
799
 
# future or implement them via loading content from files. In the meantime,
800
 
# please keep them concise.
801
 
topic_registry.register('branches', _branches,
802
 
                        'Information on what a branch is', SECT_CONCEPT)
803
 
topic_registry.register('checkouts', _checkouts,
804
 
                        'Information on what a checkout is', SECT_CONCEPT)
805
 
topic_registry.register('content-filters', _load_from_file,
806
 
                        'Conversion of content into/from working trees',
807
 
                        SECT_CONCEPT)
808
 
topic_registry.register('diverged-branches', _load_from_file,
809
 
                        'How to fix diverged branches',
810
 
                        SECT_CONCEPT)
811
 
topic_registry.register('eol', _load_from_file,
812
 
                        'Information on end-of-line handling',
813
 
                        SECT_CONCEPT)
814
 
topic_registry.register('formats', _storage_formats,
815
 
                        'Information on choosing a storage format',
816
 
                        SECT_CONCEPT)
817
 
topic_registry.register('patterns', _load_from_file,
818
 
                        'Information on the pattern syntax',
819
 
                        SECT_CONCEPT)
820
 
topic_registry.register('repositories', _repositories,
821
 
                        'Basic information on shared repositories.',
822
 
                        SECT_CONCEPT)
823
 
topic_registry.register('rules', _load_from_file,
824
 
                        'Information on defining rule-based preferences',
825
 
                        SECT_CONCEPT)
826
 
topic_registry.register('standalone-trees', _standalone_trees,
827
 
                        'Information on what a standalone tree is',
828
 
                        SECT_CONCEPT)
829
 
topic_registry.register('working-trees', _working_trees,
830
 
                        'Information on working trees', SECT_CONCEPT)
831
 
topic_registry.register('criss-cross', _criss_cross,
832
 
                        'Information on criss-cross merging', SECT_CONCEPT)
833
 
topic_registry.register('sync-for-reconfigure', _branches_out_of_sync,
834
 
                        'Steps to resolve "out-of-sync" when reconfiguring',
835
 
                        SECT_CONCEPT)
836
530
 
837
531
 
838
532
class HelpTopicIndex(object):
856
550
            return []
857
551
 
858
552
 
859
 
def _format_see_also(see_also):
860
 
    result = ''
861
 
    if see_also:
862
 
        result += '\n:See also: '
863
 
        result += ', '.join(sorted(set(see_also)))
864
 
        result += '\n'
865
 
    return result
866
 
 
867
 
 
868
553
class RegisteredTopic(object):
869
554
    """A help topic which has been registered in the HelpTopicRegistry.
870
555
 
888
573
            returned instead of plain text.
889
574
        """
890
575
        result = topic_registry.get_detail(self.topic)
891
 
        result += _format_see_also(additional_see_also)
 
576
        # there is code duplicated here and in bzrlib/plugin.py's 
 
577
        # matching Topic code. This should probably be factored in
 
578
        # to a helper function and a common base class.
 
579
        if additional_see_also is not None:
 
580
            see_also = sorted(set(additional_see_also))
 
581
        else:
 
582
            see_also = None
 
583
        if see_also:
 
584
            result += '\n:See also: '
 
585
            result += ', '.join(see_also)
 
586
            result += '\n'
892
587
        if plain:
893
588
            result = help_as_plain_text(result)
894
 
        i18n.install()
895
 
        result = i18n.gettext_per_paragraph(result)
896
589
        return result
897
590
 
898
591
    def get_help_topic(self):
902
595
 
903
596
def help_as_plain_text(text):
904
597
    """Minimal converter of reStructuredText to plain text."""
905
 
    import re
906
 
    # Remove the standalone code block marker
907
 
    text = re.sub(r"(?m)^\s*::\n\s*$", "", text)
908
598
    lines = text.splitlines()
909
599
    result = []
910
600
    for line in lines:
912
602
            line = line[1:]
913
603
        elif line.endswith('::'):
914
604
            line = line[:-1]
915
 
        # Map :doc:`xxx-help` to ``bzr help xxx``
916
 
        line = re.sub(":doc:`(.+?)-help`", r'``bzr help \1``', line)
917
605
        result.append(line)
918
606
    return "\n".join(result) + "\n"
919
 
 
920
 
 
921
 
class ConfigOptionHelpIndex(object):
922
 
    """A help index that returns help topics for config options."""
923
 
 
924
 
    def __init__(self):
925
 
        self.prefix = 'configuration/'
926
 
 
927
 
    def get_topics(self, topic):
928
 
        """Search for topic in the registered config options.
929
 
 
930
 
        :param topic: A topic to search for.
931
 
        :return: A list which is either empty or contains a single
932
 
            config.Option entry.
933
 
        """
934
 
        if topic is None:
935
 
            return []
936
 
        elif topic.startswith(self.prefix):
937
 
            topic = topic[len(self.prefix):]
938
 
        if topic in config.option_registry:
939
 
            return [config.option_registry.get(topic)]
940
 
        else:
941
 
            return []
942
 
 
943