[SCM] Debian Live manual branch, master, updated. c6aa65d7672b47674158b013b40682ac643052c5

[Chris Lamb]

The following commit has been merged in the master branch:
commit c6aa65d7672b47674158b013b40682ac643052c5
Author: Chris Lamb <chris at chris-lamb.co.uk>
Date:   Sun May 11 17:27:35 2008 +0100

    Add 'overview' page, add text on config/ layout
    
    Signed-off-by: Chris Lamb <chris at chris-lamb.co.uk>

diff --git a/chapters/overview.sgml b/chapters/overview.sgml
new file mode 100644
index 0000000..fed8352
--- /dev/null
+++ b/chapters/overview.sgml
@@ -0,0 +1,124 @@
+<chapt id="overview">
+<heading>Overview of tools</heading>
+
+<p>This chapter contains an overview of the two main tools used in building Debian Live systems.</p>
+
+<sect id="live-helper">
+<heading><tt>live-helper</tt></heading>
+<p><tt>live-helper</tt> is a collection of scripts that build Debian Live systems.</p>
+
+<p>The idea behind live-helper is a framework that uses a configuration directory to completely automate and customize all aspects of building a Live image.</p>
+
+<p>Many concepts are similar with the <tt>debhelper</tt> Debian package tools written by Joey Hess:
+
+<list>
+<item>
+<p>The scripts have a central location for configuring their operation.</p>
+<p>In <tt>debhelper</tt>, this is the <file>debian/</file> subdirectory of a package tree. For example, <tt>dh_install</tt> will look for file called <file>debian/&lt;packagename&gt;.install</file> to determine which files should exist in a particular binary package. In much the same way, <tt>live-helper</tt> stores its configuration entirely under a <file>config/</file> subdirectory.</p>
+
+</item>
+<item>The scripts are indepodent - that is to say, it is always safe to run each command.</item>
+</list>
+</p>
+
+<p>Unlike <tt>debhelper</tt>, <tt>live-helper</tt> contains a tool to generate a skeleton configuration directory, <tt>lh_config</tt>. This could be considered to be similar to tools such as <tt>dh-make</tt>. For more information about <tt>lh_config</tt>, please see <ref id="lh_config">.</p>
+
+<p>Besides the common <file>config/common</file>, which is used by all <tt>live-helper</tt> commands, some additional files can be used to configure the behavior of specific helpers. These files are typically named <tt>config/foo</tt> or <tt>config/stage</tt> (where "stage", of course, is replaced with the name of the stage that they belong to, and "helper" with the name of the helper).</p>
+
+<p>For example, <tt>lh_bootstrap_debootstrap</tt> uses files named <file>config/bootstrap</file> and <file>config/bootstrap_debootstrap</file> to read the options it will use. Generally, these files contain variables with values assigned, one variable per line. Some programs in <tt>live-helper</tt> use pairs of values or slightly more complicated variable assignments.</p>
+
+<p><tt>live-helper</tt> 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 is thus unset), <tt>live-helper</tt> will automatically set it to a default value.</p>
+
+<p>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.</p>
+
+<p>In some rare cases, you may want to have different versions of these files for different architectures or distributions. If files named <tt>config/stage.arch</tt> or <tt>config/stage_helper.arch</tt>, and <tt>config/stage.dist</tt> or <tt>config/stage_helper.dist</tt> exist (where "arch" is the same as the output of <tt>dpkg --print-architecture</tt> and "dist" is the same as the codename of the target distribution), then they will be used in preference to the other, more general files.</p>
+
+<p>Please see <ref id="installation"> for information on how to install <tt>live-helper</tt>.
+
+<p>The remainder of this section discusses the three most important helpers:
+<taglist>
+<tag><tt>lh_config</tt></tag>
+<item>Responsible for initialising a Live system configuration directory. See <ref id="lh_config"> for more information.</item>
+
+<tag><tt>lh_build</tt></tag>
+<item>Responsible for starting a Live system build. See <ref id="lh_build"> for more information.</item>
+
+<tag><tt>lh_clean</tt></tag>
+<item>Responsible for removing parts of a Live system build. <ref id="lh_clean"> for more information.</item>
+</taglist>
+</p>
+
+<sect1 id="lh_config">
+<heading>The <tt>lh_config</tt> helper</heading>
+<p>As discussed in <ref id="live-helper">, the scripts that make up <tt>live-helper</tt> source their configuration from a single directory named <tt>config/</tt>. As constructing this directory by hand would be time-consuming and error-prone, the <tt>lh_config</tt> helper can be used to create skeleton configuration folders.</p>
+
+<p>Issuing <tt>lh_config</tt> without any arguments creates a <tt>config</tt> subdirectory which it populates with some default settings:
+<example>
+% lh_config
+% ls -l
+total 4.1k
+drwxr-xr-x 19 user group 4.1k 2008-05-09 21:37 config
+% ls -l config/
+total 91k
+-rw-r--r-- 1 user group 4.0k 2008-05-09 21:37 binary
+drwxr-xr-x 2 user group 4.1k 2008-05-09 21:37 binary_debian-installer
+drwxr-xr-x 2 user group 4.1k 2008-05-09 21:37 binary_grub
+drwxr-xr-x 2 user group 4.1k 2008-05-09 21:37 binary_local-debs
+drwxr-xr-x 2 user group 4.1k 2008-05-09 21:37 binary_local-hooks
+drwxr-xr-x 2 user group 4.1k 2008-05-09 21:37 binary_local-includes
+drwxr-xr-x 2 user group 4.1k 2008-05-09 21:37 binary_local-packageslists
+drwxr-xr-x 2 user group 4.1k 2008-05-09 21:37 binary_local-udebs
+drwxr-xr-x 2 user group 4.1k 2008-05-09 21:37 binary_rootfs
+drwxr-xr-x 2 user group 4.1k 2008-05-09 21:37 binary_syslinux
+-rw-r--r-- 1 user group 1.7k 2008-05-09 21:37 bootstrap
+-rw-r--r-- 1 user group 1.5k 2008-05-09 21:37 chroot
+drwxr-xr-x 2 user group 4.1k 2008-05-09 21:37 chroot_apt
+drwxr-xr-x 2 user group 4.1k 2008-05-09 21:37 chroot_local-hooks
+drwxr-xr-x 2 user group 4.1k 2008-05-09 21:37 chroot_local-includes
+drwxr-xr-x 2 user group 4.1k 2008-05-09 21:37 chroot_local-packages
+drwxr-xr-x 2 user group 4.1k 2008-05-09 21:37 chroot_local-packageslists
+drwxr-xr-x 2 user group 4.1k 2008-05-09 21:37 chroot_sources
+-rw-r--r-- 1 user group 2.9k 2008-05-09 21:37 common
+drwxr-xr-x 2 user group 4.1k 2008-05-09 21:37 includes
+-rw-r--r-- 1 user group  212 2008-05-09 21:37 source
+drwxr-xr-x 2 user group 4.1k 2008-05-09 21:37 templates
+</example>
+</p>
+
+<p>Using <tt>lh_config</tt> without any arguments would be suitable for users who are either happy editing the generated files, or are simply happy with the defaults it creates.</p>
+
+<p>You can ask <tt>lh_config</tt> to generate <file>config/</file> directory "preseeded" with various options. This might be suitable if you do not require the default settings but do not need to change a large number of options. For example:
+
+<example>
+% lh_config -p gnome
+</example>
+
+will build a <file>config/</file> directory configured to include the '<tt>gnome</tt>' package list. It is possible to specify many options:
+
+<example>
+% lh_config --apt aptitude --binary-images net --hostname live-machine --username live-user ...
+</example>
+</p>
+
+<p>A full list of options is available FIXME. Most options have a parallel with an "<tt>LH_</tt>" prefixed variable.</p>
+
+</sect1>
+
+<sect1 id="lh_build">
+<heading>The <tt>lh_build</tt> helper</heading>
+<p>FIXME</p>
+</sect1>
+
+<sect1 id="lh_clean">
+<heading>The <tt>lh_clean</tt> helpe/heading>
+<p>It is the job of the <tt>lh_clean</tt> helper to remove various parts of a Live helper build.</p>
+</sect1>
+</sect>
+
+<sect id="live-initramfs">
+<heading>The <tt>live-initramfs</tt> package</heading>
+<p><tt>live-initramfs</tt> is a collection of scripts.</p>
+<p>FIXME link to Kernel Handbook</p>
+</sect>
+
+</chapt>
diff --git a/debian-live-manual.sgml b/debian-live-manual.sgml
index 7b7b541..51fb425 100644
--- a/debian-live-manual.sgml
+++ b/debian-live-manual.sgml
@@ -5,6 +5,7 @@
 <!entity chapter-about  SYSTEM "chapters/about.sgml">
 <!entity chapter-installation  SYSTEM "chapters/installation.sgml">
 <!entity chapter-basics  SYSTEM "chapters/basics.sgml">
+<!entity chapter-overview  SYSTEM "chapters/overview.sgml">
 <!entity chapter-customisation-packages  SYSTEM "chapters/customisation-packages.sgml">
 <!entity chapter-customisation-contents  SYSTEM "chapters/customisation-contents.sgml">
 <!entity chapter-customisation-bootup  SYSTEM "chapters/customisation-bootup.sgml">
@@ -43,6 +44,7 @@
 <toc detail="sect1">
 &chapter-meta;
 &chapter-about;
+&chapter-overview;
 &chapter-installation;
 &chapter-basics;
 &chapter-customisation-packages;

-- 
Debian Live manual