Lack of detail on "swift" command

[Chris Stratford]

The command-line swift command has no man page, making it hard to tell what the command will and will not do ("swift --help" provides some information, but not enough)

As a specific example, a file that has been "swift upload"-ed gains an md5sum in the etag, but there is no documentation to say whether the upload is verified against this or whether it is up to the user to check it matches afterwards.

Likewise, there is no docmentation of return codes. A successful upload appears to return 0, as expected and I'm assuming a failure returns something else (what?) Are there different return codes defending on the type of error (e.g. authentication failure returns 1, md5sum mismatch returns 2, etc.)?

[Christian Schwede (cschwede)]

There is already a manpage for python-swiftclient: https://github.com/openstack/python-swiftclient/blob/master/doc/manpages/swift.1

It is not very detailed yet, I'll update it with more informations.

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/67106
Committed: https://git.openstack.org/cgit/openstack/python-swiftclient/commit/?id=63c9917085ac4d5c99afc61e5865cb88417dcd27
Submitter: Jenkins
Branch: master

commit 63c9917085ac4d5c99afc61e5865cb88417dcd27
Author: Christian Schwede <email address hidden>
Date: Thu Jan 16 10:23:02 2014 +0000

    Install swiftclient manpage

    Currently the existing manpage isn't copied to /usr/local/man/man1
    when installing swiftclient from source. This patch fixes this.

    Change-Id: Ib2ee091d5e1d4c37a4e5a00f50fa19df44bd3c41
    Partial-Bug: 1269715

[Dirk Mueller (dmllr)]

this is a bit problematic if you want to install swiftclient on non-ubuntu setup though, as man pages are in share/man/* there. I'm not sure why this was special-cased for one man page for one client.. at the moment the only solution I see is to revert this patch :/

[OpenStack Infra (hudson-openstack)]

Fix proposed to branch: master
Review: https://review.openstack.org/67813

[Christian Schwede (cschwede)]

@Dirk: thanks for the note, I uploaded a new patch fixing this.

My intention was to follow the FHS, and from the spec /usr/local/man should be the correct place for files in /usr/local/bin:

"Manual pages for commands and data under /usr/local are stored in /usr/local/man."

http://www.pathname.com/fhs/pub/fhs-2.3.html#USRSHAREMANMANUALPAGES

Obviously this works not for some distros, thus I changed the prefix to share/man/man1.

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/67813
Committed: https://git.openstack.org/cgit/openstack/python-swiftclient/commit/?id=65d7a136f69a2f0a692eeaed7ca68e2a5f91b07d
Submitter: Jenkins
Branch: master

commit 65d7a136f69a2f0a692eeaed7ca68e2a5f91b07d
Author: Christian Schwede <email address hidden>
Date: Mon Jan 20 10:55:20 2014 +0000

    Install manpage in share/man/man1 instead of man/man1

    According to FHS 2.3 the correct place to install the manpage for a
    binary in /usr/local/bin/ would be /usr/local/man/.

    However, on Debian/Ubuntu-based systems /usr/local/man/ is a link to
    /usr/local/share/man/ and on other systems /usr/local/man/ might not
    exist at all.

    Even worse, if the client is installed in /usr/bin/ the manpage
    should should be installed in /usr/share/man, but will be installed
    in /usr/man/ which is completely wrong.

    This patch fixes this and uses share/man/man1 as common prefix. Doing
    this will install the manpage either in /usr/local/share/man/man1 or
    /usr/share/man/man1.

    Partial-Bug: 1269715
    Change-Id: I590932f00476eacd434cdae012fd62010845581d