RFC: show the revision specifier on help

[Goffredo Baroncelli]

On Tuesday 05 September 2006 16:40, you (John Arbash Meinel) wrote:
> Matthieu Moy wrote:
[...]
> 
> Here is the layout that I would like to see:
> 
> 1) A new registry of help topics in either bzrlib.help, or possibly a
> new file 'bzrlib.help_topics'. This can be as simple as a dictionary
> mapping the topic name to a function returning the help text. 
[...]
> 
> 2) A new target 'bzr help topics', which would list the topics. The help
> text should indicate that this is for help on general topics that might
> apply to multiple commands, etc.
> 

I followed your suggestion in the enclosed patch. I defined four topics:
1) global_help:  the help which is displayied when bazaar is runned without 
arguments
2) commands: list of commands ( bzr help -l )
3) topics: list of topics ( bzr help --list-topics )
4) revisionspec: revision specifier list

The patch creates a new file ( help_topics.py ) which defines the following 
functions:
- add_topic(name, obj, comment): add a new topic
- write_topic(name, outfile=sys.stdout): write topic 
- is_topic(name): return if exist a topic named "name"
- get_topics_list( ): return the topic list

In the same file are defined the global_help topic, the "topics" topic, and 
the "revisionspec" topic.

Comments are welcome
Goffredo
---------------------------

$ ./bzr help --help
usage: bzr help [TOPIC]
aliases: ?, --help, -?, -h

Show help on a command or other topic.

For a list of all available commands, say 'bzr help commands'.

options:
  --list-topics     show the topics list
  -h, --help        show help message
  -l, --long        show help on all commands

$ ./bzr help --list-topics
commands
        List of commands
global_help
        Basic commands
topics
        Topics list
revisionspec
        Revisions specifier

$ ./bzr help revisionspec

Revision prefix specifier:
--------------------------
  revno:
    This takes the a number  and return the related revision.
    Optionally can be specified a branch
    examples:
      revno:1                   -> return the first revision
      revno:3:/path/to/branch   -> return the 3rd revision of
                                   the branch '/path/to/branch'
  revid:
    This takes the a revision-id and return the related revision.
    examples:
      revid:aaaa at bbbb-123456789
  last:
    This takes the a namber <n> and return the <n> - 1 revision before.
    examples:
      last:1        -> return the last revision
      last3:        -> return the last - 2 revision
  before:
    This takes the a revision and return the revision before.
    examples:
      before:1913
      before:revid:aaaa at bbbb-1234567890
  tag:
    To be implemented.
  date:
    This takes the date and return the first revision which matches.
    date can be 'yesterday', 'today', 'tomorrow' or a YYYY-MM-DD string.
    matches the first entry after a given date (either at midnight or
    at a specified time).

    So the proper way of saying 'give me all entries for today' is:
          date:yesterday..date:today

    examples:
      date:yesterday
      date:2006-08-14,17:10:14
  ancestor:
    This takes the path to a branch and returns the common ancestor.
    examples:
      ancestor:/path/to/branch
  branch:
    This takes the path to a branch and returns its tip revision id.
    examples:
      branch:/path/to/branch


-- 
gpg key@ keyserver.linux.it: Goffredo Baroncelli (ghigo) <kreijack at inwind.it>
Key fingerprint = CE3C 7E01 6782 30A3 5B87  87C0 BB86 505C 6B2A CFF9
-------------- next part --------------
A non-text attachment was scrubbed...
Name: help-topics.diff
Type: text/x-diff
Size: 7816 bytes
Desc: not available
Url : https://lists.ubuntu.com/archives/bazaar/attachments/20060906/2b2c8ecc/attachment.bin 
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 191 bytes
Desc: not available
Url : https://lists.ubuntu.com/archives/bazaar/attachments/20060906/2b2c8ecc/attachment.pgp