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

[Jelmer Vernooij]

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.

I'm not a native English speaker, so perhaps somebody who is can also
have a look at the proposed help text. 

> +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.
> 
> 

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 836 bytes
Desc: This is a digitally signed message part
URL: <http://lists.samba.org/pipermail/samba-technical/attachments/20111025/08f8dadf/attachment.pgp>