bug#18207: erc-truncate-buffer-on-save: misleading variable name and docstring

bug#18207: erc-truncate-buffer-on-save: misleading variable name and docstring

[Ivan Shmakov]

Package:  emacs
Severity: minor

	The docstring for erc-truncate-buffer-on-save reads:

Truncate any ERC (channel, query, server) buffer when it is saved.

	This is somewhat misleading, as there’re also erc-truncate
	module, and, in particular, – the erc-truncate-buffer function,
	which are used to truncate buffer /to a given size/ (see
	erc-max-buffer-size.)  On the contrary, this variable, when
	non-nil, forces the buffer to be /completely erased,/ as per the
	following lisp/erc/erc-log.el fragment:

   434		      (if (and erc-truncate-buffer-on-save
   435			       (called-interactively-p 'interactive))
   436			  (progn
   437			    (let ((inhibit-read-only t)) (erase-buffer))
   438			    (move-marker erc-last-saved-position (point-max))
   439			    (erc-display-prompt))

	I believe that this behavior should be made clear in the
	documentation, like:

Erase ERC (channel, query, server) buffers when one is saved.

This function uses `erase-buffer' and has nothing to do with the
`erc-truncate-buffer' function.  In order to keep ERC buffer sizes
within a specific limit, you may set `erc-max-buffer-size' and use
`erc-truncate-mode' instead.

	It also makes sense to rename this variable (leaving a
	compatibility alias.)

-- 
FSF associate member #7257  http://boycottsystemd.org/  … 3013 B6A0 230E 334A

bug#18207: erc-truncate-buffer-on-save: misleading variable name and docstring

[Lars Ingebrigtsen]

Ivan Shmakov <ivan@siamics.net> writes:

> Package:  emacs
> Severity: minor
>
> 	The docstring for erc-truncate-buffer-on-save reads:
>
> Truncate any ERC (channel, query, server) buffer when it is saved.
>
> 	This is somewhat misleading, as there’re also erc-truncate
> 	module, and, in particular, – the erc-truncate-buffer function,
> 	which are used to truncate buffer /to a given size/ (see
> 	erc-max-buffer-size.)  On the contrary, this variable, when
> 	non-nil, forces the buffer to be /completely erased,/ as per the
> 	following lisp/erc/erc-log.el fragment:
>
>    434		      (if (and erc-truncate-buffer-on-save
>    435			       (called-interactively-p 'interactive))
>    436			  (progn
>    437			    (let ((inhibit-read-only t)) (erase-buffer))
>    438			    (move-marker erc-last-saved-position (point-max))
>    439			    (erc-display-prompt))
>
> 	I believe that this behavior should be made clear in the
> 	documentation, like:
>
> Erase ERC (channel, query, server) buffers when one is saved.
>
> This function uses `erase-buffer' and has nothing to do with the
> `erc-truncate-buffer' function.  In order to keep ERC buffer sizes
> within a specific limit, you may set `erc-max-buffer-size' and use
> `erc-truncate-mode' instead.

Can you send a patch for this change?

> 	It also makes sense to rename this variable (leaving a
> 	compatibility alias.)

I don't think that renaming the variable is worth it.

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

bug#18207: erc-truncate-buffer-on-save: misleading variable name and docstring

[Lars Ingebrigtsen]

Ivan Shmakov <ivan@siamics.net> writes:

> 	The docstring for erc-truncate-buffer-on-save reads:
>
> Truncate any ERC (channel, query, server) buffer when it is saved.
>
> 	This is somewhat misleading, as there’re also erc-truncate
> 	module, and, in particular, – the erc-truncate-buffer function,
> 	which are used to truncate buffer /to a given size/ (see
> 	erc-max-buffer-size.)  On the contrary, this variable, when
> 	non-nil, forces the buffer to be /completely erased,/ as per the
> 	following lisp/erc/erc-log.el fragment:
>
>    434		      (if (and erc-truncate-buffer-on-save
>    435			       (called-interactively-p 'interactive))
>    436			  (progn
>    437			    (let ((inhibit-read-only t)) (erase-buffer))
>    438			    (move-marker erc-last-saved-position (point-max))
>    439			    (erc-display-prompt))
>
> 	I believe that this behavior should be made clear in the
> 	documentation, like:
>
> Erase ERC (channel, query, server) buffers when one is saved.

I've now made a similar change to Emacs 27.1.

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