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]

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]

"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

[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.

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).

[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: 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: [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.

Re: [SOLVED]

[Uwe Brauer]

[-- Attachment #1: Type: text/plain, Size: 1115 bytes --]

>>> "EBvUlftGEte" == Emanuel Berg via Users list for the GNU Emacs text editor <help-gnu-emacs@gnu.org> writes:

> Uwe Brauer wrote:
>> Actually it was quite easy as in 
>> 
>> (defun randomise-region ()
>> "Like `ap/replace-words-randomly', but only replace inside region if it is active.
>> If the region is not active, replace from point to the end of the
>> buffer.  The region is never considered active outside
>> `transient-mark-mode'. "
>> (interactive)
>> (if (or (and (boundp 'zmacs-region-active-p) zmacs-region-active-p)
>> (and (boundp 'transient-mark-mode) transient-mark-mode mark-active))
>> (save-restriction
>> (save-excursion
>> (narrow-to-region (point) (mark))
>> (goto-char (point-min))
>> (ap/replace-words-randomly)))
>> (ap/replace-words-randomly)))

> ;;; -*- lexical-binding: t -*-
> ;;;
> ;;; this file:
> ;;;   http://user.it.uu.se/~embe8573/emacs-init/sort-incal.el
> ;;;   https://dataswamp.org/~incal/emacs-init/sort-incal.el

> (require 'edit)
> (require 'erc)
> (require 'sort)

Thanks but the file edit, is missing at least not included in my emacs

[-- Attachment #2: smime.p7s --]
[-- Type: application/pkcs7-signature, Size: 5673 bytes --]

Re: [SOLVED]

[Emanuel Berg via Users list for the GNU Emacs text editor]

Uwe Brauer wrote:

> Thanks but the file edit, is missing at least not included
> in my emacs

You are right, "must" fix the names, try these and only these:

(defun region-to-string ()
  "Return the region text as a string. Replace newlines with spaces."
  (when (use-region-p)
    (let ((beg (region-beginning))
          (end (region-end) ))
    (let ((text (buffer-substring-no-properties beg end)))
      (replace-regexp-in-string "\n" " " text) ))))

(defun scramble (beg end)
  "Shuffle chars in region from BEG to END."
  (interactive "r")
  (when (use-region-p)
    (save-excursion
      (let*((str        (region-to-string))
            (chars      (delete "" (split-string str "")))
            (rand-chars (sort chars (lambda (_ __) (zerop (random 2))))) )
        (delete-region beg end)
        (dolist (c rand-chars)
          (insert c) )))))

(require 'seq)
(defun scramble-string (str)
  "Randomize the characters of a string."
  (interactive "sscramble me: ")
  (let ((rand-str (seq-sort (lambda (_ __) (zerop (random 2))) str )))
    (if (called-interactively-p 'any)
        (message rand-str)
      rand-str) ))

(defun comic-book-insult ()
  (interactive)
  (insert (concat (scramble-string "@#$%&") "!")) )

;; (comic-book-insult) ; @#$%&!
;; (comic-book-insult) ; $&#@%!

;; (scramble-string "Hello there, Emacs is very cool piece of software")
;; "aye eposrr lvre olsec,ewfico ceti ftomH hseoa l E"

-- 
underground experts united
https://dataswamp.org/~incal

Re: [SOLVED]

[Uwe Brauer]

[-- Attachment #1: Type: text/plain, Size: 529 bytes --]

>>> "EBvUlftGEte" == Emanuel Berg via Users list for the GNU Emacs text editor <help-gnu-emacs@gnu.org> writes:

> Uwe Brauer wrote:
>> Thanks but the file edit, is missing at least not included
>> in my emacs

> You are right, "must" fix the names, try these and only these:

Thanks that works nicely, it is a bit different from the package I use
because mine replaces words by some randomly picked words of the same
size yours randomise also the words. Both approaches work, yours is
independent from any external tool, tough.

[-- Attachment #2: smime.p7s --]
[-- Type: application/pkcs7-signature, Size: 5673 bytes --]

Re: [SOLVED]

[Emanuel Berg via Users list for the GNU Emacs text editor]

Uwe Brauer wrote:

>>>> "EBvUlftGEte" == Emanuel Berg via Users list for the GNU
>>> Emacs text editor <help-gnu-emacs@gnu.org> writes:
>
>> Uwe Brauer wrote:
>>> Thanks but the file edit, is missing at least not included
>>> in my emacs
>
>> You are right, "must" fix the names, try these and only these:
>
> Thanks that works nicely, it is a bit different from the package I use
> because mine replaces words by some randomly picked words of the same
> size yours randomise also the words. Both approaches work, yours is
> independent from any external tool, tough.

You mean zmacs-region-active-p and/or
ap/replace-words-randomly ?

Yeah, I don't have either ...

-- 
underground experts united
https://dataswamp.org/~incal

Re: [SOLVED]

[Michael Heerdegen]

Uwe Brauer <oub@mat.ucm.es> writes:

> Thanks, that did not occur to me. I tried to advice since a while
> since it makes debugging difficult.

Not much, IME.

> (defadvice copy-to-register (before removeproperties activate)
>   "Remove all text properties before setting the property"
>   (let ((inhibit-read-only t))
>     (set-text-properties (point-min) (point-max) nil)))

It would be better and cleaner to change the value that is saved in the
register instead of modifying the buffer.

Michael.

Re: [SOLVED]

[Uwe Brauer]

[-- Attachment #1: Type: text/plain, Size: 970 bytes --]

>>> "MH" == Michael Heerdegen <michael_heerdegen@web.de> writes:

> Uwe Brauer <oub@mat.ucm.es> writes:
>> Thanks, that did not occur to me. I tried to advice since a while
>> since it makes debugging difficult.

> Not much, IME.

>> (defadvice copy-to-register (before removeproperties activate)
>> "Remove all text properties before setting the property"
>> (let ((inhibit-read-only t))
>> (set-text-properties (point-min) (point-max) nil)))

> It would be better and cleaner to change the value that is saved in the
> register instead of modifying the buffer.

Well I tried that, but I couldn't. As I said modify set-register did not
work for me.

I am not happy about my solution and would appreciate any suggestion.

Uwe 




-- 
I strongly condemn Putin's war of aggression against the Ukraine.
I support to deliver weapons to Ukraine's military. 
I support the ban of Russia from SWIFT.
I support the EU membership of the Ukraine. 

[-- Attachment #2: smime.p7s --]
[-- Type: application/pkcs7-signature, Size: 5673 bytes --]

Re: [SOLVED]

[Uwe Brauer]

[-- Attachment #1: Type: text/plain, Size: 1231 bytes --]

>>> "UB" == Uwe Brauer <oub@mat.ucm.es> writes:

>>> "MH" == Michael Heerdegen <michael_heerdegen@web.de> writes:
>> Uwe Brauer <oub@mat.ucm.es> writes:
>>> Thanks, that did not occur to me. I tried to advice since a while
>>> since it makes debugging difficult.

>> Not much, IME.

>>> (defadvice copy-to-register (before removeproperties activate)
>>> "Remove all text properties before setting the property"
>>> (let ((inhibit-read-only t))
>>> (set-text-properties (point-min) (point-max) nil)))

>> It would be better and cleaner to change the value that is saved in the
>> register instead of modifying the buffer.

I just realized that I did not read your message carefully enough.

It seems you suggest 

(defadvice copy-to-register (before removeproperties activate)
  "Remove all text properties before setting the property"
  (let ((inhibit-read-only t))
    (set-text-properties (region-beginning) (region-end) nil)))

Which is what I intended but copied the code incorrectly.

-- 
I strongly condemn Putin's war of aggression against the Ukraine.
I support to deliver weapons to Ukraine's military. 
I support the ban of Russia from SWIFT.
I support the EU membership of the Ukraine. 

[-- Attachment #2: smime.p7s --]
[-- Type: application/pkcs7-signature, Size: 5673 bytes --]

Re: [SOLVED]

[Stefan Monnier via Users list for the GNU Emacs text editor]

> It seems you suggest 
>
> (defadvice copy-to-register (before removeproperties activate)
>   "Remove all text properties before setting the property"
>   (let ((inhibit-read-only t))
>     (set-text-properties (region-beginning) (region-end) nil)))

No, that still modifies the buffer.  He suggests you apply
`set-text-properties` to the extracted string.


        Stefan

Re: [SOLVED]

[Uwe Brauer]

[-- Attachment #1: Type: text/plain, Size: 973 bytes --]

>>> "SMvUlftGEte" == Stefan Monnier via Users list for the GNU Emacs text editor <help-gnu-emacs@gnu.org> writes:

>> It seems you suggest 
>> 
>> (defadvice copy-to-register (before removeproperties activate)
>> "Remove all text properties before setting the property"
>> (let ((inhibit-read-only t))
>> (set-text-properties (region-beginning) (region-end) nil)))

> No, that still modifies the buffer.  He suggests you apply
> `set-text-properties` to the extracted string.


Well I tried 

(defadvice set-property (before removeproperties activate)
  "Remove all text properties before setting the property"
  (let ((inhibit-read-only t))
(set-text-properties (region-beginning) (region-end) nil)))

But it did not work

Uwe 




-- 
I strongly condemn Putin's war of aggression against the Ukraine.
I support to deliver weapons to Ukraine's military. 
I support the ban of Russia from SWIFT.
I support the EU membership of the Ukraine. 

[-- Attachment #2: smime.p7s --]
[-- Type: application/pkcs7-signature, Size: 5673 bytes --]

Re: [SOLVED]

[Michael Heerdegen]

Uwe Brauer <oub@mat.ucm.es> writes:

> Well I tried 
>
> (defadvice set-property (before removeproperties activate)
>   "Remove all text properties before setting the property"
>   (let ((inhibit-read-only t))
> (set-text-properties (region-beginning) (region-end) nil)))
>
> But it did not work

Wouldn't it be appropriate to refresh your knowledge about advices?

Michael.

Re: [SOLVED]

[Uwe Brauer]

[-- Attachment #1: Type: text/plain, Size: 3123 bytes --]

>>> "MH" == Michael Heerdegen <michael_heerdegen@web.de> writes:

> Uwe Brauer <oub@mat.ucm.es> writes:
>> Well I tried 
>> 
>> (defadvice set-property (before removeproperties activate)
>> "Remove all text properties before setting the property"
>> (let ((inhibit-read-only t))
>> (set-text-properties (region-beginning) (region-end) nil)))
>> 
>> But it did not work

> Wouldn't it be appropriate to refresh your knowledge about advices?

Well I tried this as well, and tried out the new advice-add
functionality.

Here is what I tried 


(defun my-remove-all-text-properties-region ()
  (interactive) ;; that is not important
  (let ((inhibit-read-only t))
    (set-text-properties (region-beginning) (region-end) nil)))

Then 

(advice-add 'set-property :before #'my-remove-all-text-properties-region)

or 

(advice-add 'set-property :around #'my-remove-all-text-properties-region)

Result: no effect


I tried 

(advice-add 'copy-to-register :before  #'my-remove-all-text-properties-region)
or 
(advice-add 'copy-to-register :around  #'my-remove-all-text-properties-region)

Results in an  error:

,----
| Debugger entered--Lisp error: (wrong-number-of-arguments
|   #f(compiled-function () (interactive nil) #<bytecode
|   0x1f6825029d2a6658>) 1)
|   my-remove-all-text-properties-region(#f(compiled-function (register
|   start end &optional delete-flag region) "Copy region into register
|   REGISTER.\nWith prefix arg, delete as well.\nCalled from program,
|   takes five args: REGISTER, START, END, DELETE-FLAG,\nand REGION. START
|   and END are buffer positions indicating what to copy.\nThe optional
|   argument REGION if non-nil, indicates that we're not just\ncopying
|   some text between START and END, but we're copying the
|   region.\n\nInteractively, reads the register using
|   `register-read-with-preview'." (interactive #f(compiled-function ()
|   #<bytecode -0x19b31a6142e6ce87>)) #<bytecode 0x18af6be063d3e91b>))
|   apply(my-remove-all-text-properties-region #f(compiled-function
|   (register start end &optional delete-flag region) "Copy region into
|   register REGISTER.\nWith prefix arg, delete as well.\nCalled from
|   program, takes five args: REGISTER, START, END, DELETE-FLAG,\nand
|   REGION. START and END are buffer positions indicating what to
|   copy.\nThe optional argument REGION if non-nil, indicates that we're
|   not just\ncopying some text between START and END, but we're copying
|   the region.\n\nInteractively, reads the register using
|   `register-read-with-preview'." (interactive #f(compiled-function ()
|   #<bytecode -0x19b31a6142e6ce87>)) #<bytecode 0x18af6be063d3e91b>) nil)
|   copy-to-register() funcall-interactively(copy-to-register)
|   call-interactively(copy-to-register nil nil)
|   command-execute(copy-to-register)
`----

At this point I give up

Uwe 




-- 
I strongly condemn Putin's war of aggression against the Ukraine.
I support to deliver weapons to Ukraine's military. 
I support the ban of Russia from SWIFT.
I support the EU membership of the Ukraine. 

[-- Attachment #2: smime.p7s --]
[-- Type: application/pkcs7-signature, Size: 5673 bytes --]

Re: [SOLVED]

[Thorsten Bonow]

>>>>> Uwe Brauer <oub@mat.ucm.es> writes: 
 
[...] 
 
> At this point I give up 
 
> Uwe 

Don't loose heart...

(defun copy-to-register--no-properties (orig-fun &rest args) 
  "Remove properties of region when calling `copy-to-register'." 
  (let ((filter-buffer-substring-function (lambda (beg end 
  &optional delete) 
					    (if delete 
						(delete-and-extract-region 
						beg end) 
						(buffer-substring-no-properties 
						beg end))))) 
    (apply orig-fun args))) 
(advice-add 'copy-to-register :around 
#'copy-to-register--no-properties) 

Works for me, but the way I understand the manual, instead of 
advising a function, better-registers.el should just modify 
`filter-buffer-substring-function' for its needs.

Hope this helps.

Toto 

-- 
Sent from my GNU Emacs running on GNU/Linux

Re: [SOLVED]

[Uwe Brauer]

[-- Attachment #1: Type: text/plain, Size: 1442 bytes --]

>>> "TB" == Thorsten Bonow <thorsten.bonow@post.rwth-aachen.de> writes:

Hello Thorsten
>>>>>> Uwe Brauer <oub@mat.ucm.es> writes: 
> [...]  > At this point I give up  > Uwe Don't loose heart...

Ok I will not (and it seems I can count on «with a little help of my
friends 😉)

> (defun copy-to-register--no-properties (orig-fun &rest args)   "Remove
> properties of region when calling `copy-to-register'."   (let
> ((filter-buffer-substring-function (lambda (beg end   &optional
> delete) 					    (if delete
> (delete-and-extract-region
> beg end)
> (buffer-substring-no-properties
> beg end)))))     (apply orig-fun args))) (advice-add 'copy-to-register
> :around #'copy-to-register--no-properties) Works for me, but the way I
> understand the manual, instead of advising a function,
> better-registers.el should just modify
> `filter-buffer-substring-function' for its needs.



> Hope this helps.



It does very much so, that solution would not have occurred to me. So thanks for 
the code.


BTW, I found it strange that «vanilla» Emacs does not provide saving
registers, but then this is a question of demand, and it seems only a
few users use that functionality.

Uwe 




-- 
I strongly condemn Putin's war of aggression against the Ukraine.
I support to deliver weapons to Ukraine's military. 
I support the ban of Russia from SWIFT.
I support the EU membership of the Ukraine. 

[-- Attachment #2: smime.p7s --]
[-- Type: application/pkcs7-signature, Size: 5673 bytes --]

Re: [SOLVED]

[Yuri Khan]

On Tue, 26 Jul 2022 at 22:08, Uwe Brauer <oub@mat.ucm.es> wrote:

> BTW, I found it strange that «vanilla» Emacs does not provide saving
> registers, but then this is a question of demand, and it seems only a
> few users use that functionality.

I don’t remember who said it doesn’t but do we consider desktop.el
“vanilla” or some other flavor? My .emacs.desktop has a ‘(setq
register-alist '…)’ and it persists across Emacs sessions. (I have not
encountered unreadable properties in there, or maybe I did but did not
make the connection.)

Re: [SOLVED]

[Michael Heerdegen]

Yuri Khan <yuri.v.khan@gmail.com> writes:

> I don’t remember who said it doesn’t but do we consider desktop.el
> “vanilla” or some other flavor? My .emacs.desktop has a ‘(setq
> register-alist '…)’ and it persists across Emacs sessions. (I have not
> encountered unreadable properties in there, or maybe I did but did not
> make the connection.)

Seems it is silently stripping (all) properties when such a problem
appears - see `desktop--v2s'.

Michael.

Re: [SOLVED]

[Uwe Brauer]

[-- Attachment #1: Type: text/plain, Size: 1119 bytes --]

>>> "YK" == Yuri Khan <yuri.v.khan@gmail.com> writes:

> On Tue, 26 Jul 2022 at 22:08, Uwe Brauer <oub@mat.ucm.es> wrote:
>> BTW, I found it strange that «vanilla» Emacs does not provide saving
>> registers, but then this is a question of demand, and it seems only a
>> few users use that functionality.

> I don’t remember who said it doesn’t but do we consider desktop.el
> “vanilla” or some other flavor? 

Since desktop is part of Emacs it is vanilla.

> My .emacs.desktop has a ‘(setq
> register-alist '…)’ and it persists across Emacs sessions. (I have not
> encountered unreadable properties in there, or maybe I did but did not
> make the connection.)

Aha, thanks I did not know that, I really never used desktop that much, 
but can you use list-register and then edit the registers?
Ok I realized that list-register is not part of emacs vanilla neither.



-- 
I strongly condemn Putin's war of aggression against the Ukraine.
I support to deliver weapons to Ukraine's military. 
I support the ban of Russia from SWIFT.
I support the EU membership of the Ukraine. 

[-- Attachment #2: smime.p7s --]
[-- Type: application/pkcs7-signature, Size: 5673 bytes --]

Re: [SOLVED]

[Yuri Khan]

On Wed, 27 Jul 2022 at 17:51, Uwe Brauer <oub@mat.ucm.es> wrote:

> Since desktop is part of Emacs it is vanilla.

[…]

> Aha, thanks I did not know that, I really never used desktop that much,
> but can you use list-register and then edit the registers?
> Ok I realized that list-register is not part of emacs vanilla neither.

Is it not? Works for me and I do not remember doing anything for it to
work, and it lives in /usr/share/emacs/29.0.50/lisp/register.el.gz, so
I guess it’s also vanilla by your definition.

I cannot edit registers directly, but I can insert the text from a
register into a buffer, edit the text there, and copy it back to the
register, and it will be persisted the next time I restart Emacs.

Re: [SOLVED$

[Uwe Brauer]

[-- Attachment #1: Type: text/plain, Size: 1270 bytes --]

>>> "YK" == Yuri Khan <yuri.v.khan@gmail.com> writes:

> On Wed, 27 Jul 2022 at 17:51, Uwe Brauer <oub@mat.ucm.es> wrote:
>> Since desktop is part of Emacs it is vanilla.

> […$

>> Aha, thanks I did not know that, I really never used desktop that much,
>> but can you use list-register and then edit the registers?
>> Ok I realized that list-register is not part of emacs vanilla neither.

> Is it not? Works for me and I do not remember doing anything for it to
> work, and it lives in /usr/share/emacs/29.0.50/lisp/register.el.gz, so
> I guess it’s also vanilla by your definition.

> I cannot edit registers directly, but I can insert the text from a
> register into a buffer, edit the text there, and copy it back to the
> register, and it will be persisted the next time I restart Emacs.

May I suggest then list-register (found in the package system):
it lists registers and allows to edit them,

There is also register-list 
(remember Monty Python: 
«The People's Front of Judea»  vs «Judean People's Front» )



-- 
I strongly condemn Putin's war of aggression against the Ukraine.
I support to deliver weapons to Ukraine's military. 
I support the ban of Russia from SWIFT.
I support the EU membership of the Ukraine. 

[-- Attachment #2: smime.p7s --]
[-- Type: application/pkcs7-signature, Size: 5673 bytes --]

Re: [SOLVED]

[Uwe Brauer]

[-- Attachment #1: Type: text/plain, Size: 982 bytes --]

>>> "EB" == Emanuel Berg <incal@dataswamp.org> writes:

> Uwe Brauer wrote:
>> a simple describe-variable suggests to use 
>> 
>> (defun my-changelog-date-format (&optional time zone)
>> (format-time-string "%Y-%m-%d %H:%M"))
>> 
>> Which indeed worked

> What time zone is that?

None, 

The code in add-log reads

(defun add-log-iso8601-time-zone (&optional time zone)
  (declare (obsolete nil "26.1"))
  (format-time-string "%:::z" time zone))

(defvar add-log-iso8601-with-time-zone nil)

(defun add-log-iso8601-time-string (&optional time zone)
  (format-time-string
   (if add-log-iso8601-with-time-zone "%Y-%m-%d %:::z" "%Y-%m-%d") time zone))

Since I don't think I will ever use time zones, I did not bother to set
this right up.

-- 
I strongly condemn Putin's war of aggression against the Ukraine.
I support to deliver weapons to Ukraine's military. 
I support the ban of Russia from SWIFT.
I support the EU membership of the Ukraine. 

[-- Attachment #2: smime.p7s --]
[-- Type: application/pkcs7-signature, Size: 5673 bytes --]