bug#13731: 24.3.50; C-h N -- Outline navigation Fails

["Drew Adams" <drew.adams@oracle.com>]

> > outline-regexp is customizable, and its default value had gotten
> > changed in my customization settings at some point.  Would be
> > wise for C-h N  to set outline-regexp appropriately -- perhaps
> > via a file-local variable in the News file?
> 
> The docstring of `outline-regexp' says
>   The recommended way to set this is with a Local Variables: list in
>   the file it applies to.
> So I'd suggest to simply follow the recommendation here.

I'd say that that is a doc bug.

This is a _user option_.  The recommended way to set (i.e., customize) it should
be to use Customize.  Users do not necessarily even have a particular file
within which using Local Variables would make sense for this.

I suggest we remove that recommendation from the doc string.  Or we change the
status of this variable from a defcustom to a defvar.

If you want to say that you recommend that Lisp code that sets the value use
Local Variables, that would presumably be OK as far as it goes.  But the general
idea is that Lisp code should not trample on user option values.

And note that nothing else in file outline.el mentions the fact that
`outline-regexp' is likely to be buffer-local.

It seems that that statement has been in the doc string from the beginning - at
least as far back as Emacs 20.  I still think it is misguided.

The same recommendation appears in (emacs) `Outline Format':

  You can customize the criterion for distinguishing heading lines by
  setting the variable `outline-regexp'.  (The recommended ways to do
  this are in a major mode function or with a file local variable.)  Any
  line whose beginning has a match for this regexp is considered a
  heading line.  Matches that start within a line (not at the left
  margin) do not count.

That hardly sounds like the kind of user customization of a defcustom that Emacs
recommends in general.  Sounds like something to be recommended for a defvar
value instead.

Just one opinion.