[MERGE] Explain revision/range identifiers

[Daniel Clemente]

Aaron Bentley <aaron at aaronbentley.com> writes:

Hi,
  apparently revision identifiers are more complex than I thought. More reasons for needing good documentation.

  Thanks to your explanations, I rewrote the patch. Some comments:


>
> 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*.
>
  Changed.

> 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.
>
  Some people might call „submit:“ also a prefix, since it is at the start of the string. I think it's better not to make a distinction „prefix“/„non-prefix“. Instead, we can call them „keywords“.
  Changed.


> 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.

  True... Now I cannot find a good definition of „revision range“ which is neither too general nor wrong. I left it out; if someone finds a short and concise definition, then add it.
  I find it interesting that a range has a different meaning for each command. But I don't know if this should be in the documentation.

>
> In fact, more than two revisions can be specified using the "REV1..REV2"
> notation, but so far, no command uses that facility.
>
  Ok; I mentioned that.
  Should that part about „so far, no command uses that facility“ also be included?

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



  I attach a new patch. It may also need a grammar review.

  Thanks,

Daniel

-------------- next part --------------
A non-text attachment was scrubbed...
Name: revisionspec_v2.patch
Type: text/x-diff
Size: 4829 bytes
Desc: Patch attempt 2
Url : https://lists.ubuntu.com/archives/bazaar/attachments/20080828/6effe098/attachment.bin