Add very basic package docs for each type of package.

Thanks to @alanc and _msw_ for quickly helping me figure out good words
to write to describe Solaris' p5p format.

For #1884.

docs/cli-reference.rst

@@ -210,6 +210,36 @@ General Options
 * ``--gem-git-branch GIT_BRANCH``
     - (gem only) When using a git repo as the source of the gem instead of rubygems.org, use this git branch.
 
+* ``--cpan-perl-bin PERL_EXECUTABLE``
+    - (cpan only) The path to the perl executable you wish to run.
+
+* ``--cpan-cpanm-bin CPANM_EXECUTABLE``
+    - (cpan only) The path to the cpanm executable you wish to run.
+
+* ``--cpan-mirror CPAN_MIRROR``
+    - (cpan only) The CPAN mirror to use instead of the default.
+
+* ``--[no-]cpan-mirror-only``
+    - (cpan only) Only use the specified mirror for metadata.
+
+* ``--cpan-package-name-prefix NAME_PREFIX``
+    - (cpan only) Name to prefix the package name with.
+
+* ``--[no-]cpan-test``
+    - (cpan only) Run the tests before packaging?
+
+* ``--[no-]cpan-verbose``
+    - (cpan only) Produce verbose output from cpanm?
+
+* ``--cpan-perl-lib-path PERL_LIB_PATH``
+    - (cpan only) Path of target Perl Libraries
+
+* ``--[no-]cpan-sandbox-non-core``
+    - (cpan only) Sandbox all non-core modules, even if they're already installed
+
+* ``--[no-]cpan-cpanm-force``
+    - (cpan only) Pass the --force parameter to cpanm
+
 * ``--[no-]deb-ignore-iteration-in-dependencies``
     - (deb only) For '=' (equal) dependencies, allow iterations on the specified version. Default is to be specific. This option allows the same version of a package but any iteration is permitted
 
@@ -429,36 +459,6 @@ General Options
 * ``--rpm-trigger-after-target-uninstall '[OPT]PACKAGE: FILEPATH'``
     - (rpm only) Adds a rpm trigger script located in FILEPATH, having 'OPT' options and linking to 'PACKAGE'. PACKAGE can be a comma seperated list of packages. See: http://rpm.org/api/4.4.2.2/triggers.html
 
-* ``--cpan-perl-bin PERL_EXECUTABLE``
-    - (cpan only) The path to the perl executable you wish to run.
-
-* ``--cpan-cpanm-bin CPANM_EXECUTABLE``
-    - (cpan only) The path to the cpanm executable you wish to run.
-
-* ``--cpan-mirror CPAN_MIRROR``
-    - (cpan only) The CPAN mirror to use instead of the default.
-
-* ``--[no-]cpan-mirror-only``
-    - (cpan only) Only use the specified mirror for metadata.
-
-* ``--cpan-package-name-prefix NAME_PREFIX``
-    - (cpan only) Name to prefix the package name with.
-
-* ``--[no-]cpan-test``
-    - (cpan only) Run the tests before packaging?
-
-* ``--[no-]cpan-verbose``
-    - (cpan only) Produce verbose output from cpanm?
-
-* ``--cpan-perl-lib-path PERL_LIB_PATH``
-    - (cpan only) Path of target Perl Libraries
-
-* ``--[no-]cpan-sandbox-non-core``
-    - (cpan only) Sandbox all non-core modules, even if they're already installed
-
-* ``--[no-]cpan-cpanm-force``
-    - (cpan only) Pass the --force parameter to cpanm
-
 * ``--pear-package-name-prefix PREFIX``
     - (pear only) Name prefix for pear package
 

docs/packages/apk.rst

@@ -0,0 +1,12 @@
+apk - Alpine package format
+===========================
+
+Supported Uses in FPM
+---------------------
+
+fpm supports using ``apk`` only as an output type. This means you can create ``apk`` packages from input types like ``deb``, ``dir``, or ``npm``
+
+apk-specific command line flags
+-------------------------------
+
+.. include:: cli/apk.rst

docs/packages/freebsd.rst

@@ -0,0 +1,12 @@
+freebsd - FreeBSD pkg
+===============================
+
+Supported Uses in FPM
+---------------------
+
+fpm supports using ``freebsd`` only as an output type. This means you can create ``freebsd`` packages from input types like ``deb``, ``dir``, or ``npm``
+
+freebsd-specific command line flags
+-------------------------------
+
+.. include:: cli/freebsd.rst

docs/packages/gem.rst

@@ -0,0 +1,13 @@
+gem - Ruby's rubygem packages
+=============================
+
+Supported Uses in FPM
+---------------------
+
+fpm supports using ``gem`` only as an input type. This means you can convert
+``gem`` input packages to output packages like ``deb``, ``rpm``, and more.
+
+gem-specific command line flags
+-------------------------------
+
+.. include:: cli/gem.rst

docs/packages/osxpkg.rst

@@ -0,0 +1,15 @@
+osxpkg - Apple macOS and OSX packages
+=====================================
+
+Supported Uses in FPM
+---------------------
+
+fpm supports input and output for Apple's package files. These files typically
+end in ".pkg". This means you can read a ``.pkg`` file and convert it to a different
+output type (such as a `dir` or `rpm`). It also means you can create a ``.pkg``
+package file.
+
+osxpkg-specific command line flags
+-------------------------------
+
+.. include:: cli/osxpkg.rst

docs/packages/p5p.rst

@@ -0,0 +1,15 @@
+p5p - Oracle Solaris 11 p5p packages
+====================================
+
+This package format for the Solaris Image Packaging System (IPS) and should be
+useful for OpenSolaris, Solaris 11, and Illumos.
+
+Supported Uses in FPM
+---------------------
+
+fpm supports using ``p5p`` only as an output type. This means you can create ``p5p`` packages from input types like ``deb``, ``dir``, or ``npm``
+
+p5p-specific command line flags
+-------------------------------
+
+.. include:: cli/p5p.rst

docs/packages/pacman.rst

@@ -0,0 +1,12 @@
+pacman - Arch Linux package format
+==================================
+
+Supported Uses in FPM
+---------------------
+
+fpm supports input and output for Arch Linux's package format, pacman. This means you can read a pacman and convert it to a different output type (such as a `dir` or `rpm`). It also means you can create a pacman package.
+
+pacman-specific command line flags
+-------------------------------
+
+.. include:: cli/pacman.rst

docs/packages/pear.rst

@@ -0,0 +1,13 @@
+pear - DESCRIPTION
+===============================
+
+Supported Uses in FPM
+---------------------
+
+fpm supports using ``pear`` only as an input type. This means you can convert
+``pear`` input packages to output packages like ``deb``, ``rpm``, and more.
+
+pear-specific command line flags
+-------------------------------
+
+.. include:: cli/pear.rst

docs/packages/pkgin.rst

@@ -0,0 +1,12 @@
+pkgin - NetBSD's pkgsrc binary packages
+=======================================
+
+Supported Uses in FPM
+---------------------
+
+fpm supports using ``pkgin`` only as an output type. This means you can create ``pkgin`` packages from input types like ``deb``, ``dir``, or ``npm``
+
+pkgin-specific command line flags
+-------------------------------
+
+.. include:: cli/pkgin.rst

docs/packages/pleaserun.rst

@@ -0,0 +1,13 @@
+pleaserun - DESCRIPTION
+===============================
+
+Supported Uses in FPM
+---------------------
+
+fpm supports using ``pleaserun`` only as an input type. This means you can convert
+``pleaserun`` input packages to output packages like ``deb``, ``rpm``, and more.
+
+pleaserun-specific command line flags
+-------------------------------
+
+.. include:: cli/pleaserun.rst

docs/packages/puppet.rst

@@ -0,0 +1,15 @@
+puppet - Puppet Manifests (deprecated)
+======================================
+
+Note: This package type hasn't been maintained since 2012 and generates puppet
+manifests that target Puppet 2.4 or 3.x.
+
+Supported Uses in FPM
+---------------------
+
+fpm supports using ``puppet`` only as an output type. This means you can create ``puppet`` packages from input types like ``deb``, ``dir``, or ``npm``
+
+puppet-specific command line flags
+----------------------------------
+
+.. include:: cli/puppet.rst

docs/packages/python.rst

@@ -0,0 +1,13 @@
+python - Python packages, PyPI, etc
+===================================
+
+Supported Uses in FPM
+---------------------
+
+fpm supports using ``python`` only as an input type. This means you can convert
+``python`` input packages to output packages like ``deb``, ``rpm``, and more.
+
+python-specific command line flags
+----------------------------------
+
+.. include:: cli/python.rst

docs/packages/sh.rst

@@ -0,0 +1,24 @@
+sh - Self-managing shell archive
+================================
+
+The 'sh' output in fpm will generate a shell script that is, itself, an archive.
+
+The resulting shell script will install the files you provided. You can run the
+resulting shell script to see more helpful information.
+
+  # Create an example.sh package
+  % fpm -s empty -t sh -n example
+
+  # Get help.
+  % ./example.sh -h
+
+
+Supported Uses in FPM
+---------------------
+
+fpm supports using ``sh`` only as an output type. This means you can create ``sh`` packages from input types like ``deb``, ``dir``, or ``npm``
+
+sh-specific command line flags
+-------------------------------
+
+.. include:: cli/sh.rst

docs/packages/snap.rst

@@ -0,0 +1,15 @@
+snap - Application package files for Linux
+==========================================
+
+You can learn more about ``snap`` itself by visiting the website: https://snapcraft.io/about
+
+
+Supported Uses in FPM
+---------------------
+
+fpm supports input and output for snap packages. This means you can read a snap and convert it to a different output type (such as a `dir` or `rpm`). It also means you can create a snap package.
+
+snap-specific command line flags
+--------------------------------
+
+.. include:: cli/snap.rst

docs/packages/solaris.rst

@@ -0,0 +1,19 @@
+solaris - Solaris SRV4 package format
+=====================================
+
+This package format is typically used in older Solaris versions (Solaris 7, 8,
+9, and 10). You may also know them by files with a SUNW prefix and may have file names that end in ".pkg".
+
+If you're using Solaris 11, OpenSolaris, or Illumos, you might want to use `the newer package format, p5p`_. 
+
+.. _newer package format, p5p: /packages/p5p.html
+
+Supported Uses in FPM
+---------------------
+
+fpm supports using ``solaris`` only as an output type. This means you can create ``solaris`` packages from input types like ``deb``, ``dir``, or ``npm``
+
+solaris-specific command line flags
+-----------------------------------
+
+.. include:: cli/solaris.rst

docs/packages/tar.rst

@@ -0,0 +1,12 @@
+tar - Tape archives aka "tar" files
+===================================
+
+Supported Uses in FPM
+---------------------
+
+fpm supports input and output for NAME (tar). This means you can read a tar and convert it to a different output type (such as a `dir` or `rpm`). It also means you can create a tar package.
+
+tar-specific command line flags
+-------------------------------
+
+.. include:: cli/tar.rst

docs/packages/virtualenv.rst

@@ -0,0 +1,13 @@
+virtualenv - Python virtualenv
+==============================
+
+Supported Uses in FPM
+---------------------
+
+fpm supports using ``virtualenv`` only as an input type. This means you can convert
+``virtualenv`` input packages to output packages like ``deb``, ``rpm``, and more.
+
+virtualenv-specific command line flags
+--------------------------------------
+
+.. include:: cli/virtualenv.rst

docs/packages/zip.rst

@@ -0,0 +1,12 @@
+zip - Zip files
+===============
+
+Supported Uses in FPM
+---------------------
+
+fpm supports input and output for zip files. This means you can read a zip and convert it to a different output type (such as a `dir` or `rpm`). It also means you can create a zip package.
+
+zip-specific command line flags
+-------------------------------
+
+.. include:: cli/zip.rst