#pragma section-numbers on
<>
= 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".
== 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.
== 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.
=== 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.
=== run_external_editor_function ===
{{{#!wiki caution
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 [-l ]':
{{{
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) {}
}
}
};
}}}
== 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.
= 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.
== 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");
}}}
== 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, just override this function.
= View Source in External Editor =
Once your external editor is set up, it is easy to use it as your view-source method. Just do the following in your rc:
{{{
view_source_use_external_editor = true;
}}}