bzr <cmd> help -- Synopsis syntax should follow de facto conventions

[Daniel Silverstone]

On Thu, 2006-09-21 at 10:46 +1000, Ben Finney wrote:
> >     $ bzr help checkout
> >     usage: bzr checkout [BRANCH_LOCATION] [TO_LOCATION]
> This tells you (syntactically) that BRANCH_LOCATION is optional,
> i.e. can be omitted.
> >     If BRANCH_LOCATION is omitted,
> This tells you (descriptively) that BRANCH_LOCATION is optional,
> i.e. can be omitted.
> There's no inconsistency in what you presented that I can see.

Given the syntax provided, the user could expect

bzr checkout /path/to/over/there

to be

"please check out what's *here* to over/there"

because the arguments are listed as independantly optional.

Perhaps we need a way to indicate that BRANCH_LOCATION is optional, but
if TO_LOCATION is wanted, BRANCH_LOCATION is required.

In normal manpage parlance:

usage: bzr checkout [BRANCH_LOCATION [TO_LOCATION]]

D.

-- 
Daniel Silverstone                         http://www.digital-scurf.org/
PGP mail accepted and encouraged.            Key Id: 2BC8 4016 2068 7895