Unable to understand a line of Emacs Lisp

Question

The line is

function info() { 
    emacs -eval "(progn (setq Man-notify-method 'bully) (info \"$1\"))" 
}

I know from manuals that

Progn

progn is a special form in `C source code'.

Setq

setq is a special form in `C source code'. (setq SYM VAL SYM VAL ...)

Set each SYM to the value of its VAL. The symbols SYM are variables; they are literal (not evaluated). The values VAL are expressions; they are evaluated. Thus, (setq x (1+ y)) sets x' to the value of(1+ y)'. The second VAL is not computed until after the first SYM is set, and so on; each VAL can use the new value of variables set earlier in the setq'. The return value of thesetq' form is the value of the last VAL.

$1 seems to a reference to the first parameter after the command man which the user gives.

'bully seems to be a random variable.

Man-notify-method seems to be an action function which is run when man command is executed.

-eval seems to be an evalutian statemant which tells Emacs to run the statement which follows it.

However, I am not completely sure about the function.

I need to understand the function, since I want to bind a bash code of mine to the action function of man. Man-notify-method seems to be that action function, at least in Emacs.

How do you understand the line of Emacs Lisp?

Answer 1

The code you posted is a combination of shell script and elisp.

function info()
{
    emacs -eval "(progn (setq Man-notify-method 'bully) (info \"$1\"))"
}

This defines a shell script function named info. It takes 1 parameter, named $1. When you call this function (say, from another shell script), the value of the argument gets substituted in for $1, and it runs the commands specified in sequence. So, if you were to call it like this:

info("something")

The shell would execute this command:

emacs -eval "(progn (setq Man-notify-method 'bully) (info \"something\"))"

This invokes the emacs executable with two arguments, -eval and the command string, which contains embedded escaped quotes. This is asking emacs to invoke the following elisp code:

(progn (setq Man-notify-method 'bully) (info "something"))

progn is a special form. Special forms evaluate their arguments differently than normal function calls. You can find the documentation for progn in chapter 10.1 of the GNU Emacs Lisp Reference Manual. progn is a simple construct for executing a sequence of statements in order. The reason you may need to do this is for cases when you want to execute multiple statements, but the context that you're in only expects a single statement.

For example, an if statement takes 3 (or more) arguments: the condition to evaluate, the expression to evaluate if true, and the expression to evaluate if false. If more than 3 arguments are provided, the subsequent arguments are part of the else branch. If you want to use more than one statement in the true branch, you have to use progn:

(if condition
   (progn first-statement-if-true
          second-statement-if-true)
   first-statement-if-false
   second-statement-if-false
)

In this case, if condition is true, then first-statement-if-true and second-statement-if-true will be evaluated. Otherwise, first-statement-if-false and second-statement-if-false will be evaluated.

Thus, your code will simply evaluate the two statements (setq Man-notify-method 'bully) and (info "something") in order.

setq is another special form. See chapter 11.8 for its documentation. It simply sets a variable, named by the first parameter, to the value of the second parameter. The first parameter is not evaluated -- it is taken literally.

A value preceded by a single quote (such as 'bully) is not evaluated. See chapter 9.3 for details on quoting. Hence, (setq Man-notify-method) sets a variable named Man-notify-method to the literal token bully (which is a data type called a symbol, which is distinct from the string "bully").

I can't find the documentation on the info function online, you can get help on any given function in emacs by typing C-h f function-name. So, by typing C-h f info, I got this:

info is an interactive autoloaded Lisp function in `info'.
[Arg list not available until function definition is loaded.]

Enter Info, the documentation browser.
Optional argument FILE specifies the file to examine;
the default is the top-level directory of Info.
Called from a program, FILE may specify an Info node of the form
`(FILENAME)NODENAME'.

In interactive use, a prefix argument directs this command
to read a file name from the minibuffer.

The search path for Info files is in the variable `Info-directory-list'.
The top-level Info directory is made by combining all the files named `dir'
in all the directories in that path.

The online reference manual is very useful, and emacs' interactive help is also indispensible. If you don't understand what a particular function does, just C-h f it.