bug#20754: checkdoc-current-buffer prints to stdout?!

bug#20754: checkdoc-current-buffer prints to stdout?!

[Paul Eggert]

[The following bug report was sent by Sebastian Wiesner to emacs-devel 
<http://lists.gnu.org/archive/html/emacs-devel/2015-06/msg00095.html>.]

Hello,

while debugging unit test failures in Flycheck, I accidentally discovered
checkdoc-current-buffer apparently prints messages to standard output in
Emacs 25.1 in noninteractive mode.

Would you please revert this change?

I can understand the motivation for this “feature”, but it's generally a
bad idea for an interactive function to print text to standard output
depending on an opaque global environment.  It also makes backwards
compatibility harder than it needs to be:  As things stand I have no choice
but to check the Emacs version to print Checkdoc Errors in a consistent way
across Emacs major versions, and that is somewhat ugly.

The purpose of this feature would also be served by a different entry
point—we have `ert-run-tests-interactively` and `ert-run-tests-batch`,
too.  If that is impossible please at least expose an option to turn this
feature off.

On a related topic, I'd have fixed this issue much faster, had this change
been mentioned in the NEWS.  Would you please be more strict about updating
NEWS for breaking changes such as this?

Sincerely,
Sebastian Wiesner

bug#20754: checkdoc-current-buffer prints to stdout?!

[Oleh Krehel]

Sebastian Wiesner <swiesner@lunaryorn.com> writes:

> while debugging unit test failures in Flycheck, I accidentally discovered
> checkdoc-current-buffer apparently prints messages to standard output in
> Emacs 25.1 in noninteractive mode.
>
> Would you please revert this change?

No, this change doesn't need to be reverted. It's useful for running
checkdoc in batch. And it does check for `noninteractive' before
printing. There's a bunch of workarounds that flycheck could use:

- bind `noninteractive'
- bind `inhibit-message'

> Would you please be more strict about updating
> NEWS for breaking changes such as this?

This isn't a breaking change. If you have any problem with checkdoc, the
usual procedure is to:

    git log --follow lisp/emacs-lisp/checkdoc.el

or the equivalent "lf" in magit.

Actually, I'd think that it would be beneficial for flycheck to be able
to run checkdoc in batch, since async can make things faster. But then,
I'm not really familiar with flycheck.

Oleh

bug#20754: checkdoc-current-buffer prints to stdout?!

[Sebastian Wiesner]

[-- Attachment #1: Type: text/plain, Size: 1832 bytes --]

2015-06-07 16:23 GMT+02:00 Oleh Krehel <ohwoeowho@gmail.com>:

> Sebastian Wiesner <swiesner@lunaryorn.com> writes:
>
> > while debugging unit test failures in Flycheck, I accidentally discovered
> > checkdoc-current-buffer apparently prints messages to standard output in
> > Emacs 25.1 in noninteractive mode.
> >
> > Would you please revert this change?
>
> No, this change doesn't need to be reverted. It's useful for running
> checkdoc in batch. And it does check for `noninteractive' before
> printing.


That is exactly _why_ I'd like to see this change reverted.  It introduces
output that is controlled by an entirely unrelated global variable.  YMMV,
but I don't think that this is good design at all.

> Would you please be more strict about updating
> > NEWS for breaking changes such as this?
>
> This isn't a breaking change.


It _did_ break Flycheck.

If you have any problem with checkdoc, the
> usual procedure is to:
>
>     git log --follow lisp/emacs-lisp/checkdoc.el


> or the equivalent "lf" in magit.
>

No offence meant, but why do you even bother with NEWS at all if that's
your general response to such issues?


> Actually, I'd think that it would be beneficial for flycheck to be able
> to run checkdoc in batch, since async can make things faster.


Flycheck has been successfully running checkdoc asynchronously in a
non-interactive batch session in batch since long before this change was
made.  This change didn't have any benefits at all for Flycheck, it only
made matters worse.

Why can't you just leave checkdoc-current-buffer as is, and introduce a new
entry point?

What works for ERT, can't be bad for checkdoc, and it means a lot less
trouble for anyone who's using checkdoc noninteractively, mostly because
they can explicitly opt in to this new behaviour instead of being forced
into it.

[-- Attachment #2: Type: text/html, Size: 3277 bytes --]

bug#20754: checkdoc-current-buffer prints to stdout?!

[Glenn Morris]

Oleh Krehel wrote:

>> Would you please be more strict about updating
>> NEWS for breaking changes such as this?
>
> This isn't a breaking change.

NEWS should be updated for any change that may affect users,
"breaking" or otherwise.
When in doubt, make a NEWS entry.
It can always be removed on review before the next release.

bug#20754: checkdoc-current-buffer prints to stdout?!

[Oleh Krehel]

Glenn Morris <rgm@gnu.org> writes:

> Oleh Krehel wrote:
>
>>> Would you please be more strict about updating
>>> NEWS for breaking changes such as this?
>>
>> This isn't a breaking change.
>
> NEWS should be updated for any change that may affect users,
> "breaking" or otherwise.
> When in doubt, make a NEWS entry.
> It can always be removed on review before the next release.

Should I make the entry now?

    ** New functionality in `checkdoc-current-buffer'
    When called in -batch, print the warnings to the standard output.

Or introduce a new function `checkdoc-file', akin to
`byte-compile-file', that would only print the warnings to the standard
output?

bug#20754: checkdoc-current-buffer prints to stdout?!

[Oleh Krehel]

Sebastian Wiesner <swiesner@lunaryorn.com> writes:

> Why can't you just leave checkdoc-current-buffer as is, and introduce
> a new entry point?

Done. Also added a NEWS entry.

bug#20754: checkdoc-current-buffer prints to stdout?!

[Sebastian Wiesner]

[-- Attachment #1: Type: text/plain, Size: 400 bytes --]

2015-06-08 8:35 GMT+02:00 Oleh Krehel <ohwoeowho@gmail.com>:

> Sebastian Wiesner <swiesner@lunaryorn.com> writes:
>
> > Why can't you just leave checkdoc-current-buffer as is, and introduce
> > a new entry point?
>
> Done. Also added a NEWS entry.
>

Thank you very much!  That's a nice change which benefits Flycheck, and
will make checkdoc easier as soon as Flycheck drops Emacs 24 compatibility.

[-- Attachment #2: Type: text/html, Size: 821 bytes --]

bug#20754: checkdoc-current-buffer prints to stdout?!

[Oleh Krehel]

Sebastian Wiesner <swiesner@lunaryorn.com> writes:

> 2015-06-08 8:35 GMT+02:00 Oleh Krehel <ohwoeowho@gmail.com>:
>
>     Sebastian Wiesner <swiesner@lunaryorn.com> writes:
>     
>     > Why can't you just leave checkdoc-current-buffer as is, and
>     introduce
>     > a new entry point?
>     
>     Done. Also added a NEWS entry.
>     
>
> Thank you very much! That's a nice change which benefits Flycheck, and
> will make checkdoc easier as soon as Flycheck drops Emacs 24
> compatibility.

You're welcome, marking as done.