[RFC] report options

[jw schultz]

I have hinted in the past of wanting to go to a more
selective control of the output of rsync.  Here it is.

	PROBLEMS with the existing --verbose et al.

The simple incrementing verbose doesn't allow one to
restrict stdout to what actually is of interest.  For
instance inside dirvish i don't care about directories,
or any kind of non-regular file because they show up every
time even if there is no change.  Someone else might not
care to see reports of files that only had a permissions
change.
	
When debugging, incrementing verbose levels turn on debug
messages for whole subsections that are of no concern.

To work around limited control there is a continual push to
add new specialised verbosity options.  --stats and
--progress are ones that got implemented.  --apt is one that
didn't but was a not unreasonable feature.  And recently we
evaded a request to bastardise --stats by linking it
into verbose.

	PROPOSED APPROACH

Replace verbose with a bitmask and provide a clean,
extensible interface to set and test them.

My first concern was that the command-line interface be
clean, intuitive and extensible.  Evaluating the existing
options and streams i suggest the stdout controlled by
--verbose be called the report.  Log refers to the logging
stream of rsyncd so it is already taken.  I have modelled the
option somewhat on stty.

One controls what is output with the --report option.  The
option takes as a single argument (no whitespace) a comma
delimited lists of keywords.  Some keywords can control
multiple flags so keywords may be proceeded by a minus sign.
For example, suppose you wanted to see a report of files
updated but didn't care about deletion.
"--report=file,-delete" would do the trick.  Progress and
statistic reports would also be specifiable through this
option so "--report=file,dir,stats,progress" would be the
near equivalent of "-v --stats --progress".

For backward compatability and because -v is intuitive the
existing options would be preserved and mapped into the
bitmasks.

	INTERNAL USAGE

The use of verbose, do_stats and do_progress are replaced
with two bitmasks: report_flags and debug_flags.  Two
bitmasks were chosen because debugging and verbosity should
be considered separate issues.  To facilitate using these
two macros are created.  Everywhere you have something like
"if (verbose)" or "if (verbose >= n)" It would be replaced
by something like "if (report(RPT_CREATE))" or "if (debug(1,
DBG_CSUM))".  That is correct, each subsection of code would
have it's own debugging flag(s) and support up to
4(cumulative) levels of debugging.

	EXAMPLE

To facilitate discussion, as well as to do unit testing i
have created (attached) a simple example program.
It has a small number of examples of using the report and
debug macros which control the verbosity of it's output.

The test program has very crude command-line parsing.  It
recognizee -v, --verbose, --stats, --progress, --report and
--report=.  It does not recognise -vv. 
--report=help will list the normal keywords and
--report=dbg_help will list the debugging keywords.

-- 
________________________________________________________________
	J.W. Schultz            Pegasystems Technologies
	email address:		jw at pegasys.ws

		Remember Cernan and Schmitt