16.3 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 this normally is not enough to bother users.

Dynamic access to documentation strings does have drawbacks:

• If you delete or move the compiled file after loading it, Emacs 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 probably give nonsense results.

If your site installs Emacs 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 Emacs 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.

You can turn off this feature at compile time by setting byte-compile-dynamic-docstrings to nil; this is useful mainly if you expect to change the file, and you want Emacs processes that have already loaded it to keep working when the file changes. You can do this globally, or for one source file by specifying a file-local binding for the variable. One way to do that is by adding this string to the file's first line:

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

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 usually best not to use these constructs in Lisp source files, since they are not designed to be clear to humans reading the file.