1. 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.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.

1.2. The Means

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

Conkeror has three user variables that control the behavior of the external editing commands:

1.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:

• The environment variable VISUAL.

• The environment variable EDITOR.

• "emacs"

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:

• a space is appended

• if a line number was provided internally, "+XX " will be appended, where XX is the number.

• a shell-quoted path to a temporary file is appended.

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

1.2.2. run_external_editor_function

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); // Conkeror magic adding Lisp-style "keyword" parameters to JS

    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) {}
        }
    }
};

1.2.3. view_source_use_external_editor

See below.

1.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.

2. File Names

Conkeror also makes it easy to customize the file names used for temp files during external editing. Setting a unique file extension, for example, allows you to easily configure your text editor to set particular modes for files sent to it by Conkeror. You can also customize the base names.

2.1. Customizing the Extension

The extension of the temp file is based on the MIME type of the content being edited. For normal text boxes, the MIME type is text/plain. The extension associated with this MIME type or any other for external editing can be customized via the MIME type table, external_editor_extension_overrides. Here is an example of how to set the extension of text/plain temp files to ".foo":

external_editor_extension_overrides.set("text/plain", "foo");

2.2. Customizing the Base Name

The base name of the temp files used in external editing is formatted by the function external_editor_make_base_filename. It takes two arguments, the element being edited, and the top-level content document in the buffer, and returns the base filename as a string. To customize the base name of temp files created by external editing, override this function.

3. View Source in External Editor

To view the HTML source of any page in your external editor, once it is set up, add the following to your rc file:

view_source_use_external_editor = true;