Re: Re: svn commit: r23760 - in branches/sparse-directories/subversion: libsvn_ra_svn svnserve

On Mon, Mar 12, 2007 at 10:34:29AM +0100, Peter Lundblad wrote:
> Yeah, my intention was to make the protocol easy to understand.
> If you make a parameter optional, you must document its meaning *today*
> (which was depth infinitiy) and then clients start relying on that...
>

Based on this conversation, I'm confused as to whether the last section
in libsvn_ra_svn/protocol is correct:

---
4.1. Extending existing commands
Extending an existing command is normally done by indicating that its
tuple is allowed to end where it currently ends, for backwards
compatibility, and then tacking on a new, possibly optional, tuple.
For example, set-path was extended to include lock-tokens like this:
  /* OLD */ set-path:
    params: ( path:string rev:number start-empty:bool )
  /* NEW */ set-path:
    params: ( path:string rev:number start-empty:bool ? [ lock-token:string ] )
The "?" says that the outer tuple is allowed to end here, because an
old client or server wouldn't know to send the new subtuple.  The new
subtuple appears in square braces because, even in the new protocol,
the lock-token is still optional (but if there's no lock-token to
send, then an empty tuple must still be transmitted, so that future
extensions to this command remain possible).  And if lock-token were
mandatory in the new protocol, then the braces would be parentheses
instead.
---
Specifically, I think the last sentence is probably wrong - if the item
isn't optional, it should probably just be standalone, not enclosed
in parentheses.
(How common is 'braces' as a synonym for 'brackets' by the way?  It's not
one I'd come across before).
Regards,
Malcolm