You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@subversion.apache.org by Gareth McCaughan <Ga...@pobox.com> on 2002/08/03 02:44:32 UTC
Suggestion: "svn explain"
Some of Subversion's error messages are a little cryptic,
especially for a new user. (Example: "Transaction is out
of date.") Hopefully, most of the obscure error messages
are rare enough that most users won't ever get used to
them :-).
I propose that typing, e.g., "svn explain 21087" should yield
a friendly description, one or two paragraphs long, of
what that error means, what's likely to have provoked it,
and what to do about it. Perhaps this should be generalized
beyond error messages: "svn explain transaction" could
give a brief explanation of what a transaction is.
I have a patch that provides the "skeleton" of this,
by which I mean that the only thing (ha!) that needs
adding is the actual descriptions. :-) I'm not including
it with this message, in case no one else thinks
"svn explain" is a good idea.
--
g
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: Suggestion: "svn explain"
Posted by Karl Fogel <kf...@newton.ch.collab.net>.
Garrett Rooney <ro...@electricjellyfish.net> writes:
> i believe there has been an issue filed about just this problem,
> although i don't know what the plan is to deal with it. perhaps
> allocating extra error values at various points in the sequence for
> later expansion, like one can do with space in data structures when
> trying to maintain binary compatability...
Yes, this is issue
http://subversion.tigris.org/issues/show_bug.cgi?id=702
-Karl
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: Suggestion: "svn explain"
Posted by Karl Fogel <kf...@newton.ch.collab.net>.
Greg Hudson <gh...@MIT.EDU> writes:
> On Sun, 2002-08-04 at 11:54, cmpilato@collab.net wrote:
> > That is precisely the plan. We need to group our error codes into
> > those that can be sent across the wire, and those that can't, leaving
> > empty error slots between the groups.
>
> Pardon my confusion here--shouldn't DAV or DeltaV specify error codes
> for the wire protocol, and not us?
Oh, these aren't protocol errors. The problem here is how to get a
filesystem error from the server to the client, so the client can
correctly report it to the users.
DAV can wrap up those errors any way it wants, so long as the client
is able to unwrap and report the right thing reliably.
An example: when the server bounces back with a "Transaction out of
date" error, the client needs to tell the user that's what happened.
-K
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: Suggestion: "svn explain"
Posted by Greg Hudson <gh...@MIT.EDU>.
On Sun, 2002-08-04 at 11:54, cmpilato@collab.net wrote:
> That is precisely the plan. We need to group our error codes into
> those that can be sent across the wire, and those that can't, leaving
> empty error slots between the groups.
Pardon my confusion here--shouldn't DAV or DeltaV specify error codes
for the wire protocol, and not us?
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: Suggestion: "svn explain"
Posted by cm...@collab.net.
Garrett Rooney <ro...@electricjellyfish.net> writes:
> On Sun, Aug 04, 2002 at 11:11:17AM +1000, Martin Pool wrote:
> > On 3 Aug 2002, Gareth McCaughan <Ga...@pobox.com> wrote:
> > > On Saturday 03 August 2002 3:22 pm, Martin Pool wrote:
> >
> > > 1. I see nothing that guarantees that the error IDs will never
> > > change. They're allocated sequentially-by-magic in
> > > svn_error_codes.h, and if someone ever adds a new one
> > > then all the later errors will get their IDs bumped up. Since
> > > they are (currently) arranged in groups, it seems quite
> > > likely that errors will get added in the middle of the list.
> >
> > I think if Subversion exposes error codes in messages, people will
> > count on them to be the same. Changing them would be confusing.
>
> i believe there has been an issue filed about just this problem,
> although i don't know what the plan is to deal with it. perhaps
> allocating extra error values at various points in the sequence for
> later expansion, like one can do with space in data structures when
> trying to maintain binary compatability...
That is precisely the plan. We need to group our error codes into
those that can be sent across the wire, and those that can't, leaving
empty error slots between the groups. And then, from 1.0 on out, we
implement an error code policy that is consistent with our API policy
and that dictates how we choose version numbers for our product such
that compatibility between versions can be easily predicted and
explained. Greg Stein has, somewhere (perhaps in the APR tree) a plan
for just such a version-number-choosing scheme.
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: Suggestion: "svn explain"
Posted by Garrett Rooney <ro...@electricjellyfish.net>.
On Sun, Aug 04, 2002 at 11:11:17AM +1000, Martin Pool wrote:
> On 3 Aug 2002, Gareth McCaughan <Ga...@pobox.com> wrote:
> > On Saturday 03 August 2002 3:22 pm, Martin Pool wrote:
>
> > 1. I see nothing that guarantees that the error IDs will never
> > change. They're allocated sequentially-by-magic in
> > svn_error_codes.h, and if someone ever adds a new one
> > then all the later errors will get their IDs bumped up. Since
> > they are (currently) arranged in groups, it seems quite
> > likely that errors will get added in the middle of the list.
>
> I think if Subversion exposes error codes in messages, people will
> count on them to be the same. Changing them would be confusing.
i believe there has been an issue filed about just this problem,
although i don't know what the plan is to deal with it. perhaps
allocating extra error values at various points in the sequence for
later expansion, like one can do with space in data structures when
trying to maintain binary compatability...
-garrett
--
garrett rooney Remember, any design flaw you're
rooneg@electricjellyfish.net sufficiently snide about becomes
http://electricjellyfish.net/ a feature. -- Dan Sugalski
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: Suggestion: "svn explain"
Posted by Martin Pool <mb...@sourcefrog.net>.
On 3 Aug 2002, Gareth McCaughan <Ga...@pobox.com> wrote:
> On Saturday 03 August 2002 3:22 pm, Martin Pool wrote:
> 1. I see nothing that guarantees that the error IDs will never
> change. They're allocated sequentially-by-magic in
> svn_error_codes.h, and if someone ever adds a new one
> then all the later errors will get their IDs bumped up. Since
> they are (currently) arranged in groups, it seems quite
> likely that errors will get added in the middle of the list.
I think if Subversion exposes error codes in messages, people will
count on them to be the same. Changing them would be confusing.
> 2. It's possible that the most appropriate message will
> need to change from one version to the next. For instance:
> I recently found what I think is a bug that leads to an
> incorrect "Transaction out of date" error. If I'm right to
> think it's a bug, and if it turns out to be easy to work
> around and hard to fix, then for a few versions it might
> be beneficial to add something to the corresponding
> error description along the lines of "There's a known
> problem with the version of Subversion you're using
> that sometimes causes this error. Try doing X instead,
> or see if the problem has been fixed in the latest version.".
It seems to me that this is an argument for not having the detailed
explanation not stored in the binary, but rather somewhere it can be
more easily updated. Some people will in 2004 be using e.g. the
RedHat build of Subversion from 2003, which will probably contain bugs
that were not known at the time of release.
> Looking back at a thread from mid-July (don't know how
> I missed it before), I see Ben suggesting a "svn help"
> feature along similar-ish lines, Karl -0 on it, Brian Fitzpatrick
> -1, and a certain Martin Pool actively in support. :-)
What I was proposing was adding help messages for things like
svn:keywords, or indeed a "subversion keywords" command. I would
argue that it's "inside the line" of reasonable on-board documentation
because it can be very concise, users will probably not remember the
magic names and will appreciate help, and it will not change much
between versions.
Thinking about error messages more: for most other programs, just
typing the error message into Google will get you a good explanation,
from a manual, faq, or mailing list archive. The important thing is
to write the documentation, not to put it into the binary.
--
Martin
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: Suggestion: "svn explain"
Posted by Gareth McCaughan <Ga...@pobox.com>.
On Saturday 03 August 2002 6:46 pm, Greg Hudson wrote:
> Well, I'm against "svn explain", partly because I think we should
> stop reporting error codes at all. Our error messages are much too
> verbose. An example error:
...
> Aside from being visually ugly with the leading newline, an
> unschooled reader is likely to get caught up in the cryptic
> "svn_error: #21044 : < ...>" and take more time to get to the
> important text.
...
> Of course, this doesn't solve your problem of cryptic error
> messages. I can only say two things about that: (1) bugs are
> generally going to result in cryptic behavior; there's very little
> we can do about that aside from fix most of the bugs; and (2) the
> correct response to a cryptic error message is not to plaster over
> it with documentation, but to make it less cryptic.
No disagreement with any of that. If it's possible to make all
error messages comprehensible without making them
excessively verbose, that's definitely the right thing to do.
I'm a little sceptical. :-)
> I also think we want to curb the expansion of our command set.
> Bitkeeper is legitimately criticized as having way too many
> functions; I don't think we want to go that route. But this is my
> smallest objection, since it would be easily addressed by making a
> sub-feature of "svn help" instead of making a new "svn explain."
<shame>I hadn't even noticed there was already a "svn help" when
I chose the name "svn explain". If I had, I'd have proposed the syntax
"svn help error 12345".</shame>
Anyway, so far we have a -0 from Martin Pool and a big fat -1
from you, so unless the tide of opinion turns I shall assume no one
other than me wants this sort of feature. Fair enough.
--
g
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: Suggestion: "svn explain"
Posted by br...@xbc.nu.
Karl Fogel wrote:
>Greg Hudson <gh...@MIT.EDU> writes:
>
>
>> svn_error: #21079 : <Item already exists in filesystem>
>> file `file:///var/ghudson/svn-test/grows' already exists.
>>
>>Aside from being visually ugly with the leading newline, an unschooled
>>reader is likely to get caught up in the cryptic "svn_error: #21044 : <
>>...>" and take more time to get to the important text. I would display
>>this as, perhaps:
>>
>> svn: Item already exists in filesystem
>> svn: file `file:///var/ghudson/svn-test/grows' already exists.
>>
>>
>
>+1 all *over* that.
>
>The error codes don't even help developers, since we don't know them
>numerically, we know them by error constant. We should print out the
>constant's source name if we can, or just not print a code at all.
>The raw codes alarm users while helping no one.
>
FYI, I'm taking this on. Have to do something while trying to grok what
Greg Stein wrote in gen_base.py...
(Ah, the good old times are back, qualifying Gregs has become necessary
again. :-)
>Also agree that the solution to cryptic errors is to write better
>error strings (both for the core error string and/or for the
>call-specific string where the error was created).
>
>
That, of course, means first deciding on a policy, documenting it, then
going through the code and implementing it. I'll wisely avoid this issue
for now. :-)
--
Brane Čibej <br...@xbc.nu> http://www.xbc.nu/brane/
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: Suggestion: "svn explain"
Posted by mark benedetto king <bk...@inquira.com>.
I'm replying to the wrong message, since I deleted the right one.
Apologies in advance.
On Mon, Aug 05, 2002 at 02:30:59PM -0400, Greg Hudson wrote:
> On Mon, 2002-08-05 at 14:07, Dave Cridland wrote:
> > As mentioned before, Google is often the best source of online help for
> > what errors *really* mean.
>
I'm not always connected to the internet. I like to code in airports
and on planes. In fact, that's usually my only opportunity to code because
when I'm online I'm buried in AIM messages and e-mails.
The "svn help" suggestion is very similar to Oracle's "oerr" facility.
Oracle gives you error "1469", and you are welcome to type
$ oerr ora 1469
01469, 00000, "PRIOR can only be followed by a column name"
// *Cause: Attempting to specify "PRIOR <something>" where <something> is not
// a column name.
// *Action: Only a column name can follow PRIOR. Replace with a column name.
> > Since the rest of the string can be internationlised, I for one would
> > really like a "This is error code 'SVNERROR_TOOMANYERRORCODES'" string
> > somewhere, giving me a suitable searchable token.
>
These could be locale-specific strings.
Sure, google might take you to the Discussion Group For People Who
Get Error Message Number 1469, but *something* local for problem resolution
is better than nothing at all.
These do not need to bloat the binary, itself. They can be zlib-compressed
and stored in a lib dir, or something.
Also, a psychoanalyst mode could be added:
$ svn help me make the bugs go away, please?
// Maybe your life has something to do with this.
--ben
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: Suggestion: "svn explain"
Posted by Karl Fogel <kf...@newton.ch.collab.net>.
Greg Hudson <gh...@MIT.EDU> writes:
> Subversion developers may certainly find it easier to communicate in
> terms of "SVN_ERR_NOT_WC" (or whatever) instead of a "Not a working
> copy" error. But I suspect most users, particularly developers, will
> mostly find such a code obstructive.
>
> If I lose this argument, I would at least suggest downcasing the
> constant name and putting it in parentheses before displaying it to the
> user. Yes, the downcasing could make it a little harder to search the
> Subversion code base for the constant, but if it's in all uppercase then
> the user's attention is called to the less useful information at the
> expense of the more useful information.
I have an idea:
As of today, Subversion does not print the error code (not as a
number, nor as a constant). Let's stick with that for a while and see
what happens. If there's no problem, we'll never notice, and the
issue won't come up again.
-K
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: Suggestion: "svn explain"
Posted by Greg Hudson <gh...@MIT.EDU>.
On Mon, 2002-08-05 at 17:48, Dave Cridland wrote:
> 1) Verbosity: Extra verbosity is one token, at minimum:
Too much, in my opinion. Error messages should be short and sweet.
On IRIX, if you ls a bad file, you see:
UX:ls: ERROR: Cannot access blah: No such file or directory
The "UX" and "ERROR" are "only" a few extra letters. But except in some
specific circumstance I don't even know about, it's extra crud to wade
through before I can find out what's wrong.
> 2) Other programs and systems *do* do this. Not all, it's true. But I
> imagine you recognise "SIGSEGV" in a program quite readily, and any http
> application you ever see give you a 404 is also an example of this to an
> extent.
I never see "SIGSEGV" when a program crashes; I see "Segmentation
fault." And I can hardly do a web search for "404" and get much of use.
> Perhaps you meant that it is incorrect practice to cover
> "uncommon cases". I'm simply not sure exactly what this means in this
> context.
In this case, the common case suffers a needless increase in verbosity,
while the uncommon case gets a little extra help looking things up by
web search. (And it's not clear to me that this extra help is generally
needed.)
If you think really hard about the uncommon case, this might seem like a
good tradeoff. How hard is it to scan over the ugly-looking Subversion
constant, after all? But if you make decisions like this routinely, the
resulting system will be cumbersome to use.
I've heard this principle (the one I am applying) called "the fairness
principle," though that doesn't seem to be a standard term. You don't
put code in the core path of a performance-critical program to handle a
rare corner case which could be handled (perhaps less efficiently) in
another way. A good C++ exception-handling system should not add even
one instruction to the case where an exception does not occur, even to
save a thousand instructions in the case where an exception does occur.
> a) My example was possibly poor, a more useful example might be someone
> natively working in, say, Polish, seeking help through the international
> community, which largely does not understand Polish.
I suppose... but the value of Polish-language information is so much
higher than the value of foreign-language information that I'm not sure
that it's useful to make it easier to find help in English or Italian.
> 6) I, personally, disagree with the assertion that this "obfuscates" the
> error. To me, errors which are accompanied by a human-recognisable code
> are clearer, as well as being more communicable. This appears to be true
> of many people on this list, hence the occasional use of the term
> "sigsegv", rather than segmentation fault, or access violation, and
> "404" rather than "File or resource not found".
Subversion developers may certainly find it easier to communicate in
terms of "SVN_ERR_NOT_WC" (or whatever) instead of a "Not a working
copy" error. But I suspect most users, particularly developers, will
mostly find such a code obstructive.
If I lose this argument, I would at least suggest downcasing the
constant name and putting it in parentheses before displaying it to the
user. Yes, the downcasing could make it a little harder to search the
Subversion code base for the constant, but if it's in all uppercase then
the user's attention is called to the less useful information at the
expense of the more useful information.
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: Suggestion: "svn explain"
Posted by David Waite <ma...@akuma.org>.
Damn, I was just going to recommend that this is printed in 'verbose'
mode ;-) Too late!
-David Waite
brane@xbc.nu wrote:
> Enough already. :-)
>
> I've gone and implemented this my way. The error numbers are shown,
> along with source file and line imformation, in maintainer mode.
> Otherwise, only the texts are printed.
>
> Once we make the texts more user-friendly, everything should be just
> fine.
>
> BTW, notice that GCC, which has tons more error and warning messages
> than we do, doesn't print error codes or mnemonics, either -- and this
> works just fine. In fact, most of the time the problem is that users
> don't post exact output and exact repros, not the lack of codes or
> mnemonics.
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: Suggestion: "svn explain"
Posted by br...@xbc.nu.
Enough already. :-)
I've gone and implemented this my way. The error numbers are shown,
along with source file and line imformation, in maintainer mode.
Otherwise, only the texts are printed.
Once we make the texts more user-friendly, everything should be just fine.
BTW, notice that GCC, which has tons more error and warning messages
than we do, doesn't print error codes or mnemonics, either -- and this
works just fine. In fact, most of the time the problem is that users
don't post exact output and exact repros, not the lack of codes or
mnemonics.
--
Brane Čibej <br...@xbc.nu> http://www.xbc.nu/brane/
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: Suggestion: "svn explain"
Posted by Karl Fogel <kf...@newton.ch.collab.net>.
I agree with Dave, basically.
The error code number is very confusing to the user; but an error code
string (e.g., "SVN_ERR_WC_CORRUPT" or whatever) is somewhat less
confusing, because at least it looks like words. Happily, it's also
far more useful for developers than the numeric code, and is not
affected by language translation. Also, we sometimes tweak the error
strings, but we still want to be able to unambiguously recognize the
error.
If we do our best to display it somewhere unobtrusive when printing an
error, then we get the best of both worlds, or at least not the worst
of any world.
Mind you, I'm not about to go and implement this tomorrow. But if
someone sent in a patch, that'd be great, IMHO...
-K
Dave Cridland <da...@cridland.net> writes:
> 1) Verbosity: Extra verbosity is one token, at minimum:
>
> svn: SVNERROR_BADEXAMPLE: This example is probably no good.
>
> > Other programs don't do this,
>
> 2) Other programs and systems *do* do this. Not all, it's true. But I
> imagine you recognise "SIGSEGV" in a program quite readily, and any http
> application you ever see give you a 404 is also an example of this to an
> extent.
>
> > and it seems to optimize for the uncommon case
>
> 3) This is not intended to be an optimization, but an addition.
> "optimize for the uncommon case" implies "at the expense of the common
> case". Perhaps you meant that it is incorrect practice to cover
> "uncommon cases". I'm simply not sure exactly what this means in this
> context.
>
> > (where the error message
> > is non-obvious,
>
> 4) If only this were uncommon by itself. But *all* error messages will
> be non-obvious to some people, and *some* error messages may well be
> non-obvious to almost everyone, in a sad parody of PT Barnum.
>
> > and the user would think to use google, and google would
> > actually find something useful given the error code, and google wouldn't
> > find something useful given the error message)
>
> 5)
>
> a) My example was possibly poor, a more useful example might be someone
> natively working in, say, Polish, seeking help through the international
> community, which largely does not understand Polish.
>
> b) The code can be searched on Google, communicated via IRC, or sent to
> this very mailing list, where only a minority of people speak Polish. (I
> know we have a couple of Polish speakers on here, hence my choice as an
> example language.)
>
> c) The same code can be used for more extensive local,
> internationalized, help, as Mark Benedetto King suggests - I wouldn't
> want to remove the "error text" entirely, though.
>
> > at the expense of
> > obfuscating the common case.
>
> 6) I, personally, disagree with the assertion that this "obfuscates" the
> error. To me, errors which are accompanied by a human-recognisable code
> are clearer, as well as being more communicable. This appears to be true
> of many people on this list, hence the occasional use of the term
> "sigsegv", rather than segmentation fault, or access violation, and
> "404" rather than "File or resource not found".
>
> Dave.
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
> For additional commands, e-mail: dev-help@subversion.tigris.org
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: Suggestion: "svn explain"
Posted by Dave Cridland <da...@cridland.net>.
On Mon, 2002-08-05 at 19:30, Greg Hudson wrote:
> On Mon, 2002-08-05 at 14:07, Dave Cridland wrote:
> > As mentioned before, Google is often the best source of online help for
> > what errors *really* mean.
>
> > Since the rest of the string can be internationlised, I for one would
> > really like a "This is error code 'SVNERROR_TOOMANYERRORCODES'" string
> > somewhere, giving me a suitable searchable token.
>
> I don't think it's worth the verbosity.
1) Verbosity: Extra verbosity is one token, at minimum:
svn: SVNERROR_BADEXAMPLE: This example is probably no good.
> Other programs don't do this,
2) Other programs and systems *do* do this. Not all, it's true. But I
imagine you recognise "SIGSEGV" in a program quite readily, and any http
application you ever see give you a 404 is also an example of this to an
extent.
> and it seems to optimize for the uncommon case
3) This is not intended to be an optimization, but an addition.
"optimize for the uncommon case" implies "at the expense of the common
case". Perhaps you meant that it is incorrect practice to cover
"uncommon cases". I'm simply not sure exactly what this means in this
context.
> (where the error message
> is non-obvious,
4) If only this were uncommon by itself. But *all* error messages will
be non-obvious to some people, and *some* error messages may well be
non-obvious to almost everyone, in a sad parody of PT Barnum.
> and the user would think to use google, and google would
> actually find something useful given the error code, and google wouldn't
> find something useful given the error message)
5)
a) My example was possibly poor, a more useful example might be someone
natively working in, say, Polish, seeking help through the international
community, which largely does not understand Polish.
b) The code can be searched on Google, communicated via IRC, or sent to
this very mailing list, where only a minority of people speak Polish. (I
know we have a couple of Polish speakers on here, hence my choice as an
example language.)
c) The same code can be used for more extensive local,
internationalized, help, as Mark Benedetto King suggests - I wouldn't
want to remove the "error text" entirely, though.
> at the expense of
> obfuscating the common case.
6) I, personally, disagree with the assertion that this "obfuscates" the
error. To me, errors which are accompanied by a human-recognisable code
are clearer, as well as being more communicable. This appears to be true
of many people on this list, hence the occasional use of the term
"sigsegv", rather than segmentation fault, or access violation, and
"404" rather than "File or resource not found".
Dave.
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: Suggestion: "svn explain"
Posted by Greg Hudson <gh...@MIT.EDU>.
On Mon, 2002-08-05 at 14:07, Dave Cridland wrote:
> As mentioned before, Google is often the best source of online help for
> what errors *really* mean.
> Since the rest of the string can be internationlised, I for one would
> really like a "This is error code 'SVNERROR_TOOMANYERRORCODES'" string
> somewhere, giving me a suitable searchable token.
I don't think it's worth the verbosity. Other programs don't do this,
and it seems to optimize for the uncommon case (where the error message
is non-obvious, and the user would think to use google, and google would
actually find something useful given the error code, and google wouldn't
find something useful given the error message) at the expense of
obfuscating the common case.
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: Suggestion: "svn explain"
Posted by Dave Cridland <da...@cridland.net>.
On Mon, 2002-08-05 at 17:13, Karl Fogel wrote:
> We should print out the
> constant's source name if we can
As mentioned before, Google is often the best source of online help for
what errors *really* mean.
Since the rest of the string can be internationlised, I for one would
really like a "This is error code 'SVNERROR_TOOMANYERRORCODES'" string
somewhere, giving me a suitable searchable token.
(Yes, this may give me explanations written in French, for instance, but
finding French is at least as useful than finding nothing.)
I'd go so far as a +1, with all that entails, and a -0.5 for abandoning
error codes entirely.
Dave.
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: Suggestion: "svn explain"
Posted by Karl Fogel <kf...@newton.ch.collab.net>.
Greg Hudson <gh...@MIT.EDU> writes:
> svn_error: #21079 : <Item already exists in filesystem>
> file `file:///var/ghudson/svn-test/grows' already exists.
>
> Aside from being visually ugly with the leading newline, an unschooled
> reader is likely to get caught up in the cryptic "svn_error: #21044 : <
> ...>" and take more time to get to the important text. I would display
> this as, perhaps:
>
> svn: Item already exists in filesystem
> svn: file `file:///var/ghudson/svn-test/grows' already exists.
+1 all *over* that.
The error codes don't even help developers, since we don't know them
numerically, we know them by error constant. We should print out the
constant's source name if we can, or just not print a code at all.
The raw codes alarm users while helping no one.
Also agree that the solution to cryptic errors is to write better
error strings (both for the core error string and/or for the
call-specific string where the error was created).
-K
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: Suggestion: "svn explain"
Posted by Greg Hudson <gh...@MIT.EDU>.
Well, I'm against "svn explain", partly because I think we should stop
reporting error codes at all. Our error messages are much too verbose.
An example error:
svn_error: #21079 : <Item already exists in filesystem>
file `file:///var/ghudson/svn-test/grows' already exists.
Aside from being visually ugly with the leading newline, an unschooled
reader is likely to get caught up in the cryptic "svn_error: #21044 : <
...>" and take more time to get to the important text. I would display
this as, perhaps:
svn: Item already exists in filesystem
svn: file `file:///var/ghudson/svn-test/grows' already exists.
Of course, this doesn't solve your problem of cryptic error messages. I
can only say two things about that: (1) bugs are generally going to
result in cryptic behavior; there's very little we can do about that
aside from fix most of the bugs; and (2) the correct response to a
cryptic error message is not to plaster over it with documentation, but
to make it less cryptic. For instance, when you try to "svn export"
over an existing directory right now, you get:
% svn export file:///var/ghudson/svn-test svn-test-exp
svn_error: #21035 : <Can't find an entry>
timestamps_equal_p: `grows' not under revision control
That's cryptic. We could make "svn explain 21035" mention that
exporting over an existing directory can cause this error, but it would
be much better to add a check for an existing target directory and yield
a sensical error message.
I also think we want to curb the expansion of our command set.
Bitkeeper is legitimately criticized as having way too many functions; I
don't think we want to go that route. But this is my smallest
objection, since it would be easily addressed by making a sub-feature of
"svn help" instead of making a new "svn explain."
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: Suggestion: "svn explain"
Posted by Gareth McCaughan <Ga...@pobox.com>.
On Saturday 03 August 2002 3:22 pm, Martin Pool wrote:
[I said:]
> > I propose that typing, e.g., "svn explain 21087" should yield
> > a friendly description, one or two paragraphs long, of
> > what that error means, what's likely to have provoked it,
> > and what to do about it. Perhaps this should be generalized
> > beyond error messages: "svn explain transaction" could
> > give a brief explanation of what a transaction is.
>
> Some people have previously expressed concern about the idea of
> putting too much documentation into the binary.
>
> Here's a counter-proposition: have a web site giving the same
> information, and easily searchable by error ID. Allow space for
> people to post followups giving additional information.
>
> One advantage is that people with old versions of svn can still get
> more up-to-date help, and it's easier for updated info to be
> accepted onto a site than merged into the main source.
I see two disadvantages to that, compared with putting the
information in the binary. (The *advantages*, I take it, are
obvious.)
1. I see nothing that guarantees that the error IDs will never
change. They're allocated sequentially-by-magic in
svn_error_codes.h, and if someone ever adds a new one
then all the later errors will get their IDs bumped up. Since
they are (currently) arranged in groups, it seems quite
likely that errors will get added in the middle of the list.
So the searching would have to be by error *message*,
which is a bit more cumbersome.
2. It's possible that the most appropriate message will
need to change from one version to the next. For instance:
I recently found what I think is a bug that leads to an
incorrect "Transaction out of date" error. If I'm right to
think it's a bug, and if it turns out to be easy to work
around and hard to fix, then for a few versions it might
be beneficial to add something to the corresponding
error description along the lines of "There's a known
problem with the version of Subversion you're using
that sometimes causes this error. Try doing X instead,
or see if the problem has been fixed in the latest version.".
Looking back at a thread from mid-July (don't know how
I missed it before), I see Ben suggesting a "svn help"
feature along similar-ish lines, Karl -0 on it, Brian Fitzpatrick
-1, and a certain Martin Pool actively in support. :-)
--
g
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: Suggestion: "svn explain"
Posted by Martin Pool <mb...@sourcefrog.net>.
On 3 Aug 2002, Gareth McCaughan <Ga...@pobox.com> wrote:
> I propose that typing, e.g., "svn explain 21087" should yield
> a friendly description, one or two paragraphs long, of
> what that error means, what's likely to have provoked it,
> and what to do about it. Perhaps this should be generalized
> beyond error messages: "svn explain transaction" could
> give a brief explanation of what a transaction is.
Some people have previously expressed concern about the idea of
putting too much documentation into the binary.
Here's a counter-proposition: have a web site giving the same
information, and easily searchable by error ID. Allow space for
people to post followups giving additional information.
One advantage is that people with old versions of svn can still get
more up-to-date help, and it's easier for updated info to be accepted
onto a site than merged into the main source.
(Not that I'm going to write it or anything :-)
--
Martin
Obscene material is proscribed in this way [by the Miller test:] it
appeals to the prurient interest [and] it's offensive. Basically, it's
"It excites me; and I hate it."
-- Prof. Jonathan Zittrain, via Seth Schoen
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org