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

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

[John Hagerman via Bug reports for GNU Emacs, the Swiss army knife of text editors]

[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:
\x06comment.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.

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)

Recent messages:
For information about GNU Emacs and the GNU system, type C-h C-a.

Configured using:
 'configure --prefix=/depot/Emacs/emacs-27.2 --with-xpm=ifavailable
 --with-gif=ifavailable --with-gnutls=ifavailable --with-mailutils
 --with-cairo'

Configured features:
JPEG TIFF PNG RSVG CAIRO SOUND DBUS GSETTINGS GLIB NOTIFY INOTIFY ACL
LIBSELINUX LIBXML2 FREETYPE HARFBUZZ LIBOTF ZLIB TOOLKIT_SCROLL_BARS
GTK3 X11 XDBE XIM MODULES THREADS PDUMPER GMP

Important settings:
  value of $LC_ALL: C
  value of $LC_COLLATE: en_US.UTF-8
  value of $LC_CTYPE: en_US.UTF-8
  value of $LC_MESSAGES: en_US.UTF-8
  value of $LC_MONETARY: en_US.UTF-8
  value of $LC_NUMERIC: en_US.UTF-8
  value of $LC_TIME: en_US.UTF-8
  value of $LANG: en_US.UTF-8
  locale-coding-system: nil

Major mode: C/*l

Minor modes in effect:
  tooltip-mode: t
  global-eldoc-mode: t
  electric-indent-mode: t
  mouse-wheel-mode: t
  tool-bar-mode: t
  menu-bar-mode: t
  file-name-shadow-mode: t
  global-font-lock-mode: t
  font-lock-mode: t
  blink-cursor-mode: t
  auto-composition-mode: t
  auto-encryption-mode: t
  auto-compression-mode: t
  line-number-mode: t
  transient-mark-mode: t
  abbrev-mode: t

Load-path shadows:
None found.

Features:
(shadow sort mail-extr emacsbug message rmc puny dired dired-loaddefs
format-spec rfc822 mml mml-sec password-cache epa derived epg epg-config
gnus-util rmail rmail-loaddefs text-property-search time-date subr-x seq
byte-opt gv bytecomp byte-compile cconv mm-decode mm-bodies mm-encode
mail-parse rfc2231 mailabbrev gmm-utils mailheader sendmail rfc2047
rfc2045 ietf-drums mm-util mail-prsvr mail-utils cc-mode cc-fonts
easymenu cc-guess cc-menus cc-cmds cc-styles cc-align cc-engine cc-vars
cc-defs cl-loaddefs cl-lib tooltip eldoc electric uniquify ediff-hook
vc-hooks lisp-float-type mwheel term/x-win x-win term/common-win x-dnd
tool-bar dnd fontset image regexp-opt fringe tabulated-list replace
newcomment text-mode elisp-mode lisp-mode prog-mode register page
tab-bar menu-bar rfn-eshadow isearch timer select scroll-bar mouse
jit-lock font-lock syntax facemenu font-core term/tty-colors frame
minibuffer cl-generic cham georgian utf-8-lang misc-lang vietnamese
tibetan thai tai-viet lao korean japanese eucjp-ms cp51932 hebrew greek
romanian slovak czech european ethiopic indian cyrillic chinese
composite charscript charprop case-table epa-hook jka-cmpr-hook help
simple abbrev obarray cl-preloaded nadvice loaddefs button faces
cus-face macroexp files text-properties overlay sha1 md5 base64 format
env code-pages mule custom widget hashtable-print-readable backquote
threads dbusbind inotify dynamic-setting system-font-setting
font-render-setting cairo move-toolbar gtk x-toolkit x multi-tty
make-network-process emacs)

Memory information:
((conses 16 71165 12625)
 (symbols 48 8457 1)
 (strings 32 22858 3926)
 (string-bytes 1 841254)
 (vectors 16 12753)
 (vector-slots 8 163125 8052)
 (floats 8 20 35)
 (intervals 56 1470 2084)
 (buffers 1000 12)
 (heap 1024 13164 1341))

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

[Lars Ingebrigtsen]

John Hagerman <John.Hagerman@synopsys.com> writes:

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

Alan added to the CCs; perhaps he has some comments.

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

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:
> \x06comment.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).