calc: Mode Settings in Embedded Mode
17.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. 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. (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.