Re: Inaccurate documentation re "cvs tag"

[Todd Denniston]

Ming Kin Lai wrote:
> 
<SNIP>
> > > 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.

Ok, unfortunately the way open source documentation works often is "Now that
you understand the problem please describe it in the doc for the next person
and submit the doc patch"....

Ok, now that you understand the problem please describe it in the doc for
the next person and submit the doc patch. (on address@hidden) :)

Honestly, I do find that having someone who does not know, but is trying to
understand, the subject matter DRAG (kicking and screaming) it out of
someone who does, makes some of the best documentation. sorry.

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

Import is a hack, according to some, that essentially does 
'for i in `find . -type d`; do cvs add $i;cvs commit $i ;done'
'for i in `find . -type f`; do cvs add $i;cvs commit $i ;done'
in an out of sand box tree. I say "essentially" because there are some other
things going on like it puts the initial version on a 'special' branch
(which causes trouble using it with normal branches, and is why some call it
a hack).

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

Agreed.
I believe though that much of your (our) confusion came from your use of RCS
keywords, and there are known problems with them.
https://www.cvshome.org/docs/manual/cvs-1.11.20/cvs_12.html#SEC102
perhaps the updating person should link from annotate documentation to
another "problems with keywords" section in 12.


BTW from section 12.2 Using keywords:
"CVS will automatically (Or, more accurately, as part of the update run that
automatically happens after a commit.) expand the string as part of the
commit operation."
https://www.cvshome.org/docs/manual/cvs-1.11.20/cvs_12.html#SEC99

Except for users with RCS keywords, the automatic update after commit is
invisible to users. Also IIRC CVS may only do that auto update if the client
found an RCS keyword in the file, but check the code to be sure.

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

Some time soon I will attempt to read that and understand it, because I do
see version and revision as two different things. Actually they are similar
but _to me_ apply at different levels and is probably where the confusion
comes in.

quick read... looks like what I mean be version, is release in the documents
nomenclature.
I probably will not remember that though:)

<SNIP>
> > > 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.
> 
Yes, I need to read subject lines a little closer :)
You just hit my "RCS keywords dont work as I expect" button again today, its
kind of related and kind of bled over.
-- 
Todd Denniston
Crane Division, Naval Surface Warfare Center (NSWC Crane) 
Harnessing the Power of Technology for the Warfighter