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

[Jelmer Vernooij]

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

Hi Theresa,

On 10/17/2011 05:44 PM, Theresa Halloran wrote:
> Hi all,
>
> 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.
>
> I also changed the samba-tool user add to samba-tool user create. I
think create is more accurate than add since the user is being created
with this command, as opposed to added, which is used for e.g. when we
add a user to a group...in the add case the user already exists.
Thanks for working on this. I didn't realize there was a way to get
optparse to stop stripping newlines from help texts.

It might make sense to split up these changes ("net user add -> net user
create" and the help improvements), so they can be discussed and landed
separately (and one doesn't have to block on the other).

The renaming of "net user add" to "net user create" seems reasonable to me.

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

Cheers,

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

iQIcBAEBAgAGBQJOnFdKAAoJEACAbyvXKaRXCbgQAIF0KyATFHa+M7n1++gqj9AC
vdaOB21Lqn/DVqWPijIswEkuNxJXGZH+HwUqIBhRKgirj02XxeLVIyDulm2TjX3n
/RieArMGANbZ7qjuqasTxp/AXycXVzy5rpXtLs8VXs4eeZy3ZRSod7bOIko3V5Ag
aiOWWaeAVacSbOIuFWMIb+u1kaFubbi3jTDKHDDFmazDb5CDka3UwC9xdWr6ekuu
Cnxi0U0GQQaDmjCLZGAK9EQjLQLMVyJtEAMSUVSDCla25JSdQDKyrG0avCRGRG0I
i5nHSr2z+xiUMk+78xOmAUJZzGIgd1fQtj380QhsrqgHA2AchilI+UePmSv5vZ6V
Vhmyr18HEGxL0z6g9In+MhMga5Ba5Av6B9+JGrHdQYxxoGeLH79983CGjbTdsKaJ
VpOF9zWLMtH2mKBvH2tuGAVZt7HuPnvkTIvQIBm5yarY35Peo1MCEkl7TQPXRMA7
HWDy2C5hAk5kmbFmmxQkwEdNIjJ5v4VWwBJz/319lDLSlxlPFfqFrESfAXj4avYI
FZxFQNUK6aJK7av4iS/KLaZt/Ru884fU6L6UaTA7WFNWqBBGRV9A2e/qSctpwgLA
/8OyKL5c+UBjo4+tkq0rr9x58R1bfxaoiAZ6jRZD/QfrT+nb/eW4QJji72/cIqFk
0A8XDkLUvRTJtaXS+REQ
=tyUm
-----END PGP SIGNATURE-----