Virtual Info keyword finder

Virtual Info keyword finder

[Juri Linkov]

I'd like to close the following TODO item from etc/TODO:

** Replace finder.el with something that generates an Info file
   which gives the same information through a menu structure.

It was easily implementable with a small patch using the virtual
Info manual architecture.  The Top node contains a menu with links
to keyword nodes, and each keyword node contains a menu with links
to nodes with a commentary section:

Index: lisp/info.el
===================================================================
RCS file: /sources/emacs/emacs/lisp/info.el,v
retrieving revision 1.560
diff -c -r1.560 info.el
*** lisp/info.el	2 Jul 2009 22:47:33 -0000	1.560
--- lisp/info.el	11 Jul 2009 20:31:52 -0000
***************
*** 3324,3329 ****
--- 3324,3411 ----
  	      Info-apropos-nodes)
  	(Info-find-node Info-apropos-file nodename)))))
  \f
+ (add-to-list 'Info-virtual-files
+ 	     '("\\`\\*Finder.*\\*\\'"
+ 	       (find-file . Info-finder-find-file)
+ 	       (find-node . Info-finder-find-node)
+ 	       ))
+ 
+ (defvar Info-finder-file "*Finder*"
+   "Info file name of the virtual Info keyword finder manual.")
+ 
+ (defun Info-finder-find-file (filename &optional noerror)
+   "Finder-specific implementation of Info-find-file."
+   filename)
+ 
+ (defvar finder-known-keywords)
+ (defvar finder-package-info)
+ (declare-function find-library-name "find-func" (library))
+ (declare-function lm-commentary "lisp-mnt" (&optional file))
+ 
+ (defun Info-finder-find-node (filename nodename &optional no-going-back)
+   "Finder-specific implementation of Info-find-node-2."
+   (cond
+    ((equal nodename "Top")
+     ;; Display Top menu with descriptions of the keywords
+     (insert (format "\n\^_\nFile: %s,  Node: %s,  Up: (dir)\n\n"
+ 		    Info-finder-file nodename))
+     (insert "Finder Keywords\n")
+     (insert "***************\n\n")
+     (insert "* Menu:\n\n")
+     (mapc
+      (lambda (assoc)
+        (let ((keyword (car assoc)))
+ 	 (insert (format "* %-14s %s.\n"
+ 			 (concat (symbol-name keyword) "::")
+ 			 (cdr assoc)))))
+      finder-known-keywords))
+    ((string-match-p "\\.el\\'" nodename)
+     ;; Display commentary section
+     (insert (format "\n\^_\nFile: %s,  Node: %s,  Up: Top\n\n"
+ 		    Info-finder-file nodename))
+     (insert "Finder Commentary\n")
+     (insert "*****************\n\n")
+     (insert
+      "Commentary section of the package `" nodename "':\n\n")
+     (let ((str (lm-commentary (find-library-name nodename))))
+       (if (null str)
+ 	  (insert "Can't find any Commentary section\n\n")
+ 	(insert
+ 	 (with-temp-buffer
+ 	   (insert str)
+ 	   (goto-char (point-min))
+ 	   (delete-blank-lines)
+ 	   (goto-char (point-max))
+ 	   (delete-blank-lines)
+ 	   (goto-char (point-min))
+ 	   (while (re-search-forward "^;+ ?" nil t)
+ 	     (replace-match "" nil nil))
+ 	   (buffer-string))))))
+    (t
+     ;; Display packages that match the keyword
+     (insert (format "\n\^_\nFile: %s,  Node: %s,  Up: Top\n\n"
+ 		    Info-finder-file nodename))
+     (insert "Finder Packages\n")
+     (insert "***************\n\n")
+     (insert
+      "The following packages match the keyword `" nodename "':\n\n")
+     (insert "* Menu:\n\n")
+     (let ((id (intern nodename)))
+       (mapc
+        (lambda (x)
+ 	 (when (memq id (cadr (cdr x)))
+ 	   (insert (format "* %-16s %s.\n"
+ 			   (concat (car x) "::")
+ 			   (cadr x)))))
+        finder-package-info)))))
+ 
+ ;;;###autoload
+ (defun info-finder ()
+   "Display descriptions of the keywords in the Finder virtual manual."
+   (interactive)
+   (require 'finder)
+   (Info-find-node Info-finder-file "Top"))
+ \f
  (defun Info-undefined ()
    "Make command be undefined in Info."
    (interactive)

-- 
Juri Linkov
http://www.jurta.org/emacs/

RE: Virtual Info keyword finder

[Drew Adams]

> I'd like to close the following TODO item from etc/TODO:
> 
> ** Replace finder.el with something that generates an Info file
>    which gives the same information through a menu structure.
> 
> It was easily implementable with a small patch using the virtual
> Info manual architecture.  The Top node contains a menu with links
> to keyword nodes, and each keyword node contains a menu with links
> to nodes with a commentary section:

(Caveat: I didn't try it; I just glanced at it.)

In spite of that TODO entry, can we please call this something else, and keep
finder.el as it is?

Info mode is not as simple as Finder mode - it has extra features and extra
limitations, which means it interacts differently from Finder with other (minor)
modes that users might use at the same time.

For example, I use Finder mode in combination with Linkd minor mode.
http://www.emacswiki.org/emacs/LinkdMode

Linkd has its own kind of hypertext links. In Finder, these work within and
between (Finder) Commentary buffers. Without Finder, the same Linkd links still
work within and between sections of files (including Commentary sections).

Coupling Finder with Info in the way you propose makes it follow Info's
limitations, from syntax to behavior, including UI. I'm not against an Info
extension to give it Finder-like functionality - that would be good. But I don't
want to see plain old, simple Finder get lost in the bargain. It is a useful
tool in its own right.

Re: Virtual Info keyword finder

[Chong Yidong]

"Drew Adams" <drew.adams@oracle.com> writes:

> Info mode is not as simple as Finder mode - it has extra features and extra
> limitations, which means it interacts differently from Finder with other (minor)
> modes that users might use at the same time.
>
> For example, I use Finder mode in combination with Linkd minor mode.
> http://www.emacswiki.org/emacs/LinkdMode
>
> Linkd has its own kind of hypertext links. In Finder, these work within and
> between (Finder) Commentary buffers. Without Finder, the same Linkd links still
> work within and between sections of files (including Commentary sections).
>
> Coupling Finder with Info in the way you propose makes it follow
> Info's limitations, from syntax to behavior, including UI. I'm not
> against an Info extension to give it Finder-like functionality - that
> would be good. But I don't want to see plain old, simple Finder get
> lost in the bargain. It is a useful tool in its own right.

How bout if we replace the programming interface to Finder with a
compatible one (e.g. providing the same interface functions), while
changing the underlying mechanics as Juri suggested.

RE: Virtual Info keyword finder

[Drew Adams]

> > Info mode is not as simple as Finder mode - it has extra 
> > features and extra limitations, which means it interacts
> > differently from Finder with other (minor)
> > modes that users might use at the same time.
> >
> > For example, I use Finder mode in combination with Linkd minor mode.
> > http://www.emacswiki.org/emacs/LinkdMode
> >
> > Linkd has its own kind of hypertext links. In Finder, these 
> > work within and between (Finder) Commentary buffers. Without
> > Finder, the same Linkd links still work within and between
> > sections of files (including Commentary sections).
> >
> > Coupling Finder with Info in the way you propose makes it follow
> > Info's limitations, from syntax to behavior, including UI. I'm not
> > against an Info extension to give it Finder-like 
> > functionality - that would be good. But I don't want to see plain
> > old, simple Finder get lost in the bargain. It is a useful tool
> > in its own right.
> 
> How bout if we replace the programming interface to Finder with a
> compatible one (e.g. providing the same interface functions), while
> changing the underlying mechanics as Juri suggested.

Maybe, but I can't really tell what you mean, so I can't say.
Could you be more specific?

My concern is to also have available the existing Finder mode, that is, not just
within Info mode. I don't really care about the mode name or function names for
Finder (e.g. `finder-commentary'), as long as the same behavior is available. I
could easily change my code to call different functions, if that's what you
meant.

Re: Virtual Info keyword finder

[Juri Linkov]

> For example, I use Finder mode in combination with Linkd minor mode.
> http://www.emacswiki.org/emacs/LinkdMode
>
> Linkd has its own kind of hypertext links. In Finder, these work within and
> between (Finder) Commentary buffers. Without Finder, the same Linkd links still
> work within and between sections of files (including Commentary sections).

There is no hurry to move finder.el to the `obsolete' directory.
You have enough time to try an Info extension of Finder and try
using it with Linkd.

-- 
Juri Linkov
http://www.jurta.org/emacs/