Re: fill-paragraph ill designed

[Tassilo Horn <tsdh@gnu.org>]

Andreas Röhler <andreas.roehler@online.de> writes:

>> So if there is an active region, `fill-paragraph' just calls
>> `fill-region', and then the `fill-paragraph-function' is irrelevant.
>
> Yeah, but that's unhappy. Where the global fill-paragraph should know
> from, what's needed in a special mode, what special modes want to do
> with strings?

Indeed, I had also expected that `fill-region' would call
`fill-paragraph-function' on each paragraph in the region which it
doesn't.  But its docstring says that modes might want to use some other
hook instead, e.g., `fill-forward-paragraph-function'.

,----[ C-h v fill-paragraph-function RET ]
| fill-paragraph-function is a variable defined in ‘fill.el’.
| Its value is message-fill-paragraph
| Local in buffer *unsent wide reply to Andreas Röhler*; global value is nil
| 
|   This variable may be risky if used as a file-local variable.
| 
| Documentation:
| Mode-specific function to fill a paragraph, or nil if there is none.
| If the function returns nil, then ‘fill-paragraph’ does its normal work.
| A value of t means explicitly "do nothing special".
| Note: This only affects ‘fill-paragraph’ and not ‘fill-region’
| nor ‘auto-fill-mode’, so it is often better to use some other hook,
| such as ‘fill-forward-paragraph-function’.
`----

That's its docstring:

,----[ C-h v nil RET ]
| fill-forward-paragraph-function is a variable defined in ‘fill.el’.
| Its value is forward-paragraph
| 
|   This variable may be risky if used as a file-local variable.
| 
| Documentation:
| Function to move over paragraphs used by the filling code.
| It is called with a single argument specifying the number of paragraphs to move.
| Just like ‘forward-paragraph’, it should return the number of paragraphs
| left to move.
`----

Well, that actually only speaks of moving over paragraphs, not about
filling while doing so.  But let's try it out anyway since I could also
use that in GNU AUCTeX.

AUCTeX has a custom `fill-paragraph-function' named
`LaTeX-fill-paragraph'.  In contrast to the normal `fill-paragraph', it
ensures that verbatim macros will never be wrapped, e.g., \verb|foo bar|
will always stay on one line which is very important.  A wrapped
verbatim macro is an error.

And indeed, when I mark multiple paragraphs and do M-q, I get normal
filling which also wrapps inside \verb stuff and thus breaks my LaTeX
code. :-(

Ok, so then I tried setting `fill-forward-paragraph-function'
buffer-locally to a new function:

--8<---------------cut here---------------start------------->8---
(defun LaTeX-fill-forward-paragraph (arg)
  (LaTeX-fill-paragraph)
  (forward-paragraph arg))
--8<---------------cut here---------------end--------------->8---

However, that doesn't change anything.  Or concretely, `fill-region'
first formats the paragraphs in the region as I'd like to have it using
`LaTeX-fill-paragraph' on each paragraph, but finally the (and ...) in
the condition

--8<---------------cut here---------------start------------->8---
	(if (and (>= (point) initial) (< (point) end))
	    (setq fill-pfx
		  (fill-region-as-paragraph (point) end justify nosqueeze))
	  (goto-char end))))
--8<---------------cut here---------------end--------------->8---

is true and thus `fill-region-as-paragraph' is called which messes up my
correctly filled region.

I can work around that by moving point out of the current paragraph
after filling:

--8<---------------cut here---------------start------------->8---
(defun LaTeX-fill-forward-paragraph (arg)
  (LaTeX-fill-paragraph)
  (let ((x (forward-paragraph arg)))
    (forward-char (if (> arg 0) 1 -1))
    x))
--8<---------------cut here---------------end--------------->8---

This seems to do the trick but is really not too obvious.

So now I'm curious, too.  What's the right way for a mode to define its
own filling rules?

Bye,
Tassilo