bug#54128: 27.2; c-paragraph-* variables not sufficiently documented

[Alan Mackenzie]

Hello, John and Lars.

On Wed, Feb 23, 2022 at 16:01:59 +0000, John Hagerman wrote:
> [Sent manually because sending from Emacs didn't work.]


> Save this as file "comment.c" (*.c as C-mode is important):
> ---8<---
> // \details
> // I want the previous line to be untouched by c-fill-paragraph.
> --->8---

> Dribble file:
> comment.c<return><escape>q<escape>:(setq c-paragraph-separate "$\\|// 
> \\\\[a-z]+$")<return><escape>:(c-setup-paragraph-variables)<return><escape>q

> Summary of actions:
> + Read comment.c; C-mode is entered.
> + Move down one line and do c-fill-paragraph: the two lines are merged
> + Undo to revert to original two lines
> + Set c-paragraph-separate and update the C-mode variables
> + Do c-fill-paragraph again; this time the two lines are not merged

> There is nothing wrong with these actions!  The bug is only about the
> c-paragraph-* variable documentation.

> The Bug:
> The documentation for c-paragraph-separate and c-paragraph-start should
> describe the fact that they must begin with "$\\|" to work properly.

Forgive me, it is nearly 20 years since I constructed these variables;
why is the "$\\|" necessary?  What happened when you tried to construct
a regular expression without it?

> Details:
> // Upon entering C-mode, the value of c-paragraph-separate is "$".
> //
> // \details
> // I want the previous line to be untouched by c-fill-paragraph.
> // With c-paragraph-separate being "$", that line will be included
> // in a paragraph fill.  So: I want lines matching "^// \\\\[a-z]+$"
> // to stand alone.  I will modify c-paragraph-separate to get this.
> //
> // As always, fill-paragraph regexps do not start with "^".  After a
> // fair amount of work I found that custom c-paragraph-separate (and
> // c-paragraph-start) must begin with "$\\|" to work properly.  So I
> // do this:
> // (setq c-paragraph-separate "$\\|// \\\\[a-z]+$")
> // (c-setup-paragraph-variables)
> //
> // This bug report is about the fact that c-paragraph-separate and
> // c-paragraph-start must begin with "$\\|".  Ideally that would be
> // fixed.  But at the least this fact should be described in the
> // variables' documentation.


> In GNU Emacs 27.2 (build 1, x86_64-pc-linux-gnu, GTK+ Version 3.22.30, cairo 
> version 1.15.12)
>  of 2021-06-11 built on depbldcs73
> Windowing system distributor 'TigerVNC', version 11.0.11400000
> System Description: CentOS Linux 7 (Core)

-- 
Alan Mackenzie (Nuremberg, Germany).