Inaccurate documentation re "cvs tag"

[Ming Kin Lai]

Sec 4.5 of 1.11.20 cederqvist says: "running the cvs tag command without 
arguments causes CVS to select the revisions which are checked out in the 
current working directory.  ... One potentially aspect of the fact that cvs 
tag operates on the repository is that you are tagging the checked-in 
revisions, which may differ from locally modified files ..."
I think it is somewhat confusing, especially to new users.  At first it 
talks about a checked-out revision, then it talks about a checked-in 
revision. Well, I understand they mean the same, at least in some cases; but 
it is not quite accurate and probably confusing.
1. The problem with "checked out" is that it does not literally mean 
"checked out".  Suppose I check out a file with revision 1.1, modify it and 
commit it, so now I have revision 1.2 in my working directory.  I run "cvs 
tag".  And 1.2 gets tagged.  Literally 1.1 is the revision I checked out.  I 
did not check out 1.2, unless commit implies check out - but I think it's 
better separate them; after all ci and co are two different commands.  Also, 
stating that a checked-out version is tagged may give the wrong impression 
that the user (unnecessarily) needs to do a "cvs co" before tagging.
2. The problem with "checked in" is that there may not be any check-in (cvs 
ci).  Suppose I check out a file for the first time and without modifying 
it, run "cvs tag".  The one and only one revision gets tagged; but there is 
never any check-in.  Stating that a checked-in revision is tagged may give 
the wrong impression that the user (unnecessarily) needs to do a "cvs ci" 
before tagging.

Anyone agrees or disagrees?

Incidentally, the entry for tag in Appendix B (page 132) says "Add a 
symbolic tag to checked out version".  I think "checked out" need to be 
re-worded, and "version" probably should be "revision".

Finally there are a number of places in cederqvist that use the phase 
"checked out".  I am not sure all mean literally "checked out".  For 
example, Sec 1.3.4 says "diff compare[s] the version (revision?) of driver.c 
that you checked out with your working copy."  Again, suppose I check out a 
file with revision 1.1, modify it and commit it, so now I have revision 1.2 
in my working directory.  I run "cvs diff".  There is no difference.  The 
comparison is NOT between 1.1 (the last revision I checked out (using cvs 
co)) and 1.2.  I think the phase "checked out" should be used with care.

Ming Kin Lai

_________________________________________________________________
Express yourself instantly with MSN Messenger! Download today - it's FREE! 
http://messenger.msn.click-url.com/go/onm00200471ave/direct/01/