[WARNING] Altering source and destination spec syntax

This represents my current thinking on an issue that's been bothering me
for some time.  It's a minor change in the implementation but an
annoying one for anyone who's got test scripts written.  Which is why
it's important to do before 1.0 because we don't want to break users'
scripts after 1.0.  This message is both fair warning and request for
feedback in case there are fatal flaws.

The source and destination specs were based on Perl's DBI specs mostly
because I thought of repositories more as databases than anything else.
However, as we've added features, the spec syntax has become overloaded
with colons and some vagueness where the parser makes a specific
decision that may not be obvious to the user.

Here's how it will look, with lots of detail of the whys and wherefores
below:

- Client/Server URIs:

     p4://public.perforce.com:1666/public/revml/...
     cvs://cvs.sourceforge.net/cvsroot/foo/...
     cvs-pserver://cvs.sourceforge.net/cvsroot/foo/...

     p4://bill:password@xxxxxxxxxxxxxxxxxxx:1666/public/revml/...
     cvs://bill:Password@xxxxxxxxxxxxxxxxxxx/cvsroot/foo/...

- Local filesystem URIs:
     p4:///home/p4d/-/depot/foo/...
     cvs:///home/cvsroot/-/foo/...
     vss:///C:/vssdata/-/BackOffice/...

     p4:///home/p4d/-/depot/foo/...?user=bill&password=Password

The "-" segment indicates where the /path/to/repository ends and the
filespec within the repository begins.  There are some alternatives
below, but I selected "/-/" because it's visually obvious and it would
not require escaping on most shells (of the filesystems I'm familiar
with, only VMS uses "-" as a token in filespec grammar, and we don't
intend to look like VMS filespecs here).

I could be convinced easily to use ";-/" instead of "/-/":

     p4:///home/p4d;-/depot/foo/...
     cvs:///home/cvsroot;-/foo/...
     vss:///C:/vssdata;-/BackOffice/...

     p4:///home/p4d;-/depot/foo/...?user=bill&password=Password

because it's almost as visually obvious and it's definitely more correct
in terms of RFC2396 semantics (the ";" indicates path parameter in URI
syntax, the parameter being "-" in this case).  The downside is
requiring quotes to get it past most Unix shells.

A nice side effect of the dichotomy between local and remote is that we
will be able to automatically run the p4d or use local file scanning
mode for CVS, so we're saving the user an option (--run-p4d, for
instance) in some cases.

Below is the thinking document I used to work through some of the
issues.  I didn't try to capture every though, I wanted to lay out why
the change is needed and some of the alternatives.

Feedback requested (before it's too late :).

- Barrie

The current syntax for sources and destinations is basically one
of:

    scheme:filespec                # use the env or registry to spec repo
    scheme:server:filespec
    scheme:user@server:filespec
    scheme:user:password@server:filespec

and "local file" versions, which are indicated by the presence of
driver-specific options like the cvs and p4 ones shown here:

    scheme:/path/to/p4repo/dir:filespec --run-p4d

and some p4-only versions:

    scheme:server:port:filespec
    scheme:user(view):password@server:filespec
    scheme:user(view):password@server:port:filespec

VCP has outgrown this simple colon-separated syntax:

    - They're hard for users to read and write when more than a couple
      of fields are involved.
    - The p4 server:port syntax was wedged in on after the initial
      design and have caused additional colitus.
    - The syntax for the local repositories is not distinct and requires
      an extra option like --run-p4d.
    - cvs uses colons for :pserver:, :auth:, etc, etc, access
    - I've started tripping over some minor inconsistancies (whether or
      not a leading '/' or trailing '/' is required on the filespec
      section).
        - This needs to be resolved no matter what, I'm just choosing to
          revamp the overall syntax to handle the leading '/' syntax.
    - They're not compatible with the more common URI syntax
        - A more URI-like syntax is more appropriate and would lead to
          easier uptake among users.
      
So I'd like to alter the syntaxes above to the URI syntaxes for remote
servers (VSS does not allow this):

    scheme:/filespec
    scheme://server/filespec
    scheme://server:port/filespec
    scheme://Admin@server:port/filespec
    scheme://Admin:Password@server:port/filespec
    scheme://server:port/filespec?user=Admin
    scheme://server:port/filespec?user=Admin;password=Password

The last two are for compatability with the next set of URIs, which
would be used to access files on the local system.  Note that VSS has no
remote URI at this time.

Local URIs would look like:

     p4:///home/p4d/-/depot/foo/...
     cvs:///home/cvsroot/-/foo/...
     vss:///C:/vssdata/-/BackOffice/...

with the user ID, password, etc. as query parameters:

     vss:///C:/vssdata/-/BackOffice/...?user=Admin&password=Snork

The query parameters are nice because they're self-documenting and
extensible.

I'm not sure how you'd wedge a DOS UNC ("//server/sharename") volume
specifier in to URI syntax.  Probably with an extra '/'.

We could also use the with the little-known ";" URI parameter syntax
flagging which path component is the the repository location:

     p4:///home/p4d;repository/depot/foo/...
     cvs:///home/cvsroot;repository/foo/...
     vss:///C:/vssdata;repository/BackOffice/...

     p4:///home/p4d;-/depot/foo/...
     cvs:///home/cvsroot;-/foo/...
     vss:///C:/vssdata;-/BackOffice/...

This would be more technically correct but would require such URIs to be
quoted on Unix command lines (though not in .vcp files, etc).

We could use shorter but less obvious p4-like "//" syntax:

     p4:///home/p4d//depot/foo/...
     cvs:///home/cvsroot//foo/...
     vss:///C:/vssdata//BackOffice/...

I'd like to avoid the '//' approach because:

    - it's not as visually obvious as "/-/" or ";-/",
    - it's likely to happen by accident when wrapper scripts munge
      paths, and
    - The syntax '//' is legal and has an unabiguos meaning on Unix.

Some anonymous "chroot"ing FTP servers specify the artificial root the
remote FTP client sees by using a "/./" component.  I don't like that
because it looks legit, the meaning's not clear.