[rfc] developer documentation on user interaction

[Martin Pool]

There's one open issue here that has come up a few times before, and
that's what to put on stderr vs stdout.  It's a bit complex and seems
to vary per command.  There was a command a while ago where someone
had a go at us for putting things that are not errors on stderr, but I
think being that strict is just not feasible.

My current thinking is that the actualy 'bulk' output of the command
should go to stdout (list of files changed, list of revisions, diffs,
etc) and any commentary or user-oriented interaction should go to
stderr.  One thing that helps is to bear in mind stdout will more
commonly be redirected to a file than stderr when a user runs the
command interactively.  So most UIFactory things that write output
will go to stderr, and prompts for user input will go to stderr.

This actually highlights an interesting direction which is that access
to stdout could be mediated by the UIFactory providing a "I want to
provide some bulk output" operation that returns a file-like object.
On the terminal this could cause it to synchronize with the progress
bar, and in a GUI it could send it into a specific output window that
shows for example a text-mode diff.  I'm not sure if that's actually
useful, but it might be.

-- 
Martin <http://launchpad.net/~mbp/>