Subject: 29.4; Doc string of `add-file-local-variable`
From: Drew Adams <[email-masked]>
To: "[email-masked]" <[email-masked]>
Date: Fri, 8 Nov 2024 21:25:01 +0000
List-Id: <debbugs-submit.debbugs.gnu.org>

The doc string doesn't make clear that it adds the variable
at the end of the file, and not on the first line (as a cookie).  This
is important in the case of a variable, such as `lexical-binding', that
must be added to the first line.

See, for example, this question:

https://emacs.stackexchange.com/q/82549/105

The user tried `M-x add-file-local-variable' and didn't understand the
error message, especially because point was at bob:

user-error: The 'lexical-binding' variable must be set at the start of the file

The Emacs manual, node Specifying File Variables makes everything clear.
But please clarify the doc string of `add-file-local-variable'.

In GNU Emacs 29.4 (build 2, x86_64-w64-mingw32) of 2024-07-05 built on
 AVALON
Windowing system distributor 'Microsoft Corp.', version 10.0.19045
System Description: Microsoft Windows 10 Pro (v10.0.2009.19045.5011)

Configured using:
 'configure --with-modules --without-dbus --with-native-compilation=aot
 --without-compress-install --with-sqlite3 --with-tree-sitter
 CFLAGS=-O2'

Configured features:
ACL GIF GMP GNUTLS HARFBUZZ JPEG JSON LCMS2 LIBXML2 MODULES NATIVE_COMP
NOTIFY W32NOTIFY PDUMPER PNG RSVG SOUND SQLITE3 THREADS TIFF
TOOLKIT_SCROLL_BARS TREE_SITTER WEBP XPM ZLIB

(NATIVE_COMP present but libgccjit not available)