File: font-lock.el.html

Font Lock mode is a minor mode that causes your comments to be displayed in one face, strings in another, reserved words in another, and so on.

Comments will be displayed in font-lock-comment-face. Strings will be displayed in font-lock-string-face. Regexps are used to display selected patterns in other faces.

To make the text you type be fontified, use M-x font-lock-mode RET. When this minor mode is on, the faces of the current line are updated with every insertion or deletion.

To turn Font Lock mode on automatically, add this to your init file:

 (add-hook 'emacs-lisp-mode-hook #'turn-on-font-lock)

Or if you want to turn Font Lock mode on in many modes:

 (global-font-lock-mode t)

Fontification for a particular mode may be available in a number of levels of decoration. The higher the level, the more decoration, but the more time it takes to fontify. See the variable font-lock-maximum-decoration. Support modes for Font Lock mode can be used to speed up Font Lock mode. See font-lock-support-mode.

;; How Font Lock mode fontifies:

When Font Lock mode is turned on in a buffer, it (a) fontifies the entire buffer and (b) installs one of its fontification functions on one of the hook variables that are run by Emacs after every buffer change (i.e., an insertion or deletion). Fontification means the replacement of face text properties in a given region; Emacs displays text with these face text properties appropriately.

Fontification normally involves syntactic (i.e., strings and comments) and regexp (i.e., keywords and everything else) passes. There are actually three passes; (a) the syntactic keyword pass, (b) the syntactic pass and (c) the keyword pass. Confused?

The syntactic keyword pass places syntax-table text properties in the buffer according to the variable font-lock-syntactic-keywords. It is necessary because Emacs's syntax table is not powerful enough to describe all the different syntactic constructs required by the sort of people who decide that a single quote can be syntactic or not depending on the time of day.
(What sort of person could decide to overload the meaning of a quote?)
Obviously the syntactic keyword pass must occur before the syntactic pass.

The syntactic pass places face text properties in the buffer according to syntactic context, i.e., according to the buffer's syntax table and buffer text's syntax-table text properties. It involves using a syntax parsing function to determine the context of different parts of a region of text. A syntax parsing function is necessary because generally strings and/or comments can span lines, and so the context of a given region is not necessarily apparent from the content of that region. Because the keyword pass only works within a given region, it is not generally appropriate for syntactic fontification. This is the first fontification pass that makes changes visible to the user; it fontifies strings and comments.

The keyword pass places face text properties in the buffer according to the variable font-lock-keywords. It involves searching for given regexps
(or calling given search functions) within the given region. This is the
second fontification pass that makes changes visible to the user; it fontifies language reserved words, etc.

Oh, and the answer is, "Yes, obviously just about everything should be done in a single syntactic pass, but the only syntactic parser available
understands only strings and comments." Perhaps one day someone will write
some syntactic parsers for common languages and a son-of-font-lock.el could use them rather then relying so heavily on the keyword (regexp) pass.

;; How Font Lock mode supports modes or is supported by modes:

Modes that support Font Lock mode do so by defining one or more variables whose values specify the fontification. Font Lock mode knows of these variable names from the buffer local variable font-lock-defaults.
(Font Lock mode is set up via (a) where a mode's patterns are
distributed with the mode's package library, and (b) where a mode's patterns are distributed with font-lock.el itself. An example of (a) is Pascal mode, an example of (b) is Lisp mode. Normally, the mechanism is
(a); (b) is used where it is not clear which package library should contain
the pattern definitions.) Font Lock mode chooses which variable to use for
fontification based on font-lock-maximum-decoration.

Font Lock mode fontification behavior can be modified in a number of ways. See the below comments and the comments distributed throughout this file.

;; Constructing patterns:

See the documentation for the variable font-lock-keywords.

Efficient regexps for use as MATCHERs for font-lock-keywords and font-lock-syntactic-keywords can be generated via the function regexp-opt.

;; Adding patterns for modes that already support Font Lock:

Though Font Lock highlighting patterns already exist for many modes, it's likely there's something that you want fontified that currently isn't, even at the maximum fontification level. You can add highlighting patterns via font-lock-add-keywords. For example, say in some C header file you #define the token and to expand to &&, etc., to make your C code almost readable. In your ~/.emacs there could be:

 (font-lock-add-keywords 'c-mode '("\\\\<\\\\(and\\\\|or\\\\|not\\\\)\\\\>"))

Some modes provide specific ways to modify patterns based on the values of other variables. For example, additional C types can be specified via the variable c-font-lock-extra-types.

;; Adding patterns for modes that do not support Font Lock:

Not all modes support Font Lock mode. If you (as a user of the mode) add patterns for a new mode, you must define in your ~/.emacs a variable or variables that specify regexp fontification. Then, you should indicate to Font Lock mode, via the mode hook setting font-lock-defaults, exactly what support is required. For example, say Foo mode should have the following regexps fontified case-sensitively, and comments and strings should not be fontified automagically. In your ~/.emacs there could be:

 (defvar foo-font-lock-keywords
   '(("\\\\<\\\\(one\\\\|two\\\\|three\\\\)\\\\>" . 'font-lock-keyword-face)
     ("\\\\<\\\\(four\\\\|five\\\\|six\\\\)\\\\>" . 'font-lock-type-face))
   "Default expressions to highlight in Foo mode.")

 (add-hook 'foo-mode-hook
  (lambda ()
    (setq-local font-lock-defaults
                '(foo-font-lock-keywords t))))

;; Adding Font Lock support for modes:

Of course, it would be better that the mode already supports Font Lock mode. The package author would do something similar to above. The mode must define at the top-level a variable or variables that specify regexp fontification. Then, the mode command should indicate to Font Lock mode, via font-lock-defaults, exactly what support is required. For example, say Bar mode should have the following regexps fontified case-insensitively, and comments and strings should be fontified automagically. In bar.el there could be:

 (defvar bar-font-lock-keywords
   '(("\\\\<\\\\(uno\\\\|due\\\\|tre\\\\)\\\\>" . 'font-lock-keyword-face)
     ("\\\\<\\\\(quattro\\\\|cinque\\\\|sei\\\\)\\\\>" . 'font-lock-type-face))
   "Default expressions to highlight in Bar mode.")

and within bar-mode there could be:

 (setq-local font-lock-defaults
             '(bar-font-lock-keywords nil t))

What is fontification for? You might say, "It's to make my code look nice."
I think it should be for adding information in the form of cues. These cues should provide you with enough information to both (a) distinguish between different items, and (b) identify the item meanings, without having to read the items and think about it. Therefore, fontification allows you to think less about, say, the structure of code, and more about, say, why the code doesn't work. Or maybe it allows you to think less and drift off to sleep.

So, here are my opinions/advice/guidelines:

- Highlight conceptual objects, such as function and variable names, and
  different objects types differently, i.e., (a) and (b) above, highlight
  function names differently to variable names.
- Keep the faces distinct from each other as far as possible.
  i.e., (a) above.
- Use the same face for the same conceptual object, across all modes.
  i.e., (b) above, all modes that have items that can be thought of as, say,
  keywords, should be highlighted with the same face, etc.
- Make the face attributes fit the concept as far as possible.
  i.e., function names might be a bold color such as blue, comments might
  be a bright color such as red, character strings might be brown, because,
  err, strings are brown (that was not the reason, please believe me).
- Don't use a non-nil OVERRIDE unless you have a good reason.
  Only use OVERRIDE for special things that are easy to define, such as the
  way ... quotes are treated in strings and comments in Emacs Lisp mode.
  Don't use it to, say, highlight keywords in commented out code or strings.
- Err, that's it.

Defined variables (46)

Defined functions (46)

Defined faces (28)