You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@subversion.apache.org by Edmund Wong <ed...@kdtc.net> on 2009/04/21 15:18:59 UTC
[PATCH] docstring changes
Hi,
Just finished reading svn_wc.h and came up with a few
changes to some docstrings.
Log
[[[
Made a few docstring changes.
* subversion/include/svn_wc.h
(svn_wc_adm_open_anchor): s/ @c/ @c/
(svn_wc_parse_externals_description3):s/, look/. Look/
(svn_opt_revision_t file_external_rev;): s/a intra/an intra/
(svn_wc_add3): s/its/it's/
(svn_wc_crawl_revisions4): s/locks are or/locks or/
s/Iff/If/
(svn_wc_get_diff_editor6): s/from repository/from the repository/
]]]
------------------------------------------------------
http://subversion.tigris.org/ds/viewMessage.do?dsForumId=462&dsMessageId=1844863
Re: [PATCH] docstring changes
Posted by Edmund Wong <ed...@belfordhk.com>.
Ed Price wrote:
> "Iff" is a common abbreviation (math-ism?) for "if and only if".
I know that. I'm a mathematician by heart. But
linguistically, it just sounds so weird having Iff there.
I've seen P iff Q. But Iff P, Q is puzzling.
>
> So you might want to leave that one alone.
>
> http://en.wikipedia.org/wiki/If_and_only_if
> http://mathworld.wolfram.com/Iff.html
Yes, I realize that, but gstein did mention that an 'if' could
be placed there. In any event, I'm not sure 'iff' makes
sense at the beginning of those two statements when
everywhere else uses 'If'.
Anyway, I'm open for suggestions.
Edmund
------------------------------------------------------
http://subversion.tigris.org/ds/viewMessage.do?dsForumId=462&dsMessageId=1851941
Re: [PATCH] docstring changes
Posted by Stefan Sperling <st...@elego.de>.
On Thu, May 21, 2009 at 05:26:08PM +0800, Edmund wrote:
> Stefan Sperling wrote:
>
>> I am explicitly +1 on this patch without the hunks that change iffs.
>>
>> I can't commit this myself right now though, because I'm in the middle
>> of evaluating a couple of operating systems to potentially switch to.
>> My Subversion development environment is not operative right now.
>>
>
> Which operating systems are you evaluating?
I took DragonFly for a spin, but it has too many issues right now
to be usable as a production system on my laptop, unfortunately.
Now I'm on Debian, but possibly just temporarily.
During the last few years, whenever I tried going back to Linux
I eventually ended up switching back to BSD for various reasons.
>> A gentle reminder in a few days would help.
>
> Not really in a hurry about it, but might this be a good
> reminder?
Yes, thanks for the reminder. I've committed your patch in r37787.
I used a simpler log message than the one you provided.
The hunks that changed "Iff" to "If" were not committed.
I've also removed one hunk that changed "repository->working copy"
to "the repository->working copy" because in my opinion that change
didn't improve the readability of the text.
All other hunks were really good fixes! Thank you!
Stefan
Re: [PATCH] docstring changes
Posted by Edmund Wong <ed...@belfordhk.com>.
Stefan Sperling wrote:
> I am explicitly +1 on this patch without the hunks that change iffs.
>
> I can't commit this myself right now though, because I'm in the middle
> of evaluating a couple of operating systems to potentially switch to.
> My Subversion development environment is not operative right now.
>
Which operating systems are you evaluating?
> A gentle reminder in a few days would help.
Not really in a hurry about it, but might this be a good
reminder?
Edmund
------------------------------------------------------
http://subversion.tigris.org/ds/viewMessage.do?dsForumId=462&dsMessageId=2344802
Re: [PATCH] docstring changes
Posted by Stefan Sperling <st...@elego.de>.
On Fri, May 01, 2009 at 11:52:56PM +0800, Edmund Wong wrote:
> Gavin Baumanis wrote:
> > Hi Edmund,
> >
> > Just thought I would check up on this thread and see if everyone had
> > come up with an agreement and if there was a final patch to propose?
> >
> > Gavin.
>
> Hi Gavin,
>
> Don't know the status. Stefan was in agreement, then
> there was a discussion on whether 'iff' should be left
> as is. Since this patch isn't a bug-biter, I suspect
> its priority is low. Back burner status, anyone?
I am explicitly +1 on this patch without the hunks that change iffs.
I can't commit this myself right now though, because I'm in the middle
of evaluating a couple of operating systems to potentially switch to.
My Subversion development environment is not operative right now.
A gentle reminder in a few days would help.
Thanks,
Stefan
Re: [PATCH] docstring changes
Posted by Edmund Wong <ed...@kdtc.net>.
Gavin Baumanis wrote:
> Hi Edmund,
>
> Just thought I would check up on this thread and see if everyone had
> come up with an agreement and if there was a final patch to propose?
>
> Gavin.
Hi Gavin,
Don't know the status. Stefan was in agreement, then
there was a discussion on whether 'iff' should be left
as is. Since this patch isn't a bug-biter, I suspect
its priority is low. Back burner status, anyone?
Edmund
------------------------------------------------------
http://subversion.tigris.org/ds/viewMessage.do?dsForumId=462&dsMessageId=2016272
Re: [PATCH] docstring changes
Posted by Gavin Baumanis <ga...@thespidernet.com>.
Hi Edmund,
Just thought I would check up on this thread and see if everyone had
come up with an agreement and if there was a final patch to propose?
Gavin.
On 23/04/2009, at 12:41 AM, Edmund Wong wrote:
> Erik Huelsmann wrote:
>
>> Hmmm. You obviously don't have a math background :-) It's a very
>> common thing in math texts to have "if and only if" shortened to iff.
>
> Yes, but at the beginning of a statement? When the rest
> of the docstring for that description used "If". Only
> two instances of "Iff". It's just strange.
>
> Only just recently someone mentioned WLOG, and that brought fond
> memories of numerical analysis.
>
> Edmund
>
> ------------------------------------------------------
> http://subversion.tigris.org/ds/viewMessage.do?dsForumId=462&dsMessageId=1861378
------------------------------------------------------
http://subversion.tigris.org/ds/viewMessage.do?dsForumId=462&dsMessageId=2013047
Re: [PATCH] docstring changes
Posted by Edmund Wong <ed...@kdtc.net>.
Erik Huelsmann wrote:
> Hmmm. You obviously don't have a math background :-) It's a very
> common thing in math texts to have "if and only if" shortened to iff.
Yes, but at the beginning of a statement? When the rest
of the docstring for that description used "If". Only
two instances of "Iff". It's just strange.
Only just recently someone mentioned WLOG, and that brought fond
memories of numerical analysis.
Edmund
------------------------------------------------------
http://subversion.tigris.org/ds/viewMessage.do?dsForumId=462&dsMessageId=1861378
Re: [PATCH] docstring changes
Posted by Stefan Sperling <st...@elego.de>.
On Wed, Apr 22, 2009 at 02:34:07PM +0200, Erik Huelsmann wrote:
> On Wed, Apr 22, 2009 at 1:22 PM, Stefan Sperling <st...@elego.de> wrote:
> > I wouldn't go as far as removing all iffs from the tree in a massive
> > series of patches. Please don't. But if the occasional iff gets
> > transformed into "if and only if", or even just "if" as a drive-by
> > side effect of a change, that's fine by me.
>
> Hmmm. You obviously don't have a math background :-)
God forbid, no! Please leave those memories alone.
I had to be dragged kicking and screaming through a total of 3
compulsory math courses in university over the course of 4 1/2 years.
Each math course takes half a year (one semester).
If you're good at math, you can now approximately work out how many
times I had to repeat each of these courses in order to finally pass
all of them :)
But at least I passed. You wouldn't believe the amount of students
dropping out of that university every year because of math.
> A must say that "if and only if" has a very different meaning that
> "if" by itself, so please don't change it to "if" alone: it's a
> different contract: the "and only if" part is an additional guarantee
> the interface is making.
That's a good point. So just shortening it to "if" is not acceptable
then, and these hunk will either have to be dropped from the diff,
or they should change iff to "if and only if".
Stefan
Re: [PATCH] docstring changes
Posted by Erik Huelsmann <eh...@gmail.com>.
On Wed, Apr 22, 2009 at 1:22 PM, Stefan Sperling <st...@elego.de> wrote:
> On Wed, Apr 22, 2009 at 09:50:29AM +1000, Gavin Baumanis wrote:
>> My view is to go for the simplest explanation possible - to leave out
>> colloquialisms / local language constructs and to be as non-technical
>> as possible for the purposes of documenting code.
>> Well written code - should be sufficient for those with the technical
>> understanding of the project and the plain-english description should
>> allow the not-so technically apt to fully understand (at least) the
>> intent of the code.
>
> I was confused by iff, too, at first sight. Luckily I had Stephen
> Butler next to me, who is a native speaker and could explain.
>
> I don't mind learning new things about the English language at all,
> though. So I welcome use of constructs that might even only be used
> locally where the person writing the comment is coming from, as long
> as they appear in some dictionary or can otherwise be deciphered.
>
> But I understand that iff may seem like a typo to many non-native speakers,
> until they discover that it is being used in a *lot* of comments. Then,
> if they don't look up the term (e.g. at http://en.wikipedia.org/wiki/Iff),
> being uncertain about its intended meaning causes uncertainty about
> their understanding of the comment, rather than the certainty which
> "if and only if" is supposed to imply.
>
> I wouldn't go as far as removing all iffs from the tree in a massive
> series of patches. Please don't. But if the occasional iff gets
> transformed into "if and only if", or even just "if" as a drive-by
> side effect of a change, that's fine by me.
Hmmm. You obviously don't have a math background :-) It's a very
common thing in math texts to have "if and only if" shortened to iff.
I guess it all depends where you're coming from.
A must say that "if and only if" has a very different meaning that
"if" by itself, so please don't change it to "if" alone: it's a
different contract: the "and only if" part is an additional guarantee
the interface is making.
Bye,
Erik.
------------------------------------------------------
http://subversion.tigris.org/ds/viewMessage.do?dsForumId=462&dsMessageId=1859848
Re: [PATCH] docstring changes
Posted by Stefan Sperling <st...@elego.de>.
On Wed, Apr 22, 2009 at 09:50:29AM +1000, Gavin Baumanis wrote:
> My view is to go for the simplest explanation possible - to leave out
> colloquialisms / local language constructs and to be as non-technical
> as possible for the purposes of documenting code.
> Well written code - should be sufficient for those with the technical
> understanding of the project and the plain-english description should
> allow the not-so technically apt to fully understand (at least) the
> intent of the code.
I was confused by iff, too, at first sight. Luckily I had Stephen
Butler next to me, who is a native speaker and could explain.
I don't mind learning new things about the English language at all,
though. So I welcome use of constructs that might even only be used
locally where the person writing the comment is coming from, as long
as they appear in some dictionary or can otherwise be deciphered.
But I understand that iff may seem like a typo to many non-native speakers,
until they discover that it is being used in a *lot* of comments. Then,
if they don't look up the term (e.g. at http://en.wikipedia.org/wiki/Iff),
being uncertain about its intended meaning causes uncertainty about
their understanding of the comment, rather than the certainty which
"if and only if" is supposed to imply.
I wouldn't go as far as removing all iffs from the tree in a massive
series of patches. Please don't. But if the occasional iff gets
transformed into "if and only if", or even just "if" as a drive-by
side effect of a change, that's fine by me.
That's why I said I think all of these changes are fine, and I still
think they are.
Stefan
Re: [PATCH] docstring changes
Posted by Edmund Wong <ed...@kdtc.net>.
Gavin Baumanis wrote:
> Hi Ed,
>
> In-line with my previous post - I would vote to changing it to your
> (and the original intent) definition of "if and only if".
> I would hate for the community to lose it's ...(I can't come up with
> an appropriate / better word - but for "flavor"),
> But in a comment - as opposed to code - anything that lowers the bar
> - so as to allow more people to understand and contribute, is a
> positive direction to take.
Hi Gavin,
I don't know the status of this patch; but as far as I know with
regards to "iff", I still believe it's a spelling error unless
I read wrong. While I am quite familiar with the 'iff' construct,
I've never seen it at the start of a sentence. Now probably
that stems from my lack of experience with reading docstrings;
still, it is weird to have 'if and only if' at the beginning of
a sentence when an 'if' works just as well.
I even asked gstein over IRC and he agreed with one of the
changes. I didn't ask about the other. Perhaps I falsely
took the liberty of assuming it was under the same 'situation'
(for lack of a better word) so to speak.
Thanks
Edmund
------------------------------------------------------
http://subversion.tigris.org/ds/viewMessage.do?dsForumId=462&dsMessageId=1940045
Re: [PATCH] docstring changes
Posted by Gavin Baumanis <ga...@thespidernet.com>.
Hi Ed,
In-line with my previous post - I would vote to changing it to your
(and the original intent) definition of "if and only if".
I would hate for the community to lose it's ...(I can't come up with
an appropriate / better word - but for "flavor"),
But in a comment - as opposed to code - anything that lowers the bar
- so as to allow more people to understand and contribute, is a
positive direction to take.
And in this instance it is obvious that Edmund (and others I am sure)
have read the documentation and believed it to be a spelling/typing
error as opposed to a technically relevant term.
Which leaves the reader at a level of thinking they understand - but
missing the point / intent entirely and by consequence not actually
understanding, what they think they do.
English speaking countries (even differing districts in the same
country) apply different meaning to words / phases.
What hope does a non-English speaking / English as a second language,
person have?
My view is to go for the simplest explanation possible - to leave out
colloquialisms / local language constructs and to be as non-technical
as possible for the purposes of documenting code.
Well written code - should be sufficient for those with the technical
understanding of the project and the plain-english description should
allow the not-so technically apt to fully understand (at least) the
intent of the code.
Gavin.
On 22/04/2009, at 2:35 AM, Ed Price wrote:
> "Iff" is a common abbreviation (math-ism?) for "if and only if".
>
> So you might want to leave that one alone.
>
> http://en.wikipedia.org/wiki/If_and_only_if
> http://mathworld.wolfram.com/Iff.html
>
> -Ed
>
> On Tue, Apr 21, 2009 at 11:29 AM, Stefan Sperling <st...@elego.de>
> wrote:
>> On Tue, Apr 21, 2009 at 11:18:59PM +0800, Edmund Wong wrote:
>>> Hi,
>>>
>>> Just finished reading svn_wc.h and came up with a few
>>> changes to some docstrings.
>>
>> All of those look all fine to me.
>>
>> Stefan
>>
>>
>
> ------------------------------------------------------
> http://subversion.tigris.org/ds/viewMessage.do?dsForumId=462&dsMessageId=1845609
------------------------------------------------------
http://subversion.tigris.org/ds/viewMessage.do?dsForumId=462&dsMessageId=1850798
Re: [PATCH] docstring changes
Posted by Ed Price <ed...@gmail.com>.
"Iff" is a common abbreviation (math-ism?) for "if and only if".
So you might want to leave that one alone.
http://en.wikipedia.org/wiki/If_and_only_if
http://mathworld.wolfram.com/Iff.html
-Ed
On Tue, Apr 21, 2009 at 11:29 AM, Stefan Sperling <st...@elego.de> wrote:
> On Tue, Apr 21, 2009 at 11:18:59PM +0800, Edmund Wong wrote:
>> Hi,
>>
>> Just finished reading svn_wc.h and came up with a few
>> changes to some docstrings.
>
> All of those look all fine to me.
>
> Stefan
>
>
------------------------------------------------------
http://subversion.tigris.org/ds/viewMessage.do?dsForumId=462&dsMessageId=1845609
Re: [PATCH] docstring changes
Posted by Stefan Sperling <st...@elego.de>.
On Tue, Apr 21, 2009 at 11:18:59PM +0800, Edmund Wong wrote:
> Hi,
>
> Just finished reading svn_wc.h and came up with a few
> changes to some docstrings.
All of those look all fine to me.
Stefan