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