emacs: lisp/recentf.el comparison

comparison lisp/recentf.el @ 32292:11bee5bae414

Doc fixes.

author	Dave Love <fx@gnu.org>
date	Sun, 08 Oct 2000 16:34:14 +0000
parents	293a86f4d8aa
children	0e626f0c2b8a

comparison

equal deleted inserted replaced

-:ad4a568e556a
+:11bee5bae414
 ;; the source code for details).  To install and use, put the file on
 ;; your Emacs-Lisp load path and add the following into your ~/.emacs
 ;; startup file:
 ;;
 ;;  (require 'recentf)
 ;;  (recentf-mode 1)
 ;;; Code:
 (require 'easymenu)
 (require 'wid-edit)
 ;; and `recentf-menu-title' values.
 (defun recentf-menu-customization-changed (sym val)
 "Function called when menu customization has changed.
 It removes the recentf menu and forces its complete redrawing."
 (when recentf-initialized-p
 (easy-menu-remove-item nil
 (symbol-value 'recentf-menu-path)
 (symbol-value 'recentf-menu-title))
 (setq recentf-update-menu-p t))
 (custom-set-default sym val))
 (defcustom recentf-menu-action 'recentf-find-file
 "*Function to invoke with a filename item of the recentf menu.
 The default action `recentf-find-file' calls `find-file' to edit an
 existing file.  If the file does not exist or is not readable, it is
-not edited and its name is removed from `recentf-list'. You can use
+not edited and its name is removed from `recentf-list'.  You can use
 `find-file' instead to open non-existing files and keep them in the
 list of recently opened files."
 :group 'recentf
 :type 'function
 :set 'recentf-menu-customization-changed)
 A menu element is a pair (MENU-ITEM . MENU-VALUE) where:
 - - MENU-ITEM  is the menu item string displayed.
 - - MENU-VALUE is the path used to open the file when the
-corresponding MENU-ITEM is selected. Or it is
+corresponding MENU-ITEM is selected.  Or it is
 a pair (SUB-MENU-TITLE . MENU-ELEMENTS) where
 SUB-MENU-TITLE is a sub-menu title and
 MENU-ELEMENTS is the list of menu elements in
 the sub-menu."
 (cons menu-item menu-value))
 (defun recentf-sub-menu-element-p (e)
 "Return non-nil if menu-element E defines a sub-menu."
 (consp (recentf-menu-element-value e)))
 (defun recentf-make-default-menu-element (file-path)
-"Make a new default menu element (MENU-ITEM . MENU-VALUE) for the
+"Make a new default menu element (MENU-ITEM . MENU-VALUE).
-given recent file path FILE-PATH. MENU-ITEM and MENU-VALUE are set to
+Do so for the given recent file path FILE-PATH.  MENU-ITEM and
-FILE-PATH. See also `recentf-make-menu-element'."
+MENU-VALUE are set to FILE-PATH.  See also
+`recentf-make-menu-element'."
 (recentf-make-menu-element file-path file-path))
 (defun recentf-menu-elements (n)
-"Return a list of the first N default menu elements from
+"Return a list of the first N default menu elements from `recentf-list'.
-`recentf-list'. See also `recentf-make-default-menu-element'."
+See also `recentf-make-default-menu-element'."
 (mapcar 'recentf-make-default-menu-element
 (recentf-elements n)))
 (defun recentf-apply-menu-filter (filter l)
-"Convenient funtion to apply the function FILTER to the list of
+"Apply function FILTER to the list of menu-elements L.
-menu-elements L. It takes care of sub-menu elements in L and
+It takes care of sub-menu elements in L and recursively apply FILTER
-recursively apply FILTER to them. It is guarantee than FILTER receives
+to them.  It is guarantee than FILTER receives only a list of single
-only a list of single menu-elements (no sub-menu)."
+menu-elements (no sub-menu)."
 (if (and (functionp filter) l)
 (let ((case-fold-search recentf-case-fold-search)
 menu-element sub-menu-elements single-elements)
 ;; split L in two sub-listes:
 ;;   one of sub-menus elements and
 (string-lessp
 (file-name-nondirectory (recentf-menu-element-value e2))
 (file-name-nondirectory (recentf-menu-element-value e1)))))))
 (defun recentf-directory-compare (p1 p2)
-"Compare directories then filenames in pathes P1 and P2 and return
+"Compare directories then filenames in paths P1 and P2.
-non-nil if P1 is less than P2."
+Return non-nil if P1 is less than P2."
 (let ((d1 (file-name-directory    p1))
 (f1 (file-name-nondirectory p1))
 (d2 (file-name-directory    p2))
 (f2 (file-name-nondirectory p2)))
 (if (string= d1 d2)
 (recentf-directory-compare (recentf-menu-element-value e2)
 (recentf-menu-element-value e1))))))
 (defun recentf-show-basenames (l)
 "Filter the list of menu elements L to show only file names (no directories)
-in the menu. When file names are duplicated their directory component is added."
+in the menu.  When file names are duplicated their directory component is added."
 (let ((names  (mapcar (function
 (lambda (item)
 (file-name-nondirectory
 (recentf-menu-element-value item))))
 l))
 filtered-list))
 (setq filtered-items (cons item filtered-items)))
 (nreverse filtered-list)))
 (defun recentf-show-basenames-ascending (l)
-"Filter the list of menu elements L to show only file names in the menu,
+"Filter the list of menu elements L.
-sorted in ascending order. This filter combines the `recentf-sort-basenames-ascending'
+Show only file names in the menu, sorted in ascending order.  This
-and `recentf-show-basenames' filters."
+filter combines the `recentf-sort-basenames-ascending' and
+`recentf-show-basenames' filters."
 (recentf-show-basenames (recentf-sort-basenames-ascending l)))
 (defun recentf-show-basenames-descending (l)
-"Filter the list of menu elements L to show only file names in the menu,
+"Filter the list of menu elements L.
-sorted in descending order. This filter combines the `recentf-sort-basenames-descending'
+Show only file names in the menu, sorted in descending order.  This
-and `recentf-show-basenames' filters."
+filter combines the `recentf-sort-basenames-descending' and
+`recentf-show-basenames' filters."
 (recentf-show-basenames (recentf-sort-basenames-descending l)))
 (defun recentf-relative-filter (l)
-"Filter the list of `recentf-menu-elements' L to show filenames
+"Filter the list of `recentf-menu-elements' L.
-relative to `default-directory'."
+Show filenames relative to `default-directory'."
 (setq recentf-update-menu-p t)        ; force menu update
 (mapcar (function
 (lambda (menu-element)
 (let* ((ful-path (recentf-menu-element-value menu-element))
 (rel-path (file-relative-name ful-path)))
 ("Elisp files (%d)" ".\\.el$")
 ("Java files (%d)"  ".\\.java$")
 ("C/C++ files (%d)" "c\\(pp\\)?$")
 )
 "*List of rules used by `recentf-arrange-by-rule' to build sub-menus.
-A rule is a pair (SUB-MENU-TITLE . MATCHER). SUB-MENU-TITLE is the
+A rule is a pair (SUB-MENU-TITLE . MATCHER).  SUB-MENU-TITLE is the
 displayed title of the sub-menu where a '%d' `format' pattern is
-replaced by the number of items in the sub-menu. MATCHER is a regexp
+replaced by the number of items in the sub-menu.  MATCHER is a regexp
-or a list of regexps. Items matching one of the regular expressions in
+or a list of regexps.  Items matching one of the regular expressions in
 MATCHER are added to the corresponding sub-menu."
 :group 'recentf-filters
 :type '(repeat (cons string (repeat regexp)))
 :set 'recentf-menu-customization-changed)
 (defcustom recentf-arrange-by-rule-others "Other files (%d)"
-"*Title of the `recentf-arrange-by-rule' sub-menu where items that
+"*Title of the `recentf-arrange-by-rule' sub-menu.
-don't match any `recentf-arrange-rules' are displayed. If nil
+This is for the menu where items that don't match any
-these items are displayed in the main recent files menu. A '%d'
+`recentf-arrange-rules' are displayed.  If nil these items are
-`format' pattern in the title is replaced by the number of items in
+displayed in the main recent files menu.  A '%d' `format' pattern in
-the sub-menu."
+the title is replaced by the number of items in the sub-menu."
 :group 'recentf-filters
 :type '(choice (const  :tag "Main menu" nil)
 (string :tag "Title"))
 :set 'recentf-menu-customization-changed)
 :type 'number
 :set 'recentf-menu-customization-changed)
 (defcustom recentf-arrange-by-rule-subfilter nil
 "*Function used by `recentf-arrange-by-rule' to filter sub-menu elements.
-Nil means no filter. See also `recentf-menu-filter'. You can't use
+Nil means no filter.  See also `recentf-menu-filter'.  You can't use
 `recentf-arrange-by-rule' itself here!"
 :group 'recentf-filters
 :type 'function
 :set (lambda (sym val)
 (if (eq val 'recentf-arrange-by-rule)
 (not (string-match (car matcher) file-path)))
 (setq matcher (cdr matcher)))
 matcher))
 (defun recentf-arrange-by-rule (l)
-"Filter the list of menu-elements L to arrange them in sub-menus
+"Filter the list of menu-elements L.
-following rules in `recentf-arrange-rules'."
+Arrange them in sub-menus following rules in `recentf-arrange-rules'."
 (let ((sub-menus-number (length recentf-arrange-rules)))
 (if (> sub-menus-number 0)
 (let ((sub-menus (apply 'vector
 (mapcar (function
 (lambda (pair)
 ;; It is important to preserve auto-mode-alist order
 ;; to ensure the right file <-> mode association
 (nreverse rules)))
 (defun recentf-arrange-by-mode (l)
-"Filter the list of menu-elements L to build sub-menus for each
+"Filter the list of menu-elements L to build sub-menus for each major mode."
-major mode."
 (let ((recentf-arrange-rules (recentf-build-mode-rules))
 (recentf-arrange-by-rule-others "others (%d)"))
 (recentf-arrange-by-rule l)))
 (defun recentf-build-dir-rules (l)
-"Convert directories in the list of menu-elements L to rules in
+"Convert directories in menu-elements L to rules in `recentf-arrange-rules' format."
-`recentf-arrange-rules' format."
 (let (dirs)
 (mapcar (function
 (lambda (e)
 (let ((dir (file-name-directory
 (recentf-menu-element-value e))))
 (cons (concat d " (%d)")
 (concat "\\`" d))))
 (nreverse (sort dirs 'string-lessp)))))
 (defun recentf-file-name-nondir (l)
-"Filter the list of menu-elements L to show only filenames. This
+"Filter the list of menu-elements L to show only filenames.
-simplified version of `recentf-show-basenames' do not handle
+This simplified version of `recentf-show-basenames' does not handle
-duplicates. It is used by `recentf-arrange-by-dir' as its
+duplicates.  It is used by `recentf-arrange-by-dir' as its
 `recentf-arrange-by-rule-subfilter'."
 (mapcar (function
 (lambda (e)
 (recentf-make-menu-element
 (file-name-nondirectory (recentf-menu-element-value e))
 (recentf-menu-element-value e))))
 l))
 (defun recentf-arrange-by-dir (l)
-"Filter the list of menu-elements L to build sub-menus for each
+"Filter the list of menu-elements L to build sub-menus for each directory."
-directory."
 (let ((recentf-arrange-rules (recentf-build-dir-rules l))
 (recentf-arrange-by-rule-subfilter 'recentf-file-name-nondir)
 recentf-arrange-by-rule-others)
 (nreverse (recentf-arrange-by-rule l))))
 (setq filters (cdr filters)))))
 (if (consp filters)
 (car filters))))
 (defun recentf-filter-changer (l)
-"Manage a ring of filters. `recentf-filter-changer-alist' defines
+"Manage a ring of filters.
-the filters in the ring. Actual filtering of L is delegated to the
+`recentf-filter-changer-alist' defines the filters in the ring.
-current filter in the ring. A filter menu item is displayed allowing
+Actual filtering of L is delegated to the current filter in the
-to dynamically activate the next filter in the ring. If the filter
+ring.  A filter menu item is displayed allowing to dynamically activate
-ring is empty L is left unchanged."
+the next filter in the ring.  If the filter ring is empty L is left
+unchanged."
 (let ((current-filter-item (recentf-filter-changer-get-current))
 (next-filter-item    (recentf-filter-changer-get-next)))
 (when current-filter-item
 (setq l (recentf-apply-menu-filter (car current-filter-item) l))
 (if next-filter-item
 ;;;
 ;;; Dialogs stuff
 ;;;
 (defun recentf-cancel-dialog (&rest ignore)
-"Cancel the current dialog. Used by `recentf-edit-list' and
+"Cancel the current dialog.
-`recentf-open-files' dialogs."
+Used by `recentf-edit-list' and `recentf-open-files' dialogs."
 (interactive)
 (kill-buffer (current-buffer))
 (message "Dialog canceled."))
 (defvar recentf-dialog-mode-map nil
 (recentf-make-menu-items)
 recentf-menu-before))
 (error nil))))
 (defun recentf-dump-variable (variable &optional limit)
-"Insert a \"(setq VARIABLE value)\" in the current buffer. Optional
+"Insert a \"(setq VARIABLE value)\" in the current buffer.
-argument LIMIT specifies a maximum length when VARIABLE value is a
+Optional argument LIMIT specifies a maximum length when VARIABLE value
-list (default to the full list)."
+is a list (default to the full list)."
 (let ((value (symbol-value variable)))
 (insert (format "(setq %S\n      '(\n" variable))
 (cond ((consp value)
 (if (and (integerp limit) (> limit 0))
 (setq value (recentf-trunc-list value limit)))
 (write-region (point-min) (point-max) recentf-save-file))
 (kill-buffer (current-buffer)))
 nil)
 (defvar recentf-edit-selected-items nil
-"Used by `recentf-edit-list' to hold the list of files to be deleted
+"Used by `recentf-edit-list'.
-from `recentf-list'.")
+Holds list of files to be deleted from `recentf-list'.")
 (defun recentf-edit-list-action (widget &rest ignore)
 "Checkbox widget action used by `recentf-edit-list' to select/unselect a file."
 (let ((value (widget-get widget ':tag)))
 ;; if value is already in the selected items
 "Button widget action used by `recentf-open-files' to open a file."
 (kill-buffer (current-buffer))
 (funcall recentf-menu-action (widget-value widget)))
 (defvar recentf-open-files-item-shift ""
-"String used by `recentf-open-files' to shift right sub-menu
+"String used by `recentf-open-files' to shift right sub-menu items.")
-items.")
 (defun recentf-open-files-item (menu-element)
-"Function called by `recentf-open-files' to insert a menu-element
+"Insert menu-element item in the current interaction buffer."
-item in the current interaction buffer."
 (let ((menu-item (car menu-element))
 (file-path (cdr menu-element)))
 (if (consp file-path)               ; This is a sub-menu
 (let* ((shift recentf-open-files-item-shift)
 (recentf-open-files-item-shift (concat shift "  ")))
 file-path)
 (widget-insert "\n"))))
 ;;;###autoload
 (defun recentf-open-files (&optional files buffer-name)
-"Open a buffer that allows the user to choose a file to open from
+"Display buffer allowing user to choose a file from recently-opened list.
-the list of recently opened files. The optional argument FILES may be
+The optional argument FILES may be used to specify the list, otherwise
-used to specify the list, otherwise recentf-list is used. The optional
+recentf-list is used.  The optional argument BUFFER-NAME specifies
-argument BUFFER-NAME specifies which buffer to use for the interaction."
+which buffer to use for the interaction."
 (interactive)
 (if (null files)
 (setq files recentf-list))
 (if (null buffer-name)
 (setq buffer-name (concat "*" recentf-menu-title "*")))

Mercurial > emacs

comparison lisp/recentf.el @ 32292:11bee5bae414