Re: 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".
>
> Actually it does literally mean the version which was checked out, not what
> you currently have (i.e., not possible local mods).

Apparently you and I have disagreement about what "literally means" means.

> > 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.
>
> Well this commit does do essentially a checkout (actually update, which is
> why things like $Log:$ and $Id:$ get updated).

This makes it clear what you mean by "literally means" - to you, a commit 
essentially does a checkout, so a commit literally means a checkout.  But to 
me, even though a commit essentially does a checkout, it is not a 
"literally" a checkout.  Please note that there is nowhere in cederqvist 
that says a commit is essentially a checkout or a commit implies a checkout, 
etc (if you can find such, please show me).  To an experienced user like 
you, that may be clear.  But as I said, that may be confusing to a new user. 
 A manual such as cederqvist is to make things clear.  People should not 
need a yaer's experience using CVS to understand what cederqvist really 
means.

> > I run "cvs
> > tag".  And 1.2 gets tagged.
>
> Because you checked out (updated to) 1.2 by committing it.

Again, I cannot find any place in cederqvist that says when the user commits 
a file, he in effect checks it out.  And that's my point: cederqvist should 
mke this clear or use the word "checked out" with care.

> > 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.
>
> It was learned long ago that less confusion was created by cvs handling the
> immediate update, otherwise cvs would have a hard time being Concurrent
> Versions System, the command you imply are serial locking commands and CVS
> is a parallel merging system.

I did not imply any command.  What I mean is less confusion would be created 
by explaining what "check out" really mean, e.g. that would be implied by a 
commit.

> >  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.
>
> No the update makes it the checked out version, this is simply a
> misconception on your part.

I am pointing out a potential misconception because of the way "checked out" 
is used in cederqvist.

> > 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.
>
> If you checked it out there was a check in, which created 1.1.

Not necessarily.  I initially import the file and then check it out.  There 
is no check-in.  Well, I guess you would say something like "an import 
essentially does a check-in" or "an import literally means a check-in".  My 
take is that if that's what the CVS designers mean, fine, document it in 
cederqvist to avoid misunderstanding.  A user should be not be left 
wondering whether xxx is essentially doing yyy.
> From this discussion it is quite apparent that you separate the _concept_ of 
checkin and checkout, respectively, from the actual command of "cvs checkin" 
(or "cvs ci") and "cvs checkout" (or "cvs ci"), respectively.  It appears, 
to you, the concept of checkout encompasses both the "cvs checkout" and "cvs 
commit", for example.  I am not arguing about the merit of this way of 
thinking.  Look at the title of my post - "inacurrate documentation".  I am 
talking about the documentation.  If you can find any place in cederqvist 
that explains that the concept of checkin encompasses "cvs checkout" and 
"cvs commit", please show me.  If you do not explain that to a new user, can 
you expect him to somehow figure it out himself?  Yes, he will eventually.  
But why can't the documentation give him an easier time?  cederqvist is not 
just a reference for experienced users, it also serves as a guide for 
first-time users.

> > 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?
>
> Yes, see above.
>
> >
> > 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".
>
> In most cases people tag an entire baseline (which is also the better
> practice), which has a "version", but also has many files which have
> "revisions". It seems clear as written from here.

Section 4.2 of the 1.11.20 cederqvist says "To avoid confusion, the word 
version is almost never used in this document."  Apparently the authors of 
the manual think that the use of the word "version" is not clear and may 
create confusion.  And I agree with the authors of the manual.

> > 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))
>
> see above information about your misunderstanding because cvs commit does 
> an
> update to get you synchronized with what is in the baseline after commit.

You can call it my "misunderstanding" but I don't think I misunderstand 
anything.  If there is, then I think cederqvist can be improved to avoid 
misunderstanding.  That's my point.

> > and 1.2.  I think the phase "checked out" should be used with care.
>
> It is, you simply have a little learning to do.

I think everyone, including you, is learning.  I surely hope you can learn 
something from this discussion.

_________________________________________________________________
On the road to retirement? Check out MSN Life Events for advice on how to 
get there! http://lifeevents.msn.com/category.aspx?cid=Retirement