Document how to specify fallback modes

* doc/emacs/custom.texi (Specifying File Variables): Document
fallback mode order.

1 files changed, 25 insertions, 0 deletions

diff --git a/doc/emacs/custom.texi b/doc/emacs/custom.texi
index a3c9c7c206a..63e3bb5815c 100644
--- a/doc/emacs/custom.texi
+++ b/doc/emacs/custom.texi
@@ -1232,6 +1232,31 @@ Manual}.
 These four keywords are not really variables; setting them in any
 other context has no special meaning.
 
+  If you're editing a file across Emacs versions, and a new mode has
+been introduced to handle a file in a newer Emacs version, you can use
+several @code{mode} entries to use the new mode (called
+@code{my-new-mode}) in the new Emacs, and fall back to the old mode
+(called @code{my-old-mode}) in older Emacs versions.  If you're
+enabling the modes in the first line of the file, you should use this
+order:
+
+@example
+-*- mode: my-new; mode: my-old -*-
+@end example
+
+  Emacs will ignore undefined modes until it finds one it can use.
+However, if you're using a local variable block at the end up the
+file, the order is reversed:
+
+@example
+Local variables:
+mode: my-old
+mode: my-new
+@end example
+
+  Here Emacs will use the @emph{last} defined mode it finds.  (This is
+for historical reasons.)
+
   Do not use the @code{mode} keyword for minor modes.  To enable or
 disable a minor mode in a local variables list, use the @code{eval}
 keyword with a Lisp expression that runs the mode command