You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@subversion.apache.org by Julian Foad <ju...@btopenworld.com> on 2005/03/21 14:58:28 UTC

Terminology for "revision keywords" and "expansion keywords" [was: [PATCH] #2219 canonicalized keyword and new UUID keyword documentation]

John Peacock wrote:
> p.s. is anyone else bothered by the fact that both svn:keywords and "revision keywords" (being the aliases HEAD, BASE, etc) share the same term?  Is it too late to change the latter to be "revision aliases" instead or something???

> "Revision keywords" are almost nothing like the 
> keywords concept that svn:keywords embodies.  HEAD /et al/ are aliases 
> for certain revision numbers; they share no common behavior with the 
> keywords in files (a concept that Subversion inherited from CVS, granted).

(HEAD isn't, by my reckoning, an "alias" for a certain revision number, it's a 
special (key) word which means "go and find the number of the head revision 
right now, and use the number that you find".  I don't think the word "alias" 
has that meaning.)

The two types of keyword do share behaviour: they each cause the software to 
look up a particular piece of information and replace the keyword with the 
information.  The important and big difference is in where and how they are 
used: in specifying revisions, or in embedding version control information in 
files.  Those are the two concepts that we need to distinguish.  The problem is 
that we don't have a _specific_ term for each concept.

I think "Revision keyword" is an adequate term for the concept of identifying 
certain revisions mnemonically.

The other concept is in-file expansion of metadata.  This feature is activated 
by keywords and by a property named "svn:keywords", but neither "keywords" nor 
"svn:keywords" is the name of this feature.  We need to give it a name (how 
about "Insertion of Version Control Data in Working Files,"?) and call it by 
its name more often until we have a good concise name for it.

> I'm not that worked up about it, except for the fact that in the index 
> of the book, the section "Revisions: Numbers, Keywords, and Dates, Oh 
> My!" is given prominent billing in the "Guided Tour," but the 
> potentially much more useful information about expanding keywords in 
> files is listed somewhat obliquely in "Advanced Topics" under "Special 
> Properties."

Expansion of Metadata Inside Text Files should be a topic in its own right, 
under "Advanced Topics".  Then it should be cross-referenced from "Special 
Properties" and from the section for CVS users.

(The feature is potentially useful, but I don't agree that it is "potentially 
much more useful".  It still belongs under "advanced topics", but not hidden 
away as it is now.)

- Julian

-- 
http://www.foad.me.uk/

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org

Re: Terminology for "revision keywords" and "expansion keywords" [was: [PATCH] #2219 canonicalized keyword and new UUID keyword documentation]

Posted by Molle Bestefich <mo...@gmail.com>.
Julian Foad wrote:
> (HEAD isn't, by my reckoning, an "alias" for a certain revision number, it's a

It's not an alias for a certain revision number, it's an alias for the
HEAD revision.

Tomatoe, potato.  (Or is that how it goes?)


> special (key) word which means "go and find the number of the head revision
> right now, and use the number that you find".  I don't think the word "alias"
> has that meaning.)

As a Subversion user, I find it confusing that 'keyword' is used for
two different features.
Not so much when using the program, but definitely when reading the
documentation.

If I had a vote that counted, I'd throw it at using alias for HEAD and BASE.

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org

Re: Terminology for "revision keywords" and "expansion keywords" [was: [PATCH] #2219 canonicalized keyword and new UUID keyword documentation]

Posted by John Peacock <jp...@rowman.com>.
Julian Foad wrote:
> I think "Revision keyword" is an adequate term for the concept of 
> identifying certain revisions mnemonically.

I think that we, as developers, need to try very hard to to think like 
users as much as possible, especially when writing documentation.  I 
suspect that most users new to revision control software are 
experiencing Subversion primarily as mediated by a GUI.  None of these 
users is ever likely to utilize any of these "keywords" except as a 
byproduct of clicking on "Revert" in their GUI.

For that matter, I have never consciously used any of these terms myself 
(that I can recall); for retrieving previous versions from the 
repository I am almost always using "revert" or a specific "-r" value. 
I'm agreeing that, at times, these shortcuts are very valuable to have. 
  I'm just saying I don't think they deserve the prominence they have 
been given in the documentation.  And I don't think their usage 
justifies overloading an existing concept.

> 
> The other concept is in-file expansion of metadata.  This feature is 
> activated by keywords and by a property named "svn:keywords", but 
> neither "keywords" nor "svn:keywords" is the name of this feature.  We 
> need to give it a name (how about "Insertion of Version Control Data in 
> Working Files,"?) and call it by its name more often until we have a 
> good concise name for it.

Except that CVS was already referring to this exact same concept as 
"keyword expansion" for many years (including the "CVS Book" by our very 
own Karl Vogel).  Why do we need a new term for the same concept in 
Subversion, just to allow the "Revision keywords" term to stay?

John

p.s. I'd rather stop arguing about semantics and terminology and start 
arguing about the patches I submitted, so that we can move forward to 
eventually support user-defined keywords fully, and I am able to move on 
with my life... ;-)

-- 
John Peacock
Director of Information Research and Technology
Rowman & Littlefield Publishing Group
4501 Forbes Boulevard
Suite H
Lanham, MD  20706
301-459-3366 x.5010
fax 301-429-5748

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org