16.4 Mode Settings in Embedded Mode

The mode settings can be changed while Calc is in embedded mode, but by default they will revert to their original values when embedded mode is ended. However, the modes saved when the mode-recording mode is Save (see below) and the modes in effect when the m e (calc-embedded-preserve-modes) command is given will be preserved when embedded mode is ended.

Embedded mode has a rather complicated mechanism for handling mode settings in Embedded formulas. It is possible to put annotations in the file that specify mode settings either global to the entire file or local to a particular formula or formulas. In the latter case, different modes can be specified for use when a formula is the enabled Embedded mode formula.

When you give any mode-setting command, like m f (for Fraction mode) or d s (for scientific notation), Embedded mode adds a line like the following one to the file just before the opening delimiter of the formula.

% [calc-mode: fractions: t]
% [calc-mode: float-format: (sci 0)]

When Calc interprets an embedded formula, it scans the text before the formula for mode-setting annotations like these and sets the Calc buffer to match these modes. Modes not explicitly described in the file are not changed. Calc scans all the way to the top of the file, or up to a line of the form

% [calc-defaults]

which you can insert at strategic places in the file if this backward scan is getting too slow, or just to provide a barrier between one “zone” of mode settings and another.

If the file contains several annotations for the same mode, the closest one before the formula is used. Annotations after the formula are never used (except for global annotations, described below).

The scan does not look for the leading ‘% ’, only for the square brackets and the text they enclose. In fact, the leading characters are different for different major modes. You can edit the mode annotations to a style that works better in context if you wish. See Customizing Embedded Mode, to see how to change the style that Calc uses when it generates the annotations. You can write mode annotations into the file yourself if you know the syntax; the easiest way to find the syntax for a given mode is to let Calc write the annotation for it once and see what it does.

If you give a mode-changing command for a mode that already has a suitable annotation just above the current formula, Calc will modify that annotation rather than generating a new, conflicting one.

Mode annotations have three parts, separated by colons. (Spaces after the colons are optional.) The first identifies the kind of mode setting, the second is a name for the mode itself, and the third is the value in the form of a Lisp symbol, number, or list. Annotations with unrecognizable text in the first or second parts are ignored. The third part is not checked to make sure the value is of a valid type or range; if you write an annotation by hand, be sure to give a proper value or results will be unpredictable. Mode-setting annotations are case-sensitive.

While Embedded mode is enabled, the word Local appears in the mode line. This is to show that mode setting commands generate annotations that are “local” to the current formula or set of formulas. The m R (calc-mode-record-mode) command causes Calc to generate different kinds of annotations. Pressing m R repeatedly cycles through the possible modes.

LocEdit and LocPerm modes generate annotations that look like this, respectively:

% [calc-edit-mode: float-format: (sci 0)]
% [calc-perm-mode: float-format: (sci 5)]

The first kind of annotation will be used only while a formula is enabled in Embedded mode. The second kind will be used only when the formula is not enabled. (Whether the formula is “active” or not, i.e., whether Calc has seen this formula yet, is not relevant here.)

Global mode generates an annotation like this at the end of the file:

% [calc-global-mode: fractions t]

Global mode annotations affect all formulas throughout the file, and may appear anywhere in the file. This allows you to tuck your mode annotations somewhere out of the way, say, on a new page of the file, as long as those mode settings are suitable for all formulas in the file.

Enabling a formula with C-x * e causes a fresh scan for local mode annotations; you will have to use this after adding annotations above a formula by hand to get the formula to notice them. Updating a formula with C-x * u will also re-scan the local modes, but global modes are only re-scanned by C-x * a.

Another way that modes can get out of date is if you add a local mode annotation to a formula that has another formula after it. In this example, we have used the d s command while the first of the two embedded formulas is active. But the second formula has not changed its style to match, even though by the rules of reading annotations the ‘(sci 0)’ applies to it, too.

% [calc-mode: float-format: (sci 0)]
1.23e2

456.

We would have to go down to the other formula and press C-x * u on it in order to get it to notice the new annotation.

Two more mode-recording modes selectable by m R are available which are also available outside of Embedded mode. (see General Mode Commands.) They are Save, in which mode settings are recorded permanently in your Calc init file (the file given by the variable calc-settings-file, typically ~/.emacs.d/calc.el) rather than by annotating the current document, and no-recording mode (where there is no symbol like Save or Local in the mode line), in which mode-changing commands do not leave any annotations at all.

When Embedded mode is not enabled, mode-recording modes except for Save have no effect.