Re: master ec9523a: Add a keybinding to the help menu to display manuals

Re: master ec9523a: Add a keybinding to the help menu to display manuals

[Stefan Kangas]

larsi@gnus.org (Lars Ingebrigtsen) writes:

> +*** New keybinding in 'help-for-help' to display a manual.
> +The 'R' keybinding after 'C-h C-h' will prompt for a manual name and
> +then display it.

Shouldn't this NEWS entry rather say something like:

* New keybinding 'C-h R' prompts for a manual display and displays it.

Testing the command, the completion is a bit unsatisfactory.  It doesn't
seem to prompt for a manual name, but a file name?  Or maybe it allows
both?  I see all of "gnus", "gnus.info" and "gnus.info.gz" in the
completion list, yet they all seem to lead to the same manual.  I also
see ".", ".." and a directory "emacs/".

Re: master ec9523a: Add a keybinding to the help menu to display manuals

[Stephen Berman]

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

On Wed, 14 Oct 2020 12:06:48 -0700 Stefan Kangas <stefankangas@gmail.com> wrote:

> larsi@gnus.org (Lars Ingebrigtsen) writes:
>
>> +*** New keybinding in 'help-for-help' to display a manual.
>> +The 'R' keybinding after 'C-h C-h' will prompt for a manual name and
>> +then display it.
>
> Shouldn't this NEWS entry rather say something like:
>
> * New keybinding 'C-h R' prompts for a manual display and displays it.
>
> Testing the command, the completion is a bit unsatisfactory.  It doesn't
> seem to prompt for a manual name, but a file name?  Or maybe it allows
> both?  I see all of "gnus", "gnus.info" and "gnus.info.gz" in the
> completion list, yet they all seem to lead to the same manual.  I also
> see ".", ".." and a directory "emacs/".
      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

These last three are due to this bit in Info-read-node-name-2:

	  ;; If the file name has no suffix or a standard suffix,
	  ;; include it.
	  (and (or (null (file-name-extension file))
               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
		   (string-match suffix file))

And it's even worse if Info-directory-list includes directories that
contain lots of extensionless files that aren't info files, such as, for
example, the AUCTeX package from GNU ELPA, which contains such files as
ChangeLog, COPYING, GNUmakefile, etc., all of which are listed in the
*Completions* buffer, and if you choose one of them, it gets visited in
Info mode, which throws the user-error: "No such node or anchor: Top".

An odd thing about Info-read-node-name-2 is that it explicitly removes
the empty string from Info-suffix-list but then in effect adds it back
by checking for extensionless files in the above code.  I checked the
info files installed on my system and all of them end in ".info" or
"info.gz" (in some cases followed by a dash and a number, indicating
split info subfiles, see below).  And also in the Emacs source all info
files under info/ end in ".info".  Are there known cases of
extensionless info files that do not correspond to a file ending in
".info" or ".info.gz" (or another compression suffix)?  If not, then
removing that bit of the code will prevent the current false positives.

In addition, Info-read-node-name-2 excludes subfiles of split info files
only where these are extensionless files ending in the regexp "-[0-9]+",
but this misses files which have the number before a compression
extension, of which my system has several, e.g. R-exts.info-3.gz.
However, in all cases on my system, split info files contain "info"
before "-[0-9]+", and if that's always the case, then the patch below
will make tab completion on info-display-manual (i.e. `C-h R') show all
info files without shwoing the .info extension and also excluding
numbered subfiles and false positives.  Granted this is still not the
manual name as shown in the top level Info directory but only the
extensionless file name, e.g. "eintr" instead of "Emacs Lisp Intro", but
at least it seems better than the status quo (if the assumption that all
info files include the ".info" extension is correct).

Steve Berman


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: Info-read-node-name-2 patch --]
[-- Type: text/x-patch, Size: 1588 bytes --]

diff --git a/lisp/info.el b/lisp/info.el
index 6dffb3993c..fb0de4d598 100644
--- a/lisp/info.el
+++ b/lisp/info.el
@@ -1830,21 +1830,16 @@ Info-read-node-name-2
       (when (file-directory-p dir)
 	(dolist (file (file-name-all-completions
 		       (file-name-nondirectory string) dir))
-	  ;; If the file name has no suffix or a standard suffix,
-	  ;; include it.
-	  (and (or (null (file-name-extension file))
-		   (string-match suffix file))
-	       ;; But exclude subfiles of split Info files.
-	       (not (string-match "-[0-9]+\\'" file))
+	  ;; Check if the file name has a standard suffix.
+	  (and (string-match suffix file)
+	       ;; Exclude subfiles of split Info files.
+	       (not (string-match "info-[0-9]+\\(\\..*\\)?\\'" file))
 	       ;; And exclude backup files.
 	       (not (string-match "~\\'" file))
-	       (push (if string-dir (concat string-dir file) file) names))
-	  ;; If the file name ends in a standard suffix,
-	  ;; add the unsuffixed name as a completion option.
-	  (when (string-match suffix file)
-	    (setq file (substring file 0 (match-beginning 0)))
-	    (push (if string-dir (concat string-dir file) file)
-		  names-sans-suffix)))))
+	       ;; Use the unsuffixed name as a completion option.
+	       (let ((file (substring file 0 (match-beginning 0))))
+		 (push (if string-dir (concat string-dir file) file)
+		       names-sans-suffix))))))
     ;; If there is just one file, don't duplicate it with suffixes,
     ;; so `Info-read-node-name-1' will be able to complete a single
     ;; candidate and to add the terminating ")".

Re: master ec9523a: Add a keybinding to the help menu to display manuals

[Stefan Monnier]

> files under info/ end in ".info".  Are there known cases of
> extensionless info files that do not correspond to a file ending in
> ".info" or ".info.gz" (or another compression suffix)?  If not, then
> removing that bit of the code will prevent the current false positives.

It used to be common to have Info files with names like `foo`, `foo-1`,
`foo-2`, ...  Splitting Info files has gotten out of fashion due to the
growing size of RAM, and the use of a `.info` extension has grown
a lot too.  Maybe we could start assuming that all those files nowadays
have a `.info` extension?


        Stefan

Re: master ec9523a: Add a keybinding to the help menu to display manuals

[Lars Ingebrigtsen]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

>> files under info/ end in ".info".  Are there known cases of
>> extensionless info files that do not correspond to a file ending in
>> ".info" or ".info.gz" (or another compression suffix)?  If not, then
>> removing that bit of the code will prevent the current false positives.
>
> It used to be common to have Info files with names like `foo`, `foo-1`,
> `foo-2`, ...  Splitting Info files has gotten out of fashion due to the
> growing size of RAM, and the use of a `.info` extension has grown
> a lot too.  Maybe we could start assuming that all those files nowadays
> have a `.info` extension?

I had a look in

/usr/share/info/

here, and it looks like they all have .info in their names.

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

Re: master ec9523a: Add a keybinding to the help menu to display manuals

[Stephen Berman]

On Thu, 15 Oct 2020 09:00:12 +0200 Lars Ingebrigtsen <larsi@gnus.org> wrote:

> Stefan Monnier <monnier@iro.umontreal.ca> writes:
>
>>> files under info/ end in ".info".  Are there known cases of
>>> extensionless info files that do not correspond to a file ending in
>>> ".info" or ".info.gz" (or another compression suffix)?  If not, then
>>> removing that bit of the code will prevent the current false positives.
>>
>> It used to be common to have Info files with names like `foo`, `foo-1`,
>> `foo-2`, ...  Splitting Info files has gotten out of fashion due to the
>> growing size of RAM, and the use of a `.info` extension has grown
>> a lot too.  Maybe we could start assuming that all those files nowadays
>> have a `.info` extension?
>
> I had a look in
>
> /usr/share/info/
>
> here, and it looks like they all have .info in their names.

Same here.  But as I was looking at this last night, I had a vague
recollection of having seen info files named just emacs, emacs-1,
emacs-2, etc., i.e. without the suffix, which Stefan confirms.  If such
info files are still around on older systems, I guess my patch is
insufficient.

Steve Berman

Re: master ec9523a: Add a keybinding to the help menu to display manuals

[Eli Zaretskii]

On October 15, 2020 10:00:12 AM GMT+03:00, Lars Ingebrigtsen <larsi@gnus.org> wrote:
> Stefan Monnier <monnier@iro.umontreal.ca> writes:
> 
> >> files under info/ end in ".info".  Are there known cases of
> >> extensionless info files that do not correspond to a file ending in
> >> ".info" or ".info.gz" (or another compression suffix)?  If not,
> then
> >> removing that bit of the code will prevent the current false
> positives.
> >
> > It used to be common to have Info files with names like `foo`,
> `foo-1`,
> > `foo-2`, ...  Splitting Info files has gotten out of fashion due to
> the
> > growing size of RAM, and the use of a `.info` extension has grown
> > a lot too.  Maybe we could start assuming that all those files
> nowadays
> > have a `.info` extension?
> 
> I had a look in
> 
> /usr/share/info/
> 
> here, and it looks like they all have .info in their names.

I have in my /usr/share/info gobs of old Info files without any extension.  So please let's not make any changes that would exclude them from completion by this command.

If someone has files in Info-related directories that are not Info files, they should get their act together.  And if we do that on ELPA, let's get our act together, instead of making breaking changes like that.

Re: master ec9523a: Add a keybinding to the help menu to display manuals

[Stephen Berman]

On Thu, 15 Oct 2020 10:43:44 +0300 Eli Zaretskii <eliz@gnu.org> wrote:

> On October 15, 2020 10:00:12 AM GMT+03:00, Lars Ingebrigtsen <larsi@gnus.org> wrote:
>> Stefan Monnier <monnier@iro.umontreal.ca> writes:
>> 
>> >> files under info/ end in ".info".  Are there known cases of
>> >> extensionless info files that do not correspond to a file ending in
>> >> ".info" or ".info.gz" (or another compression suffix)?  If not,
>> then
>> >> removing that bit of the code will prevent the current false
>> positives.
>> >
>> > It used to be common to have Info files with names like `foo`,
>> `foo-1`,
>> > `foo-2`, ...  Splitting Info files has gotten out of fashion due to
>> the
>> > growing size of RAM, and the use of a `.info` extension has grown
>> > a lot too.  Maybe we could start assuming that all those files
>> nowadays
>> > have a `.info` extension?
>> 
>> I had a look in
>> 
>> /usr/share/info/
>> 
>> here, and it looks like they all have .info in their names.
>
> I have in my /usr/share/info gobs of old Info files without any extension.  So
> please let's not make any changes that would exclude them from completion by
> this command.
>
> If someone has files in Info-related directories that are not Info files, they
> should get their act together.  And if we do that on ELPA, let's get our act
> together, instead of making breaking changes like that.

According to (info "(elisp) Multi-file Packages"), it seems that the
package library currently does not support a separate info directory
within the package directory:

  "If the content directory contains a file named ‘dir’, this is assumed
  to be an Info directory file made with ‘install-info’.  *Note Invoking
  install-info: (texinfo)Invoking install-info.  The relevant Info files
  should also be present in the content directory.  In this case, Emacs
  will automatically add the content directory to ‘Info-directory-list’
  when the package is activated."

I haven't looked at the code so I don't know how feasible it is for ELPA
to accommodate a separate info directory.

Steve Berman

Re: master ec9523a: Add a keybinding to the help menu to display manuals

[Eli Zaretskii]

> From: Stephen Berman <stephen.berman@gmx.net>
> Date: Thu, 15 Oct 2020 00:33:52 +0200
> Cc: Lars Ingebrigtsen <larsi@gnus.org>, emacs-devel@gnu.org
> 
> And it's even worse if Info-directory-list includes directories that
> contain lots of extensionless files that aren't info files, such as, for
> example, the AUCTeX package from GNU ELPA, which contains such files as
> ChangeLog, COPYING, GNUmakefile, etc., all of which are listed in the
> *Completions* buffer, and if you choose one of them, it gets visited in
> Info mode, which throws the user-error: "No such node or anchor: Top".

Why do we use that directory for Info files?  It sounds like a royal
mess; info.el was never meant to face these problems.

We have a docs directory, where we keep Texinfo sources of the
documentation; why not keep the Info files there?  Then we'd only need
to avoid *.texi files as completion candidates (which is a good idea
anyway).

Alternatively, we could, of course, have a list of files in the
package's main directory that need to be skipped when looking for the
Info files (ChangeLog, COPYING, GNUmakefile, *.el, *.elc, etc.).  But
I think using a separate directory is much cleaner.

Re: master ec9523a: Add a keybinding to the help menu to display manuals

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > We have a docs directory, where we keep Texinfo sources of the
  > documentation; why not keep the Info files there?

It is ok for the command which generates them to generate them there.
But we need to install them in the system's directory for Info files.

Many programs generate Info files, not just Emacs.  We want all
programs to do so.  Thus, they need to be installed in a soecufuc
directory for the Info files of all programs.

-- 
Dr Richard Stallman
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: master ec9523a: Add a keybinding to the help menu to display manuals

[Eli Zaretskii]

> From: Richard Stallman <rms@gnu.org>
> Cc: stephen.berman@gmx.net, larsi@gnus.org, stefankangas@gmail.com,
> 	emacs-devel@gnu.org
> Date: Fri, 16 Oct 2020 00:08:58 -0400
> 
>   > We have a docs directory, where we keep Texinfo sources of the
>   > documentation; why not keep the Info files there?
> 
> It is ok for the command which generates them to generate them there.
> But we need to install them in the system's directory for Info files.

The ELPA package installation procedure (implemented in package.el,
AFAIU), doesn't install Info files.

It is not a catastrophe not to move the files physically -- they come
with a DIR file of their own, and thus can be added to the Info
directory list -- but the problem is that they are mixed with many
non-Info files, and that violates the expectations of Info readers.

Re: master ec9523a: Add a keybinding to the help menu to display manuals

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > The ELPA package installation procedure (implemented in package.el,
  > AFAIU), doesn't install Info files.

Indeed, it can't install them in the system's Info directory,
and shouldn't if it could.

  > It is not a catastrophe not to move the files physically -- they come
  > with a DIR file of their own, and thus can be added to the Info
  > directory list -- but the problem is that they are mixed with many
  > non-Info files, and that violates the expectations of Info readers.

How about making an 'info' subdirectory in the package
and putting the info files there?  Then it  could put
that subdirectory in the Info directory list.

Would that be a solution?




-- 
Dr Richard Stallman
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: master ec9523a: Add a keybinding to the help menu to display manuals

[Eli Zaretskii]

> From: Richard Stallman <rms@gnu.org>
> Cc: larsi@gnus.org, stephen.berman@gmx.net, stefankangas@gmail.com,
> 	emacs-devel@gnu.org
> Date: Sun, 18 Oct 2020 00:10:25 -0400
> 
>   > It is not a catastrophe not to move the files physically -- they come
>   > with a DIR file of their own, and thus can be added to the Info
>   > directory list -- but the problem is that they are mixed with many
>   > non-Info files, and that violates the expectations of Info readers.
> 
> How about making an 'info' subdirectory in the package
> and putting the info files there?

That'd be ideal, but AFAIU there were reasons why ELPA didn't go for
that structure.

Re: master ec9523a: Add a keybinding to the help menu to display manuals

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > That'd be ideal, but AFAIU there were reasons why ELPA didn't go for
  > that structure.

Dows anyone know?

If not, how about trying that in one package as a test?

-- 
Dr Richard Stallman
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: master ec9523a: Add a keybinding to the help menu to display manuals

[Lars Ingebrigtsen]

Eli Zaretskii <eliz@gnu.org> writes:

> Alternatively, we could, of course, have a list of files in the
> package's main directory that need to be skipped when looking for the
> Info files (ChangeLog, COPYING, GNUmakefile, *.el, *.elc, etc.).  But
> I think using a separate directory is much cleaner.

A blocklist of file names is probably the only realistic solution here,
considering how things look in the wild.

That is, this command should only list files that have ".info" in their
names somewhere, or have no suffix (except .gz) and not be in the
blocklist.  So *.el etc in the blocklist shouldn't be necessary.

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

Re: master ec9523a: Add a keybinding to the help menu to display manuals

[Lars Ingebrigtsen]

Stefan Kangas <stefankangas@gmail.com> writes:

> Shouldn't this NEWS entry rather say something like:
>
> * New keybinding 'C-h R' prompts for a manual display and displays it.

Yup; fixed now.

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