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

[Theresa Halloran]

On 10/25/2011 4:41 AM, Jelmer Vernooij wrote:
> Hi Theresa,
>
> On Wed, 2011-10-19 at 14:05 -0400, Theresa Halloran wrote:
>> 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!
> Sorry for taking so long to get back to you. I think this looks good.
>
> In general, we stick to 80 characters per line, consistent with PEP8
> (www.python.org/dev/peps/pep-0008), but I guess in this case that would
> break the paragraphs? That can perhaps be improved in a later patch.
Jelmer, Thanks for your response and for info on the PEP8 doc.  I will 
review it.

If I start adding newlines to break the input at 80 chars, it will mess up
the formatting, so I'm open to suggestions on fixing that at some point.
I guess for now I'll leave as is....

> I'm not a native English speaker, so perhaps somebody who is can also
> have a look at the proposed help text.
>
Ok.
>> +This command creates a new user account in the Active Directory
> domain.  The username specified on the command is the SAMaccountname.
> Should this perhaps be "specified on the command-line" ?
>
>> +User accounts may represent physical entities, such as people or may
> be used as service accounts for applications.  User accounts are also
> referred to as security principals and are assigned a security
> identifier (SID).
> "may be used for application service accounts" sounds better to me.
>
>> +A user account enables a user to logon to a computer and domain with
> an identity that can be authenticate.  To maximize security, each user
> should have their own unique user account and password.  A user's access
> to domain resources is based on permissions assigned to the user
> account.
> s/authenticate/authenticated/
>
> I think "user's" should be "users'"
>
> Cheers,
>
> Jelmer
>
>>>>> 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.
>>