[RFC] report options

[jw schultz]

Only two non-developers have responded to this.  Barring a
favourable response from other developers i'll shelve this
proposal.

On Thu, May 15, 2003 at 08:11:09PM -0700, jw schultz wrote:
> 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
> -- 
> To unsubscribe or change options: http://lists.samba.org/mailman/listinfo/rsync
> Before posting, read: http://www.catb.org/~esr/faqs/smart-questions.html
> 

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

		Remember Cernan and Schmitt