Add documentation

cdist/conf/type/__apt_pin/man.rst

@@ -13,11 +13,21 @@ This space intentionally left blank.
 
 REQUIRED PARAMETERS
 -------------------
-None.
+distribution
+   Specifies what distribution the package should be pinned to. Accepts both codenames (buster/bullseye/sid) and suite names (stable/testing/...).
 
 
 OPTIONAL PARAMETERS
 -------------------
+package
+   Package name or glob/RE expression to match multiple packages. If not specified `__object_id` is used.
+
+priority
+   The priority value to assign to matching packages. Deafults to 500. (To match the default target distro's priority)
+
+state
+   Will be passed to underlying `__file` type; see there for valid values and defaults.
+
 None.
 
 
@@ -31,14 +41,31 @@ EXAMPLES
 
 .. code-block:: sh
 
+   # Add the bullseye repo to buster, but do not install any pacakges by default
+   # only if explicitely asked for
+    __apt_pin bullseye-default \
+       --package "*" \
+       --distribution bullseye \
+       --priority -1
+
+    require="__apt_pin/bullseye-default" __apt_source bullseye \
+       --uri http://deb.debian.org/debian/ \
+       --distribution bullseye \
+       --component main
        # TODO
        __apt_pin
 
+    __apt_pin foo --package "foo foo-*" --distribution bullseye
+
+    __foo # Installs the `foo` package internally
+
+    __package foo-plugin-extras
+
 
 SEE ALSO
 --------
-:strong:`TODO`\ (7)
+:strong:`apt_preferences`\ (7)
-
+:strong:`cdist-type__file`\ (7)
 
 AUTHORS
 -------