bug#7500: 24.0.50; doc string of `current-kill'

bug#7500: 24.0.50; doc string of `current-kill'

[Drew Adams]

Please split this long sentence, and make it comprehensible:

 "If N is zero, `interprogram-paste-function' is set, and calling
  it returns a string or list of strings, then that string (or
  list) is added to the front of the kill ring and the string (or
  first string in the list) is returned as the latest kill."

`interprogram-paste-function' is set to what? to the kill-ring head?

Is "and calling it returns..." a statement of one of the _consequences_
of N being 0, or is it a further condition for what follows: "then that
string..." - i.e. "AND _IF_ calling it results... then..."?

bug#7500: 24.0.50; doc string of `current-kill'

[Andreas Schwab]

"Drew Adams" <drew.adams@oracle.com> writes:

> Please split this long sentence, and make it comprehensible:
>
>  "If N is zero, `interprogram-paste-function' is set, and calling
>   it returns a string or list of strings, then that string (or
>   list) is added to the front of the kill ring and the string (or
>   first string in the list) is returned as the latest kill."
>
> `interprogram-paste-function' is set to what?

interprogram-paste-function should be set to a function, otherwise it
wouldn't be called interprogram-paste-function.

> to the kill-ring head?

Since when is the kill-ring head a function?

> Is "and calling it returns..." a statement of one of the _consequences_
> of N being 0, or is it a further condition for what follows: "then that
> string..." - i.e. "AND _IF_ calling it results... then..."?

"then" starts a consequence, not "and".

Andreas.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

bug#7500: 24.0.50; doc string of `current-kill'

[Drew Adams]

> interprogram-paste-function should be set to a function, otherwise it
> wouldn't be called interprogram-paste-function.
... 
> Since when is the kill-ring head a function?
...
> "then" starts a consequence, not "and".

Stop trying to justify it.  It is a rambling, confusing sentence.

It reads like a translation to English from some long sentence that might (or
might not) have been clear in some other language (perhaps one that revels in
long sentences?).  The result is not clear.

I can't even tell whether (a) "then" here is part of an "if...then" construct or
(b) there is a comma splice (no-no) and "then" here is a _temporal_ adverb
starting an independent clause.  In the latter case, the comma should be a
period and "then" should start a new sentence.

If you don't know where to begin to improve the text, start by splitting it into
shorter, simpler sentences, preferably in the active voice.  That will probably
make the meaning clear.

Once I have the meaning I can propose something, if needed.  But my guess is
that once you've changed to active, short sentences the meaning will be clear
enough for everyone - no further improvement needed.

bug#7500: 24.0.50; doc string of `current-kill'

[Andreas Schwab]

"Drew Adams" <drew.adams@oracle.com> writes:

>> interprogram-paste-function should be set to a function, otherwise it
>> wouldn't be called interprogram-paste-function.
> ... 
>> Since when is the kill-ring head a function?
> ...
>> "then" starts a consequence, not "and".
>
> Stop trying to justify it.

It was already left justfied.

Andreas.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

bug#7500: 24.0.50; doc string of `current-kill'

[Stefan Monnier]

> Please split this long sentence, and make it comprehensible:
>  "If N is zero, `interprogram-paste-function' is set, and calling

The above is parsed as

   (and "if N is zero"
        "`interprogram-paste-function' is set"
        "calling ...")

since (and A B C) is usually written in (US) English "A, B, and C".
How 'bout:

 "If N is zero and `interprogram-paste-function' is set to a function
  that returns a string or list of strings, then that string (or
  list) is added to the front of the kill ring and the string (or
  first string in the list) is returned as the latest kill."


        Stefan

bug#7500: 24.0.50; doc string of `current-kill'

[Drew Adams]

> >  "If N is zero, `interprogram-paste-function' is set, and calling
> 
> The above is parsed as
>    (and "if N is zero"
>         "`interprogram-paste-function' is set"
>         "calling ...")

Thank you!  That's just the kind of succinct statement that makes the meaning
clear and advances the schmilblick.

But if that is the meaning then we also need to document what happens if N is
zero and one of the other conjuncts is false.  Are you sure you don't mean the
following instead?

 When N is zero, if i-p-f is set then calling...

IOW, _IF_ N is zero then (if `i-p-f' is....) else ZZZ.
(We already say what happens when N is not zero (ZZZ).)

> since (and A B C) is usually written in (US) English "A, B, and C".
> How 'bout:
> 
>  "If N is zero and `interprogram-paste-function' is set to a function
>   that returns a string or list of strings, then that string (or
>   list) is added to the front of the kill ring and the string (or
>   first string in the list) is returned as the latest kill."

See above.  If my guess above is correct, then:

 When N is zero, if `i-p-f' is set to...

And since the return value of i-p-a is _supposed_ to be either nil or a
string-or-list-of-strings:

 When N is zero, call the value of `interprogram-paste-function'.
 If that call returns nil, do nothing more and return the
 kill-ring car (??).  Otherwise, prepend the returned string
 (or list of strings) to the kill ring and then return the new
 kill-ring car.

See "??" above.  What does `current-kill' return if `i-p-f' returns nil when
called? the existing kill-ring head? nil?

bug#7500: 24.0.50; doc string of `current-kill'

[Lars Magne Ingebrigtsen]

"Drew Adams" <drew.adams@oracle.com> writes:

> And since the return value of i-p-a is _supposed_ to be either nil or a
> string-or-list-of-strings:
>
>  When N is zero, call the value of `interprogram-paste-function'.
>  If that call returns nil, do nothing more and return the
>  kill-ring car (??).  Otherwise, prepend the returned string
>  (or list of strings) to the kill ring and then return the new
>  kill-ring car.
>
> See "??" above.  What does `current-kill' return if `i-p-f' returns nil when
> called? the existing kill-ring head? nil?

Looking at the code, if it returns nil, then the entire "When" statement
fails.  I'll try to work that in...  somehow...

-- 
(domestic pets only, the antidote for overdose, milk.)
  bloggy blog http://lars.ingebrigtsen.no/

bug#7500: 24.0.50; doc string of `current-kill'

[Lars Magne Ingebrigtsen]

Stefan Monnier <monnier@IRO.UMontreal.CA> writes:

> How 'bout:
>
>  "If N is zero and `interprogram-paste-function' is set to a function
>   that returns a string or list of strings, then that string (or
>   list) is added to the front of the kill ring and the string (or
>   first string in the list) is returned as the latest kill."

I've now added this.

-- 
(domestic pets only, the antidote for overdose, milk.)
  bloggy blog http://lars.ingebrigtsen.no/