[PATCH] (woman-always-choose-first-hit): New defcustom.

[PATCH] (woman-always-choose-first-hit): New defcustom.

[Eric Hanchrow]

From: Eric Hanchrow <erich@cozi.com>

---
 lisp/woman.el |   11 +++++++++++
 1 files changed, 11 insertions(+), 0 deletions(-)

diff --git a/lisp/woman.el b/lisp/woman.el
index b7b856c..a459f7c 100644
--- a/lisp/woman.el
+++ b/lisp/woman.el
@@ -654,6 +654,16 @@ of `woman-expand-locale' on `woman-locale' added, where they exist."
         ;; Non-locale-specific has lowest precedence.
         (add-to-list 'lst elem)))))
 
+(defcustom woman-always-choose-first-hit nil
+  "If t, and we find more than one file for the given topic,
+  simply return the first topic, without prompting.  This is
+convenient if you have two sets of man pages for one program, and
+always want to look at just one of them."
+  :type 'boolean
+  :version "23.1"                    ; added woman-manpath-add-locales
+  :group 'woman-interface
+  :link '(function-link woman-file-name))
+
 (defcustom woman-manpath
   ;; Locales could also be added in woman-expand-directory-path.
   (or (woman-manpath-add-locales
@@ -1341,6 +1351,7 @@ cache to be re-read."
       (cond
        ((null files) nil)		; no file found for topic.
        ((null (cdr files)) (car (car files))) ; only 1 file for topic.
+       (woman-always-choose-first-hit (car (car files))) ; user asked to never be prompted
        (t
 	;; Multiple files for topic, so must select 1.
 	;; Unread the command event (TAB = ?\t = 9) that runs the command
-- 
1.6.2.rc1.20.g8c5b

Re: [PATCH] (woman-always-choose-first-hit): New defcustom.

[Richard M Stallman]

The name `woman-always-choose-first-hit' suggests some other somewhat
disreputable meanings.  If this feature is to be installed, I suggest
the name `woman-auto-first-match' instead.

Note also that the first line of a doc string must stand on its own.

Re: [PATCH] (woman-always-choose-first-hit): New defcustom.

[Stefan Monnier]

> The name `woman-always-choose-first-hit' suggests some other somewhat
> disreputable meanings.  If this feature is to be installed, I suggest
> the name `woman-auto-first-match' instead.

> Note also that the first line of a doc string must stand on its own.

Actually, why doesn't woman act like man, showing the first manual it
found, along with the number it found and some way to switch to the
next/previous?


        Stefan

Re: [PATCH] (woman-always-choose-first-hit): New defcustom.

[Richard M Stallman]

    Actually, why doesn't woman act like man,

That question has been asked for a long time ;-).

RE: [PATCH] (woman-always-choose-first-hit): New defcustom.

[Drew Adams]

>     Actually, why doesn't woman act like man,
> 
> That question has been asked for a long time ;-).

Or to use the active voice, and leave no doubt about the actor:

_Men_ have asked that question for a long time.

Re: RE: [PATCH] (woman-always-choose-first-hit): New defcustom.

[xahlee]

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

the number of times i tried to use WoMan as a replacement of unix's
“man” utility, but i find it unusable. Here's some problems i encountered:

• I had aliased “man” to “woman”, but noticed that sometimes when i type  
“Mx man” it still calls “man” despite this. (haven't looked into what  
causes this or how this happens)

• When calling “woman”, it takes some 3 secs to start up. (probably only  
happen when called first time in a session) On the other hand, “man” starts  
right away without this delay.
(The message is: “Building list of manual directory expansions...”,
“Building completion list of all manual topics...”)

• often “woman” will prompt me to make a choice. Very annoying. From my  
experiences in unix using in the past 10 years, maybe once a year when  
“man” didn't make the right choice. (hopefully the patch in this thread  
fixes this)

• another flaw, perhaps reasonable, is that “woman” does not work for some  
“man” pages. eg recently i was trying to do “woman” on “killall” on OS X  
10.4.x, and it returns
“.Dd June 25, 1995
.Os
.Dt KILLALL 1
.Sh NAME
.Nm killall
...”

The advantage to me for using “woman” is that it does syntax coloring.  
Possibly “man” can do too but i have not explored.

Xah

☄

[-- Attachment #2: Type: text/html, Size: 1432 bytes --]

Re: [PATCH] (woman-always-choose-first-hit): New defcustom.

[Eli Zaretskii]

> Date: Wed, 11 Mar 2009 23:08:09 +0000
> From: xahlee@gmail.com
> Cc: 
> 
> the number of times i tried to use WoMan as a replacement of unix's
> “man” utility, but i find it unusable. Here's some problems i encountered:

The problems you mention are a far cry from making WoMan ``unusable''.

> • I had aliased “man” to “woman”, but noticed that sometimes when i type  
> “Mx man” it still calls “man” despite this. (haven't looked into what  
> causes this or how this happens)

How's that a problem with WoMan?

> • When calling “woman”, it takes some 3 secs to start up.

What kind of a CPU do you have?  Here it takes 1 second.

> (probably only happen when called first time in a session)

Yes.

> On the other hand, “man” starts right away without this delay.

And then does the same after you type RET.  The advantage of WoMan is
that it offers you completion for man-page names, while `man' doesn't.

> • another flaw, perhaps reasonable, is that “woman” does not work for some  
> “man” pages. eg recently i was trying to do “woman” on “killall” on OS X  
> 10.4.x, and it returns
> “.Dd June 25, 1995
> .Os
> .Dt KILLALL 1
> .Sh NAME
> .Nm killall
> ...”

And why do you think `man' doesn't have such problems, sometimes?  It
all depends on the troff back-end you have installed vs the man pages.

Re: Re: [PATCH] (woman-always-choose-first-hit): New defcustom.

[xahlee]

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

Eli Zaretskii wrote:
> • The problems you mention are a far cry from making WoMan ``unusable''.

“unusable” is probably a exaggeration. I'm trying to express how it is  
unusable to most users who are not emacs enthusiasts.

consider emacs as a tool, and likewise man and woman are tools. People want  
to run man/woman mostly to get the job done, namely, reading unix man page  
in emacs. “man” works. However, woman is a improvement, but isn't default.  
The extra option of minor improvement to user adds a slight complexity. But  
adding the fact that woman itself provides some rough edges. So for some  
emacs user who are beginning to be adventurous, when they read about woman  
and try it, its problem is frustrating, another tiny time drain in emacs.

Each thing individually are trivial problems, but emacs with so many  
unusual streaks, terminologies, keyboard shortcut notation, unusual undo,  
etc, earns emacs the steep learning curve and drive away most professional  
programers.

I think most, or all of these can be fixed, without sacrificing ANY of  
emacs's power.

back to the particular case of woman... for example, i think that:

• man and woman should be merged, in the sense that user are taught one  
single command “man” to read unix manual page. This can possibly be done by  
aliasing man to woman, and:

• the onset delay of woman can certainly be minimized, perhaps by looking  
into ways to optimize, cache, or done after the first call of woman, in the  
background. (eg when user is not typing actively) (so that, at the second  
call of woman in a session, name completion feature is there,  
transparently) Here, i think caching it under “~/.emacs.d/” is probably a  
very good solution.

• when woman detect a page it cannot read, launch man.

• eliminate the fact that woman prompt user to make a choice. (which i  
think this thread's patch fixes)

Xah
∑ http://xahlee.org/

☄

------------------------------
> [aliasing man to woman sometimes doesn't work]
> How's that a problem with WoMan?
> And then does the same after you type RET. The advantage of WoMan
> is that it offers you completion for man-page names, while `man'
> doesn't.
> And why do you think `man' doesn't have such problems, sometimes?
> It all depends on the troff back-end you have installed vs the man
> pages.

On Mar 11, 2009 9:13pm, Eli Zaretskii <eliz@gnu.org> wrote:
> Date: Wed, 11 Mar 2009 23:08:09 +0000
> From: xahlee@gmail.com
> Cc:

> the number of times i tried to use WoMan as a replacement of unix's
> “man” utility, but i find it unusable. Here's some problems i encountered:

The problems you mention are a far cry from making WoMan ``unusable''.

> • I had aliased “man” to “woman”, but noticed that sometimes when i type
> “Mx man” it still calls “man” despite this. (haven't looked into what
> causes this or how this happens)

How's that a problem with WoMan?

> • When calling “woman”, it takes some 3 secs to start up.

What kind of a CPU do you have? Here it takes 1 second.

> (probably only happen when called first time in a session)

Yes.

> On the other hand, “man” starts right away without this delay.

And then does the same after you type RET. The advantage of WoMan is
that it offers you completion for man-page names, while `man' doesn't.

> • another flaw, perhaps reasonable, is that “woman” does not work for some
> “man” pages. eg recently i was trying to do “woman” on “killall” on OS X
> 10.4.x, and it returns
> “.Dd June 25, 1995
> .Os
> .Dt KILLALL 1
> .Sh NAME
> .Nm killall
> ...”

And why do you think `man' doesn't have such problems, sometimes? It
all depends on the troff back-end you have installed vs the man pages.

[-- Attachment #2: Type: text/html, Size: 4305 bytes --]

Re: [PATCH] (woman-always-choose-first-hit): New defcustom.

[Eli Zaretskii]

> Date: Sat, 14 Mar 2009 21:21:47 +0000
> From: xahlee@gmail.com
> 
> Eli Zaretskii wrote:
> > • The problems you mention are a far cry from making WoMan ``unusable''.
> 
> “unusable” is probably a exaggeration. I'm trying to express how it is  
> unusable to most users who are not emacs enthusiasts.

IMO, it is no less usable than `man', to newbies and veterans alike.

> consider emacs as a tool, and likewise man and woman are tools. People want  
> to run man/woman mostly to get the job done, namely, reading unix man page  
> in emacs. “man” works. However, woman is a improvement, but isn't default.  

`woman' is not meant to be an improvement.  From the commentary at the
beginning of woman.el:

    ;; WoMan implements a subset of the formatting performed by the Emacs
    ;; `man' (or `manual-entry') command to format a UN*X manual `page'
    ;; for display, but without calling any external programs.

IOW, it's a clone of `man' that does not require `man' the external
command.  That's all there is to it.  On some platforms, that's a heck
of an advantage; on others, it isn't.

> The extra option of minor improvement to user adds a slight complexity. But  
> adding the fact that woman itself provides some rough edges. So for some  
> emacs user who are beginning to be adventurous, when they read about woman  
> and try it, its problem is frustrating, another tiny time drain in emacs.

`woman' works, period.  So does `man', of course.  Each one has its
quirks and bugs (I fixed one in each just the other day), but they are
minor bugs.  I use both, on 3 radically different platforms, and I
don't find any of them ``frustrating'', nor do they need my Emacs
expertise to show me a manual page in a reasonably legible way.

> I think most, or all of these can be fixed, without sacrificing ANY of  
> emacs's power.

Agreed.

Re: [PATCH] (woman-always-choose-first-hit): New defcustom.

[tomas]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On Sun, Mar 15, 2009 at 12:19:16AM +0200, Eli Zaretskii wrote:
> > Date: Sat, 14 Mar 2009 21:21:47 +0000
> > From: xahlee@gmail.com
> > 
> > Eli Zaretskii wrote:
> > > • The problems you mention are a far cry from making WoMan ``unusable''.
> > 
> > “unusable” is probably a exaggeration. I'm trying to express how it is  
> > unusable to most users who are not emacs enthusiasts.

I must concur  with xahlee here. I have tried woman several times and my
first reaction was "oh, nifty!". But then, many details (the most
prominent being start-up time) drove me away from it. At long last, I'm
still using man on a conventional terminal (and I do use Emacs as my
primary editor most of the time!).

I'm convinced that woman could realize its potential more if criticism
wouldn't be shrugged off like this. Xahlees comments were, after all
quite clear and to the point.

Regards
- -- tomás
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.6 (GNU/Linux)

iD8DBQFJvQvSBcgs9XrR2kYRAiksAJ9WTJHAiup2T6X0EpuTjPcerowpfwCcDhO+
Esx0XVHFCCu/bZcTW/Nm30Q=
=dfSI
-----END PGP SIGNATURE-----

Re: [PATCH] (woman-always-choose-first-hit): New defcustom.

[Richard M Stallman]

      man and woman should be merged,

I used to have fantasies of that.