[MERGE] updated help topics

[John Arbash Meinel]

Goffredo Baroncelli wrote:
> On Wednesday 08 November 2006 17:38, you (John Arbash Meinel) wrote:
> [....] 
>> 2) Change from using RevisionSpec.__doc__ to using
>> RevisionSpec.help_txt. As you say, it wasn't that hard to do. I went
>> with 'help_txt' because 'help' is a builtin python command. (Although
>> only really useful from the command line)
> 
> Even tough I prefer using the __doc__ attribute fo the help, what about 
> calling a function instead a static attribute in order to get the help text ?
> 
> We can add to the RevisionSpec class a function as:
> 
> class RevisionSpec
> 	[...]
> 	def get_help_summary(self):
> 		return self.__doc__.split('\n')[0]
> 
> 	def get_help(self):
> 		return '\n'.join(self.__doc__.split('\n')[2:])
> 
> which can be overraidable if we want separate the help text from the __doc__,
> but only if it is necessary.
> The same path can be used for the help of the Command class...
> 

Actually, I believe Command already does that.

The problem with __doc__ is that it is stripped if you use "python -OO".
 So all of a sudden all of your help text and error messages are stripped.

For me, the bigger one is just Exceptions, because there you frequently
want a specifically formatted message, and the doc string doesn't lend
itself well to the type of formatting that you would use elsewhere.

Also, for Exceptions, we really wanted to have a developer string, which
lets us say "This exception should be used in these circumstances".
Which isn't something you want to print out to users.

There isn't quite as much need for this with Command or RevisionSpec,
but it isn't a lot of work to add it.

I like __doc__ for the fact that if you browse something like
auto-generated documentation (epydoc, for example), then it has the same
(hopefully good) documentation.

I can see where we may want to give a developer different documentation
than a user. But the common case for Command or RevisionSpec is that
they would be the same...

>> Attached is the new diff. I realize there are still some changes in
>> builtins which might conflict, but I don't think they are serious.
> 
> If this time the your (our) patch will not accepted, I suggest to divide the 
> patch itself in two: the first one will be related to the help text only ( 
> which I think raises less concern ); the second one will be related to the 
> code.
> 
> Goffredo
> 
> ( Of course a +1 to your patch )
> 

It isn't very hard to do:

bzr revert -r ancestor:../bzr.dev bzrlib/builtins.py

To revert all of the changes to certain files (and you can use shelve or
'bzr vimdiff' to bring back selected hunks).

So if it is important, we can do it. I just didn't feel like taking the
time yet.

John
=:->


-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 254 bytes
Desc: OpenPGP digital signature
Url : https://lists.ubuntu.com/archives/bazaar/attachments/20061108/678cc39b/attachment.pgp