[rfc] developer documentation on user interaction

[John Arbash Meinel]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Martin Pool wrote:
> 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.
> 

Well, we currently also have the "Command.outf" functionality. Which is
still always bound to stdout but sometimes has unicode encoding/decoding
enabled.

If we went to put something like this onto ui_factory, I'd like to see
an object that was smarter than .write(bytes).

Possibly a minimal api would be something like:
  .write(bytes)
  .write_unicode(Unicode)
  (arguably you could go so far as .write_path(), .write_url()...)

I think internally we know when we are writing something like a Log
message, that should be in Unicode locally, and translated for the
screen. Versus writing the diff output ('log -p').

I believe Mercurial does this by passing a 'ui' object to most of their
commands. Which is a bit ugly because you have to pass it through all
the layers. Doing it as a ui_factory is nicer in that aspect, though it
introduces global state, and makes things non-threadsafe.

At the moment, we try to have functions that want to do output take a
'to_file' style parameter. (show_tree_status, for example), which is the
same thing as above, only you have a simple file object, rather than
something richer.


I guess all this to say that yes, we should think about this, and think
what would be best.

I honestly feel that Gui's should be interacting with an object model,
and never interacting via a stdout pipe. Though qbzr's policy of
interacting via a subprocess (to preserve interactivity in the main
thread, IIRC) means that this is difficult.

John
=:->



-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.9 (Cygwin)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/

iEYEARECAAYFAkq7r/YACgkQJdeBCYSNAAMtSACglbJhk3djeQHwD5AsX2mz9MdV
ZpYAn23Ni5uAMJd0KnpT99+YRb/vZgHj
=pFRg
-----END PGP SIGNATURE-----