bug#45864: 27.1; hack-local-variables-hook is not documented in Emacs Manual

bug#45864: 27.1; hack-local-variables-hook is not documented in Emacs Manual

[Howard Melman]

I've been frustrated with a few packages that set
outline-regexp as a file local variable in a way I don't
prefer.  Since this is set after my major-mode hook is run I
didn't think I had a way to override these.  The Emacs
manual only describes how to affect this with the variable
enable-local-variables which isn't granular enough to fix
this. 

Today I learned about the hack-local-variables-hook which
allows me to correct these.  I'm surprised that it and
before-hack-local-variables-hook are not documented in the
Emacs Manual but are only mentioned in the Elisp Reference
Manual.  Unless I'm misunderstanding something they're meant
for users and not just for elisp programmers so they should
be in the Emacs Manual.

In GNU Emacs 27.1 (build 1, x86_64-apple-darwin19.5.0, Carbon Version 162 AppKit 1894.5)
of 2020-11-14 built on Traviss-Mac.local
Repository revision: 443027ae4946e227b8eb7754751eea62ab7f3386
Repository branch: HEAD
Windowing system distributor 'Apple Inc.', version 10.15.7
System Description:  Mac OS X 10.15.7

-- 

Howard

bug#45864: 27.1; hack-local-variables-hook is not documented in Emacs Manual

[Lars Ingebrigtsen]

Howard Melman <hmelman@gmail.com> writes:

> Today I learned about the hack-local-variables-hook which
> allows me to correct these.  I'm surprised that it and
> before-hack-local-variables-hook are not documented in the
> Emacs Manual but are only mentioned in the Elisp Reference
> Manual.  Unless I'm misunderstanding something they're meant
> for users and not just for elisp programmers so they should
> be in the Emacs Manual.

The doc string of the former variable says:

----
Major modes can use this to examine user-specified local variables
in order to initialize other data structure based on them.
----

So they are meant for people implementing major modes, which is why
they're in the lispref manual, and not the Emacs manual.  (Users can use
them, too, but that's not really their purpose.)

So I think it makes sense to keep the documentation as is, and I'm
closing this bug report.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#45864: 27.1; hack-local-variables-hook is not documented in Emacs Manual

[Howard Melman]

> On Jan 19, 2021, at 8:18 AM, Howard Melman <hmelman@gmail.com> wrote:
> 
> On Jan 19, 2021, at 1:22 AM, Lars Ingebrigtsen <larsi@gnus.org> wrote:
>> 
>> Howard Melman <hmelman@gmail.com> writes:
>> 
>>> Today I learned about the hack-local-variables-hook which
>>> allows me to correct these.  I'm surprised that it and
>>> before-hack-local-variables-hook are not documented in the
>>> Emacs Manual but are only mentioned in the Elisp Reference
>>> Manual.  Unless I'm misunderstanding something they're meant
>>> for users and not just for elisp programmers so they should
>>> be in the Emacs Manual.
>> 
>> The doc string of the former variable says:
>> 
>> ----
>> Major modes can use this to examine user-specified local variables
>> in order to initialize other data structure based on them.
>> ----
>> 
>> So they are meant for people implementing major modes, which is why
>> they're in the lispref manual, and not the Emacs manual.  (Users can use
>> them, too, but that's not really their purpose.)
> 
> Ok, so is there another way to address my issue.  Some packages set
> outline-regexp as a file local variable in their elisp source and I'd
> prefer a different value.  Since file local variables are set after
> the major mode hooks are run I didn't think there was a way for me to
> override the.  I know about enable-local-variables but that's about
> safety and not really granular enough for me to override an otherwise
> safe variable without having to get asked about them every time I
> visit the file.  I found out about this hook and it seems to be
> exactly what I want, it lets me override the file local variables set
> in the file.  Is there another way to do this?  If not, can this hook
> be exposed to users for this purpose?
> 
> Howard

bug#45864: 27.1; hack-local-variables-hook is not documented in Emacs Manual

[Lars Ingebrigtsen]

Howard Melman <hmelman@gmail.com> writes:

>>  I found out about this hook and it seems to be
>> exactly what I want, it lets me override the file local variables set
>> in the file.  Is there another way to do this?  If not, can this hook
>> be exposed to users for this purpose?

Users are free to use whatever parts of Emacs they want, so there's
nothing much to expose.  Things that we don't expect users to commonly
want to hack around with (because things are a bit more complicated) are
not documented in the Emacs manual, but in the Emacs Lisp manual.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no