bug#45412: File ... is large (... MiB), really open? (y)es or (n)o or (l)iterally

[Eli Zaretskii <eliz@gnu.org>]

> Cc: 45412@debbugs.gnu.org, Lars Ingebrigtsen <larsi@gnus.org>,
>  積丹尼 Dan Jacobson <jidanni@jidanni.org>
> Date: Sun, 11 Apr 2021 00:32:34 +0200
> From:  Daniel Martín via "Bug reports for GNU Emacs,
>  the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>
> 
> >>> Another approach could be to offer a C-h binding that opens a help
> >>> window that describes the possible options and briefly links to the
> >>> customization entry point that removes the prompt permanently.
> >>
> >> Yeah, that sounds like a good idea.
> >
> > I agree, this is really the best idea.
> 
> OK, I've implemented it in the attached patch.  Suggestions
> welcome.

Thanks, see below for some comments.

> +---
> +** When Emacs prompts before opening a large file, a new help window
> +has been added.  This help window describes the available options and
> +how to disable the prompt by customizing the
> +'large-file-warning-threshold' variable.

This should mention the C-h key which triggers the help display:
IMO that's the most important piece of information users should know
about the new feature.

NEWS is visited in Outline mode, so each entry should have a heading
line which is a complete sentence with a concise description of the
change.

> +
>  \f
>  * Editing Changes in Emacs 28.1
>  
> diff --git a/lisp/files.el b/lisp/files.el
> index 60d6034011..49224e4b1e 100644
> --- a/lisp/files.el
> +++ b/lisp/files.el
> @@ -2123,28 +2123,62 @@ out-of-memory-warning-percentage
>  
>  (declare-function x-popup-dialog "menu.c" (position contents &optional header))
>  
> +(defun files--ask-user-about-large-file-help (op-type size)
> +  "Show a buffer explaining the options to open large files in Emacs."
> +  (with-output-to-temp-buffer "*Help*"
> +    (with-current-buffer standard-output
> +      (insert
> +       (format
> +        "The file that you want to %s is large (%s).

I suggest to say here what is the threshold above which Emacs asks the
question (because users may wish to customize it, as mentioned below).

> +You can press ‘y‘ to open the file.

  Press 'y' to open the file.

And please also use our style of quoting in documentation and strings,
'like this'.

> +You can press ‘n‘ to abort.

This should explain what "abort" means in this case.

> +You can press ‘l‘ to open the file literally, which means that

Suggest to say "(the letter ell)" here, to avoid confusion with the
digit 1.

Also, the text says literally "open", but the function actually
accepts an argument that describes the operation, which could be
something else.

> +Emacs will open the file without doing any format or character code
> +conversion and in Fundamental mode, without loading any potentially
> +expensive feature.
             ^^^^^^^
"features", in plural.

> +You can customize the option ‘large-file-warning-threshold‘ to be
                                ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Quoting style again.  Please quote `like this' here, so that Emacs
creates a hyperlink to the variable's doc.

> +the file size, in bytes, from which Emacs will ask for
> +confirmation.  Set it to ‘nil‘ to never request

We don't quote nil and t in this context.

> +          (if use-dialog
> +              (setq choice (x-popup-dialog t `(,prompt
> +                                               ("Yes" . ?y)
> +                                               ("No" . ?n)
> +                                               ("Open literally" . ?l))))

A literal "Open" again.

Also, don't we want to add a Help option to the dialog?  If not, why
not?

> +            (while (null choice)
> +              (setq choice (read-char-choice
> +                            (concat prompt " (y)es, (n)o, (l)iterally, (?)")
> +                            '(?y ?Y ?n ?N ?l ?L ?? ?\C-h)))
> +              (when (memq choice '(?? ?\C-h))

Why only ? or C-h?  What about F1? what about the case that help-char
is something else?