[darcs-users] Re: ann --xml only works with --summary (was: Re: darcs annotate and options)

[David Roundy]

On Sat, Apr 02, 2005 at 02:49:51PM +0000, Mark Stosberg wrote:
> On 2005-04-02, Michael G Schwern <schwern at pobox.com> wrote:
> > On Sat, Apr 02, 2005 at 02:49:58AM +0000, Mark Stosberg wrote:
> >> For me --summary works and --xml works too, but only with summary.
> >
> ><snip>
> >
> >> The --xml issue issue confusing and deserves some attention.
> >> 
> >> Maybe it's short help should say:
> >> 
> >>  generate XML formatted output (only with --summary)
> >> 
> >> Can someone confirm that's the way it's supposed to work? 
> >
> > If its only useful in conjunction with --summary... maybe using --xml
> > should imply --summary rather than explicitly requiring it.

That's not quite the case (see below).

> > Or, looking at it the other way, --xml should fail or warn or produce some
> > sort of noise if --summary is not given.
> >
> > Silently doing nothing is the wrong thing to do.

Agreed.  Unfortunately, there is a small difficulty about being noisy on
irrelevant flags, which is that users may have put the flag in the defaults
file, in which case it would be highly inconvenient to complain about them.
For example, a user might include

ALL --unified

which would have the effect of making send, whatsnew and annotate all
provide unified output.  It would be a shame to break this useful
behavior, and currently there's no particularly easy way to tell if a flag
was included as a result of the defaults file or if it was specified
manually.  :(



Explanation of annotate options and behavior:

There are three ways to call annotate.  You either provide a file name, a
directory name, or neither.  In the latter case, you must provide a patch
name with --patch.

If you provide a file or directory name, --xml and --human are both
meaningful, although one might argue that the --human-readable annotation
isn't actually readable by sane humans.  However, --summary and --unified
have no effect.

If you don't provide either a file or directory name, you get a patch
output.  In this case, --xml only works if you also use --summary, and
--unified is only meaninful if you *don't* use --summary.

I'd definitely love to have the annotate command broken up into a query
command with subcommands.  Annotate has become a sort of catch-all, which
tries to do too much.
-- 
David Roundy
http://www.darcs.net