Customizing Embedded Mode
=========================

You can modify Embedded Mode's behavior by setting various Lisp
variables described here.  Use `M-x set-variable' or `M-x
edit-options' to adjust a variable on the fly, or put a suitable
`setq' statement in your `~/.emacs' file to set a variable
permanently.  (Another possibility would be to use a file-local
variable annotation at the end of the file; *Note Local Variables in
Files: (emacs)File Variables..)

While none of these variables will be buffer-local by default, you can
make any of them local to any embedded-mode buffer.  (Their values in
the `*Calculator*' buffer are never used.)

The `calc-embedded-open-formula' variable holds a regular expression
for the opening delimiter of a formula.  *Note Regular Expression
Search: (emacs)Regexp Search, to see how regular expressions work.
Basically, a regular expression is a pattern that Calc can search for.
A regular expression that considers blank lines, `$', and `$$' to be
opening delimiters is `"\\`\\|^\n\\|\\$\\$?"'.  Just in case the
meaning of this regular expression is not completely plain, let's go
through it in detail.

The surrounding `" "' marks quote the text between them as a Lisp
string.  If you left them off, `set-variable' or `edit-options' would
try to read the regular expression as a Lisp program.

The most obvious property of this regular expression is that it
contains indecently many backslashes.  There are actually two levels
of backslash usage going on here.  First, when Lisp reads a quoted
string, all pairs of characters beginning with a backslash are
interpreted as special characters.  Here, `\n' changes to a new-line
character, and `\\' changes to a single backslash.  So the actual
regular expression seen by Calc is `\`\|^ (newline) \|\$\$?'.

Regular expressions also consider pairs beginning with backslash to
have special meanings.  Sometimes the backslash is used to quote a
character that otherwise would have a special meaning in a regular
expression, like `$', which normally means "end-of-line," or `?',
which means that the preceding item is optional.  So `\$\$?' matches
either one or two dollar signs.

The other codes in this regular expression are `^', which matches
"beginning-of-line," `\|', which means "or," and `\`', which matches
"beginning-of-buffer."  So the whole pattern means that a formula
begins at the beginning of the buffer, or on a newline that occurs at
the beginning of a line (i.e., a blank line), or at one or two dollar
signs.

The default value of `calc-embedded-open-formula' looks just like this
example, with several more alternatives added on to recognize various
other common kinds of delimiters.

By the way, the reason to use `^\n' rather than `^$' or `\n\n', which
also would appear to match blank lines, is that the former expression
actually "consumes" only one newline character as *part of* the
delimiter, whereas the latter expressions consume zero or two
newlines, respectively.  The former choice gives the most natural
behavior when Calc must operate on a whole formula including its
delimiters.

See the Emacs manual for complete details on regular expressions.  But
just for your convenience, here is a list of all characters which must
be quoted with backslash (like `\$') to avoid some special
interpretation: `. * + ? [ ] ^ $ \'.  (Note the backslash in this
list; for example, to match `\[' you must use `"\\\\\\["'.  An
exercise for the reader is to account for each of these six
backslashes!)

The `calc-embedded-close-formula' variable holds a regular expression
for the closing delimiter of a formula.  A closing regular expression
to match the above example would be `"\\'\\|\n$\\|\\$\\$?"'.  This is
almost the same as the other one, except it now uses `\''
("end-of-buffer") and `\n$' (newline occurring at end of line, yet
another way of describing a blank line that is more appropriate for
this case).

The `calc-embedded-open-word' and `calc-embedded-close-word' variables
are similar expressions used when you type `M-# w' instead of `M-# e'
to enable Embedded mode.

The `calc-embedded-open-plain' variable is a string which begins a
"plain" formula written in front of the formatted formula when `d p'
mode is turned on.  Note that this is an actual string, not a regular
expression, because Calc must be able to write this string into a
buffer as well as to recognize it.  The default string is `"%%% "'
(note the trailing space).

The `calc-embedded-close-plain' variable is a string which ends a
"plain" formula.  The default is `" %%%\n"'.  Without the trailing
newline here, the first line of a "big" mode formula that followed
might be shifted over with respect to the other lines.

The `calc-embedded-open-new-formula' variable is a string which is
inserted at the front of a new formula when you type `M-# f'.  Its
default value is `"\n\n"'.  If this string begins with a newline
character and the `M-# f' is typed at the beginning of a line, `M-# f'
will skip this first newline to avoid introducing unnecessary blank
lines in the file.

The `calc-embedded-close-new-formula' variable is the corresponding
string which is inserted at the end of a new formula.  Its default
value is also `"\n\n"'.  The final newline is omitted by
`M-# f' if typed at the end of a line.  (It follows that if
`M-# f' is typed on a blank line, both a leading opening
newline and a trailing closing newline are omitted.)

The `calc-embedded-announce-formula' variable is a regular expression
which is sure to be followed by an embedded formula.  The `M-# a'
command searches for this pattern as well as for `=>' and `:='
operators.  Note that `M-# a' will not activate just anything
surrounded by formula delimiters; after all, blank lines are
considered formula delimiters by default!  But if your language
includes a delimiter which can only occur actually in front of a
formula, you can take advantage of it here.  The default pattern is
`"%Embed\n\\(% .*\n\\)*"', which checks for `%Embed' followed by any
number of lines beginning with `%' and a space.  This last is
important to make Calc consider mode annotations part of the pattern,
so that the formula's opening delimiter really is sure to follow the
pattern.

The `calc-embedded-open-mode' variable is a string (not a regular
expression) which should precede a mode annotation.  Calc never scans
for this string; Calc always looks for the annotation itself.  But
this is the string that is inserted before the opening bracket when
Calc adds an annotation on its own.  The default is `"% "'.

The `calc-embedded-close-mode' variable is a string which follows a
mode annotation written by Calc.  Its default value is simply a
newline, `"\n"'.  If you change this, it is a good idea still to end
with a newline so that mode annotations will appear on lines by
themselves.