Basic Setup

Let us first explain how to use external editing on a well-configured machine, so we know the end we wish to attain. Then we will explain the means: how to configure the machine "well".

1. The End

To invoke an external editor on a text box, focus the text box and press C-i. Edit and save the file that comes up, and exit the editor. Conkeror then fills in the text box with the contents of the file.

2. The Means

First, you need to have the program conkeror-spawn-helper installed. Please read ConkerorSpawnHelper for details.

Conkeror has two user variables that control the behavior of the external editing commands.

2.1. editor_shell_command

This variable provides the normal means for configuring the editor to run. Its default value is the first of the following that has a value:

You can set this in a couple of places, e.g. try adding a line similar to the following to ~/.xsession or ~/.xinitrc

export EDITOR=emacsclient

The value of editor_shell_command is a string command line that will be modified as follows:

If you need more control than this, proceed to the next section.

2.2. run_external_editor_function

run_external_editor_function is a power toy, more complex than most users need. If you're just trying to get a basic external editor set up, see above, and don't mess with this variable. If you need more control, though, and know your js, read on...

This variable defaults to null. It overrides editor_shell_command when non-null. When it is non-null, it must be a coroutine function that invokes an editor. This function need not return a value. Its first parameter is the name of the file to open. It may also be passed the optional keyword parameters $line and $temporary. The value of $line gives the desired line number to jump to. When $temporary is true, it means that the user function should take care of deleting the file after the editor has closed. (Normally Conkeror deletes the temp file.)

The following example runs an editor as 'frobnicate -f <file> [-l <line>]':

run_external_editor_function = function (file) {
    keywords(arguments);

    var args = [null, "-f", file.path];
    if (arguments.$line) {
        args.push(["-l", arguments.$line]);
    }

    try {
        yield spawn_and_wait_for_process("frobnicate", args);
    } finally {
        if (arguments.$temporary) {
            try {
                file.remove(false);
            } catch (e) {}
        }
    }
};

3. Debugging

After closing editor, changes are not applied

Editors that fork and immediately exit cause this problem. For example, emacsclient with the -n switch. Make sure that your configured editor waits for completion before exiting.