[MERGE] Explain revision/range identifiers

[Aaron Bentley]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Daniel Clemente wrote:
> Documentation for „bzr help revisionspec“ that better explains revision identifiers (e.g. 'last:1') and introduces range identifiers. I wanted examples of ranges because I didn't know if something like branch:/a/..344 was a valid range (due to the possibly ambiguous ..).
> 
> This is my first patch; please change the wording as necessary.
Hi Daniel,

Thanks for trying to clarify things for our users.  Unfortunately, I
think these changes would make the help less accurate.

bb:resubmit

The patch states "A revision identifier ... refers to a specific
change", but this is not accurate.  A revision identifier refers to a
revision.  Revisions are *states* or *snapshots*, not *changes* or *deltas*.

Text strings in revision identifiers are not required to be prefixes,
though many are.  For example, the submit: revision specifier is not a
prefix.  The loom plugin provides thread:, which can be used as a
non-prefix.

The patch states "A revision range refers to the sequence of changes
which happened between the two revisions REV1 and REV2", but this is too
general.  A range is a start and an end.  What that means depends on the
command.  To the "log" command, the range denotes a sequence of log
messages.  To the "diff" command, the range denotes the change between
start and end, and not the sequence of changes between start and end.

In fact, more than two revisions can be specified using the "REV1..REV2"
notation, but so far, no command uses that facility.

Also, I find the frequent references to "revno:" strange.  "revno:" is
hardly ever used, so few people are likely to be familiar with it.

Aaro
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.6 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iD4DBQFItFZ80F+nu1YWqI0RAnpOAJjywLpOHeZQWr+n499mwM3dwSouAJ9udmSp
0lHAniwnSDtiCw7HVuv/Kw==
=yJQN
-----END PGP SIGNATURE-----