21.4 Documentation Strings and Compilation

Functions and variables loaded from a byte-compiled file access their documentation strings dynamically from the file whenever needed. This saves space within Emacs, and makes loading faster because the documentation strings themselves need not be processed while loading the file. Actual access to the documentation strings becomes slower as a result, but normally not enough to bother users.

Dynamic access to documentation strings does have drawbacks:

• If you delete or move the compiled file after loading it, SXEmacs can no longer access the documentation strings for the functions and variables in the file.
• If you alter the compiled file (such as by compiling a new version), then further access to documentation strings in this file will give nonsense results. This will often show as documentation strings moved by a certain offset.

If your site installs SXEmacs following the usual procedures, these problems will never normally occur. Installing a new version uses a new directory with a different name; as long as the old version remains installed, its files will remain unmodified in the places where they are expected to be.

However, if you have built SXEmacs yourself and use it from the directory where you built it, you will experience this problem occasionally if you edit and recompile Lisp files. When it happens, you can cure the problem by reloading the file after recompiling it.

Versions of Emacs up to and including XEmacs 19.14 and FSF Emacs 19.28 do not support the dynamic docstrings feature, and so will not be able to load bytecode created by more recent Emacs versions. You can turn off the dynamic docstring feature by setting byte-compile-dynamic-docstrings to nil.

Once this is done, you can compile files that will load into older Emacs versions. You can do this globally, or for one source file by specifying a file-local binding for the variable. Here’s one way to do that:

-*-byte-compile-dynamic-docstrings: nil;-*-

Variable: byte-compile-dynamic-docstrings

If this is non-nil, the byte compiler generates compiled files that are set up for dynamic loading of documentation strings. Default: t.

The dynamic documentation string feature writes compiled files that use a special Lisp reader construct, ‘#@count’. This construct skips the next count characters. It also uses the ‘#$’ construct, which stands for “the name of this file, as a string.” It is best not to use these constructs in Lisp source files.