Re: Generating completion functions from XML

[Felix Rosencrantz <f_rosencrantz@xxxxxxxxx>]

>Note that the exclusion lists are not necessarily repeated. An option
>listed in the exclusion list is excluded after the option and there
>are some commands where the exclusion is dependent on the ordering. I
>can't think of much information repetition in the current _arguments
>syntax.

I know there are some tricky exclusion list rules where it is not
always repetitive, though I think it is more common to use the same
set.  Also, the other place for repetition is for equivalent flags
(short/long versions).  Also, I'm hoping that there might be ways to
take advantage of shared flags that commands with subcommands (e.g.
cvs, bitkeeper, clearcase) typically have.  Other than that, I agree
there isn't much repetition.

>Have you used XSLT at all? I've used it for some things and it is
>quite cunning. If you use XML, I'd recommend you try it with this
>transformation in mind. I actually struggled to find a decent program
>to do XSL transformations - most of the information on the web relates
>to direct browser support yet it makes a lot of sense currently to use
>XSL on the server side. libxslt (which needs libxml2) comes with a
>little program called xsltproc which is what I have used (and I have a
>simple completion for it so I've attached that).

I got hooked on XSLT, and that has actually fueled my interest in XML.
I will keep it in mind for generating _argument calls.  There are many
constraints for this file, which probably won't all be satisfied in
initial drafts.

I would like to make it simple to create the initial XML; it should
be possible to write simple throw away shell/perl scripts that just
toss out the facts (flag names, help, exclusion, actions) and have XSLT
clean it up.  Another thing that interests me is using XSLT to augment
the XML command description with generic documentation describing the
XML.  Another thing would be to use XSLT to customize an _arguments
call before it is generated.  (I've been using Xalan from Apache&IBM.
I've included my simple completion.)

>Another thing you might want to think about is if your XML format can
>somehow be flexible enough to include support for multiple languages.

That's a great idea.  And this is one of the places where the XML would
actually contain information you can't easily place in _arguments call.

I sent mail recently about the shell standard talking about some
completion-like things (prediction, correction, validation) the shell
might do someday which might also benefit from having a declarative
description of a command.  Also, it might be a useful format to
generate a gui wrapper for a command.

>It'll be interesting to see but to be honest I'm a bit doubtful that
>an XML equivalent will be any easier to modify or understand that the
>current script. A gui wizard might do more to easing things but then
>that could use the XML. The completion functions may not have gained
>much in ease of writing over compctls (and as you said this is largely
>because of the provision greater functionality) but I think they are
>a lot more readable. I could never remember all the compctl flags and
>always needed the manual to write them whereas tcsh completes were
>easy.

I agree I find many are readable, but there are a lot of special cases
for which I would need to read the manual. Also, I don't find them so
editable...  I find it hard to create and edit an _arguments call.
(e.g. What's the difference between help for the flag vs. help for the
flag's argument?  I know now, but it took me a little time to grok.) I
have the manual accessible, and am reading as much as I need to and
then flip back to my completion function.  Or I tend to look at an
example function.  I hope that pertinent documentation can be placed in
the XML right at the place you need it.  Also, folks are at different
levels of understanding of the system, so it might be possible to add
different levels of insertable documentation.

I guess the process I see for creating a new completion function would
be to take the command usage and give it to some tool (maybe in perl),
which would generate some simple XML.  There might be another tool that
could take the man page for the command, and generate more XML that can
augment the XML from the first script.  Together this generated XML
would be a draft that could be processed by an XSLT sytlesheet to come
up with a more canonical form of the XML.  Then the user would edit
this XML (e.g by hand, with a nifty gui tool, or via web based gui).
If editing by hand, the user may also run an XSLT stylesheet that adds
zsh documentation to describe things like how exclusion groups work or
how to handle equivalent flags.  Then when the user is done or wants
to try out the new completion, the user would run some sort of XSLT
stylesheet to generate the function.  (It shouldn't be too hard to
generate some sort of compctl or tcsh completion, if that is wanted.
....)

I guess I'm still hopeful that there will be tools to help with the
process, and I think XML is an easier format to parse than a zsh
script.  XML has the potential to provide a good medium for the user to
understand, even though it will contain a lot more syntactic sugar.

-FR.

#compdef org.apache.xalan.xslt.Process
    local context state line
    typeset -A opt_args

_arguments \
    "-IN:inputXMLURL: _files" \
    "-XSL:XSLTransformationURL:_urls" \
    "-XSL:XSLTransformationURL:_urls" \
    "-LXCIN:compiledStylesheetFileNameIn:_file" \
    "-LXCOUT:compiledStylesheetFileNameOutOut:_file" \
    "-PARSER:fully qualified class name of parser liaison:java_class" \
     "-E[Do not expand entity refs]" \
    "-QC[Quiet Pattern Conflicts Warnings]" \
    "-Q[Quiet Mode]" \
    "-LF[Use linefeeds only on output {default is CR/LF}]" \
    "-CR[Use carriage returns only on output {default is CR/LF}]" \
    "-ESCAPE:(Which characters to escape {default is <>&\"'\\r\\n}:" \
    "-INDENT:(Control how many spaces to indent {default is 0}):" \
    "-TT[Trace the templates as they are being called.]" \
    "-TG[Trace each generation event.]" \
    "-TS[Trace each selection event.]" \
    "-TTC[Trace the template children as they are being processed.]" \
    "-TCLASS[TraceListener class for trace extensions.]" \
    "-VALIDATE[Set whether validation occurs.  Validation is off by default.]"
\
    "-EDUMP[{optional filename} (Do stackdump on error.]:_file" \
    "-XML[Use XML formatter and add XML header.]" \
    "-TEXT[Use simple Text formatter.]" \
    "-HTML[Use HTML formatter.]" \
    "-PARAM:name expression (Set a stylesheet parameter):" \
    "-MEDIA[use media attribute to find stylesheet associated with a
document.]::" \
    "-SX[User Xerces Serializers]"


__________________________________________________
Do You Yahoo!?
Make international calls for as low as $.04/minute with Yahoo! Messenger
http://phonecard.yahoo.com/