Rewritten live-helper manpage.

1 files changed, 100 insertions, 93 deletions

diff --git a/manpages/live-helper.en.7 b/manpages/live-helper.en.7
index 113509cd1..67dcd3267 100644
--- a/manpages/live-helper.en.7
+++ b/manpages/live-helper.en.7
@@ -1,161 +1,164 @@
 .TH LIVE\-HELPER 7 "2007\-11\-19" "1.0~a37" "live\-helper"
 
 .SH NAME
-live\-helper \- Debian Live helper programs
+live\-helper \- the Debian Live tool suite
 
 .SH SYNOPSIS
-.B lh_* [\fIlive\-helper\ options\fR\|]
+\fBdh_\fR\fI*\fR [\fB\-h|\-\-help\fR] [\fB\-u|\-\-usage\fR] [\fB\-v|\-\-version\fR]
 
 .SH DESCRIPTION
-Live\-helper is a collection of programs that can be used to build Debian Live system images. The philosophy behind live\-helper is to provide a collection of small, simple, and easily understood tools that can be used in your own program to automate building of a Live system.
-.PP
-A typical program that uses live\-helper will call several live\-helper commands in sequence. Live\-helper commands are all named with a "lh_" prefix.
-
-.\" .SH CONFIGURATION FILE
-.\" live\-helper reads debian\-live/config/live\-helper if available. See ENVIRONMENT for the correct environment variables to use.
-
-.\" .SH ENVIRONMENT
-.\" Every live\-helper command respects the following environment variables if available.
-.\" .IP "\fI$LH_DEBUG\fR" 4
-.\" enables debug (Default: false)
-.\" .IP "\fI$LH_QUIET\fR" 4
-.\" be quiet (Default: false)
-.\" .IP "\fI$LH_VERBOSE\fR" 4
-.\" be verbose (Default: false)
+live\-helper is used to help you build a Debian Live system. The philosophy
+behind live\-helper is to provide a collection of small, simple, and easily
+understood tools that are used on a config directory to automate all aspects of
+building a Debian Live image.
 
 .SH LIVE\-HELPER COMMANDS
-Here is the complete list of available live\-helper commands. See their man pages for additional documentation.
+Here is the complete list of available live\-helper commands. See their man
+pages for additional documentation.
+.IP "\fIlh\fR(1)" 4
+generic live\-helper wrapper
 .IP "\fIlh_binary\fR(1)" 4
-meta\-helper for lh_binary_*.
+meta\-helper for lh_binary_*
 .IP "\fIlh_binary_chroot\fR(1)" 4
-copies chroot into chroot.
-.IP "\fIlh_binary_debian\-installer\fR(1)" 4
-copies debian-installer into the binary image.
+.IP "\fIlh_binary_debian-installer\fR(1)" 4
+.IP "\fIlh_binary_disk\fR(1)" 4
 .IP "\fIlh_binary_encryption\fR(1)" 4
-encrypts the root filesystem.
 .IP "\fIlh_binary_grub\fR(1)" 4
-copies grub into the binary image.
-.IP "\fIlh_binary_tar\fR(1)" 4
-creates the harddisk binary tarball.
 .IP "\fIlh_binary_includes\fR(1)" 4
-copies files into the binary image.
 .IP "\fIlh_binary_iso\fR(1)" 4
-creates the CD/DVD binary image.
 .IP "\fIlh_binary_linux-image\fR(1)" 4
-copies linux\-image into the binary image.
+.IP "\fIlh_binary_local-hooks\fR(1)" 4
 .IP "\fIlh_binary_local-includes\fR(1)" 4
-copies local files into the binary image.
+.IP "\fIlh_binary_local-packageslists\fR(1)" 4
 .IP "\fIlh_binary_manifest\fR(1)" 4
-creates the package list of the root filesystem.
 .IP "\fIlh_binary_md5sum\fR(1)" 4
-creates md5sum.txt in the binary image.
 .IP "\fIlh_binary_memtest\fR(1)" 4
-copies a memtest into the binary image.
 .IP "\fIlh_binary_net\fR(1)" 4
-creates the netboot binary tarball.
 .IP "\fIlh_binary_rootfs\fR(1)" 4
-creates the root filesystem.
 .IP "\fIlh_binary_syslinux\fR(1)" 4
-copies syslinux into the binary image.
+.IP "\fIlh_binary_tar\fR(1)" 4
 .IP "\fIlh_binary_usb-hdd\fR(1)" 4
-creates the USB-hdd binary image.
 .IP "\fIlh_binary_yaboot\fR(1)" 4
-copies yaboot into the binary image.
 .IP "\fIlh_bootstrap\fR(1)" 4
-meta\-helper for lh_bootstrap_*.
+meta\-helper for lh_bootstrap_*
+.IP "\fIlh_bootstrap_cache\fR(1)" 4
 .IP "\fIlh_bootstrap_cdebootstrap\fR(1)" 4
-bootstraps system with cdebootstrap.
+.IP "\fIlh_bootstrap_copy\fR(1)" 4
 .IP "\fIlh_bootstrap_debootstrap\fR(1)" 4
-bootstraps system with debootstrap.
 .IP "\fIlh_build\fR(1)" 4
-meta\-helper for lh_bootstrap, lh_chroot, lh_binary and lh_source.
+meta\-helper for lh_bootstrap, lh_chroot, lh_binary, and lh_source
 .IP "\fIlh_chroot\fR(1)" 4
-meta\-helper for lh_chroot_*.
+meta\-helper for lh_chroot_*
 .IP "\fIlh_chroot_apt\fR(1)" 4
-configures /etc/apt/apt.conf in chroot.
+.IP "\fIlh_chroot_cache\fR(1)" 4
 .IP "\fIlh_chroot_debianchroot\fR(1)" 4
-configures /etc/debian_chroot in chroot.
+.IP "\fIlh_chroot_devpts\fR(1)" 4
+.IP "\fIlh_chroot_dpkg\fR(1)" 4
 .IP "\fIlh_chroot_hacks\fR(1)" 4
-does evil (temporary) hacks in the chroot.
 .IP "\fIlh_chroot_hooks\fR(1)" 4
-executes additional commands in the chroot.
+.IP "\fIlh_chroot_hostname\fR(1)" 4
 .IP "\fIlh_chroot_hosts\fR(1)" 4
-configures /etc/hosts in the chroot.
 .IP "\fIlh_chroot_interactive\fR(1)" 4
-makes build interactive.
 .IP "\fIlh_chroot_linux-image\fR(1)" 4
-configures /etc/kernel\-img.conf in the chroot.
 .IP "\fIlh_chroot_local-hooks\fR(1)" 4
-executes additional local commands in the chroot.
 .IP "\fIlh_chroot_local-includes\fR(1)" 4
-copies local files into the binary image.
-.IP "\fIlh_chroot_localization\fR(1)" 4
-installs localization packages in the chroot.
 .IP "\fIlh_chroot_local-packages\fR(1)" 4
-installs local packages in the chroot.
 .IP "\fIlh_chroot_local-packageslists\fR(1)" 4
-installs local packages lists in the chroot.
+.IP "\fIlh_chroot_local-preseed\fR(1)" 4
+.IP "\fIlh_chroot_localization\fR(1)" 4
 .IP "\fIlh_chroot_packages\fR(1)" 4
-installs packages in the chroot.
 .IP "\fIlh_chroot_packageslists\fR(1)" 4
-installs packages lists in the chroot.
+.IP "\fIlh_chroot_preseed\fR(1)" 4
 .IP "\fIlh_chroot_proc\fR(1)" 4
-mounts /proc in the chroot.
 .IP "\fIlh_chroot_resolv\fR(1)" 4
-configures /etc/resolv.conf in the chroot.
 .IP "\fIlh_chroot_sources\fR(1)" 4
-configures /etc/apt/sources.list in the chroot.
 .IP "\fIlh_chroot_symlinks\fR(1)" 4
-converts symlinks in the chroot.
 .IP "\fIlh_chroot_sysfs\fR(1)" 4
-mounts /sys in the chroot.
+.IP "\fIlh_chroot_sysv-rc\fR(1)" 4
 .IP "\fIlh_chroot_sysvinit\fR(1)" 4
-minimizes daemon startup in the chroot.
-.IP "\fIlh_chroot_sysvrc\fR(1)" 4
-installs policy\-id hack in the chroot.
 .IP "\fIlh_chroot_tasks\fR(1)" 4
-installs packages tasks in the chroot.
 .IP "\fIlh_clean\fR(1)" 4
-cleans up build directory.
+clean up build directories
 .IP "\fIlh_config\fR(1)" 4
-creates sample configuration.
+create configuration directory
 .IP "\fIlh_losetup\fR(1)" 4
-manages loop device handling
+wrapper for losetup
 .IP "\fIlh_source\fR(1)" 4
-meta\-helper for lh_source_*.
-.IP "\fIlh_source_debian-live\fR(1)" 4
-copies config into source directory.
+meta\-helper for lh_source_*
 .IP "\fIlh_source_debian\fR(1)" 4
-downloads source packages.
+.IP "\fIlh_source_debian-live\fR(1)" 4
+.IP "\fIlh_source_disk\fR(1)" 4
 .IP "\fIlh_source_iso\fR(1)" 4
-creates CD/DVD source image.
+.IP "\fIlh_source_md5sum\fR(1)" 4
 .IP "\fIlh_source_net\fR(1)" 4
-creates netboot source tarball.
+.IP "\fIlh_source_tar\fR(1)" 4
 .IP "\fIlh_source_usb-hdd\fR(1)" 4
-creates USB-hdd source image.
 .IP "\fIlh_testroot\fR(1)" 4
-checks for root privileges.
+ensure that a system is built as root
+.PP
+If a program's name starts with "lh_", and the program is not on the above list,
+then it is not part of the live\-helper package, but it should still work like
+the other programs described on this page.
+
+.SH LIVE\-HELPER CONFIG FILES
+Many live\-helper commands make use of files in the \fIconfig/\fR directory to
+control what they do. Besides the common \fIconfig/common\fR, which is used by
+all live\-helper commands, some additional files can be used to configure the
+behavior of specific live\-helper commands. These files are typically named
+config/stage or config/stage_helper (where "stage" of course, is replaced with
+the name of the stage that they belong to, and "helper" with the name of the
+helper).
+.PP
+For example, dh_bootstrap_debootstrap uses files named config/bootstrap and
+config/bootstrap_debootstrap to read the options it will use. See the man pages
+of individual commands for details about the names and formats of the files they
+use. Generally, these files contain variables with values assigned, one variable
+per line. Some programs in live\-helper use pairs of values or slightly more
+complicated variable assignements.
+.PP
+Note that live\-helper will respects environment variables which are present in
+the context of the shell it is running. If variables can be read from config
+files, then they override environment variables, and if command line options are
+used, they override values from config files. If no value for a given variable
+can be found and thus is unset, live\-helper will automatically set it to the
+default value.
+.PP
+In some rare cases, you may want to have different versions of these files for
+different architectures or distributions. If files named config/stage.arch or
+config/stage_helper.arch, and config/stage.dist or config/stage_helper.dist
+exists, where "arch" is the same as the output of "dpkg \-\-print\-architecture"
+and "dist" is the same as the codename of the target distribution, then they
+will be used in preference to other, more general files.
+.PP
+All config files are shell scripts which are sourced by a live\-helper program.
+That means they have to follow the normal shell syntax. You can also put
+comments in these files; lines beginning with "#" are ignored.
 
-.SH LIVE\-HELPER OPTIONS
+.SH SHARED LIVE\-HELPER OPTIONS
 The following command line options are supported by all live\-helper programs.
+.IP "\fB-h, --help\fR" 4
+display help and exit.
+.IP "\fB-u, --usage\fR" 4
+show usage and exit.
+.IP "\fB-v, --version\fR" 4
+output version information and exit.
+
+.SH COMMON LIVE\-HELPER OPTIONS
+The following command line options are supported by some live\-helper programs.
+See the man page of each program for a complete explanation of what each option
+does.
 .IP "\fB\-\-breakpoints\fR" 4
-run with breakpoints
+run with breakpoints.
 .IP "\fB\-\-conffile\fR" 4
-use custom configuration file
+use custom configuration file.
 .IP "\fB\-\-debug\fR" 4
-show debug information
+show debug information.
 .IP "\fB\-\-force\fR" 4
 force helper execution, even if stage file exists.
-.IP "\fB\-h, \-\-help\fR" 4
-display help and exit
 .IP "\fB\-\-quiet\fR" 4
-be quiet
-.IP "\fB\-u, \-\-usage\fR" 4
-show usage and exit
+be quiet.
 .IP "\fB\-\-verbose\fR" 4
-be verbose
-.IP "\fB\-v, \-\-version\fR" 4
-output version information and exit
+be verbose.
 
 .SH SEE ALSO
 \fIlive\-initramfs\fR(7)
@@ -165,10 +168,14 @@ output version information and exit
 \fIlive\-webhelper\fR(7)
 
 .SH BUGS
-Report bugs against live\-helper <\fIhttp://packages.qa.debian.org/live\-helper\fR>.
+Report bugs against live\-helper
+<\fIhttp://packages.qa.debian.org/live\-helper\fR>.
 
 .SH HOMEPAGE
-More information about the Debian Live project can be found at <\fIhttp://debian\-live.alioth.debian.org/\fR> and <\fIhttp://wiki.debian.org/DebianLive/\fR>.
+More information about the Debian Live project can be found at
+<\fIhttp://debian\-live.alioth.debian.org/\fR> and
+<\fIhttp://wiki.debian.org/DebianLive/\fR>.
 
 .SH AUTHOR
-live\-helper was written by Daniel Baumann <\fIdaniel@debian.org\fR> for the Debian project.
+live\-helper was written by Daniel Baumann <\fIdaniel@debian.org\fR> for the
+Debian project.