From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 12848 invoked from network); 3 Aug 2001 07:45:18 -0000 Received: from sunsite.dk (130.225.51.30) by ns1.primenet.com.au with SMTP; 3 Aug 2001 07:45:18 -0000 Received: (qmail 26057 invoked by alias); 3 Aug 2001 07:45:09 -0000 Mailing-List: contact zsh-workers-help@sunsite.dk; run by ezmlm Precedence: bulk X-No-Archive: yes X-Seq: 15564 Received: (qmail 26027 invoked from network); 3 Aug 2001 07:45:07 -0000 Message-ID: <20010803073159.35853.qmail@web10401.mail.yahoo.com> Date: Fri, 3 Aug 2001 00:31:59 -0700 (PDT) From: Felix Rosencrantz Subject: Re: XML version of completion function To: zsh-workers@sunsite.dk In-Reply-To: <1010801073909.ZM324@candle.brasslantern.com> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Bart Schaefer wrote: > Are you really, seriously suggesting that it's worthwhile to expend > 50-70 thousand bytes defining the completion for a single command? > In the case of zip that's 45% larger than the executable; it's even > larger than the executable and its manual page combined. > > In find.xml there are about 5500 bytes of actual data, including the > help text ... the other 89% is XML tags. I'm sorry, I just can't get > excited about this. That's a scary metric... Though on my box, adding the size of the executable and the gzip'd .man page, does make the xml file smaller... Not by much though... ;) I tried to make almost everything elements rather than stuffing data into attributes. There probably could be some small space savings that way. And I used spaces where tabs should have been used, leading spaces make up about 56% of the zip.xml file. If all else fails, there has been some research on compression of xml showing improvements over compressing the same data as plain text.... ;) A smaller file format would be nicer. Possibly, this XML format might be one of several formats. Different, but equivalent formats, might make different types of processing easier to perform. Equivalent to me means that there are XSLT transformations that can be written to convert the data between the two formats. Or there might be simpler subsets for common types of completion. Though, even at this size I think the file is sort of usable. There is documentation right where the user needs it. All the flags that can be handed to _arguments are listed for the zip completion along with the documentation. With the documentation at the place where you make the modifications makes it much easier to work with. Sven Wischnowsky wrote: >But apart from that... some comments: > >- I actually like being able to add help texts. Peter and I > half-heartedly discussed that around the time _complete_help was > added. I still don't know where the help texts could be saved and how > _complete_help or a similar function could look them up, though. > Especially if there are versions in different languages. Actually, that is one thing I was sort of hoping might happen. I think an XML format might make it possible to generate multiple related functions. When I was doing this I wrote a quick&dirty perl script to break out the option sections from the man page, (I cut out the option sections by hand, and did some hand tweaking...) and placed them in a directory with files name by the flag. So I had a directory tree helpfiles// e.g. helpfiles/zip/-d. It wouldn't be hard to add another directory level that contained language (e.g. helpfiles/en/zip/-d) >- I don't understand why is always nested in -- is > the latter meant to be an _arguments-arg? If so, see next point. There's not much reason for it that I can see right now. I think I was mostly following the man page to build up the structure. Since optargs are one subsection of a complete specification, I made that a different element. The _arguments-arg is handled by the argoption element. >- I think this should be more like describing the command than > describing arguments for _arguments. That should also make the things > shorter and more readable. But whenever I try to describe how that > would look like, I more or less describe _arguments. Hm. I'd like to have tools that can generate XML from the usage information of a command. The user would then edit the XML. Then convert the XML into a completion function. There might be an intermediate XML format before generating the function. _arguments already can do something like this with GNU commands directly. It seems to me that for a script, usage information looks like three basic things: flagname, flagargs & simple description. So basically there would be three elements like that, with some surrounding structure (elements for containment). A script might be able to figure out other things (e.g. equivalence, constants, exclusion lists). But it would be up to the user to provide information about what the description is for and what the flagargs really are. That format might not explode as much as for _arguments. The next XML example I try to produce will be based on usage information. It would be possible to have a tool or set of tools for making simple edits to the usage.XML file. These tools might allow the user to say give action "_files" to flag "-f", or flags -v and --version are equivalent. Sure it's pretty easy to do that by hand now with the _arguments call, but it might make it easier to do simple piecemeal changes. So a completion function might develop as a user has the desire. These changes might require less need to head to the documentation, which can be daunting. (To come up with the XML structure, I extracted the section on _arguments from the man page, the resulting file is still 558 lines.) >- I don't think I'll ever use this format unless someone comes up with a > tool that converts a much shorter description to it or that generates > most of this automatically. How have you generated this? Typed it > in? If so, tell us about your experience with it -- would you like to > write completions this way? Based on your feedback I'm starting to realize that without tools this becomes useless. But I don't think I expected anyone to type in this format by scratch (except for those who believe editors are for wimps, and prefer cat and "^D", but they don't need completion...). I think this format will be generated and converted by tools. Though there might be some manual tweaking. I created the zip.xml file first, and then the find.xml file. I started with a perl script that could convert the _arguments command lines from _zip into XML. I pasted in the argoption documentation by hand, some small edits to make it standalone. I mentioned the stuff about the man page documentation, which was added by hand to zip.xml. I added and sections by hand. I had to make some modifications to the perl script to handle the specifications used by _find and to the tool that parsed the man page. But after those hand edits, find.xml was generated by script. I think if the XML is generated, and the documentation is in the correct spot, I would be willing to tweak the XML. Tools to perform simple edits would be really welcome. Also, I expect there would need to be tools to insert and remove documentation. I did find it difficult in vim to get my bearings in the XML since a lot of it looked alike, and there is a limited context that fits on the screen. Though with search it was possible to move to the flag or place I wanted to be. When I first put the zip.xml file in an XML viewer I was pretty happy with navigating the document, it seemed a lot more manageable. There were some problems with it in the XML viewer; without expanding the argspecs level, it was not possible to tell what flag was being described. So I think some flag information might need to be placed as an attribute at this level. Designing for the viewers hadn't occurred to me as being an issue until that point. -FR __________________________________________________ Do You Yahoo!? Make international calls for as low as $.04/minute with Yahoo! Messenger http://phonecard.yahoo.com/