Improve style in README and upload usage

Ref. #11.

README.rst

@@ -14,26 +14,27 @@ Why Should I Use This?
 The goal of ``twine`` is to improve PyPI interaction by improving
 security and testability.
 
-The biggest reason to use ``twine`` is that it securely authenticates you to PyPI
-over HTTPS using a verified connection, while ``python setup.py upload`` `only
-recently stopped using HTTP <https://bugs.python.org/issue12226>`_ in Python
-2.7.9+ and Python 3.2+. This means anytime you use ``python setup.py upload``
-with an older Python version, you expose your username and password to being
-easily sniffed. Twine uses only verified TLS to upload to PyPI, protecting your
-credentials from theft.
+The biggest reason to use ``twine`` is that it securely authenticates
+you to `PyPI`_ over HTTPS using a verified connection, while ``python
+setup.py upload`` `only recently stopped using HTTP
+<https://bugs.python.org/issue12226>`_ in Python 2.7.9+ and Python
+3.2+. This means anytime you use ``python setup.py upload`` with an
+older Python version, you expose your username and password to being
+easily sniffed. Twine uses only verified TLS to upload to PyPI,
+protecting your credentials from theft.
 
 Secondly, it allows you to precreate your distribution files.
 ``python setup.py upload`` only allows you to upload something that you've
 created in the same command invocation. This means that you cannot test the
 exact file you're going to upload to PyPI to ensure that it works before
 uploading it.
 
-Finally, it allows you to pre-sign your files and pass the ``.asc``
-files into the command line invocation (``twine upload
-twine-1.0.1.tar.gz twine-1.0.1.tar.gz.asc``). This enables you to be
-assured that you're typing your ``gpg`` passphrase into ``gpg`` itself
-and not anything else, since *you* will be the one directly executing
-``gpg --detach-sign -a <filename>``.
+Finally, ``twine`` allows you to pre-sign your files and pass the
+``.asc`` files into the command line invocation (``twine upload
+myproject-1.0.1.tar.gz myproject-1.0.1.tar.gz.asc``). This enables you
+to be assured that you're typing your ``gpg`` passphrase into ``gpg``
+itself and not anything else, since *you* will be the one directly
+executing ``gpg --detach-sign -a <filename>``.
 
 
 Features
@@ -43,7 +44,7 @@ Features
 - Uploading doesn't require executing ``setup.py``
 - Uploading files that have already been created, allowing testing of
   distributions before release
-- Supports uploading any packaging format (including wheels)
+- Supports uploading any packaging format (including `wheels`_)
 
 
 Installation
@@ -238,9 +239,10 @@ trackers, chat rooms, and mailing lists is expected to follow the
 .. _`PyPI`: https://pypi.org
 .. _`Test PyPI`: https://packaging.python.org/guides/using-testpypi/
 .. _`Python Packaging User Guide`: https://packaging.python.org/tutorials/distributing-packages/
-.. _`documentation`: http://twine.readthedocs.io/
+.. _`documentation`: https://twine.readthedocs.io/
 .. _`developer documentation`: https://twine.readthedocs.io/en/latest/contributing.html
 .. _`projects`: https://packaging.python.org/glossary/#term-project
 .. _`distributions`: https://packaging.python.org/glossary/#term-distribution-package
 .. _`PyPA Code of Conduct`: https://www.pypa.io/en/latest/code-of-conduct/
 .. _`Warehouse`: https://github.com/pypa/warehouse
+.. _`wheels`: https://packaging.python.org/glossary/#term-wheel

twine/commands/upload.py

@@ -165,60 +165,60 @@ def main(args):
         action=utils.EnvironmentDefault,
         env="TWINE_REPOSITORY",
         default="pypi",
-        help="The repository to upload the package to. "
+        help="The repository (package index) to upload the package to. "
              "Should be a section in the config file (default: "
              "%(default)s). (Can also be set via %(env)s environment "
-             "variable)",
+             "variable.)",
     )
     parser.add_argument(
         "--repository-url",
         action=utils.EnvironmentDefault,
         env="TWINE_REPOSITORY_URL",
         default=None,
         required=False,
-        help="The repository URL to upload the package to. "
+        help="The repository (package index) URL to upload the package to. "
              "This overrides --repository."
              "(Can also be set via %(env)s environment variable.)"
     )
     parser.add_argument(
         "-s", "--sign",
         action="store_true",
         default=False,
-        help="Sign files to upload using gpg",
+        help="Sign files to upload using GPG.",
     )
     parser.add_argument(
         "--sign-with",
         default="gpg",
-        help="GPG program used to sign uploads (default: %(default)s)",
+        help="GPG program used to sign uploads (default: %(default)s).",
     )
     parser.add_argument(
         "-i", "--identity",
-        help="GPG identity used to sign files",
+        help="GPG identity used to sign files.",
     )
     parser.add_argument(
         "-u", "--username",
         action=utils.EnvironmentDefault,
         env="TWINE_USERNAME",
         required=False, help="The username to authenticate to the repository "
-                             "as (can also be set via %(env)s environment "
-                             "variable)",
+                             "(package index) as. (Can also be set via "
+                             "%(env)s environment variable.)",
     )
     parser.add_argument(
         "-p", "--password",
         action=utils.EnvironmentDefault,
         env="TWINE_PASSWORD",
         required=False, help="The password to authenticate to the repository "
-                             "with (can also be set via %(env)s environment "
-                             "variable)",
+                             "(package index) with. (Can also be set via "
+                             "%(env)s environment variable.)",
     )
     parser.add_argument(
         "-c", "--comment",
-        help="The comment to include with the distribution file",
+        help="The comment to include with the distribution file.",
     )
     parser.add_argument(
         "--config-file",
         default="~/.pypirc",
-        help="The .pypirc config file to use",
+        help="The .pypirc config file to use.",
     )
     parser.add_argument(
         "--skip-existing",
@@ -236,21 +236,22 @@ def main(args):
         required=False,
         metavar="path",
         help="Path to alternate CA bundle (can also be set via %(env)s "
-             "environment variable)",
+             "environment variable).",
     )
     parser.add_argument(
         "--client-cert",
         metavar="path",
         help="Path to SSL client certificate, a single file containing the "
-             "private key and the certificate in PEM format",
+             "private key and the certificate in PEM format.",
     )
     parser.add_argument(
         "dists",
         nargs="+",
         metavar="dist",
-        help="The distribution files to upload to the repository, may "
-             "additionally contain a .asc file to include an existing "
-             "signature with the file upload",
+        help="The distribution files to upload to the repository "
+             "(package index). Usually dist/* . May additionally contain "
+             "a .asc file to include an existing signature with the "
+             "file upload.",
     )
 
     args = parser.parse_args(args)