[rfc] developer documentation on user interaction

[Alexander Belchenko]

Martin Pool пишет:
> 2009/9/25 John Arbash Meinel <john at arbash-meinel.com>:
>>> 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.
> 
> I would question whether the Command object is really the right place
> for it vs the UI, and I think if it has to be explicitly passed from
> the command down to whatever code actually writes, people are likely
> to cheat and use stdout.
> 
> It's not very consistently used and that to me indicates it's probably
> not the right interface.
>> 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.

I'd prefer Mercurial way to use in bzrlib: explicit ui object to handle 
everything what should be printed on the screen.

Today this is REAL problem to create GUI equivalent of CLI bzr: 
"bzrw.exe" because py2exe does not allow application to print to 
stdout/stderr without error message on application exit.

For QBzr needs I'd like to have in UI explicit methods to write error 
messages. Currently we detect error messages by 'bzr: ERROR:' prefix of 
the line. And some error messages are multi-line. Heh?

>> 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 think some of those methods should still take a to_file parameter.
> For diff, for instance, it's quite reasonable that a gui or loggerhead
> would want to generate a diff to be sent somewhere else.
> 
>> 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.
> 
> I agree, though I think it still makes sense for the UIModel to map
> some library-driven interactions onto the GUI, so that when you have
> code that hasn't been rewritten as a specific GUI application it will
> still do something sane, rather than writing to stdout.