Next: , Previous: Compilation Functions, Up: Byte Compilation

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:

These problems normally occur only if you build Emacs yourself and use it from the directory where you built it, and you happen to edit and/or recompile the Lisp source files. They can be easily cured by reloading each file after recompiling it.

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.

You can disable the dynamic documentation string 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;-*-
— User Option: 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.