From mboxrd@z Thu Jan 1 00:00:00 1970 From: Memnon Anon Subject: Docstrings: Use of `C-u' (was: [OT] Passing universal argument to a function) Date: Sun, 15 Aug 2010 01:41:21 +0200 Message-ID: <87tymwreu6.fsf@mean.albasani.net> References: <0vhbizzap7.fsf@gmail.com> <87ocd71jz6.fsf@gmx.net> <87bp978cz8.fsf@mean.albasani.net> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Return-path: Received: from [140.186.70.92] (port=55816 helo=eggs.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1OkQQH-0003HV-PC for emacs-orgmode@gnu.org; Sat, 14 Aug 2010 19:45:58 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.69) (envelope-from ) id 1OkQQG-0004Av-7z for emacs-orgmode@gnu.org; Sat, 14 Aug 2010 19:45:57 -0400 Received: from mail-ey0-f169.google.com ([209.85.215.169]:36632) by eggs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1OkQQF-0004Ai-VN for emacs-orgmode@gnu.org; Sat, 14 Aug 2010 19:45:56 -0400 Received: by eyg7 with SMTP id 7so972968eyg.0 for ; Sat, 14 Aug 2010 16:45:55 -0700 (PDT) In-Reply-To: <87bp978cz8.fsf@mean.albasani.net> (Memnon Anon's message of "Fri, 13 Aug 2010 05:12:42 +0200") List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org Errors-To: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org To: Memnon Anon Cc: Markus Heller , emacs-orgmode@gnu.org Memnon Anon 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