zsh-workers
 help / color / mirror / code / Atom feed
* generals observations about completion system
@ 2000-09-17 23:33 E. Jay Berkenbilt
  2000-09-19  4:59 ` Bart Schaefer
  0 siblings, 1 reply; 7+ messages in thread
From: E. Jay Berkenbilt @ 2000-09-17 23:33 UTC (permalink / raw)
  To: zsh-workers


As I've been playing in some depth with the completion system lately,
I've had a few general observations which I'd like to make.

The new completion system seems very powerful and highly
configurable at the low level.  This is a really nice feature -- one
that I am quickly becoming quite addicted to.  However, I suspect most
users will probably not customize it too much or write too many of
their own completion functions, and, based on the manual, I suspect
the authors share this belief.

So that means that it would be good if the "standard" completion
functions, i.e., those installed by default, were easily customizable
by users.

The primary way in which this is achieved seems to be through styles.
The zsh documentation, which seems to be well written and far ahead of
the documentation with most systems, it naturally is still somewhat
incomplete about how specific completion functions can be customized
through styles.  Also, it is up to the individual function to support
styles.

I will give a few specific examples of what I'm talking about.

 1.  I have been a Kerberos user for some time.  I like to have the
     Kerberos and non-Kerberos versions of the r* commands in my path.
     Sometimes I call them krlogin, krsh, etc. instead of rlogin, rsh,
     etc.  I wanted zsh to use rlogin's completion rules for krlogin,
     rsh's rules for krsh, and rcp's rules for krcp.  My first attempt
     at doing this was to say

     compdef -a _rlogin krlogin krsh rcp

     This, however, did not work because the code in the _rlogin
     function hard-codes the names of the commands and uses them
     in conditions to decide what specific behavior to use.  It seems
     to me that it would have been better to have three separate
     completion functions here that can share common functions to
     avoid this.  The way I worked around this was to define my own
     completion function called _krlogin which looks like this:

     #compdef krlogin krsh krcp

     # The _rlogin function is conditional on words[1], so we have to
     # fake it out to make it work.
     if [[ $words[1] == /* ]]; then
	words[1]=${words[1]:h}/${${words[1]:t}/#k/}
     else
	words[1]=${words[1]/#k/}
     fi
     _rlogin

 2.  The ssh completion function does not use the user-hosts style
     even though this style is documented.  (If it uses it, I've
     missed it.)  It knows about ssh's ability to say ssh user@host
     rather than ssh host -l user.  You can easily override the list
     of hosts to be completed by setting the hosts style for the ssh
     command, but this doesn't entirely solve the problem.  If I hit

     ssh TAB

     I get a list of all users and hosts.  There are a lot more users
     on my system than there are hosts that I ssh to.  I want to
     change ssh to complete only on hosts, not on users.  If I want
     users, I'll use -l.  There seems to be no good way to do this
     without simply copying and modifying the _ssh file.

     Now I can mitigate this somewhat by saying

     zstyle ':completion:*:*:ssh:*' users ejb

     but this doesn't entirely work either.  If the first character
     that I type doesn't match any users, then the completion system
     falls back to matching against all users.  I haven't figured out
     why whether I can do anything about this.

 3.  Sometimes I think it would be nice to have an "advice"-like
     capability (as in lisp).  That way it would be easier to write
     wrappers for things.  I'm not sure this is really a good
     idea.... I don't know enough about how bindings work in zsh to
     really have a strong opinion....

 4.  It's very hard to know what features are documented reliable
     parts of the interface and what parts aren't.  I could change the
     behavior of the ssh completion function by redefining some of its
     internally defined functions, but that would be evil and I would
     probably find that that would stop working in a future release.
     On the other hand, I feel like a lot of what I'm learning about
     zsh is just from reading the code, and the danger there of course
     is that I may accidentally rely on an internal private part of an
     interface.  Certainly the guideline that things that start with _
     are not intended to be called directly by users is a start, but
     then what about things like my workaround for krlogin?

Anyway, I understand that I'm using a development release of an
experimental version of zsh, so these aren't intended as complaints or
criticisms but more as comments or questions.  Perhaps a lot of this
has already been discussed.

All this said, I love using zsh and think it's a great program,
wrinkles and all!

--
E. Jay Berkenbilt (ejb@ql.org)  |  http://www.ql.org/q/


^ permalink raw reply	[flat|nested] 7+ messages in thread

* Re: generals observations about completion system
  2000-09-17 23:33 generals observations about completion system E. Jay Berkenbilt
@ 2000-09-19  4:59 ` Bart Schaefer
  2000-09-19  9:04   ` Peter Stephenson
  0 siblings, 1 reply; 7+ messages in thread
From: Bart Schaefer @ 2000-09-19  4:59 UTC (permalink / raw)
  To: zsh-workers

On Sep 17,  7:33pm, E. Jay Berkenbilt wrote:
} Subject: generals observations about completion system
}
} I suspect most users will probably not customize it too much or write
} too many of their own completion functions, and, based on the manual,
} I suspect the authors share this belief.
} 
} So that means that it would be good if the "standard" completion
} functions, i.e., those installed by default, were easily customizable
} by users.

Have you tried using "compinstall"?  It does an question-and-answer menu-
driven session to establish likely completion customizations, so that an
"ordinary user" doesn't have to comprehend all the details at once, and
you end up with nice examples of style usage to look at.

} The zsh documentation [...] naturally is still somewhat incomplete

There's also PWS's work-in-progess on-line user's guide:

    http://sunsite.auc.dk/zsh/Guide/zshguide.html

} about how specific completion functions can be customized through
} styles.

It does tend to be easier to add new completion functions than it is to
document them.

} I will give a few specific examples of what I'm talking about.
} 
}      compdef -a _rlogin krlogin krsh rcp
} 
}      This, however, did not work because the code in the _rlogin
}      function hard-codes the names of the commands and uses them
}      in conditions to decide what specific behavior to use.

This same problem exists for _ssh (which it would be nice to use for
the ssh1 and ssh2 versions of those commands), and probably a couple
of others.

}      It seems to me that it would have been better to have three
}      separate completion functions here that can share common
}      functions to avoid this.

The reason that *wasn't* done was to be able to keep all the related
functions together in one file, which has to have the same name as the
function invoked for each of the commands named in the #compdef line.

However ... there isn't any reason the file _rlogin couldn't define
several functions, and issue new `compdef' commands to point rcp and
rsh at different functions.  (In fact, on systems that have `remsh',
`rsh' is not an rlogin-related function at all.)  Stay tuned.

}  2.  The ssh completion function does not use the user-hosts style
}      even though this style is documented.  (If it uses it, I've
}      missed it.)

It does use it; see the _ssh_users and _ssh_hosts functions, at the
end of Completion/User/_ssh.  They get at it via the _combination
helper function.  As documented under the users-hosts style entry:

     If set for the my-accounts tag, this is used for commands such as
     rlogin and ssh; in this case the style should contain the names of
     the user's own accounts on remote hosts.  If set for the
     other-accounts tag, it is used for commands such as talk and
     finger and should contain other people's accounts.  Finally, it
     may also be used by some commands with the accounts tag.

The trouble is that ^Xh can't descend all the way through _combination
to show you the styles and tags that it supports, so all you see are the
separate hosts and users tags.  I don't know what would be involved in
fixing that.

If you've set users-hosts and are still having trouble getting ssh to
use them, it may have something to do with that completer style we've
been discussing in the other thread.

}  3.  Sometimes I think it would be nice to have an "advice"-like
}      capability (as in lisp).  That way it would be easier to write
}      wrappers for things.

There actually is such a capability, sort of, but only compiled zmodload
modules can make use of it.  It might be possible to write an "advice"
module to expose the facility at the user level.  (I'm not going to try
that anytime soon.)

However, maybe what you're looking for is this, from "Utility Functions"
in zsh.info:
----------------------
When writing completion functions or other ZLE widgets that call
completion, it might be interesting to know about two more features
offered by the _main_complete function. The arrays compprefuncs and
comppostfuncs may be set to contain names of functions that are to be
called immediately before or after completion has been tried. The
functions will only be called once, unless they put themselves into the
arrays again.
----------------------

Hmm, it really ought to say a bit more about it than that ...

}  4.  It's very hard to know what features are documented reliable
}      parts of the interface and what parts aren't.

If it's in the documentation, then it's documented. :-)

There's also Etc/completion-style-guide in the distribution, if you're
planning to write functions that can be included in the standard system.

}      Certainly the guideline that things that start with _
}      are not intended to be called directly by users is a start, but
}      then what about things like my workaround for krlogin?

I'd have followed the advice about copying one of the existing completion
functions and modifying it, rather than rely on calling through to it.
(Hmm, I thought that advice appeared somewhere in either the docs or in
completion-style-guide, but now I can't find it.)

More from zsh.info:
----------------------
This describes the shell code for the new completion system.  It
consists of various shell functions; those beginning `comp' are to be
called directly by the user, while those beginning `_' are called by the
completion code.  The shell functions of the second set which implement
completion behaviour and which may be bound to keystrokes, are referred
to as `widgets'.

In the source distribution, the files are contained in various
subdirectories of the Completion directory.  They may have been
installed in the same structure, or into one single function directory.
The following is a description of the files found in the original
directory structure.  If you wish to alter an installed file, you will
need to copy it to some directory which appears earlier in your fpath
than the standard directory where it appears.

The convention for autoloaded functions used in completion is that they
start with an underscore; as already mentioned, the fpath/FPATH
parameter must contain the directory in which they are stored.

When compinit is run, it searches all such files accessible via
fpath/FPATH and reads the first line of each of them.  This line should
contain one of the tags described below.  Files whose first line does
not start with one of these tags are not considered to be part of the
completion system and will not be treated specially.

The # is part of the tag name and no white space is allowed after it.
The #compdef tags use the compdef function described below; the main
difference is that the name of the function is supplied implicitly.

Descriptions follow for utility functions that may be useful when
writing completion functions.  Most of these reside in the Core
subdirectory. Like the example functions for commands in the
distribution, the utility functions generating matches all follow the
convention of returning zero if they generated completions and non-zero
if no matching completions could be added.
----------------------

(The above is clipped from several chapters, you won't find it in that
order anywhere in the document.)

} Anyway, I understand that I'm using a development release of an
} experimental version of zsh, so these aren't intended as complaints or
} criticisms but more as comments or questions.  Perhaps a lot of this
} has already been discussed.

The new completion system is the reason zsh-workers had nearly as many
messages in 1999 as in its entire previous history.  It took a lot of
discussion to get it to where it is now ...

-- 
Bart Schaefer                                 Brass Lantern Enterprises
http://www.well.com/user/barts              http://www.brasslantern.com

Zsh: http://www.zsh.org | PHPerl Project: http://phperl.sourceforge.net   


^ permalink raw reply	[flat|nested] 7+ messages in thread

* Re: generals observations about completion system
  2000-09-19  4:59 ` Bart Schaefer
@ 2000-09-19  9:04   ` Peter Stephenson
  2000-09-19 15:19     ` Bart Schaefer
  2000-09-20 14:33     ` Thoughts on self-documenting functions Bart Schaefer
  0 siblings, 2 replies; 7+ messages in thread
From: Peter Stephenson @ 2000-09-19  9:04 UTC (permalink / raw)
  To: Zsh hackers list

Bart wrote:
> It does tend to be easier to add new completion functions than it is to
> document them.

I haven't had much time for replying (have you seen the specification for
Bluetooth park mode? :-() but self-documenting functions with something
like pod, except using shell functions to strip out the bits and turn them
into yodl, should be pretty easy.  Adding comments is usually much easier
than fiddling with the full documentation.

Moving the string functions to their own file would be a step in the right
direction, too.  It's hard to know what's in utils.c.  (It's not as if the
rest of the shell doesn't consist of utilities, despite the double
negative.)

By the way, I'm finally getting a week's holiday from tomorrow and luckily
in a PC-free zone.

-- 
Peter Stephenson <pws@csr.com>                  Software Engineer
Cambridge Silicon Radio, Unit 300, Science Park, Milton Road,
Cambridge, CB4 0XL, UK                          Tel: +44 (0)1223 392070


^ permalink raw reply	[flat|nested] 7+ messages in thread

* Re: generals observations about completion system
  2000-09-19  9:04   ` Peter Stephenson
@ 2000-09-19 15:19     ` Bart Schaefer
  2000-09-19 15:51       ` Clint Adams
  2000-09-20 14:33     ` Thoughts on self-documenting functions Bart Schaefer
  1 sibling, 1 reply; 7+ messages in thread
From: Bart Schaefer @ 2000-09-19 15:19 UTC (permalink / raw)
  To: Zsh hackers list

On Sep 19, 10:04am, Peter Stephenson wrote:
} Subject: Re: generals observations about completion system
}
} Moving the string functions to their own file would be a step in the right
} direction, too.  It's hard to know what's in utils.c.

If anyone else wants to do this:  The convention in the past for new files
has been to copy the copyright notice from one of the existing files, and
then either add or change the name of the copyright holder to that of the
current coordinator (which would be Peter).

-- 
Bart Schaefer                                 Brass Lantern Enterprises
http://www.well.com/user/barts              http://www.brasslantern.com

Zsh: http://www.zsh.org | PHPerl Project: http://phperl.sourceforge.net   


^ permalink raw reply	[flat|nested] 7+ messages in thread

* Re: generals observations about completion system
  2000-09-19 15:19     ` Bart Schaefer
@ 2000-09-19 15:51       ` Clint Adams
  0 siblings, 0 replies; 7+ messages in thread
From: Clint Adams @ 2000-09-19 15:51 UTC (permalink / raw)
  To: Bart Schaefer; +Cc: Zsh hackers list

> If anyone else wants to do this:  The convention in the past for new files
> has been to copy the copyright notice from one of the existing files, and
> then either add or change the name of the copyright holder to that of the
> current coordinator (which would be Peter).

I only moved functions that depended solely on mem.c.  Anything
involving metafication was left alone.

Index: Src/.distfiles
===================================================================
RCS file: /cvsroot/zsh/zsh/Src/.distfiles,v
retrieving revision 1.2
diff -u -r1.2 .distfiles
--- Src/.distfiles	2000/08/16 13:34:54	1.2
+++ Src/.distfiles	2000/09/19 15:45:43
@@ -7,7 +7,7 @@
     hist.c init.c input.c jobs.c lex.c linklist.c loop.c main.c makepro.awk
     math.c mem.c mkbltnmlst.sh mkmakemod.sh mkmodindex.sh
     module.c options.c params.c parse.c pattern.c prompt.c prototypes.h
-    signals.c signals.h subst.c system.h text.c utils.c
+    signals.c signals.h string.c subst.c system.h text.c utils.c
     watch.c xmods.conf zsh.h zsh.mdd ztype.h
     zsh.rc zsh.ico
 '
Index: Src/mem.c
===================================================================
RCS file: /cvsroot/zsh/zsh/Src/mem.c,v
retrieving revision 1.2
diff -u -r1.2 mem.c
--- Src/mem.c	2000/07/28 09:10:37	1.2
+++ Src/mem.c	2000/09/19 15:45:50
@@ -507,32 +507,6 @@
 }
 
 /**/
-mod_export char *
-dupstring(const char *s)
-{
-    char *t;
-
-    if (!s)
-	return NULL;
-    t = (char *) zhalloc(strlen((char *)s) + 1);
-    strcpy(t, s);
-    return t;
-}
-
-/**/
-mod_export char *
-ztrdup(const char *s)
-{
-    char *t;
-
-    if (!s)
-	return NULL;
-    t = (char *)zalloc(strlen((char *)s) + 1);
-    strcpy(t, s);
-    return t;
-}
-
-/**/
 #ifdef ZSH_MEM
 
 /*
Index: Src/string.c
===================================================================
RCS file: string.c
diff -N string.c
--- /dev/null	Tue May  5 13:32:27 1998
+++ string.c	Tue Sep 19 08:45:50 2000
@@ -0,0 +1,135 @@
+/*
+ * string.c - string manipulation
+ *
+ * This file is part of zsh, the Z shell.
+ *
+ * Copyright (c) 2000 Peter Stephenson
+ * All rights reserved.
+ *
+ * Permission is hereby granted, without written agreement and without
+ * license or royalty fees, to use, copy, modify, and distribute this
+ * software and to distribute modified versions of this software for any
+ * purpose, provided that the above copyright notice and the following
+ * two paragraphs appear in all copies of this software.
+ *
+ * In no event shall Peter Stephenson or the Zsh Development Group be liable
+ * to any party for direct, indirect, special, incidental, or consequential
+ * damages arising out of the use of this software and its documentation,
+ * even if Peter Stephenson and the Zsh Development Group have been advised of
+ * the possibility of such damage.
+ *
+ * Peter Stephenson and the Zsh Development Group specifically disclaim any
+ * warranties, including, but not limited to, the implied warranties of
+ * merchantability and fitness for a particular purpose.  The software
+ * provided hereunder is on an "as is" basis, and Peter Stephenson and the
+ * Zsh Development Group have no obligation to provide maintenance,
+ * support, updates, enhancements, or modifications.
+ */
+
+#include "zsh.mdh"
+
+/**/
+mod_export char *
+dupstring(const char *s)
+{
+    char *t;
+
+    if (!s)
+	return NULL;
+    t = (char *) zhalloc(strlen((char *)s) + 1);
+    strcpy(t, s);
+    return t;
+}
+
+/**/
+mod_export char *
+ztrdup(const char *s)
+{
+    char *t;
+
+    if (!s)
+	return NULL;
+    t = (char *)zalloc(strlen((char *)s) + 1);
+    strcpy(t, s);
+    return t;
+}
+
+/* concatenate s1, s2, and s3 in dynamically allocated buffer */
+
+/**/
+mod_export char *
+tricat(char const *s1, char const *s2, char const *s3)
+{
+    /* This version always uses permanently-allocated space. */
+    char *ptr;
+    size_t l1 = strlen(s1);
+    size_t l2 = strlen(s2);
+
+    ptr = (char *)zalloc(l1 + l2 + strlen(s3) + 1);
+    strcpy(ptr, s1);
+    strcpy(ptr + l1, s2);
+    strcpy(ptr + l1 + l2, s3);
+    return ptr;
+}
+
+/**/
+mod_export char *
+zhtricat(char const *s1, char const *s2, char const *s3)
+{
+    char *ptr;
+    size_t l1 = strlen(s1);
+    size_t l2 = strlen(s2);
+    
+    ptr = (char *)zhalloc(l1 + l2 + strlen(s3) + 1);
+    strcpy(ptr, s1);
+    strcpy(ptr + l1, s2);
+    strcpy(ptr + l1 + l2, s3);
+    return ptr;
+}
+
+/* concatenate s1 and s2 in dynamically allocated buffer */
+
+/**/
+mod_export char *
+dyncat(char *s1, char *s2)
+{
+    /* This version always uses space from the current heap. */
+    char *ptr;
+    size_t l1 = strlen(s1);
+
+    ptr = (char *)zhalloc(l1 + strlen(s2) + 1);
+    strcpy(ptr, s1);
+    strcpy(ptr + l1, s2);
+    return ptr;
+}
+
+/**/
+mod_export char *
+dupstrpfx(const char *s, int len)
+{
+    char *r = zhalloc(len + 1);
+
+    memcpy(r, s, len);
+    r[len] = '\0';
+    return r;
+}
+
+/**/
+mod_export char *
+ztrduppfx(const char *s, int len)
+{
+    char *r = zalloc(len + 1);
+
+    memcpy(r, s, len);
+    r[len] = '\0';
+    return r;
+}
+
+/* Append a string to an allocated string, reallocating to make room. */
+
+/**/
+mod_export char *
+appstr(char *base, char const *append)
+{
+    return strcat(realloc(base, strlen(base) + strlen(append) + 1), append);
+}
Index: Src/utils.c
===================================================================
RCS file: /cvsroot/zsh/zsh/Src/utils.c,v
retrieving revision 1.19
diff -u -r1.19 utils.c
--- Src/utils.c	2000/09/18 06:50:55	1.19
+++ Src/utils.c	2000/09/19 15:46:00
@@ -3438,86 +3438,6 @@
 }
 
 /**/
-mod_export char *
-dupstrpfx(const char *s, int len)
-{
-    char *r = zhalloc(len + 1);
-
-    memcpy(r, s, len);
-    r[len] = '\0';
-    return r;
-}
-
-/**/
-mod_export char *
-ztrduppfx(const char *s, int len)
-{
-    char *r = zalloc(len + 1);
-
-    memcpy(r, s, len);
-    r[len] = '\0';
-    return r;
-}
-
-/* Append a string to an allocated string, reallocating to make room. */
-
-/**/
-mod_export char *
-appstr(char *base, char const *append)
-{
-    return strcat(realloc(base, strlen(base) + strlen(append) + 1), append);
-}
-
-/* concatenate s1, s2, and s3 in dynamically allocated buffer */
-
-/**/
-mod_export char *
-tricat(char const *s1, char const *s2, char const *s3)
-{
-    /* This version always uses permanently-allocated space. */
-    char *ptr;
-    size_t l1 = strlen(s1);
-    size_t l2 = strlen(s2);
-
-    ptr = (char *)zalloc(l1 + l2 + strlen(s3) + 1);
-    strcpy(ptr, s1);
-    strcpy(ptr + l1, s2);
-    strcpy(ptr + l1 + l2, s3);
-    return ptr;
-}
-
-/**/
-mod_export char *
-zhtricat(char const *s1, char const *s2, char const *s3)
-{
-    char *ptr;
-    size_t l1 = strlen(s1);
-    size_t l2 = strlen(s2);
-    
-    ptr = (char *)zhalloc(l1 + l2 + strlen(s3) + 1);
-    strcpy(ptr, s1);
-    strcpy(ptr + l1, s2);
-    strcpy(ptr + l1 + l2, s3);
-    return ptr;
-}
-
-/* concatenate s1 and s2 in dynamically allocated buffer */
-
-/**/
-mod_export char *
-dyncat(char *s1, char *s2)
-{
-    /* This version always uses space from the current heap. */
-    char *ptr;
-    size_t l1 = strlen(s1);
-
-    ptr = (char *)zhalloc(l1 + strlen(s2) + 1);
-    strcpy(ptr, s1);
-    strcpy(ptr + l1, s2);
-    return ptr;
-}
-
-/**/
 static int
 upchdir(int n)
 {
Index: Src/zsh.mdd
===================================================================
RCS file: /cvsroot/zsh/zsh/Src/zsh.mdd,v
retrieving revision 1.2
diff -u -r1.2 zsh.mdd
--- Src/zsh.mdd	2000/07/30 17:03:53	1.2
+++ Src/zsh.mdd	2000/09/19 15:46:00
@@ -8,7 +8,7 @@
 objects="builtin.o compat.o cond.o exec.o glob.o hashtable.o \
 hist.o init.o input.o jobs.o lex.o linklist.o loop.o math.o \
 mem.o module.o options.o params.o parse.o pattern.o prompt.o signals.o \
-signames.o subst.o text.o utils.o watch.o"
+signames.o string.o subst.o text.o utils.o watch.o"
 
 headers="../config.h system.h zsh.h sigcount.h signals.h \
 prototypes.h hashtable.h ztype.h"


^ permalink raw reply	[flat|nested] 7+ messages in thread

* Thoughts on self-documenting functions
  2000-09-19  9:04   ` Peter Stephenson
  2000-09-19 15:19     ` Bart Schaefer
@ 2000-09-20 14:33     ` Bart Schaefer
  1 sibling, 0 replies; 7+ messages in thread
From: Bart Schaefer @ 2000-09-20 14:33 UTC (permalink / raw)
  To: Zsh hackers list

On Sep 19, 10:04am, Peter Stephenson wrote:
} Subject: Re: generals observations about completion system
}
} Bart wrote:
} > It does tend to be easier to add new completion functions than it is to
} > document them.
} 
} [...] self-documenting functions with something
} like pod, except using shell functions to strip out the bits and turn them
} into yodl, should be pretty easy.  Adding comments is usually much easier
} than fiddling with the full documentation.

I actually have a bit of experience with this, and I have reservations
about how effective it will be.

In Z-Mail, which has a shell-like scripting language with "#...\n"
comments, each function may contain a block that looks like

	#%
	# Documentation goes here
	# across several lines if
	# necessary
	#%

The zscript parser grabs those comments and uses them to generate on-line
help in the GUI.  Also, if you run `func -?' the documentation block is
printed (with the leading '# ' stripped from each line) instead of
executing the real function body.

POD's biggest advantage over this scheme is that you don't have to put a
comment character on every line, which makes editing the doc a lot easier
should you ever need to change it.  The value of that convenience should
not be underestimated; zmail was heavily customized through zscript by
each of several organizations that bought it, but I never heard of anyone
who made use of this inline doc feature. Conversely, the use of POD is
quite common.

In any case, in both zscript and POD, the support for stripping the doc
out of the function is built in to the parser.  Since I don't think PWS
is suggesting we diddle with zsh's parser, we can't avoid using comments
(any other approach, e.g., here-documents, would store the documentation
as part of the function definition when it gets loaded).  That's my first
reservation.

The second is with the idea of "generating yodl" from the text in the
comment.  That seems doomed from the start; yodl's designed to be the
source language, not the generated one, and consequently has a whole
syntactic menagerie that can't be inferred from un-marked-up text, which
is all we can expect anyone to write in a shell script comment -- no one
will want to document their functions twice, so whatever form we choose
ought to be plainly readable without preprocessing.

One thought that I had is to put the documentation into its own function,
which is then unfunction'd after the whole file has been autoloaded.  So
each file _xxx would look something like:

    _xxx_doc () {
	some sort of documentation format
    }

    _xxx () {
        the actual function
    }

    unfunction _xxx_doc
    _xxx "$@"

This way, the doc format wouldn't have to be a comment, but would still
get flushed out of zsh's memory after the file is loaded.  On the other
hand, I think redefining _xxx that way prevents taking full advantage of
memory-mapped .zwc files, which is also undesirable.  However, using a
function might let us do something clever with shell expansions to mark
up the documentation for conversion to yodl.

Anyway, no conclusions yet, just musings.

-- 
Bart Schaefer                                 Brass Lantern Enterprises
http://www.well.com/user/barts              http://www.brasslantern.com

Zsh: http://www.zsh.org | PHPerl Project: http://phperl.sourceforge.net   


^ permalink raw reply	[flat|nested] 7+ messages in thread

* Re: generals observations about completion system
@ 2000-10-04 11:44 Sven Wischnowsky
  0 siblings, 0 replies; 7+ messages in thread
From: Sven Wischnowsky @ 2000-10-04 11:44 UTC (permalink / raw)
  To: zsh-workers


E. Jay Berkenbilt wrote:

Most of this has been answered or is being thought about or worked
upon elsewhere, so I'll jump to:

> ...
> 
>  2.  The ssh completion function does not use the user-hosts style
>      even though this style is documented.  (If it uses it, I've
>      missed it.)  It knows about ssh's ability to say ssh user@host
>      rather than ssh host -l user.  You can easily override the list
>      of hosts to be completed by setting the hosts style for the ssh
>      command, but this doesn't entirely solve the problem.  If I hit
> 
>      ssh TAB
> 
>      I get a list of all users and hosts.  There are a lot more users
>      on my system than there are hosts that I ssh to.  I want to
>      change ssh to complete only on hosts, not on users.  If I want
>      users, I'll use -l.  There seems to be no good way to do this
>      without simply copying and modifying the _ssh file.

Look at the `tag-order' style (probably the most important style). If
you're feeling bold, look at the `hidden' style (probably together
with `group-name'; it would allow you to just keep the user names from 
being listed).

Bye
 Sven


--
Sven Wischnowsky                         wischnow@informatik.hu-berlin.de


^ permalink raw reply	[flat|nested] 7+ messages in thread

end of thread, other threads:[~2000-10-04 11:44 UTC | newest]

Thread overview: 7+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2000-09-17 23:33 generals observations about completion system E. Jay Berkenbilt
2000-09-19  4:59 ` Bart Schaefer
2000-09-19  9:04   ` Peter Stephenson
2000-09-19 15:19     ` Bart Schaefer
2000-09-19 15:51       ` Clint Adams
2000-09-20 14:33     ` Thoughts on self-documenting functions Bart Schaefer
2000-10-04 11:44 generals observations about completion system Sven Wischnowsky

Code repositories for project(s) associated with this public inbox

	https://git.vuxu.org/mirror/zsh/

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).