patch to improve documentation for samba-tool command --help

[Theresa Halloran]

Hello Jelmer and all,

I am using full_description for the enhanced --help information and 
updated user.py to add the text to the __doc__ section.  I added the 
formatter code so the newlines are preserved.  This will work well for 
the enhanced help.  I don't see the full_description being used for 
anything else...unless there is a plan to do so and a reason I should 
not use it (or if I missed something).

I've included the text I'll be adding for samba-tool user create.  
Please review the text for accuracy and completeness (which I realize is 
subjective)....

Attached is the patch.  Thanks, as always, comments are appreciated!

Theresa
>>>
>>> I've attached a patch with an implementation to improve the --help
>> command for samba-tool. It includes some formatting stuff and an example
>> of the samba-tool user create --help doc that gives an idea of the level
>> of detail and some command examples.
>> Thanks for working on this. I didn't realize there was a way to get
>> optparse to stop stripping newlines from help texts.
>>> Input is appreciated. Once an approach is decided upon, I'll be
>> updating the --help for the rest of the samba-tool commands.
>>
>> The base Command class in samba.netcmd already supports a
>> "long_description" field, which is intended to contain the same contents
>> your patch now puts into 'full_description'. It bases its contents on
>> the contents of the docstring, and dedents it, so that you can simply
>> write that as you normally would, and there's no need to add extra
>> newlines and the like.
>>
>> I'm not sure if long_description is used anywhere with multiple
>> paragraphs yet (there hasn't been a point in doing that, as the help
>> formatter would just discard the newlines), but we should fix that up if
>> it doesn't work.
> Ok, originally I had coded long_description, but then I saw 
> full_description (which I think is relatively new?) on the
> description field (description=self.full_description), prior to my 
> update... I changed it to use full_description...what is 
> full_description used for?
> anyway, I'll look into it.


-------------- next part --------------
An embedded and charset-unspecified text was scrubbed...
Name: 0001-s4-samba-tool-help-enhancement.patch
URL: <http://lists.samba.org/pipermail/samba-technical/attachments/20111019/9959e15f/attachment.ksh>