[MERGE] bzr help locationspec

[Aaron Bentley]

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

Goffredo Baroncelli wrote:
> Hi Aaron,
> 
> I agree with the most of your comments, but these comments are related to the 
> *actual* documentation of the python class inside the source and not to my 
> patch.

Your patch is providing help, and I think the help provided is very
poor.  When you chose to use API documentation as user help, you took
responsibility for its contents.

We recently changed BzrError so that it doesn't use the docstring as
user text anymore.  It was felt that trying to have the same string
serve as both API and user text was a poor fit.  I think it's a poor fit
here, too.  My complaints about it as user text are that it speaks in
terms of internal details.  But API text is *supposed* to speak in terms
of internal details.

> The real fix is to correct these info, but that is not the goal of my patch.

If you are offering your patch as an alternative to Marius' patch, I
would prefer Marius', because its help is more user-friendly.  While
your patch doesn't meet that level, I consider it incomplete.

> If we merge this patch, the people will update the internal documentation.

As discussed above, I think that would be a loss.

> On Thursday 18 January 2007 01:22, you (Aaron Bentley) wrote:
>> Goffredo Baroncelli wrote:
>>
>>> ghigo at venice:~/bazaar/repo/bzr-help-topics-transport$ ./bzr help transport
>> I also think "transport" is a very poor topic name.  My favourite would
>> be "locations", I'd accept "urls", but "protocol" and "transport" aren't
>> good topic names, because they're not very discoverable.
> 
> I intend "location" as place ( == repositories/branches ), and not as "method 
> of transmission". URL is both: place and method. 
> Instead in my opinion protocol or transport are the best; but I am open to 
> other opinions.

My opinion is that because there are no 'protocol' arguments, just
'location', etc, 'location'/'url' are more discoverable.


>>> Supported decorators:
>> Perhaps "prefixes" would be a better term.
> 
> We should find a better definition. prefixes ( as decorators ) is a syntax 
> definition: instead we need a better "semantic" definition...

I disagree.  You don't need to understand the concept of a decorator in
order to know how to use a prefix, so we should use the terminology that
 is familiar.

>> This is a very ugly approach.  We already have registries, which are a
>> much cleaner approach, so I think it would make sense to change
>> _supported_protocols into a Registry subclass.
> 
> This is a different problem, which has to be fix with a different patch.

I disagree.  Instead of implementing an ugly approach of extracting help
from docstrings, you could choose to implement the clean approach of
getting help from a Registry.

Aaron
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.3 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iD8DBQFFsACa0F+nu1YWqI0RArP4AJ4gIoeMD/tfAf0R7QIMQQ8M8TRwxwCeODoe
udVRwqR9DrsuVsCJ8GAlQI4=
=nfSy
-----END PGP SIGNATURE-----