Annotate examples with a description of their effect

mmdebstrap

@@ -2518,15 +2518,32 @@ be added at the end of the option if necessary. If the command line argument
 is an existing I<file>, the content of the file will be appended to 99mmdebstrap
 verbatim.
 
-Examples:
+Example: This is necessary for allowing old timestamps from snapshot.debian.org
 
     --aptopt='Acquire::Check-Valid-Until "false"'
+
+Example: Settings controlling download of package description translations
+
     --aptopt='Acquire::Languages { "environment"; "en"; }'
     --aptopt='Acquire::Languages "none"'
+
+Example: Enable installing Recommends (by default mmdebstrap doesn't)
+
     --aptopt='Apt::Install-Recommends "true"'
+
+Example: Configure apt-cacher or apt-cacher-ng as an apt proxy
+
     --aptopt='Acquire::http { Proxy "http://127.0.0.1:3142"; }'
+
+Example: For situations in which the apt sandbox user cannot access the chroot
+
     --aptopt='APT::Sandbox::User "root"'
 
+Example: Minimizing the number of packages installed from experimental
+
+    --aptopt='APT::Solver "aspcud"'
+    --aptopt='APT::Solver::aspcud::Preferences "-count(solution,APT-Release:=/a=experimental/),-removed,-changed,-new"'
+
 =item B<--dpkgopt>=I<option>|I<file>
 
 Pass arbitrary I<option>s to dpkg. Will be added to
@@ -2535,7 +2552,15 @@ multiple times. Each I<option> will be appended to 99mmdebstrap. If the command
 line argument is an existing I<file>, the content of the file will be appended to
 99mmdebstrap verbatim.
 
-Example: --dpkgopt="path-exclude=/usr/share/man/*"
+Example: Exclude paths to reduce chroot size
+
+    --dpkgopt='path-exclude=/usr/share/man/*'
+    --dpkgopt='path-include=/usr/share/man/man[1-9]/*'
+    --dpkgopt='path-exclude=/usr/share/locale/*'
+    --dpkgopt='path-include=/usr/share/locale/locale.alias'
+    --dpkgopt='path-exclude=/usr/share/doc/*'
+    --dpkgopt='path-include=/usr/share/doc/*/copyright'
+    --dpkgopt='path-include=/usr/share/doc/*/changelog.Debian.*'
 
 =item B<--include>=I<pkg1>[,I<pkg2>,...]
 
@@ -2580,7 +2605,7 @@ directory can be accessed via I<$1>. All environment variables used by
 B<mmdebstrap> (like C<APT_CONFIG>, C<DEBIAN_FRONTEND>, C<LC_ALL> and C<PATH>)
 are preserved.
 
-Examples:
+Example: Setup merged-/usr via symlinks
 
     --setup-hook='for d in bin sbin lib; do ln -s usr/$d "$1/$d"; mkdir -p "$1/usr/$d"; done'
 
@@ -2598,9 +2623,12 @@ chroot directory can be accessed via I<$1>. All environment variables used by
 B<mmdebstrap> (like C<APT_CONFIG>, C<DEBIAN_FRONTEND>, C<LC_ALL> and C<PATH>)
 are preserved.
 
-Examples:
+Example: Enable unattended upgrades
 
     --essential-hook='echo unattended-upgrades unattended-upgrades/enable_auto_updates boolean true | chroot "$1" debconf-set-selections'
+
+Example: Select Europe/Berlin as the timezone
+
     --essential-hook='echo tzdata tzdata/Areas select Europe | chroot "$1" debconf-set-selections'
     --essential-hook='echo tzdata tzdata/Zones/Europe select Berlin | chroot "$1" debconf-set-selections'
 
@@ -2617,7 +2645,7 @@ chroot directory can be accessed via I<$1>. All environment variables used by
 B<mmdebstrap> (like C<APT_CONFIG>, C<DEBIAN_FRONTEND>, C<LC_ALL> and C<PATH>)
 are preserved.
 
-Examples:
+Example: Preparing a chroot for use with autopkgtest
 
     --customize-hook='chroot "$1" passwd --delete root'
     --customize-hook='chroot "$1" useradd --home-dir /home/user --create-home user'