Bug#932696: Please document Haskell team style Vcs-Git sytax [and 1 more messages]

[Russ Allbery]

Ian Jackson <ijackson at chiark.greenend.org.uk> writes:
> Russ Allbery writes:

>> Sure, an extensible syntax sounds great.  The problem is that we kind
>> of had one (Vcs-Git was a subset of a git checkout command line, which
>> allowed support of the -b option), but this (if I understand it
>> correctly) is a whole new type of thing that I don't think corresponds
>> to any git command-line flags.

> By "extensible" I meant "new information can be added in a way that
> will be ingored by existing parsers".

Oh, I see.

So the idea is that normally the results will be "good enough" if the
additional information is ignored.  Yeah, I think that can work as long as
the extensibility is reserved for more accurate location of the right
packaging information and not for something more fundamental.  (Which
probably just means saying explicitly that authors of future extensions
should anticipate what happens if existing code just ignores the extension
and ensure that doesn't result in anything too terrible.)

Wedging extensibility into the existing format might be a little bit
weird, particularly if we don't want to break the Haskell convention (and
I assume we don't since there's already some software support).  I think
we're stuck with a bit of an ugly format since we also don't want to break
the current branch support, even though it would in retrospect make more
sense to use the same extensibility for the branch.

So, maybe something like:

    <url> -b <branch> [<path>; <key>=<value> ...]

to build off of what we already have?  (With, obviously, a bunch of that
syntax marked as optional.)  If we ban "=" in <path>, we can allow for
<path> to be optional but some other key/value pair to be provided.

-- 
Russ Allbery (rra at debian.org)               <http://www.eyrie.org/~eagle/>