Prefix-Arg (non-interactive!) in Info

Prefix-Arg (non-interactive!) in Info

[Memnon Anon]

[ Fairly long mail, questions are at the very bottom.]
Hi,

Someone had a fairly easy question on the orgmode ml:

,----[ Message-ID: <0vhbizzap7.fsf@gmail.com> ]
| I'd like to bind `C-u C-c C-x C-i' to the <f10> key in emacs 23.
`----

So, I thought this should be easy to find in the Info documentation and 
started looking through the relevant documentation via the indices, and
plain repeated `C-s' for things like C-u, universal argument etc.

But it was surprisingly difficult to find an answer to a simple
question: How do I non-interactively! pass a prefix argument to a
function?

On the one hand, it strengthened my remembrance, that C-u =
argument of 4, C-u C-u = argument of 16 etc, but I found no way how to
put this into good use; first tries in *scratch* failed.

On the contrary, this FAQ entry suggested another way and put me on the
wrong track for a minute or two:

,----[ (info "(efaq)Replying to the sender of a message") ]
| 12.6 How can I force Rmail to reply to the sender of a message, but not the other recipients?
|
| Ron Isaacson <isaacson@seas.upenn.edu> says: When you hit <r> to reply
| in Rmail, by default it CCs all of the original recipients (everyone on
! the original `To' and `CC' lists). With a prefix argument (i.e., typing
! `C-u' before <r>), it replies only to the sender.  However, going
! through the whole `C-u' business every time you want to reply is a
! pain.  This is the best fix I've been able to come up with:
| 
|      (defun rmail-reply-t ()
|        "Reply only to the sender of the current message. (See rmail-reply.)"
|        (interactive)
!        (rmail-reply t))
|      (add-hook 'rmail-mode-hook
|        (lambda ()
|          (define-key rmail-mode-map "r" 'rmail-reply-t)
|          (define-key rmail-mode-map "R" 'rmail-reply)))
`----
( Thinking: "C-u = Argument t?!" Nah, this can not be right, can it?
  But this other guy [Message ID: <87ocd71jz6.fsf@gmx.net>]
  suggested exactly that ...")

I finally gave up and went to google, where I found the right(?)
solution: 

,----[ http://www.emacs.uniyar.ac.ru/doc/em24h/emacs200.htm ]
| (define-key c++-mode-map [(f6)] (definteractive (comment-region '(4)))) 
| [...]
| definteractive declares an anonymous function at point with the body
! containing a call to comment region with argument '(4), which is the
! Lisp representation for the C-u prefix argument.
`----

Up to now, I was not only able to find such information in Info, I even
found them easily and quicker than with google, so I am wondering:

      Did I miss a crucial Info page? (I think so, but ... which?)
      If not, is this worth a wishlist bug against the documentation?
      If so, where would you suggest to put this information?

Memnon

Re: Prefix-Arg (non-interactive!) in Info

[Eli Zaretskii]

> From: Memnon Anon <gegendosenfleisch@googlemail.com>
> Date: Fri, 13 Aug 2010 16:37:04 +0200
> 
> So, I thought this should be easy to find in the Info documentation and 
> started looking through the relevant documentation via the indices, and
> plain repeated `C-s' for things like C-u, universal argument etc.
> 
> But it was surprisingly difficult to find an answer to a simple
> question: How do I non-interactively! pass a prefix argument to a
> function?

This information is usually in the doc string of the function you want
to invoke.  For example:

    rename-buffer is an interactive built-in function in `C source code'.

    (rename-buffer NEWNAME &optional UNIQUE)

    Change current buffer's name to NEWNAME (a string).
    If second arg UNIQUE is nil or omitted, it is an error if a
    buffer named NEWNAME already exists.
    If UNIQUE is non-nil, come up with a new name using
    `generate-new-buffer-name'.
    Interactively, you can set UNIQUE with a prefix argument.
    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

IOW, the prefix argument is normally one of the function's arguments,
so if you want to call the function non-interactively, just put there
the value you want to pass it.

The reason why you didn't find this in the Info manual is twofold:

  . You were looking for some general way of doing this, while the
    "normal" way is not general, but specific to each function --
    exactly which argument is mapped to the prefix argument is
    something each function determines for itself.

  . Since every function has a different argument mapped to the prefix
    arg, the manual doesn't have any discussions of this, except when
    it describes each and every function.

Re: Prefix-Arg (non-interactive!) in Info

[Memnon Anon]

Eli Zaretskii <eliz@gnu.org> writes:

> This information is usually in the doc string of the function you want
> to invoke.  For example:

Sorry, my description was not clear enough.
I knew that `C-u' produces a prefix arg, 4 by default, or any other
number if you specify it, as does M-4; and the manual states this in
several places. I also knew that each function uses prefixes
differently - as flag, as a repeater etc. -, and I knew where to look
for it, which is in the docstring.

What I did not find, was, how to pass this argument non interactively -
i.e. without `C-u' or M-4 - to a function.

I found this sentence in an old version of the emacs lisp intro:

http://www.cs.tut.fi/lintula/manual/elisp/emacs-lisp-intro-1.05/emacs-lisp-intro_21.html
,----
| (C-u produces an unprocessed prefix argument of (4), which is a list of
| one element.) 
`----

Exactly the "list of one element" part I was not aware of.

So, `C-u C-c C-x C-i' calls org-clock-in with an argument of (4).
(global-set-key (kbd "<f12>") (lambda () (interactive) (org-clock-in '(4))))

Well, I guess I should stop patching up my elisp knowledge bit by bit
and finally read and digest the whole emacs lisp intro and not just
browse it.

Memnon

Re: Prefix-Arg (non-interactive!) in Info

[Eli Zaretskii]

> From: Memnon Anon <gegendosenfleisch@googlemail.com>
> Cc: help-gnu-emacs@gnu.org
> Date: Fri, 13 Aug 2010 17:50:13 +0200
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > This information is usually in the doc string of the function you want
> > to invoke.  For example:
> 
> Sorry, my description was not clear enough.

I think it was clear enough, but perhaps my response wasn't.

Let's try a different approach: which function would you like to call
non-interactively, passing it some value of the prefix arg?  (Please
don't say "it's not important which function": my point is _precisely_
that it _is_ important, because the answer to your question is
specific to the function you want to invoke.)

> What I did not find, was, how to pass this argument non interactively -
> i.e. without `C-u' or M-4 - to a function.

It depends on the function.

RE: Prefix-Arg (non-interactive!) in Info

[Drew Adams]

> Let's try a different approach: which function would you like to call
> non-interactively, passing it some value of the prefix arg?  (Please
> don't say "it's not important which function": my point is _precisely_
> that it _is_ important, because the answer to your question is
> specific to the function you want to invoke.)
> 
> > What I did not find, was, how to pass this argument non 
> > interactively - i.e. without `C-u' or M-4 - to a function.
> 
> It depends on the function.

Eli's answers to you have been exactly correct.  His point is that it is the
definition of the particular function that determines which argument is (or
uses) the prefix argument, and how.  Any function can use the prefix argument
anyway it likes. 

Consequently, if you want to pass a prefix arg to a function non-interactively
then you must know how that function definition handles the value you pass.
Does it look only at whether or not a raw prefix arg is present (nil vs
non-nil)?  Does it look at the numeric value of the argument?  Does it
distinguish a cons such as (4) from a numeric value such as 4?  It is the
function that decides.

But perhaps you are writing your own function (that was not clear), and you want
to know how you can access the prefix argument and handle its possible values?

In any case, the relevant doc is node `Prefix Command Arguments' of the Elisp
manual.  You can find it easily via `i prefix argument RET' (that is, using the
manual's index).

There you will find not only a complete description of the possible values but
also the variable `current-prefix-arg' and the function `prefix-numeric-value',
both of which can be useful in handling prefix-arg values.

Re: Prefix-Arg (non-interactive!) in Info

[Memnon Anon]

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

> In any case, the relevant doc is node `Prefix Command Arguments' of the Elisp
> manual.  You can find it easily via `i prefix argument RET' (that is, using the
> manual's index).

Ah, thank you very much for this hint.

,----[ (info "(elisp)Prefix Command Arguments") ]
|    Here are the possible values of a raw prefix argument:  
|    * Nil [...]
|    * An integer, which stands for itself.
*    * A list of one element, which is an integer.  This form of prefix
*      argument results from one or a succession of `C-u''s with no
*      digits.  The numeric value is the integer in the list, but some
*      commands make a distinction between such a list and an integer
*      alone.
|    * The symbol `-' [...]
`----

I remember seeing it when I searched, but I dismissed it too quickly.
Curious, an 'integer', or a 'list of one element' ... which is an
integer.

Well, thats then the way it is.

Thanks Drew, thanks Eli!

RE: Prefix-Arg (non-interactive!) in Info

[Drew Adams]

> I remember seeing it when I searched, but I dismissed it too quickly.
> Curious, an 'integer', or a 'list of one element' ... which is an
> integer.
> 
> Well, thats then the way it is.

No, this is not just a curiosity. 

If you read a bit about nil, you will see that it can act in Lisp in two
important ways:

1. It represents (it is) an empty list.
2. It represents false, with non-nil representing true.

Instead of false and true, think alligator and non-alligator: _any_ dichotomous
choice.

The _raw_ prefix arg is most often looked at as a boolean choice: nil or
non-nil, the particular non-nil value making no difference.

But a non-nil value can be, well, anything other than nil. And that means that a
program is free to attach different meanings (behaviors) to different non-nil
values.

In addition, a non-nil raw prefix argument, which can be one of several things
(an integer, the atom `-', a cons with integer car, etc.) also has an associated
numeric value, given by function `prefix-numeric-value'.

A given function could, if it wanted, produce different behaviors for different
numerical values of its prefix arg.  Or, for a cons value, it could produce
different behaviors depending on which integer is the car of its cons value (4,
16, 256,...).  And it can mix these possibilities.  The possibilities are
endless (there are an endless number of integers, for one thing).

Re: Prefix-Arg (non-interactive!) in Info

[Memnon Anon]

Eli Zaretskii <eliz@gnu.org> writes:

> Let's try a different approach: which function would you like to call
> non-interactively, passing it some value of the prefix arg?  (Please
> don't say "it's not important which function": my point is _precisely_
> that it _is_ important, because the answer to your question is
> specific to the function you want to invoke.)

The function asked for was org-clock-in.

,----[ org-clock-in ]
| org-clock-in is an interactive compiled Lisp function.
| 
| (org-clock-in &optional SELECT START-TIME)
| 
| Start the clock on the current item.
| If necessary, clock-out of the currently active clock.
| With a prefix argument SELECT (C-u), offer a list of recently clocked tasks to
| clock into.  When SELECT is C-u C-u, clock into the current task and mark
| is as the default task, a special task that will always be offered in
| the clocking selection, associated with the letter `d'.
`----

I knew `C-u' = 4 (and not "t" as someone suggested), so I tried 
(global-set-key (kbd "<F12>") (lambda () (interactive) (org-clock-in 4)))
                                                        ^^^^^^^^^^^^^^^
This did not work, but I was hardly surprised.
It never does on the first approach :)

===
(Well, I had this example in mind: (info "(eintr)Interactive multiply-by-seven") 

(defun multiply-by-seven (number)       ; Interactive version.
       "Multiply NUMBER by seven."
       (interactive "p")
       (message "The result is %d" (* 7 number)))

(multiply-by-seven 2) --> 14
M-8 M-x multiply-by-seven --> 56
C-u M-x multiply-by-seven --> 28
Works for this function...
===

So I tried to figure out in what form org-clock-in wanted its argument
of 4 passed in.

And I found nothing, until I turned to google.

...

Now I am really confused:
I expected this to work, but it does not:
(multiply-by-seven '(4)).

Oh well, I still don't get it.

But 
(global-set-key (kbd "<F12>") (lambda () (interactive) (org-clock-in
'(4))))
works, the questioner has an answer; problem solved. And I will 
dedicate some time to learn elisp some, soon (at least the basics); 
and I will start with a thorough reading of the elisp intro.

Up to now, I could fix my and others problems by looking at working code
and fiddling until mine worked finally, too ... somehow; but I am
getting the impression this takes way more time on the long run than
learning the beast properly.

Memnon

Re: Prefix-Arg (non-interactive!) in Info

[Andreas Röhler]

Am 13.08.2010 19:04, schrieb Memnon Anon:
> Eli Zaretskii<eliz@gnu.org>  writes:
>
>> Let's try a different approach: which function would you like to call
>> non-interactively, passing it some value of the prefix arg?  (Please
>> don't say "it's not important which function": my point is _precisely_
>> that it _is_ important, because the answer to your question is
>> specific to the function you want to invoke.)
>
> The function asked for was org-clock-in.
>
> ,----[ org-clock-in ]
> | org-clock-in is an interactive compiled Lisp function.
> |
> | (org-clock-in&optional SELECT START-TIME)
> |
> | Start the clock on the current item.
> | If necessary, clock-out of the currently active clock.
> | With a prefix argument SELECT (C-u), offer a list of recently clocked tasks to
> | clock into.  When SELECT is C-u C-u, clock into the current task and mark
> | is as the default task, a special task that will always be offered in
> | the clocking selection, associated with the letter `d'.
> `----
>
> I knew `C-u' = 4 (and not "t" as someone suggested), so I tried
> (global-set-key (kbd "<F12>") (lambda () (interactive) (org-clock-in 4)))
>                                                          ^^^^^^^^^^^^^^^
> This did not work, but I was hardly surprised.
> It never does on the first approach :)
>
> ===
> (Well, I had this example in mind: (info "(eintr)Interactive multiply-by-seven")
>
> (defun multiply-by-seven (number)       ; Interactive version.
>         "Multiply NUMBER by seven."
>         (interactive "p")
>         (message "The result is %d" (* 7 number)))
>
> (multiply-by-seven 2) -->  14
> M-8 M-x multiply-by-seven -->  56
> C-u M-x multiply-by-seven -->  28
> Works for this function...
> ===
>
> So I tried to figure out in what form org-clock-in wanted its argument
> of 4 passed in.
>
> And I found nothing, until I turned to google.
>
> ...
>
> Now I am really confused:
> I expected this to work, but it does not:
> (multiply-by-seven '(4)).
>
> Oh well, I still don't get it.
>
> But
> (global-set-key (kbd "<F12>") (lambda () (interactive) (org-clock-in
> '(4))))
> works, the questioner has an answer; problem solved. And I will
> dedicate some time to learn elisp some, soon (at least the basics);
> and I will start with a thorough reading of the elisp intro.
>
> Up to now, I could fix my and others problems by looking at working code
> and fiddling until mine worked finally, too ... somehow; but I am
> getting the impression this takes way more time on the long run than
> learning the beast properly.
>
> Memnon
>
>

Hi,

remember having that kind of diffcults too when starting with Emacs.
Somehow that issue may fit into another thread at emacs-devel "Emacs 
learning curve."

Difficulty was the notion of "Universal argument".
 From now:

it's a kind of interface from the Emacs Lisp side providing an input 
facility bound to a predefined key.

Basically it's a tool to toggle, a switch taking args with it.

You must only think of it, when writing something taking user input.
There are more provisions for user input.

Universal argument is just one.


Andreas

Re: Prefix-Arg (non-interactive!) in Info

[Memnon Anon]

Andreas Röhler <andreas.roehler@easy-emacs.de> writes:

> Somehow that issue may fit into another thread at emacs-devel "Emacs
> learning curve."

I think this thread is way too long already :)

Memnon

Re: Prefix-Arg (non-interactive!) in Info

[Eli Zaretskii]

> From: Memnon Anon <gegendosenfleisch@googlemail.com>
> Cc: help-gnu-emacs@gnu.org
> Date: Fri, 13 Aug 2010 19:04:30 +0200
> 
> The function asked for was org-clock-in.
> 
> ,----[ org-clock-in ]
> | org-clock-in is an interactive compiled Lisp function.
> | 
> | (org-clock-in &optional SELECT START-TIME)
> | 
> | Start the clock on the current item.
> | If necessary, clock-out of the currently active clock.
> | With a prefix argument SELECT (C-u), offer a list of recently clocked tasks to
> | clock into.  When SELECT is C-u C-u, clock into the current task and mark
> | is as the default task, a special task that will always be offered in
> | the clocking selection, associated with the letter `d'.
> `----
> 
> I knew `C-u' = 4 (and not "t" as someone suggested), so I tried 
> (global-set-key (kbd "<F12>") (lambda () (interactive) (org-clock-in 4)))
>                                                         ^^^^^^^^^^^^^^^
> This did not work, but I was hardly surprised.

You are wrong assuming that the prefix arg is always 4.  Its ``value''
depends on how the function accesses it; the node in the ELisp manual
that Drew pointed to spells out the possible ``values''.  In addition,
it matters how the function tests the possible values of the argument;
if the function just checks that its argument (in this case, SELECT)
is non-nil, then '(4) will do, but so will '(foobar).

> (defun multiply-by-seven (number)       ; Interactive version.
>        "Multiply NUMBER by seven."
>        (interactive "p")
>        (message "The result is %d" (* 7 number)))
> 
> (multiply-by-seven 2) --> 14
> M-8 M-x multiply-by-seven --> 56
> C-u M-x multiply-by-seven --> 28
> Works for this function...
> 
> So I tried to figure out in what form org-clock-in wanted its argument
> of 4 passed in.
> 
> And I found nothing, until I turned to google.

It would be better (and more educational) to simply read the code of
the function (and submit a bug report regarding the unclear doc
string).  In there, you'd see that org-clock-in uses (interactive "P"),
which assigns the raw prefix argument to SELECT, and it tests its
value like this:

      (when (equal select '(4))

which tells you that it really wants the list '(4) -- not very clean,
I'd say.

> Now I am really confused:
> I expected this to work, but it does not:
> (multiply-by-seven '(4)).

That's because multiply-by-seven uses (interactive "p") -- lowercase
`p' -- which assigns to NUMBER the numerical value of the prefix arg.

The meaning of the interactive codes, such as "P" and "p", is
explained in the node "Interactive Codes" in the ELisp manual.

[Solved] (was: Prefix-Arg (non-interactive!) in Info)

[Memnon Anon]

Eli Zaretskii <eliz@gnu.org> writes:

>> This did not work, but I was hardly surprised.
>
> You are wrong assuming that the prefix arg is always 4.  Its ``value''
> depends on how the function accesses it; the node in the ELisp manual
> that Drew pointed to spells out the possible ``values''.  In addition,
> it matters how the function tests the possible values of the argument;
> if the function just checks that its argument (in this case, SELECT)
> is non-nil, then '(4) will do, but so will '(foobar).

Yes, now I understand. I thought it would always be an integer and
`C-u' just is default 4 without further ado. I did not expect it 
to be that versatile :).

> It would be better (and more educational) to simply read the code of
> the function (and submit a bug report regarding the unclear doc
> string). 

I usually do, when I investigate for my own purpose.
But here, I wanted to help another person (and investigate a wrong^W not
working answer he got).
So, I went the short route this time.

w.r.t. Bug report, no, I would not do that.
I am no programmer, I hardly ever write anything from scratch; I modify
existing code for my own needs and at best effort. Imho, for reporting
Bugs like this, a more profound level of expertise is needed or you are 
most certainly waisting a developers precious time.

(My area of expertise is latin. So I need a tool that handles text well,
especially latex, but also grep et al. Emacs is just perfect for that.
Of course, orgmode all by itself would be enough. I think this is a 
point that is stressed not enough: Emacs is not only a "a great tool for
programmers. It is an excellent tool for everyone who has to deal with
large amount of text! If you are willing to learn its ways that is :)

> That's because multiply-by-seven uses (interactive "p") -- lowercase
> `p' -- which assigns to NUMBER the numerical value of the prefix arg.
> The meaning of the interactive codes, such as "P" and "p", is
> explained in the node "Interactive Codes" in the ELisp manual.

Thank you *very much* for taking the time to explain.
I really learned a lot today :).

Memnon "Happy" Anon

Re: [Solved] (was: Prefix-Arg (non-interactive!) in Info)

[Eli Zaretskii]

> From: Memnon Anon <gegendosenfleisch@googlemail.com>
> Cc: help-gnu-emacs@gnu.org
> Date: Fri, 13 Aug 2010 22:58:11 +0200
> 
> w.r.t. Bug report, no, I would not do that.
> I am no programmer, I hardly ever write anything from scratch; I modify
> existing code for my own needs and at best effort. Imho, for reporting
> Bugs like this, a more profound level of expertise is needed or you are 
> most certainly waisting a developers precious time.

I urge you to reconsider.  Sending an email saying that the doc string
of org-clock-in does not say what value to assign to the SELECT
argument in a non-interactive call does not need any high level of
expertise.  If a doc string does not explain what are the valid
values of the function's arguments, then that doc string needs to be
improved.  Documenting this is the absolute minimum of any doc string;
without that, the doc string is useless.  It is sometimes okay to omit
these details if the valid values are clear from the text and the
context.  But I cannot see how someone could claim that the value '(4)
could be "clear".

Re: [Solved]

[Memnon Anon]

Eli Zaretskii <eliz@gnu.org> writes:

> I urge you to reconsider.  Sending an email saying that the doc string
> of org-clock-in does not say what value to assign to the SELECT
> argument in a non-interactive call does not need any high level of
> expertise.  

Sending the mail does not need expertise. But recognizing if something
really is a deficiency does. Bug reports are great, but creating
"noise" is not; and I really don't want to be a nuisance to the experts
who provide me with so excellent tools. And even if I did recognize a
lack of precision - which requires some knowledge of best practice in
doc strings - I would want to send a patch, which requires even more
knowledge of doc strings in general (= not only seeing what is wrong but
also 'fixing' it).

One way is looking for other docstrings that seem to be "better".
In org, I found lots of functions that are usually called interactively
that have a doc string like the one before.
see eg:

,----[ org-remember.el ]
| (defun org-remember (&optional goto org-force-remember-template-char)
|   "Call `remember'.  If this is already a remember buffer, re-apply template.
| If there is an active region, make sure remember uses it as initial content
| of the remember buffer.
| 
| When called interactively with a \\[universal-argument] \
| prefix argument GOTO, don't remember
| anything, just go to the file/headline where the selected template usually
| stores its notes.  With a double prefix argument \
| \\[universal-argument] \\[universal-argument], go to the last
| note stored by remember.
| 
| Lisp programs can set ORG-FORCE-REMEMBER-TEMPLATE-CHAR to a character
| associated with a template in `org-remember-templates'."
|   (interactive "P")
|   (org-require-remember)
|   (cond
|    ((equal goto '(4)) (org-go-to-remember-target))
|    ((equal goto '(16)) (org-remember-goto-last-stored))
`----

I (so far) only found one docstring that seems "better" in this regard:

,----[ org-agenda.el ]
| (defun org-agenda-set-restriction-lock (&optional type)
|   "Set restriction lock for agenda, to current subtree or file.
| Restriction will be the file if TYPE is `file', or if type is the
* universal prefix '(4), or if the cursor is before the first headline
| ^^^^^^^^^^^^^^^^^^^^^^               
| in the file.  Otherwise, restriction will be to the current subtree."
`----

This one says explicitly '(4) is what is tested against.

So should I look for all interactive functions that check against a
universal argument with 

          (when (equal arg '(4)) ... 

and suggest the docstring, which usually only says something like: "When 
using \\[universal-argument], ..." to be modified like:
"When using \\[universal-argument] '(4)"? (Of course on a case to case
basis whenever it seems not clear so far.)

> If a doc string does not explain what are the valid values of the
> function's arguments, then that doc string needs to be improved.
> Documenting this is the absolute minimum of any doc string; without
> that, the doc string is useless.  It is sometimes okay to omit these
> details if the valid values are clear from the text and the context.
> But I cannot see how someone could claim that the value '(4) could be
> "clear".

Mhhh.
Please have a look at this docstring:

,----[ org-agenda.el ]
| (defun org-agenda-clock-out (&optional arg)
|   "Stop the currently running clock."
|   (interactive "P")
|   (unless (marker-buffer org-clock-marker)
|     (error "No running clock"))
|   (let ((marker (make-marker)) newhead)
|     (org-with-remote-undo (marker-buffer org-clock-marker)
|       (with-current-buffer (marker-buffer org-clock-marker)
| 	(save-excursion
| 	  (save-restriction
| 	    (widen)
| 	    (goto-char org-clock-marker)
| 	    (org-back-to-heading t)
| 	    (move-marker marker (point))
| 	    (org-clock-out)
| 	    (setq newhead (org-get-heading))))))
|     (org-agenda-change-all-lines newhead marker)
|     (move-marker marker nil)))
`----

This function takes an (optioal) arg, but it is in now way explain what
this arg does.

To tell the truth, in contrast to `org-agenda-clock-in', I do not even
see where this arg is used anywhere in the function...

Should I really file bug reports when I obviously do not understand
whats going on? I don't think so.

Plus: All these points are not really important, because these functions
are meant to be used interactively, what they usually are ...  except
when someone wants to bind them to a key with a lambda like in the case
of C-u C-c C-x C-i (org-clock-in) before.


Memnon

P.S.: Cool, I saw you really use the convention to start a new sentence
      with <SPC> <SPC>. I never saw anyone really that :)

Re: [Solved]

[Eli Zaretskii]

> From: Memnon Anon <gegendosenfleisch@googlemail.com>
> Cc: help-gnu-emacs@gnu.org
> Date: Sat, 14 Aug 2010 23:18:21 +0200
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > I urge you to reconsider.  Sending an email saying that the doc string
> > of org-clock-in does not say what value to assign to the SELECT
> > argument in a non-interactive call does not need any high level of
> > expertise.  
> 
> Sending the mail does not need expertise. But recognizing if something
> really is a deficiency does. Bug reports are great, but creating
> "noise" is not; and I really don't want to be a nuisance to the experts
> who provide me with so excellent tools. And even if I did recognize a
> lack of precision - which requires some knowledge of best practice in
> doc strings - I would want to send a patch, which requires even more
> knowledge of doc strings in general (= not only seeing what is wrong but
> also 'fixing' it).

Sending a patch is fine.  But if you cannot send a patch, at least
make a bug report.  Doing nothing after you spotted a problem is IMO
worse than sending a bug report out of mistake or misunderstanding.

> One way is looking for other docstrings that seem to be "better".
> In org, I found lots of functions that are usually called interactively
> that have a doc string like the one before.

Even more reason to submit a report: it sounds like many doc strings
there need the same treatment.

> Should I really file bug reports when I obviously do not understand
> whats going on?

Yes.  An unclear doc string needs improvement.