bug#74267: 29.4; Doc string of `add-file-local-variable`

bug#74267: 29.4; Doc string of `add-file-local-variable`

[Drew Adams via Bug reports for GNU Emacs, the Swiss army knife of text editors]

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)

bug#74267: 29.4; Doc string of `add-file-local-variable`

[Eli Zaretskii]

> Date: Fri, 8 Nov 2024 21:25:01 +0000
> From:  Drew Adams via "Bug reports for GNU Emacs,
>  the Swiss army knife of text editors" <bug-gnu-emacs@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'.

The main problem is not the doc string, but the text of the user-error
message.

Thanks, fixed, and closing the bug.

bug#74267: 29.4; Doc string of `add-file-local-variable`

[Drew Adams via Bug reports for GNU Emacs, the Swiss army knife of text editors]

> The main problem is not the doc string, but the text of the user-error
> message.

The main problem, yes, probably.
The doc string and/or bug should perhaps (also)
refer to the other command,
`add-file-local-variable-prop-line'.

> Thanks, fixed, and closing the bug.

Thx.