emacs-orgmode
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

[Orgmode] Docstrings: Use of `C-u' (was: [OT] Passing universal argument


From: Memnon Anon
Subject: [Orgmode] Docstrings: Use of `C-u' (was: [OT] Passing universal argument to a function)
Date: Sun, 15 Aug 2010 01:41:21 +0200
User-agent: Gnus/5.13 (Gnus v5.13) Emacs/23.2 (gnu/linux)

Memnon Anon <address@hidden> writes:

> I am confused.

[I prepared a long mail, but I deleted it all. I will try to keep it
short]

If one wants to bind a key to `C-u C-c C-x C-i', the easiest way is to
have a look at the docstring and try to figure out, how to call the
function in a lambda, i.e. an unnamed function, bound to the preferred
key. 
Right?

This person usually has a look at the docstring and tries to figure out
how the argument is interpreted by the function: Sure, it is *most of
the times* used as an interactive funtion, but binding a key (i.e. a
common task) to a function called with `C-u' via a lambda (= a non
interactive call) seems to be probable action. 
Right?

So, in orgmode, I see 'some' functions - usually called interactively -
which provide a docstring like this:

,----[ org-clock.el ]
| (defun 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 (\\[universal-argument]), offer a list of \
| recently clocked tasks to
| clock into.  When SELECT is \\[universal-argument] \\[universal-argument], \
| 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'."
`----

which say: use universal argument. 
But this seems - all by itself without looking at how the argument is
used in the function - uncomplete for a user who wants to call the
function non-interactively.

I found only one other example so far, which is different:
,----[ 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."
`----

Adding that the prefix argument will be interpretated as a *list of one*
integer like this -> '(4) seems great. This clarifies that the test
against the prefix argument is something like "(when (equal arg '(4))"
without looking at the code of the function itself.

Does this make any sense? 
Would adding the `'(4)' part to other docstrings be welcome?

=========
Info

Another point I am confused about:
,----[ (info "(org)Agenda commands") ]
| Remote editing
| ..............
| 
| `0-9'
|      Digit argument.  
`----

Okay, a number - as a Prefix, right? - gives a Digit argument.
But what does this really do? For some commands, it works as a repeater:
`5 n' in an agenda buffer moves down 5 lines. (This is not mentioned in
the manual. Should it be?)

But what does the Digit argument do for e.g. org-agenda-clock-out?

,----[ 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)))
`----

It takes an (optional) arg, but is it used anywhere?!
If there is no arg interpreted anywhere, why is it there?

I am *really* sorry if I waste your time on this, because it is clear to
you and should be to anyone else; but I don't get. 
And orgmode brought me into this stuff, so where else should I ask? ;)

Memnon "I should stick to latin!" Anon













reply via email to

[Prev in Thread] Current Thread [Next in Thread]