From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 19239 invoked from network); 4 Oct 2000 09:42:30 -0000 Received: from sunsite.auc.dk (130.225.51.30) by ns1.primenet.com.au with SMTP; 4 Oct 2000 09:42:30 -0000 Received: (qmail 13398 invoked by alias); 4 Oct 2000 09:41:40 -0000 Mailing-List: contact zsh-workers-help@sunsite.auc.dk; run by ezmlm Precedence: bulk X-No-Archive: yes X-Seq: 12875 Received: (qmail 13390 invoked from network); 4 Oct 2000 09:41:39 -0000 Date: Wed, 4 Oct 2000 11:41:36 +0200 (MET DST) Message-Id: <200010040941.LAA09412@beta.informatik.hu-berlin.de> From: Sven Wischnowsky To: zsh-workers@sunsite.auc.dk In-reply-to: "Bart Schaefer"'s message of Wed, 20 Sep 2000 14:33:14 +0000 Subject: Re: Thoughts on self-documenting functions Bart Schaefer wrote: > ... > > 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 "$@" Sounds interesting, but... > 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. yes, I'd say. > 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. Some time ago we were discussing (well, not really discussing, but I mentioned it, I think) this kind of automatic documentation for the completion system already. At that time I played a bit with such special comments Bart described. Because I would like those comments to be enough to automatically generate the docs I needed to make it be converted to yodl. I used some convention, like `foo' being turned into `tt(foo)' and things like that, trying to keep the work load for the function writer low. But it still was a bit clumsy. I don't have any really good ideas either (obviously, you would have heard about them), but I still like the whole idea of it. So that it would allow us to 1) always keep the docs up to date, including utility functions, 2) correctly list all tags and styles in _complete_help, preferrably even with short descriptions 3) add a mode to _complete_help that displays a description like the one Peter suggested some time ago (a real, textual description, not just a list of things). Bye Sven -- Sven Wischnowsky wischnow@informatik.hu-berlin.de