[PATCH] woman.el (woman-file-name): custom option `woman-use-file-directly'

[PATCH] woman.el (woman-file-name): custom option `woman-use-file-directly'

[Vladimir Alexiev]

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

Hi everyone and Merry Christmas!

Sometimes a system may have several versions of man pages. E.g. my cygwin installation has these for "ls":
- c:/cygwin/usr/man/man1/ls.1 -- ls (fileutils) 4.1 (April 2001)
- c:/cygwin/usr/share/man/man1/ls.1.gz -- GNU coreutils 8.5 (June 2010)
In this case woman.el asks you to select one.
This is distracting if you are in the middle of something and want to quickly refer to man, and don't care about the particular version.

I attach a small patch for woman.el that fixes this.
Tested on: GNU Emacs 24.0.50.1 (i386-mingw-nt5.1.2600) of 2010-11-10 on SHAN-PC

It's less than 20 lines (I've signed a GPL waiver before, but that was like 10 years ago).

Cheers! V


[-- Attachment #2: woman.patch --]
[-- Type: application/octet-stream, Size: 1135 bytes --]

2010-12-23  Vladimir Alexiev  <vladimir@sirma.bg>

	* woman.el (woman-file-name): custom option `woman-use-first-file'
	to use the first file found, if multiple files match the man topic.

--- c:/emacs/lisp/woman.el	2010-11-10 08:39:48.000000000 +0200
+++ woman.el	2010-12-25 11:41:56.796875000 +0200
@@ -809,4 +809,11 @@
   :group 'woman-interface)
 
+(defcustom woman-use-file-directly nil
+  "If multiple files match the man topic, use the first or last file directly."
+  :type '(choice (const :tag "No" nil)
+		 (const :tag "First" 'first)
+                 (const :tag "Last" 'last))
+  :group 'woman-interface)
+
 (defvar woman-file-regexp nil
   "Regexp used to select (possibly compressed) man source files, e.g.
@@ -1320,4 +1327,6 @@
        ((null files) nil)		; no file found for topic.
        ((null (cdr files)) (car (car files))) ; only 1 file for topic.
+       ((eq 'first woman-use-file-directly) (car (car files))) ; use the first file
+       ((eq 'last woman-use-file-directly) (car (car (last files)))) ; use the last file
        (t
 	;; Multiple files for topic, so must select 1.

Re: [PATCH] woman.el (woman-file-name): custom option `woman-use-file-directly'

[Chong Yidong]

"Vladimir Alexiev" <vladimir@sirma.bg> writes:

> Sometimes a system may have several versions of man pages. E.g. my
> cygwin installation has these for "ls":
> - c:/cygwin/usr/man/man1/ls.1 -- ls (fileutils) 4.1 (April 2001)
> - c:/cygwin/usr/share/man/man1/ls.1.gz -- GNU coreutils 8.5 (June 2010)
> In this case woman.el asks you to select one.
> This is distracting if you are in the middle of something and want to
> quickly refer to man, and don't care about the particular version.
>
> I attach a small patch for woman.el that fixes this.
>
> It's less than 20 lines (I've signed a GPL waiver before, but that was
> like 10 years ago).

This is along the right lines, but there ought to be a way to
interactively get woman to view the other versions.  Unfortunately, the
prefix arg for M-x woman is already used to toggle the RE-CACHE arg.

Maybe a prefix arg should re-cache in addition to changing the
`woman-use-file-directly' effect.  I don't think the former
functionality is commonly used, anyway.

Re: [PATCH] woman.el (woman-file-name): custom option `woman-use-file-directly'

[Stefan Monnier]

> This is along the right lines, but there ought to be a way to
> interactively get woman to view the other versions.  Unfortunately, the
> prefix arg for M-x woman is already used to toggle the RE-CACHE arg.

> Maybe a prefix arg should re-cache in addition to changing the
> `woman-use-file-directly' effect.  I don't think the former
> functionality is commonly used, anyway.

Another approach is to do what M-x man does: show you the first "page"
found, together with the number of "pages" found and a command to switch
to subsequent ones.


        Stefan

RE: [PATCH] woman.el (woman-file-name): custom option `woman-use-file-directly'

[Vladimir Alexiev]

> there ought to be a way to
> interactively get woman to view the other versions.  Unfortunately, the
> prefix arg for M-x woman is already used to toggle the RE-CACHE arg.

Oops, I didn't see this arg.
I think it makes sense to integrate my option with the RE-CACHE arg, since if you want to re-cache you'll likely want to select explicitly.
Renaming to woman-file-name-option:

(defcustom woman-file-name-option nil
  "Whether to use the cached list of topics, and whether to select automatically if multiple files match a requested topic.
The values are such that they can be entered as interactive prefix argument to the (woman) command."
  :type '(choice (const :tag "Use first file, cached (default)" nil) ; TODO: changes the current default, is this ok?
		 (const :tag "Use first file, cached (M-1)" 1)
		 (const :tag "Use last file, cached (M-0)" 0)
		 (const :tag "Select file using completion, cached (C-u)" '(4))
		 (const :tag "Re-cache, Use first file (M--1)" -1)
		 (const :tag " Re-cache, Use last file, re-cache (M--)" '-)
		 (const :tag " Re-cache, Select file using completion (C-u C-u)" 16)
  :group 'woman-interface)

(woman &optional TOPIC ARG)
  "Browse UN*X man page for TOPIC (Without using external Man program).
The major browsing mode used is essentially the standard Man mode.
Choose the filename for the man page, based on the topic selected from 
the directories specified in `woman-manpath' and `woman-path'.
The directory expansions and topics are cached for speed.

The prefix argument ARG determines whether to use the cached list of topics, 
and whether to select automatically if multiple files match a requested topic.
It is interpreted as the choices for `woman-file-name-option': customize it to see what they mean.
No argument means use the current value of  `woman-file-name-option'."

;; And similarly for (woman-file-name)

Re: [PATCH] woman.el (woman-file-name): custom option `woman-file-name-option'

[Vladimir Alexiev]

If the woman.el maintainer likes the idea of `woman-file-name-option',
I'll submit a proper patch.