diff lisp/woman.el @ 84355:2276ead2dd45

Remove spurious * in docstrings. (woman-mini-help, woman-non-underline-faces, woman0-rename) (woman-topic-all-completions-merge, woman-file-name-all-completions) (woman-select-symbol-fonts, woman-expand-directory-path): Use dolist. (woman-write-directory-cache, woman-display-extended-fonts) (WoMan-log-begin, WoMan-log-1): Use with-current-buffer. (woman-really-find-file): Use pop-to-buffer if switch-to-buffer fails. (woman-mode): Use inhibit-read-only. (woman-negative-vertical-space): Use dotimes. (woman2-tagged-paragraph, woman-tab-to-tab-stop): Use insert-char.

--- a/lisp/woman.el	Fri Sep 07 00:28:06 2007 +0000
+++ b/lisp/woman.el	Fri Sep 07 02:45:28 2007 +0000
@@ -520,19 +520,19 @@
   :group 'help)
 
 (defcustom woman-show-log nil
-  "*If non-nil then show the *WoMan-Log* buffer if appropriate.
+  "If non-nil then show the *WoMan-Log* buffer if appropriate.
 I.e. if any warning messages are written to it.  Default is nil."
   :type 'boolean
   :group 'woman)
 
 (defcustom woman-pre-format-hook nil
-  "*Hook run by WoMan immediately before formatting a buffer.
+  "Hook run by WoMan immediately before formatting a buffer.
 Change only via `Customization' or the function `add-hook'."
   :type 'hook
   :group 'woman)
 
 (defcustom woman-post-format-hook nil
-  "*Hook run by WoMan immediately after formatting a buffer.
+  "Hook run by WoMan immediately after formatting a buffer.
 Change only via `Customization' or the function `add-hook'."
   :type 'hook
   :group 'woman)
@@ -550,7 +550,7 @@
     (if (eq system-type 'windows-nt)
 	(mapcar 'woman-Cyg-to-Win path)
       path))
-  "*List of dirs to search and/or files to try for man config file.
+  "List of dirs to search and/or files to try for man config file.
 A trailing separator (`/' for UNIX etc.) on directories is
 optional, and the filename is used if a directory specified is
 the first to start with \"man\" and has an extension starting
@@ -606,7 +606,7 @@
 (defcustom woman-manpath
   (or (woman-parse-colon-path (getenv "MANPATH"))
       '("/usr/man" "/usr/share/man" "/usr/local/man"))
-  "*List of DIRECTORY TREES to search for UN*X manual files.
+  "List of DIRECTORY TREES to search for UN*X manual files.
 Each element should be the name of a directory that contains
 subdirectories of the form `man?', or more precisely subdirectories
 selected by the value of `woman-manpath-man-regexp'.  Non-directory
@@ -649,7 +649,7 @@
 
 (defcustom woman-path
   (if (eq system-type 'ms-dos) '("$DJDIR/info" "$DJDIR/man/cat[1-9onlp]"))
-  "*List of SPECIFIC DIRECTORIES to search for UN*X manual files.
+  "List of SPECIFIC DIRECTORIES to search for UN*X manual files.
 For example
 
   (\"/emacs/etc\").
@@ -676,7 +676,7 @@
   :group 'woman-interface)
 
 (defcustom woman-cache-level 2
-  "*The level of topic caching.
+  "The level of topic caching.
 1 - cache only the topic and directory lists
     (the only level before version 0.34 - only for compatibility);
 2 - cache also the directories for each topic
@@ -695,7 +695,7 @@
   :group 'woman-interface)
 
 (defcustom woman-cache-filename nil
-  "*The full pathname of the WoMan directory and topic cache file.
+  "The full pathname of the WoMan directory and topic cache file.
 It is used to save and restore the cache between sessions.  This is
 especially useful with remote-mounted man page files!  The default
 value of nil suppresses this action.  The `standard' non-nil
@@ -707,7 +707,7 @@
   :group 'woman-interface)
 
 (defcustom woman-dired-keys t
-  "*List of `dired' mode keys to define to run WoMan on current file.
+  "List of `dired' mode keys to define to run WoMan on current file.
 E.g. '(\"w\" \"W\"), or any non-null atom to automatically define
 \"w\" and \"W\" if they are unbound, or nil to do nothing.
 Default is t."
@@ -719,20 +719,20 @@
 (defcustom woman-imenu-generic-expression
   '((nil "\n\\([A-Z].*\\)" 1) ; SECTION, but not TITLE
     ("*Subsections*" "^   \\([A-Z].*\\)" 1))
-  "*Imenu support for Sections and Subsections.
+  "Imenu support for Sections and Subsections.
 An alist with elements of the form (MENU-TITLE REGEXP INDEX) --
 see the documentation for `imenu-generic-expression'."
   :type 'sexp
   :group 'woman-interface)
 
 (defcustom woman-imenu nil
-  "*If non-nil then WoMan adds a Contents menu to the menubar.
+  "If non-nil then WoMan adds a Contents menu to the menubar.
 It does this by calling `imenu-add-to-menubar'.  Default is nil."
   :type 'boolean
   :group 'woman-interface)
 
 (defcustom woman-imenu-title "CONTENTS"
-  "*The title to use if WoMan adds a Contents menu to the menubar.
+  "The title to use if WoMan adds a Contents menu to the menubar.
 Default is \"CONTENTS\"."
   :type 'string
   :group 'woman-interface)
@@ -741,13 +741,13 @@
   ;; `woman-use-topic-at-point' may be let-bound when woman is loaded,
   ;; in which case its global value does not get defined.
   ;; `woman-file-name' sets it to this value if it is unbound.
-  "*Default value for `woman-use-topic-at-point'."
+  "Default value for `woman-use-topic-at-point'."
   :type '(choice (const :tag "Yes" t)
 		 (const :tag "No" nil))
   :group 'woman-interface)
 
 (defcustom woman-use-topic-at-point woman-use-topic-at-point-default
-  "*Control use of the word at point as the default topic.
+  "Control use of the word at point as the default topic.
 If non-nil the `woman' command uses the word at point automatically,
 without interactive confirmation, if it exists as a topic."
   :type '(choice (const :tag "Yes" t)
@@ -778,7 +778,7 @@
 
 (defcustom woman-uncompressed-file-regexp
   "\\.\\([0-9lmnt]\\w*\\)"		; disallow no extension
-  "*Do not change this unless you are sure you know what you are doing!
+  "Do not change this unless you are sure you know what you are doing!
 Regexp used to select man source files (ignoring any compression extension).
 
 The SysV standard man pages use two character suffixes, and this is
@@ -793,7 +793,7 @@
 
 (defcustom woman-file-compression-regexp
   "\\.\\(g?z\\|bz2\\)\\'"
-  "*Do not change this unless you are sure you know what you are doing!
+  "Do not change this unless you are sure you know what you are doing!
 Regexp used to match compressed man file extensions for which
 decompressors are available and handled by auto-compression mode,
 e.g. \"\\\\.\\\\(g?z\\\\|bz2\\\\)\\\\'\" for `gzip' or `bzip2'.
@@ -809,7 +809,7 @@
 (defcustom woman-use-own-frame		; window-system
   (or (and (fboundp 'display-graphic-p) (display-graphic-p)) ; Emacs 21
       (memq window-system '(x w32)))	; Emacs 20
-  "*If non-nil then use a dedicated frame for displaying WoMan windows.
+  "If non-nil then use a dedicated frame for displaying WoMan windows.
 Only useful when run on a graphic display such as X or MS-Windows."
   :type 'boolean
   :group 'woman-interface)
@@ -823,37 +823,37 @@
   :group 'woman)
 
 (defcustom woman-fill-column 65
-  "*Right margin for formatted text -- default is 65."
+  "Right margin for formatted text -- default is 65."
   :type 'integer
   :group 'woman-formatting)
 
 (defcustom woman-fill-frame nil
   ;; Based loosely on a suggestion by Theodore Jump:
-  "*If non-nil then most of the window width is used."
+  "If non-nil then most of the window width is used."
   :type 'boolean
   :group 'woman-formatting)
 
 (defcustom woman-default-indent 5
-  "*Default prevailing indent set by -man macros -- default is 5.
+  "Default prevailing indent set by -man macros -- default is 5.
 Set this variable to 7 to emulate GNU man formatting."
   :type 'integer
   :group 'woman-formatting)
 
 (defcustom woman-bold-headings t
-  "*If non-nil then embolden section and subsection headings.  Default is t.
+  "If non-nil then embolden section and subsection headings.  Default is t.
 Heading emboldening is NOT standard `man' behavior."
   :type 'boolean
   :group 'woman-formatting)
 
 (defcustom woman-ignore t
-  "*If non-nil then unrecognized requests etc. are ignored.  Default is t.
+  "If non-nil then unrecognized requests etc.. are ignored.  Default is t.
 This gives the standard ?roff behavior.  If nil then they are left in
 the buffer, which may aid debugging."
   :type 'boolean
   :group 'woman-formatting)
 
 (defcustom woman-preserve-ascii t
-  "*If non-nil, preserve ASCII characters in the WoMan buffer.
+  "If non-nil, preserve ASCII characters in the WoMan buffer.
 Otherwise, to save time, some backslashes and spaces may be
 represented differently (as the values of the variables
 `woman-escaped-escape-char' and `woman-unpadded-space-char'
@@ -865,7 +865,7 @@
   :group 'woman-formatting)
 
 (defcustom woman-emulation 'nroff
-  "*WoMan emulation, currently either nroff or troff.  Default is nroff.
+  "WoMan emulation, currently either nroff or troff.  Default is nroff.
 Troff emulation is experimental and largely untested.
 \(Add groff later?)"
   :type '(choice (const nroff) (const troff))
@@ -884,7 +884,7 @@
   (or (and (fboundp 'display-color-p) (display-color-p))
       (and (fboundp 'display-graphic-p) (display-graphic-p))
       (x-display-color-p))
-  "*If non-nil then WoMan assumes that face support is available.
+  "If non-nil then WoMan assumes that face support is available.
 It defaults to a non-nil value if the display supports either colors
 or different fonts."
   :type 'boolean
@@ -955,11 +955,10 @@
   (let (symbol-fonts)
     ;; With NTEmacs 20.5, the PATTERN option to `x-list-fonts' does
     ;; not seem to work and fonts may be repeated, so ...
-    (while fonts
-      (and (string-match "-Symbol-" (car fonts))
-	   (not (member (car fonts) symbol-fonts))
-	   (setq symbol-fonts (cons (car fonts) symbol-fonts)))
-      (setq fonts (cdr fonts)))
+    (dolist (font fonts)
+      (and (string-match "-Symbol-" font)
+	   (not (member font symbol-fonts))
+	   (setq symbol-fonts (cons font symbol-fonts))))
     symbol-fonts))
 
 (when woman-font-support
@@ -969,12 +968,12 @@
   ;; avoid unnecessarily upsetting the line spacing in NTEmacs 20.5!
 
   (defcustom woman-use-extended-font t
-    "*If non-nil then may use non-ASCII characters from the default font."
+    "If non-nil then may use non-ASCII characters from the default font."
     :type 'boolean
     :group 'woman-faces)
 
   (defcustom woman-use-symbol-font nil
-    "*If non-nil then may use the symbol font.
+    "If non-nil then may use the symbol font.
 It is off by default, mainly because it may change the line spacing
 \(in NTEmacs 20.5)."
     :type 'boolean
@@ -986,7 +985,7 @@
     "Symbol font(s), preferably same size as default when WoMan was loaded.")
 
   (defcustom woman-symbol-font (car woman-symbol-font-list)
-    "*A string describing the symbol font to use for special characters.
+    "A string describing the symbol font to use for special characters.
 It should be compatible with, and the same size as, the default text font.
 Under MS-Windows, the default is
   \"-*-Symbol-normal-r-*-*-*-*-96-96-p-*-ms-symbol\"."
@@ -1199,10 +1198,9 @@
   "Save the directory and topic cache.
 It is saved to the file named by the variable `woman-cache-filename'."
   (if woman-cache-filename
-      (save-excursion			; to restore current buffer
+      (with-current-buffer (generate-new-buffer "WoMan tmp buffer")
 	;; Make a temporary buffer; name starting with space "hides" it.
-	(let ((standard-output
-	       (set-buffer (generate-new-buffer "WoMan tmp buffer")))
+	(let ((standard-output (current-buffer))
 	      (backup-inhibited t))
 	  ;; (switch-to-buffer standard-output t) ; only for debugging
 	  (buffer-disable-undo standard-output)
@@ -1344,10 +1342,8 @@
   ;; Allow each path to be a single string or a list of strings:
   (if (not (listp woman-manpath)) (setq woman-manpath (list woman-manpath)))
   (if (not (listp woman-path)) (setq woman-path (list woman-path)))
-  (let (dir head dirs path)
-    (while woman-manpath
-      (setq dir (car woman-manpath)
-	    woman-manpath (cdr woman-manpath))
+  (let (head dirs path)
+    (dolist (dir woman-manpath)
       (when (consp dir)
 	(unless path
 	  (setq path (split-string (getenv "PATH") path-separator t)))
@@ -1361,9 +1357,7 @@
 	  (setq dir (woman-canonicalize-dir dir)
 		dirs (nconc dirs (directory-files
 				  dir t woman-manpath-man-regexp)))))
-    (while woman-path
-      (setq dir (car woman-path)
-	    woman-path (cdr woman-path))
+    (dolist (dir woman-path)
       (if (or (null dir)
 	      (null (setq dir (woman-canonicalize-dir dir)
 			  head (file-name-directory dir)))
@@ -1402,7 +1396,7 @@
   ;; will be a list of the first `woman-cache-level' elements of the
   ;; following list: (topic path-index filename).  This alist `files'
   ;; is re-processed by `woman-topic-all-completions-merge'.
-  (let (dir files (path-index 0))	; indexing starts at zero
+  (let (files (path-index 0))	; indexing starts at zero
     (while path
       (setq dir (pop path))
       (if (woman-not-member dir path)	; use each directory only once!
@@ -1455,22 +1449,20 @@
 \(Note that this function changes the value of ALIST.)"
   ;; Replaces unreadably "optimized" O(n^2) implementation.
   ;; Instead we use sorting to merge stuff efficiently.  -- dak
-  (let (elt newalist)
+  (let (newalist)
     ;; Sort list into reverse order
     (setq alist (sort alist (lambda(x y) (string< (car y) (car x)))))
     ;; merge duplicate keys.
     (if (> woman-cache-level 1)
-	(while alist
-	  (setq elt (pop alist))
+	(dolist (elt alist)
 	  (if (equal (car elt) (caar newalist))
 	      (unless (member (cdr elt) (cdar newalist))
 		(setcdr (car newalist) (cons (cdr elt)
 					     (cdar newalist))))
 	    (setcdr elt (list (cdr elt)))
 	    (push elt newalist)))
-    ;; woman-cache-level = 1 => elements are single-element lists ...
-      (while alist
-	(setq elt (pop alist))
+      ;; woman-cache-level = 1 => elements are single-element lists ...
+      (dolist (elt alist)
 	(unless (equal (car elt) (caar newalist))
 	  (push elt newalist))))
     newalist))
@@ -1496,10 +1488,9 @@
 	;; Use cached path-info to locate files for each topic:
 	(let ((path-info (cdr (assoc topic topics)))
 	      filename)
-	  (while path-info
-	    (setq dir (nth (car (car path-info)) path)
-		  filename (car (cdr (car path-info)))
-		  path-info (cdr path-info)
+	  (dolist (elt path-info)
+	    (setq dir (nth (car elt) path)
+		  filename (car (cdr elt))
 		  files (nconc files
 			       ;; Find the actual file name:
 			       (if filename
@@ -1648,7 +1639,10 @@
 	(select-frame
 	 (or (and (frame-live-p woman-frame) woman-frame)
 	     (setq woman-frame (make-frame)))))
-    (switch-to-buffer (get-buffer-create bufname))
+    (set-buffer (get-buffer-create bufname))
+    (condition-case nil
+        (switch-to-buffer (current-buffer))
+      (error (pop-to-buffer (current-buffer))))
     (buffer-disable-undo)
     (setq buffer-read-only nil)
     (erase-buffer)			; NEEDED for reformat
@@ -1916,7 +1910,7 @@
   ;; necessary to avoid re-installing the same imenu:
   (setq woman-imenu-done nil)
   (if woman-imenu (woman-imenu))
-  (let (buffer-read-only)
+  (let ((inhibit-read-only t))
     (Man-highlight-references 'WoMan-xref-man-page))
   (set-buffer-modified-p nil)
   (run-mode-hooks 'woman-mode-hook))
@@ -1956,11 +1950,9 @@
 			      (or (commandp symbol)
 				  (user-variable-p symbol)))))
     ;; Filter out any inhibited symbols:
-    (let ((tem apropos-accumulator))
-      (while tem
-	(if (get (car tem) 'apropos-inhibit)
-	    (setq apropos-accumulator (delq (car tem) apropos-accumulator)))
-	(setq tem (cdr tem))))
+    (dolist (sym apropos-accumulator)
+      (if (get sym 'apropos-inhibit)
+          (setq apropos-accumulator (delq sym apropos-accumulator))))
     ;; Find documentation strings:
     (let ((p apropos-accumulator)
 	  doc symbol)
@@ -2190,15 +2182,13 @@
 (defun woman-non-underline-faces ()
   "Prepare non-underlined versions of underlined faces."
   (let ((face-list (face-list)))
-    (while face-list
-      (let* ((face (car face-list))
-	     (face-name (symbol-name face)))
+    (dolist (face face-list)
+      (let ((face-name (symbol-name face)))
 	(if (and (string-match "\\`woman-" face-name)
 		 (face-underline-p face))
 	    (let ((face-no-ul (intern (concat face-name "-no-ul"))))
 	      (copy-face face face-no-ul)
-	      (set-face-underline-p face-no-ul nil))))
-      (setq face-list (cdr face-list)))))
+	      (set-face-underline-p face-no-ul nil)))))))
 
 ;; Preprocessors
 ;; =============
@@ -2731,11 +2721,9 @@
 (defun woman0-rename ()
   "Effect renaming required by .rn requests."
   ;; For now, do this backwards AFTER all macro expansion.
-  (while woman0-rename-alist
-    (let* ((new (car woman0-rename-alist))
-	   (old (cdr new))
-	   (new (car new)))
-      (setq woman0-rename-alist (cdr woman0-rename-alist))
+  (dolist ((new woman0-rename-alist))
+    (let ((old (cdr new))
+          (new (car new)))
       (goto-char (point-min))
       (setq new (concat "^[.'][ \t]*" (regexp-quote new)))
       (setq old (concat "." old))
@@ -3016,8 +3004,7 @@
 Useful for constructing the alist variable `woman-special-characters'."
   (interactive)
   (with-output-to-temp-buffer "*WoMan Extended Font Map*"
-    (save-excursion
-      (set-buffer standard-output)
+    (with-current-buffer standard-output
       (let ((i 32))
 	(while (< i 256)
 	  (insert (format "\\%03o " i) (string i) " " (string i))
@@ -3920,12 +3907,10 @@
 		((eq c ?\t)		; skip
 		 (if (eq (following-char) ?\t)
 		     (forward-char)	; both tabs, just skip
-		   (let ((i woman-tab-width))
-		     (while (> i 0)
-		       (if (eolp)
-			   (insert ?\ )	; extend line
-			 (forward-char)) ; skip
-		       (setq i (1- i)))
+		   (dotimes (i woman-tab-width)
+                     (if (eolp)
+                         (insert ?\ )	; extend line
+                       (forward-char)) ; skip
 		     )))
 		(t
 		 (if (or (eq (following-char) ?\ ) ; overwrite OK
@@ -4312,7 +4297,7 @@
 		  ;; Necessary to avoid spaces inheriting underlines.
 		  ;; Cannot simply delete (current-column) whitespace
 		  ;; characters because some may be tabs!
-		  (while (> i 0) (insert ? ) (setq i (1- i)))))
+		  (insert-char ?\s i)))
 	   (goto-char to)		; necessary ???
 	   ))
     ))
@@ -4468,9 +4453,7 @@
 		    n (- (if n (1- n) eol) (point))
 		    tab (- tab (if (eq type ?C) (/ n 2) n))) )
 	  (setq n (- tab (current-column)))
-	  (while (> n 0)
-	    (insert ?\ )
-	    (setq n (1- n))))
+	  (insert-char ?\s n))
       (insert ?\ ))))
 
 (defun woman2-DT (to)
@@ -4571,8 +4554,7 @@
 (defun WoMan-log-begin ()
   "Log the beginning of formatting in *WoMan-Log*."
   (let ((WoMan-current-buffer (buffer-name)))
-    (save-excursion
-      (set-buffer (get-buffer-create "*WoMan-Log*"))
+    (with-current-buffer (get-buffer-create "*WoMan-Log*")
       (or (eq major-mode 'view-mode) (view-mode 1))
       (setq buffer-read-only nil)
       (goto-char (point-max))
@@ -4615,8 +4597,7 @@
   "Log a message STRING in *WoMan-Log*.
 If optional argument END is non-nil then make buffer read-only after
 logging the message."
-  (save-excursion
-    (set-buffer (get-buffer-create "*WoMan-Log*"))
+  (with-current-buffer (get-buffer-create "*WoMan-Log*")
     (setq buffer-read-only nil)
     (goto-char (point-max))
     (or end (insert "  "))  (insert string "\n")
@@ -4635,5 +4616,5 @@
 
 (provide 'woman)
 
-;;; arch-tag: eea35e90-552f-4712-a94b-d9ffd3db7651
+;; arch-tag: eea35e90-552f-4712-a94b-d9ffd3db7651
 ;;; woman.el ends here