From: Memnon Anon <gegendosenfleisch@googlemail.com>
To: Memnon Anon <gegendosenfleisch@googlemail.com>
Cc: Markus Heller <hellerm2@gmail.com>, emacs-orgmode@gnu.org
Subject: Docstrings: Use of `C-u' (was: [OT] Passing universal argument to a function)
Date: Sun, 15 Aug 2010 01:41:21 +0200 [thread overview]
Message-ID: <87tymwreu6.fsf@mean.albasani.net> (raw)
In-Reply-To: <87bp978cz8.fsf@mean.albasani.net> (Memnon Anon's message of "Fri, 13 Aug 2010 05:12:42 +0200")
Memnon Anon <gegendosenfleisch@googlemail.com> 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
next prev parent reply other threads:[~2010-08-14 23:45 UTC|newest]
Thread overview: 9+ messages / expand[flat|nested] mbox.gz Atom feed top
2010-08-12 23:13 Bind C-u C-c C-x C-i to a key Markus Heller
2010-08-12 23:37 ` Andreas Burtzlaff
2010-08-13 3:12 ` [OT] Passing universal argument to a function (was: Bind C-u C-c C-x C-i to a key) Memnon Anon
2010-08-13 16:49 ` Markus Heller
2010-08-14 23:41 ` Memnon Anon [this message]
2010-08-16 18:54 ` Docstrings: Use of `C-u' Bastien
2010-08-16 19:01 ` Bastien
2010-08-13 7:09 ` Re: Bind C-u C-c C-x C-i to a key Bastien
2010-08-13 7:12 ` Bastien
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.orgmode.org/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=87tymwreu6.fsf@mean.albasani.net \
--to=gegendosenfleisch@googlemail.com \
--cc=emacs-orgmode@gnu.org \
--cc=hellerm2@gmail.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).