bug#9758: 24.0.90; Elisp doc strings and fill-paragraph on region

bug#9758: 24.0.90; Elisp doc strings and fill-paragraph on region

[Stephen Berman]

The doc string of fill-paragraph-function notes that it affects
fill-paragraph but not fill-region.  But fill-paragraph itself calls
fill-region, and one case where this asymmetry is problematic is Elisp
doc strings.  Typing `M-q' with point within a doc string in Emacs Lisp
mode calls lisp-fill-paragraph (via fill-paragraph-function) with
fill-column set to emacs-lisp-docstring-fill-column.  But selecting (and
highlighting) a region within a doc string calls fill-region, which uses
either the local, global or customized value of fill-column, which is
most likely different from emacs-lisp-docstring-fill-column.  In this
case, using `M-q' on a highlighted region of a doc string (say, several
paragraphs of a long doc string) produces an ill-formatted result.  (The
doc string of fill-paragraph-function says "it is often better to use
some other hook, such as `fill-forward-paragraph-function'," but I don't
see how that would help in this case.)

In GNU Emacs 24.0.90.6 (i686-suse-linux-gnu, GTK+ Version 2.22.1)
 of 2011-10-13 on escher
Windowing system distributor `The X.Org Foundation', version 11.0.10903000
configured using `configure  '--without-toolkit-scroll-bars' 'CFLAGS=-g''

bug#9758: 24.0.90; Elisp doc strings and fill-paragraph on region

[Lars Ingebrigtsen]

Stephen Berman <stephen.berman@gmx.net> writes:

> But selecting (and highlighting) a region within a doc string calls
> fill-region, which uses either the local, global or customized value
> of fill-column, which is most likely different from
> emacs-lisp-docstring-fill-column.

(This bug report unfortunately got no response at the time.)

The bug report is, in essence, that `fill-paragraph' uses
`fill-paragraph-function', while `fill-region' doesn't.

In practice that means that you get different filling in Emacs Lisp doc
strings are filled differently if you select a region and uses the `M-q'
command, or if you just use `M-q' without selecting a region.

I'm not quite sure whether this is a bug or not -- it's slightly odd
behaviour, but it is consistent, if you squint at it a bit.  That is,
`fill-region' is a non-DWIM, very predictable function, while
`fill-paragraph' is more intuitive.

I'm leaning towards this being intended behaviour, so I'm closing this
bug report.  If anybody feels strongly that this is something that
should somehow be changed, feel free to reopen it.

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