Re: XML version of completion function

[Felix Rosencrantz <f_rosencrantz@xxxxxxxxx>]

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/<command>/<flag> 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 <optspec> is always nested in <argspec> -- 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 <code>
and <state> 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/