run-help: Support for svn and git

run-help: Support for svn and git

[Jörg Sommer]

Hi,

calling run-help for svn or git is often not very helpful. svn has no
real information in the manpage and the infos for git blubb are in
git-blubb (not git). So, run-help should pay attention to the subcommand
for git and should call svn help subcommand |pager. My proposal:

#v+
--- /usr/share/zsh-beta/functions/Misc/run-help	2007-12-26 00:58:01.000000000 +0100
+++ /tmp/run-help	2007-12-30 20:18:37.530179261 +0100
@@ -12,8 +12,37 @@
 
 : ${HELPDIR:=/usr/share/zsh-beta/help}
 
-[[ $1 == "." ]] && 1="dot"
-[[ $1 == ":" ]] && 1="colon"
+local subcmd
+subcmd=
+
+case $1 in
+  (.) 1=dot;;
+  (:) 1=colon;;
+  (git|sv[kn])
+    local full_cmd
+    builtin getln full_cmd
+    builtin print -z "$full_cmd"
+    local i
+    for i in ${(z)full_cmd#*$1}; do      # remove VARIABLE=... $1
+        case "$i" in
+          (-*) ;;
+          (*)
+            case $1 in
+              (git)
+                if al=$(git config --get "alias.$i"); then
+                    1="git-${al%% *}"
+                else
+                    1="git-$i"
+                fi
+                ;;
+              (sv[kn]) subcmd=$i;;
+            esac
+            break
+            ;;
+        esac
+    done
+    ;;
+esac
 
 if [[ $# == 0 || $1 == "-l" ]]
 then
@@ -85,7 +114,11 @@
 	man zsh-betamisc
 	;;
     (*)
+        if [[ -n "${subcmd:-}" ]]; then
+            ((! didman++)) && $1 help $subcmd | ${=PAGER:-/usr/bin/pager}
+        else
 	((! didman++)) && man $@
+        fi
 	;;
     esac
     if ((i < $#places && ! didman))
#v-

Would you include this change?

Bye, Jörg.
-- 
Es liegt in der Natur des Menschen, vernünftig zu denken und
unlogisch zu handeln! Das Gesagte ist nicht das Gemeinte und das Gehörte
nicht das Verstandene!

Re: run-help: Support for svn and git

[Bart Schaefer]

On Dec 30,  7:19pm, joerg@alea.gnuu.de wrote:
}
} calling run-help for svn or git is often not very helpful.
} 
} Would you include this change?

I don't think there's any reason to give git and/or svn any special
treatment that isn't applied to (say) cvs or apt or yum or ztcp or
zftp or any other command that uses "subcommands".

I also don't think it's the right approach to build special knowledge
into run-help of all possible commands that have subcommands.

If we're going to make a change for this it should be one that can
also be applied to "perl someprog.plx" or "sh yourscript.sh".

So, how about the below (which replaces the patch I sent in 243260).
This looks for a function (or alias or command) named "run-help-$1",
e.g. run-help-git or run-help-svn or run-help-perl or whatever.  If
one is found, it invokes that, otherwise it invokes "man" as always.

Then one can do:

    run-help-svn () {
      local cmd_args
      cmd_args=( ${@:#-*} )
      svn help $cmd_args[1]
    }

And something similar for git.

Of course at this point we ought to add something to the manual (in the
contributions section, perhaps?) about the run-help function and its,
um, helpers.

Index: Functions/Misc/run-help
===================================================================
diff -c -r1.3 run-help
--- Functions/Misc/run-help	30 May 2007 03:36:56 -0000	1.3
+++ Functions/Misc/run-help	31 Dec 2007 02:51:44 -0000
@@ -85,7 +85,20 @@
 	man zshmisc
 	;;
     (*)
-	((! didman++)) && man $@
+        set -- $@:t
+	if ((! didman++))
+	then
+	    if whence -w "run-help-$1" >/dev/null
+	    then
+		local cmd_args
+		builtin getln cmd_args
+		builtin print -z "$cmd_args"
+		cmd_args=( ${${(z)cmd_args}[2,-1]} )
+		eval "run-help-$1 $cmd_args[@]"
+	    else
+		man $1
+	    fi
+	fi
 	;;
     esac
     if ((i < $#places && ! didman))

Re: run-help: Support for svn and git

[Jörg Sommer]

Hi Bart,

Bart Schaefer <schaefer@brasslantern.com> wrote:
> On Dec 30,  7:19pm, joerg@alea.gnuu.de wrote:
> }
> } calling run-help for svn or git is often not very helpful.
> } 
> } Would you include this change?
>
> I don't think there's any reason to give git and/or svn any special
> treatment

ACK.

> I also don't think it's the right approach to build special knowledge
> into run-help of all possible commands that have subcommands.

Yes, yours is a better approach. It's more generic.

> Then one can do:
>
>     run-help-svn () {
>       local cmd_args
>       cmd_args=( ${@:#-*} )
>       svn help $cmd_args[1]

I'm not very familiar with zsh programming. So this question might sound
stupid, but why do you create a new variable? Why don't you use
${${@:#-*}[1]} ?

Is it possible to get the point where run-help was called? Maybe for

  ssh -option <1> host cmd <2>

run-help invoked at <1> opens the manpage of ssh and at <2> it opens the
manpage of cmd.

> Index: Functions/Misc/run-help
> ===================================================================
> diff -c -r1.3 run-help
> --- Functions/Misc/run-help	30 May 2007 03:36:56 -0000	1.3
> +++ Functions/Misc/run-help	31 Dec 2007 02:51:44 -0000
> @@ -85,7 +85,20 @@
>  	man zshmisc
>  	;;
>      (*)
> -	((! didman++)) && man $@
> +        set -- $@:t
> +	if ((! didman++))
> +	then
> +	    if whence -w "run-help-$1" >/dev/null

Why do you use -w, while you throw the output away.

> +	    then
> +		local cmd_args
> +		builtin getln cmd_args
> +		builtin print -z "$cmd_args"
> +		cmd_args=( ${${(z)cmd_args}[2,-1]} )
> +		eval "run-help-$1 $cmd_args[@]"

Where do you remove the part before $1, e.g. LANG=bla? Why do you have to
use eval? Doesn't run-help-$1 work?

Bye, Jörg.
-- 
Wer einen Traum verwirklichen will, muss erst aufwachen.

Re: run-help: Support for svn and git

[Bart Schaefer]

On Dec 31, 12:10pm, joerg@alea.gnuu.de wrote:
} Subject: Re: run-help: Support for svn and git
}
} >     run-help-svn () {
} >       local cmd_args
} >       cmd_args=( ${@:#-*} )
} >       svn help $cmd_args[1]
} 
} I'm not very familiar with zsh programming. So this question might sound
} stupid, but why do you create a new variable? Why don't you use
} ${${@:#-*}[1]} ?

No particular reason except that the above evolved from a couple of
earlier attempts that had the "getln" part in the helper instead of
in run-help.
 
} Is it possible to get the point where run-help was called? Maybe for
} 
}   ssh -option <1> host cmd <2>

Not from within the run-help shell function.  For that one would need
information that's only available inside the ZLE widget.  In fact,
that's probably why nobody has bothered with improving run-help much
before:  Most people just hit TAB at those places and rely on the help
strings from the completion function to tell them what they can do.

One could replace the run-help widget itself with something that takes
the line apart with $LBUFFER and $RBUFFER and analyzes it in more
detail, and if run-help had been invented after user-defined widgets
were, it would probably never have been designed the way it is.
 
} > +	    if whence -w "run-help-$1" >/dev/null
} 
} Why do you use -w, while you throw the output away.

Evolution again.  At one point I thought I cared what type of command
it was.

} > +		cmd_args=( ${${(z)cmd_args}[2,-1]} )
} > +		eval "run-help-$1 $cmd_args[@]"
} 
} Where do you remove the part before $1, e.g. LANG=bla?

Ah, I missed that bit.  I wondered why you were doing ${full_cmd#*$1}.
Yours doesn't quite work, either; consider something like

    PATH=/opt/cvs/bin:$PATH cvs commit ...

(which admittedly is contrived, but demonstrative).

} Why do you have to use eval? Doesn't run-help-$1 work?

Aliases would not be expanded without the eval, and I wanted one to
be able to do e.g.:  alias run-help-perl=perldoc

Here's a new patch.

Index: run-help
===================================================================
RCS file: /extra/cvsroot/zsh/zsh-4.0/Functions/Misc/run-help,v
retrieving revision 1.3
diff -c -r1.3 run-help
--- run-help	30 May 2007 03:36:56 -0000	1.3
+++ run-help	31 Dec 2007 16:13:25 -0000
@@ -85,7 +85,24 @@
 	man zshmisc
 	;;
     (*)
-	((! didman++)) && man $@
+	if ((! didman++))
+	then
+	    if whence "run-help-$1:t" >/dev/null
+	    then
+		local cmd_args
+		builtin getln cmd_args
+		builtin print -z "$cmd_args"
+		cmd_args=( ${(z)cmd_args} )
+		# Discard environment assignments, etc.
+		while [[ $cmd_args[1] != $1 ]]
+		do
+		    shift cmd_args
+		done
+		eval "run-help-$1:t ${(@)cmd_args[2,-1]}"
+	    else
+		man $@:t
+	    fi
+	fi
 	;;
     esac
     if ((i < $#places && ! didman))


-- 

Re: run-help: Support for svn and git

[Jörg Sommer]

Hi,

Bart Schaefer <schaefer@brasslantern.com> wrote:
> On Dec 31, 12:10pm, joerg@alea.gnuu.de wrote:
> } Subject: Re: run-help: Support for svn and git
> } Is it possible to get the point where run-help was called? Maybe for
> } 
> }   ssh -option <1> host cmd <2>
>
> One could replace the run-help widget itself with something that takes
> the line apart with $LBUFFER and $RBUFFER and analyzes it in more
> detail, and if run-help had been invented after user-defined widgets
> were, it would probably never have been designed the way it is.

Isn't it enough to replace the widget by a shell function and register it
with zle?

> Here's a new patch.

Would you apply it to the repository? Here are the functions for svn, svk
and git:

run-help-svn()
{
    svn help ${${@:#-*}[1]} | ${=PAGER:-/usr/bin/pager}
}

run-help-svk()
{
    svk help ${${@:#-*}[1]} | ${=PAGER:-/usr/bin/pager}
}

run-help-git()
{
    if [ $# -eq 0 ]; then
        man git
    else
        local al
        if al=$(git config --get "alias.$1"); then
            1=${al%% *}
        fi
        man git-$1
    fi
}

Bye, Jörg.
-- 
Diskusion „Pascal vs. Rest der Welt“:
30 Aug 2000 00:13:11 GMT, Adrian Knoth <adi@drcomp.erfurt.thur.de>
Und selbst wenn eure 100000 Zeilen‐Programme noch so oft unter Windows
verwendet werden: mit einem Handwagen fährt man nicht Formel‐1.

Re: run-help: Support for svn and git

[Bart Schaefer]

On Dec 31,  5:26pm, joerg@alea.gnuu.de wrote:
}
} Bart Schaefer <schaefer@brasslantern.com> wrote:
} > One could replace the run-help widget itself with something that takes
} > the line apart with $LBUFFER and $RBUFFER and analyzes it
} 
} Isn't it enough to replace the widget by a shell function and register
} it with zle?

That's what I meant.  (A widget is never really directly replaced by a
shell function -- a new widget is created that is implemented by the
shell function, and then the original widget's name may be pointed at
the new widget.)

Re: run-help: Support for svn and git

[Jörg Sommer]

Hi,

Bart Schaefer <schaefer@brasslantern.com> wrote:
> Of course at this point we ought to add something to the manual (in the
> contributions section, perhaps?) about the run-help function and its,
> um, helpers.

Is run-help really an alias, by default? At Debian it is the function
from Functions/Misc.

The first patch changes the text for the case the alias is not the
default and the second one explains the new behaviour.

--- contrib.yo+	2007-12-31 18:41:54.000000000 +0100
+++ contrib.yo	2007-12-31 18:54:23.000000000 +0100
@@ -31,10 +31,10 @@
 ifzman(zmanref(zshzle))\
 ifnzman(noderef(Zsh Line Editor))\
 ).  This invokes the tt(run-help) command with the command word from the
-current input line as its argument.  By default, tt(run-help) is an alias
-for the tt(man) command, so this often fails when the command word is a
-shell builtin or a user-defined function.  By redefining the tt(run-help)
-alias, one can improve the on-line help provided by the shell.
+current input line as its argument.  tt(run-help) can simply be an alias
+for the tt(man) command, but so this often fails when the command word is a
+shell builtin or a user-defined function.  By default, tt(run-help)
+is an more intelligent function found in tt(Functions/Misc).
 
 The tt(helpfiles) utility, found in the tt(Util) directory of the
 distribution, is a Perl program that can be used to process the zsh manual
@@ -61,23 +61,13 @@
 Next, to use the tt(run-help) function, you need to add lines something
 like the following to your tt(.zshrc) or equivalent startup file:
 
-example(unalias run-help
-autoload run-help
-HELPDIR=~/zsh_help)
+example(HELPDIR=~/zsh_help)
 
 vindex(HELPDIR)
 The tt(HELPDIR) parameter tells tt(run-help) where to look for the help
 files.  If your system already has a help file directory installed, set
 tt(HELPDIR) to the path of that directory instead.
 
-Note that in order for `tt(autoload run-help)' to work, the tt(run-help)
-file must be in one of the directories named in your tt(fpath) array (see
-ifzman(zmanref(zshparam))\
-ifnzman(noderef(Parameters Used By The Shell))\
-).  This should already be the case if you have a standard zsh
-installation; if it is not, copy tt(Functions/Misc/run-help) to an
-appropriate directory.
-
 subsect(Recompiling Functions)
 cindex(functions, recompiling)
 cindex(zrecompile utility)

diff -u contrib.yo contrib.yo
--- contrib.yo	2007-12-31 18:54:23.000000000 +0100
+++ contrib.yo	2007-12-31 19:18:01.000000000 +0100
@@ -68,6 +68,40 @@
 files.  If your system already has a help file directory installed, set
 tt(HELPDIR) to the path of that directory instead.
 
+If a command, alias or function tt(run-help-CMD) exists than tt(run-help)
+executes this to get help for the command tt(CMD) and passes to it all
+arguments of the command. This way you can define specialised functions
+for some commands. Here are some examples:
+
+example(run-help-svn()
+{
+    svn help ${${@:#-*}[1]} | ${=PAGER:-/usr/bin/pager}
+})
+
+example(run-help-git()
+{
+    if [ $# -eq 0 ]; then
+        man git
+    else
+        local al
+        if al=$(git config --get "alias.$1"); then
+            1=${al%% *}
+        fi
+        man git-$1
+    fi
+})
+
+example(run-help-ssh()
+{
+    local args
+    args=(${@:#-*})
+    if [ ${#args} -lt 2 ]; then
+        man ssh
+    else
+        run-help $args[2]
+    fi
+})
+
 subsect(Recompiling Functions)
 cindex(functions, recompiling)
 cindex(zrecompile utility)

Bye, Jörg.
-- 
“Perl—the only language that looks the same
 before and after RSA encryption.”           (Keith Bostic)

Re: run-help: Support for svn and git

[Bart Schaefer]

On Dec 31,  6:24pm, joerg@alea.gnuu.de wrote:
} Subject: Re: run-help: Support for svn and git
}
} Is run-help really an alias, by default? At Debian it is the function
} from Functions/Misc.

Yes, it really is an alias by default.

schaefer[515] Src/zsh -f
torch% alias
run-help=man
which-command=whence
torch% 

There must be something in the /etc/z* files installed with the Debian
zsh package that removes the alias and loads the function instead.

Re: run-help: Support for svn and git

[Clint Adams]

On Mon, Dec 31, 2007 at 01:08:40PM -0800, Bart Schaefer wrote:
> There must be something in the /etc/z* files installed with the Debian
> zsh package that removes the alias and loads the function instead.

Right, the tail end of the global zshrc unaliases and autoloads it.
The function is also modified slightly; I'm not sure how to make it
more generic without doing a build-time replacement.

--- Functions/Misc/run-help	2007-12-17 14:52:56.000000000 -0500
+++ debian/run-help	2008-01-03 19:15:30.000000000 -0500
@@ -2,19 +2,19 @@
 #
 # Figure out where to get the best help, and get it.
 #
-# Install this function by placing it in your FPATH and then
-# adding to your .zshrc the lines:
-#	unalias run-help
-#	autoload run-help
+# This version adapted for Debian GNU/Linux by Robert Leslie <rob@mars.org>
+# from source written by Bart Schaefer <schaefer@brasslantern.com>,
+# and modified by Clint Adams <schizo@debian.org>.
 #
 
 emulate -R zsh
 setopt localoptions
 
+: ${HELPDIR:=/usr/share/zsh/help}
+
 [[ $1 == "." ]] && 1="dot"
 [[ $1 == ":" ]] && 1="colon"
 
-# Check whether Util/helpfiles has been used to generate zsh help
 if [[ $# == 0 || $1 == "-l" ]]
 then
     if [[ -n "${HELPDIR:-}" && -d $HELPDIR ]]
@@ -28,7 +28,7 @@
     return 0
 elif [[ -n "${HELPDIR:-}" && -r $HELPDIR/$1 && $1 != compctl ]]
 then
-    ${=PAGER:-more} $HELPDIR/$1
+    ${=PAGER:-/usr/bin/pager} $HELPDIR/$1
     return $?
 fi
 
@@ -61,7 +61,7 @@
 	case ${what[(w)1]} in
 	(comp*) man zshcompsys;;
 	(zf*) man zshftpsys;;
-	(*) builtin functions ${what[(w)1]} | ${=PAGER:-more};;
+	(*) builtin functions ${what[(w)1]} | ${=PAGER:-/usr/bin/pager};;
 	esac;;
     (*( is a * builtin))
 	case ${what[(w)1]} in

Re: run-help: Support for svn and git

[Bart Schaefer]

On Jan 3,  7:18pm, Clint Adams wrote:
}
} +# This version adapted for Debian GNU/Linux by Robert Leslie <rob@mars.org>
} +# from source written by Bart Schaefer <schaefer@brasslantern.com>,
} +# and modified by Clint Adams <schizo@debian.org>.

Wow, I don't remember if I'm really the original author of run-help.
I see that I sent it to zsh-workers back in August 1996, so I guess I
must be.  However, Jeorg Sommer ought to get some credit for the idea
behind the run-help-$1 part.

Re: run-help: Support for svn and git

[Clint Adams]

On Thu, Jan 03, 2008 at 07:21:34PM -0800, Bart Schaefer wrote:
> Wow, I don't remember if I'm really the original author of run-help.
> I see that I sent it to zsh-workers back in August 1996, so I guess I
> must be.  However, Jeorg Sommer ought to get some credit for the idea
> behind the run-help-$1 part.

I'd be happier to ditch the fork, attributions and all.

With this I can just
sed 's,^# HELPDIR should be.*,: ${HELPDIR:=/usr/share/zsh/help},;s,:-more,:-/usr/bin/pager,' Functions/Misc/run-help

Better ideas are welcome.

Index: Functions/Misc/run-help
===================================================================
RCS file: /cvsroot/zsh/zsh/Functions/Misc/run-help,v
retrieving revision 1.8
diff -u -r1.8 run-help
--- Functions/Misc/run-help	31 Dec 2007 22:13:47 -0000	1.8
+++ Functions/Misc/run-help	4 Jan 2008 04:26:18 -0000
@@ -11,6 +11,8 @@
 emulate -R zsh
 setopt localoptions
 
+# HELPDIR should be set to the location of the help files
+
 [[ $1 == "." ]] && 1="dot"
 [[ $1 == ":" ]] && 1="colon"
 

Re: run-help: Support for svn and git

[Bart Schaefer]

On Jan 3, 11:32pm, Clint Adams wrote:
} Subject: Re: run-help: Support for svn and git
}
} With this I can just
} sed 's,^# HELPDIR should be.*,: ${HELPDIR:=/usr/share/zsh/help},;s,:-more,:-/usr/bin/pager,' Functions/Misc/run-help
} 
} Better ideas are welcome.

Not having a Debian install available anywhere, I'm not sure what
/usr/bin/pager does.  Is there a reason you can't simply assign to
$PAGER in /etc/z* as well?  With appropriate checks that it isn't
already set to something else, of course.
 
Then, how about this?  It's not really a problem to have a default
value of HELPDIR in the function, since we check that it exists.  I
suppose if someone wanted to explicitly turn OFF the use of HELPDIR,
this would be a problem ... is that worth worrying about?

Also, would /usr/share/zsh/$ZSH_VERSION/help be more appropriate?

Index: Functions/Misc/run-help
===================================================================
diff -c -r1.3 run-help
--- Functions/Misc/run-help	30 May 2007 03:36:56 -0000	1.3
+++ Functions/Misc/run-help	5 Jan 2008 17:38:35 -0000
@@ -11,13 +11,15 @@
 emulate -R zsh
 setopt localoptions
 
+local HELPDIR="${HELPDIR:-/usr/share/zsh/help}"
+
 [[ $1 == "." ]] && 1="dot"
 [[ $1 == ":" ]] && 1="colon"
 
 # Check whether Util/helpfiles has been used to generate zsh help
 if [[ $# == 0 || $1 == "-l" ]]
 then
-    if [[ -n "${HELPDIR:-}" && -d $HELPDIR ]]
+    if [[ -d $HELPDIR ]]
     then
 	echo "Here is a list of topics for which special help is available:"
 	echo ""

Re: run-help: Support for svn and git

[Clint Adams]

On Sat, Jan 05, 2008 at 10:05:18AM -0800, Bart Schaefer wrote:
> Not having a Debian install available anywhere, I'm not sure what
> /usr/bin/pager does.  Is there a reason you can't simply assign to
> $PAGER in /etc/z* as well?  With appropriate checks that it isn't
> already set to something else, of course.

/usr/bin/pager is just a symlink to the system's preferred pager.
Debian policy dictates that software wanting to use a pager should
first check $PAGER, running /usr/bin/pager if that's unset.

> Then, how about this?  It's not really a problem to have a default
> value of HELPDIR in the function, since we check that it exists.  I
> suppose if someone wanted to explicitly turn OFF the use of HELPDIR,
> this would be a problem ... is that worth worrying about?

This is fine by me.

> Also, would /usr/share/zsh/$ZSH_VERSION/help be more appropriate?

I'd still have to sed it, but it probably makes more sense for
people installing from source.

Re: run-help: Support for svn and git

[Bart Schaefer]

On Jan 9,  2:07pm, Clint Adams wrote:
}
} > Also, would /usr/share/zsh/$ZSH_VERSION/help be more appropriate?
} 
} I'd still have to sed it, but it probably makes more sense for
} people installing from source.

I've committed it this way.

Re: run-help: Support for svn and git

[Jörg Sommer]

Hallo Clint,

Clint Adams <schizo@debian.org> wrote:
> On Mon, Dec 31, 2007 at 01:08:40PM -0800, Bart Schaefer wrote:
>> There must be something in the /etc/z* files installed with the Debian
>> zsh package that removes the alias and loads the function instead.
>
> Right, the tail end of the global zshrc unaliases and autoloads it.
> The function is also modified slightly; I'm not sure how to make it
> more generic without doing a build-time replacement.

Don't you use dpatch or thelike? Where is the problem?

Bye, Jörg.
-- 
Der kommt den Göttern am nächsten, der auch dann schweigen kann,
wenn er im Recht ist.                         (Cato; 234–149 v. Chr.)