[SCM] Debian Live manual branch, master, updated. 9ae7b1cd849ea350bd5dc6e26544b935978f33fb
Chris Lamb
chris at chris-lamb.co.uk
Wed Jul 2 11:18:46 UTC 2008
The following commit has been merged in the master branch:
commit 9518a7bfc723a8df83e03db0168fa75ef915f6fb
Author: Chris Lamb <chris at chris-lamb.co.uk>
Date: Sun Jun 22 01:03:48 2008 +0100
Try to adopt a SGML-formatting style that matches d-i's
Signed-off-by: Chris Lamb <chris at chris-lamb.co.uk>
diff --git a/chapters/about.xml b/chapters/about.xml
index b5f703e..618023b 100644
--- a/chapters/about.xml
+++ b/chapters/about.xml
@@ -49,31 +49,51 @@
<section>
<title>Only unchanged, official packages</title>
-<para>We will only use official packages from the Debian repository, section main or maybe contrib (the use of contrib is not decided yet). The non-free section is not part of Debian and therefore not used at all for the live system.</para>
+<para>
+ We will only use official packages from the Debian repository, section main or maybe contrib (the use of contrib is not decided yet). The non-free section is not part of Debian and therefore not used at all for the live system.
+</para>
-<para>We will not change any packages. Whenever we need to change something, we will do that in coordination with its package maintainer in Debian.</para>
+<para>
+ We will not change any packages. Whenever we need to change something, we will do that in coordination with its package maintainer in Debian.
+</para>
-<para>Exception: temporarly, our own packages like live-helper or live-initramfs may be used from our own repository for development reasons (e.g. to create development snapshots). They will be synced into Debian on a regular basis.</para>
+<para>
+ Exception: temporarly, our own packages like live-helper or live-initramfs may be used from our own repository for development reasons (e.g. to create development snapshots). They will be synced into Debian on a regular basis.
+</para>
</section>
<section>
<title>No configuration of the live system</title>
-<para>In this phase we will not ship or install sample or alternative configurations. All packages are used in their default configuration as they are after a regular installation of Debian.</para>
+<para>
+ In this phase we will not ship or install sample or alternative configurations. All packages are used in their default configuration as they are after a regular installation of Debian.
+</para>
-<para>Whenever we need a different default configuration, we will do that in coordination with its package maintainer in Debian.</para>
+<para>
+ Whenever we need a different default configuration, we will do that in coordination with its package maintainer in Debian.
+</para>
-<para>A system for configuring packages is provided using debconf in lh_config (use --preseed FILE) allowing custom configured packages to be installed in your custom produced Debian Live images, but for official live images only default configuration will be used.</para>
+<para>
+ A system for configuring packages is provided using debconf in lh_config (use --preseed FILE) allowing custom configured packages to be installed in your custom produced Debian Live images, but for official live images only default configuration will be used.
+</para>
-<para>Exception: There are a few essential changes needed to be make a live system alive (e.g. configuring pam to allow empty passwords). These essential changes have to be kept as minimal as possible and, should be merged within the Debian repository if possible.</para>
+<para>
+ Exception: There are a few essential changes needed to be make a live system alive (e.g. configuring pam to allow empty passwords). These essential changes have to be kept as minimal as possible and, should be merged within the Debian repository if possible.
+</para>
</section>
<section>
<title>No live system to hardisk installer</title>
-<para>[ this is no longer valid after etch release, we will work on an installer for lenny ]</para>
+<para>
+ [ this is no longer valid after etch release, we will work on an installer for lenny ]
+</para>
-<para>For the moment we will not ship a installer to copy the live system to a partition on the hardisk. Although we keep the changes in the live system as drastically minimal as possible compared to a regular Debian installation, the live system does differ in a few essential points (see exceptions, guideline 2).</para>
+<para>
+ For the moment we will not ship a installer to copy the live system to a partition on the hardisk. Although we keep the changes in the live system as drastically minimal as possible compared to a regular Debian installation, the live system does differ in a few essential points (see exceptions, guideline 2).
+</para>
-<para>Therefore, we will ship a copy of the regular DebianInstaller (resp. Debian Installer, Graphical Installer) instead, to allow users to perform a regular Debian installation (and, of course, cdebootstrap and debootstrap are on the system too).</para>
+<para>
+ Therefore, we will ship a copy of the regular DebianInstaller (resp. Debian Installer, Graphical Installer) instead, to allow users to perform a regular Debian installation (and, of course, cdebootstrap and debootstrap are on the system too).
+</para>
</section>
</section>
diff --git a/chapters/basics.xml b/chapters/basics.xml
index f326633..ca60fb0 100644
--- a/chapters/basics.xml
+++ b/chapters/basics.xml
@@ -6,32 +6,46 @@
<chapter id="basics">
<title>The basics</title>
-<para>This chapter contains a brief overview of the build process as well as containing instructions on how to boot the various binary image types.</para>
+<para>
+ This chapter contains a brief overview of the build process as well as containing instructions on how to boot the various binary image types.
+</para>
<section>
<title>First steps: building an ISO image</title>
-<para>The following sequence of commands will create a basic ISO image containing just the Debian standard system without X.org. It is suitable for burning to CD or DVD media.</para>
+<para>
+ The following sequence of commands will create a basic ISO image containing just the Debian standard system without X.org. It is suitable for burning to CD or DVD media.
+</para>
-<para>First, we must configure our Live system:</para>
+<para>
+ First, we must configure our Live system:
+</para>
<screen>
$ lh_config
</screen>
-<para>Passing no parameters indicated that we wish to use the default binary image type. You will see that &live-helper; created a <filename>"config/"</filename> hierarchy in your current directory - this is used by the rest of &live-helper; to build your live image.</para>
+<para>
+ Passing no parameters indicated that we wish to use the default binary image type. You will see that &live-helper; created a <filename>"config/"</filename> hierarchy in your current directory - this is used by the rest of &live-helper; to build your live image.
+</para>
-<para>We can then build the image with <filename>lh_build</filename> as root:</para>
+<para>
+ We can then build the image with <filename>lh_build</filename> as root:
+</para>
<screen>
# lh_build
</screen>
-<para>This process can take a while, depending on the speed of your network connection.</para>
+<para>
+ This process can take a while, depending on the speed of your network connection.
+</para>
<section>
<title>Testing an ISO image with Qemu</title>
-<para>Testing an ISO is simple:</para>
+<para>
+ Testing an ISO is simple:
+</para>
<screen>
# apt-get install qemu
@@ -53,21 +67,29 @@ $ wodim binary.iso
<section>
<title>Building an USB/HDD image</title>
-<para>The following sequence of commands will create a basic USB/HDD image containing just the Debian standard system without X.org. It is suitable for booting from USB sticks, hard drives and various other portable storage devices.</para>
+<para>
+ The following sequence of commands will create a basic USB/HDD image containing just the Debian standard system without X.org. It is suitable for booting from USB sticks, hard drives and various other portable storage devices.
+</para>
-<para>Note if an iso image had been previously built, you will need to clean live-helper:</para>
+<para>
+ Note if an iso image had been previously built, you will need to clean live-helper:
+</para>
<screen>
$ lh_clean --binary
</screen>
-<para>First, we must configure &live-helper; to create a USD/HDD image type:</para>
+<para>
+ First, we must configure &live-helper; to create a USD/HDD image type:
+</para>
<screen>
$ lh_config -b usb-hdd
</screen>
-<para>We can then build the image with <filename>lh_build</filename> as root:</para>
+<para>
+ We can then build the image with <filename>lh_build</filename> as root:
+</para>
<screen>
# lh_build
@@ -92,28 +114,42 @@ $ qemu -hda binary.img
<section>
<title>Building an netboot image</title>
-<para>First, we configure our Live system:</para>
+<para>
+ First, we configure our Live system:
+</para>
<screen>
$ lh_config -b net --net-root-path "/srv/debian-live" --net-root-server "192.168.0.1"
</screen>
-<para>In contrast with the ISO and USB/HDD image types, netbooting does not support serving a filesystem image with the client so we must serve the files via NFS. The <replaceable>net-root-path</replaceable> and <replaceable>net-root-server</replaceable> options specify the location and server respectfully of the NFS server on the filesytem image will be located at boot-time.</para>
+<para>
+ In contrast with the ISO and USB/HDD image types, netbooting does not support serving a filesystem image with the client so we must serve the files via NFS. The <replaceable>net-root-path</replaceable> and <replaceable>net-root-server</replaceable> options specify the location and server respectfully of the NFS server on the filesytem image will be located at boot-time.
+</para>
-<para>We can then build the image with <filename>lh_build</filename> as root:</para>
+<para>
+ We can then build the image with <filename>lh_build</filename> as root:
+</para>
<screen>
# lh_build
</screen>
-<para>We must now configure three services:</para>
+<para>
+ We must now configure three services:
+</para>
<variablelist>
<varlistentry><term>NFS server</term>
<listitem>
-<para>This contains the Live filesystem image which the system will use at run-time.</para>
-<para>You should install the <computeroutput>nfs-kernel-server</computeroutput> server package -- <computeroutput>nfs-user-server</computeroutput> does not function correctly with netboot.</para>
-<para>FIXME</para>
+<para>
+ This contains the Live filesystem image which the system will use at run-time.
+</para>
+<para>
+ You should install the <computeroutput>nfs-kernel-server</computeroutput> server package -- <computeroutput>nfs-user-server</computeroutput> does not function correctly with netboot.
+</para>
+<para>
+ FIXME
+</para>
<screen>
/srv/debian-live *(rw,sync,no_root_squash)
@@ -123,20 +159,28 @@ $ lh_config -b net --net-root-path "/srv/debian-live" --net-root-server "192.168
<varlistentry><term>TFTPd server</term>
<listitem>
-<para>This serves the kernel and initial ramdisk to the system at run-time.</para>
-<para>You should install the <computeroutput>tftpd-hpa</computeroutput> package.
+<para>
+ This serves the kernel and initial ramdisk to the system at run-time.
+</para>
+<para>
+ You should install the <computeroutput>tftpd-hpa</computeroutput> package.
+</para>
<screen>
$ ls /var/lib/tftpboot/
initrd.gz memtest pxelinux.0 pxelinux.cfg vmlinuz
</screen>
-</para></listitem>
+</listitem>
</varlistentry>
<varlistentry><term>DHCP server</term>
<listitem>
-<para>We must configure our network's DHCP server to advertise the location of the PXE server.</para>
-<para>FIXME</para>
+<para>
+ We must configure our network's DHCP server to advertise the location of the PXE server.
+</para>
+<para>
+ FIXME
+</para>
<screen>
next-server 192.168.0.78;
diff --git a/chapters/common-tasks.xml b/chapters/common-tasks.xml
index d9b7ade..8c4c844 100644
--- a/chapters/common-tasks.xml
+++ b/chapters/common-tasks.xml
@@ -8,7 +8,9 @@
<section id="debian-installer">
<title>The Debian Installer</title>
-<para>FIXME.</para>
+<para>
+ FIXME.
+</para>
</section>
</chapter>
diff --git a/chapters/customisation-bootup.xml b/chapters/customisation-bootup.xml
index efd302b..73fa5ed 100644
--- a/chapters/customisation-bootup.xml
+++ b/chapters/customisation-bootup.xml
@@ -16,11 +16,15 @@
<section id="bootloaders">
<title>Bootloaders</title>
-<para>FIXME</para>
+<para>
+ FIXME
+</para>
<section>
<title>Choosing a bootloader</title>
-<para>FIXME</para>
+<para>
+ FIXME
+</para>
</section>
<section id="syslinux">
@@ -30,29 +34,41 @@
<section>
<title>Bootloader templates</title>
-<para>FIXME</para>
+<para>
+ FIXME
+</para>
</section>
</section>
<section id="splash">
<title>Splash screens</title>
-<para>FIXME</para>
+<para>
+ FIXME
+</para>
</section>
<section id="memtest">
<title>Memtest</title>
-<para>FIXME</para>
+<para>
+ FIXME
+</para>
</section>
<section id="startup-scripts">
<title>Startup scripts</title>
-<para>FIXME</para>
+<para>
+ FIXME
+</para>
</section>
<section id="cheat-codes">
<title>Cheat codes</title>
-<para>FIXME</para>
-<para>Checksums.</para>
+<para>
+ FIXME
+</para>
+<para>
+ Checksums.
+</para>
</section>
</chapter>
diff --git a/chapters/customisation-packages.xml b/chapters/customisation-packages.xml
index 7aeda5f..61b9bce 100644
--- a/chapters/customisation-packages.xml
+++ b/chapters/customisation-packages.xml
@@ -6,7 +6,9 @@
<chapter id="packages">
<title>Customising package installation</title>
-<para>This chapter discusses the customisation of package installation. This involves:</para>
+<para>
+ This chapter discusses the customisation of package installation. This involves:
+</para>
<orderedlist>
<listitem><para>Selecting additional packages to be installed</para></listitem>
@@ -15,26 +17,38 @@
<section id="package-sources">
<title>Package sources</title>
-<para>FIXME</para>
+<para>
+ FIXME
+</para>
</section>
<section id="package-installation">
<title>Package installation</title>
-<para>You can elect to use either <computeroutput>apt</computeroutput> or <computeroutput>aptitude</computeroutput> when installing packages. Which utility is used is governed by the <computeroutput>LH_APT</computeroutput> variable in <filename>config/chroot</filename> or by the <computeroutput>--apt</computeroutput> argument to <filename>lh_config</filename>:</para>
+<para>
+ You can elect to use either <computeroutput>apt</computeroutput> or <computeroutput>aptitude</computeroutput> when installing packages. Which utility is used is governed by the <computeroutput>LH_APT</computeroutput> variable in <filename>config/chroot</filename> or by the <computeroutput>--apt</computeroutput> argument to <filename>lh_config</filename>:
+</para>
<variablelist>
<varlistentry><term><computeroutput>apt</computeroutput></term>
<listitem>
-<para>Specifying a missing package causes package installation to fail, which may not be the desired behaviour.</para>
-<para>This is the default setting for building images for Lenny or later.</para>
+<para>
+ Specifying a missing package causes package installation to fail, which may not be the desired behaviour.
+</para>
+<para>
+ This is the default setting for building images for Lenny or later.
+</para>
</listitem>
</varlistentry>
<varlistentry><term><computeroutput>aptitude</computeroutput></term>
<listitem>
-<para>Specifying a missing package causes package installation to succeed, which may not be the desired behaviour.</para>
-<para>This is the default setting for building images for Etch.</para>
+<para>
+ Specifying a missing package causes package installation to succeed, which may not be the desired behaviour.
+</para>
+<para>
+ This is the default setting for building images for Etch.
+</para>
</listitem>
</varlistentry>
</variablelist>
@@ -44,7 +58,9 @@
<section>
<title>Installing additional packages</title>
-<para>&live-helper; has a number of mechanisms for indicating that additional packages should be installed, including:</para>
+<para>
+ &live-helper; has a number of mechanisms for indicating that additional packages should be installed, including:
+</para>
<orderedlist>
<listitem><para>The <computeroutput>LH_PACKAGES</computeroutput> variable</para></listitem>
@@ -55,13 +71,17 @@
<section id="lh-packages">
<title>The <computeroutput>LH_PACKAGES</computeroutput> variable</title>
-<para>To install additional packages, simply add them to the <computeroutput>LH_PACKAGES</computeroutput> variable in <filename>config/chroot</filename>. For example:</para>
+<para>
+ To install additional packages, simply add them to the <computeroutput>LH_PACKAGES</computeroutput> variable in <filename>config/chroot</filename>. For example:
+</para>
<screen>
LH_PACKAGES="package1 package2 package3 ... "
</screen>
-<para>You can also specify an initial values on the command line:</para>
+<para>
+ You can also specify an initial values on the command line:
+</para>
<screen>
% lh_config --packages "package1 package2 package3"
@@ -69,12 +89,16 @@ LH_PACKAGES="package1 package2 package3 ... "
<para>The behaviour of &live-helper; when specifying a package that does not exist is determined by your choice of APT utility. See <xref linkend="package-installation"/> for more details.</para>
-<para>If you need to specify a large number of packages to be installed or you need flexibility regarding which packages to install, you should probably be using package lists. See <xref linkend="package-lists"/> for more information.</para>
+<para>
+ If you need to specify a large number of packages to be installed or you need flexibility regarding which packages to install, you should probably be using package lists. See <xref linkend="package-lists"/> for more information.
+</para>
</section>
<section id="package-lists">
<title>Package lists</title>
-<para>Package lists are a powerful way of expressing which packages should be installed. &live-helper; ships with a number of predefined package lists which provide sensible default package selections for the GNOME and KDE desktop environments, as well as standard systems.</para>
+<para>
+ Package lists are a powerful way of expressing which packages should be installed. &live-helper; ships with a number of predefined package lists which provide sensible default package selections for the GNOME and KDE desktop environments, as well as standard systems.
+</para>
<para>To specify a package list, add the name of the list to the <computeroutput>LH_PACKAGES_LISTS</computeroutput> variable in <filename>config/chroot</filename>. For example:</para>
@@ -86,8 +110,12 @@ LH_PACKAGES_LISTS="gnome"
<section>
<title>Local packages lists</title>
-<para>You may supplement the supplied lists using local package lists stored in <computeroutput>config/chroot_local-packageslists</computeroutput>.</para>
-<para>Package lists that exist in this directory always override package lists distributed with &live-helper;. This can cause undesired effects when..</para>
+<para>
+ You may supplement the supplied lists using local package lists stored in <computeroutput>config/chroot_local-packageslists</computeroutput>.
+</para>
+<para>
+ Package lists that exist in this directory always override package lists distributed with &live-helper;. This can cause undesired effects when..
+</para>
</section>
@@ -100,7 +128,9 @@ LH_PACKAGES_LISTS="gnome"
iceweasel
</screen>
-<para>The package lists that are included with &live-helper; make extensive use of includes. They are available to view in the <computeroutput>/usr/share/live-helper/lists</computeroutput> directory.</para>
+<para>
+ The package lists that are included with &live-helper; make extensive use of includes. They are available to view in the <computeroutput>/usr/share/live-helper/lists</computeroutput> directory.
+</para>
</section>
<section>
@@ -137,8 +167,12 @@ vrms
#endif
</screen>
-<para>Any &live-helper; configuration variable that begins with <computeroutput>LH_</computeroutput> can be tested in this way.</para>
-<para>The nesting of conditionals is not supported.</para>
+<para>
+ Any &live-helper; configuration variable that begins with <computeroutput>LH_</computeroutput> can be tested in this way.
+</para>
+<para>
+ The nesting of conditionals is not supported.
+</para>
</section>
@@ -182,23 +216,37 @@ vrms
<section id="custom-apt-repo">
<title>Using an APT repository to install custom packages</title>
-<para>FIXME</para>
-<para>Unlike You must ensure that you specify the package elsewhere, see (FIXME)</para>
-<para>Whilst it may seem unnecessary effort to create an APT repository to install custom packages, the infrastructure can be easily re-used at a later date to offer updates of the modified package.</para>
+<para>
+ FIXME
+</para>
+<para>
+ Unlike You must ensure that you specify the package elsewhere, see (FIXME)
+</para>
+<para>
+ Whilst it may seem unnecessary effort to create an APT repository to install custom packages, the infrastructure can be easily re-used at a later date to offer updates of the modified package.
+</para>
</section>
<section id="custom-packages-apt">
<title>Custom packages and APT</title>
-<para>&live-helper; uses APT to install all packages into the live system so will therefore inherit behaviours from this program. One relevant example is that (assuming a default configuration) given a package is available in two different repositories, APT will elect to install the package with a higher version number over one with the lower.</para>
+<para>
+ &live-helper; uses APT to install all packages into the live system so will therefore inherit behaviours from this program. One relevant example is that (assuming a default configuration) given a package is available in two different repositories, APT will elect to install the package with a higher version number over one with the lower.
+</para>
-<para>Because of this. you may wish to increment the version number in your custom packages' <computeroutput>debian/changelog</computeroutput> files to ensure that your modified version is installed over one in the official Debian repositories. This may also be achieved by altering the live system's APT pinning preferences - see <xref linkend="apt-preferences"/> for more information.</para>
+<para>
+ Because of this. you may wish to increment the version number in your custom packages' <computeroutput>debian/changelog</computeroutput> files to ensure that your modified version is installed over one in the official Debian repositories. This may also be achieved by altering the live system's APT pinning preferences - see <xref linkend="apt-preferences"/> for more information.
+</para>
</section>
<section id="apt-preferences">
<title>Altering APT preferences during Live system</title>
-<para>FIXME</para>
-<para>Whilst it may seem unnecessary effort to create an APT repository to install custom packages, the infrastructure can be easily re-used at a later date to offer updates of the modified package.</para>
+<para>
+ FIXME
+</para>
+<para>
+ Whilst it may seem unnecessary effort to create an APT repository to install custom packages, the infrastructure can be easily re-used at a later date to offer updates of the modified package.
+</para>
</section>
</section>
diff --git a/chapters/installation.xml b/chapters/installation.xml
index 574e434..89fd0e1 100644
--- a/chapters/installation.xml
+++ b/chapters/installation.xml
@@ -9,7 +9,9 @@
<section>
<title>Requirements</title>
-<para>Building Debian Live images has very few system requirements:</para>
+<para>
+ Building Debian Live images has very few system requirements:
+</para>
<orderedlist>
<listitem><para>Super user (root) access</para></listitem>
<listitem><para>An up-to-date version of &live-helper;</para></listitem>
@@ -25,7 +27,9 @@
<section>
<title>Installing &live-helper;</title>
-<para>You may install &live-helper; in a number of different ways:</para>
+<para>
+ You may install &live-helper; in a number of different ways:
+</para>
<orderedlist>
<listitem><para>From the Debian repository</para></listitem>
@@ -39,13 +43,17 @@
<section>
<title>From the Debian repository</title>
- <para>Simply install &live-helper; like any other package:</para>
+<para>
+ Simply install &live-helper; like any other package:
+</para>
<screen>
% apt-get install live-helper
</screen>
-<para>or</para>
+<para>
+ or
+</para>
<screen>
% aptitude install live-helper
@@ -56,13 +64,17 @@
<section>
<title>From source</title>
- <para>&live-helper; is developed using the Git revision control system. On Debian systems, this is provided by the <computeroutput>git-core</computeroutput> package. To check out the latest code, execute:</para>
+<para>
+ &live-helper; is developed using the Git revision control system. On Debian systems, this is provided by the <computeroutput>git-core</computeroutput> package. To check out the latest code, execute:
+</para>
<screen>
% git clone git://git.debian.net/git/live-helper.git
</screen>
- <para>You can build and install your own Debian package by executing:</para>
+<para>
+ You can build and install your own Debian package by executing:
+</para>
<screen>
% cd live-helper
@@ -77,7 +89,9 @@
% live-helper/helpers/lh_local
</screen>
- <para>Subsequent calls to <filename>lh_</filename>-prefixed helpers in that shell environment will then use the version located in the directory you executed <filename>lh_local</filename> from.</para>
+<para>
+ Subsequent calls to <filename>lh_</filename>-prefixed helpers in that shell environment will then use the version located in the directory you executed <filename>lh_local</filename> from.
+</para>
<para>You can also install &live-helper; directly to your system by executing:</para>
--
Debian Live manual
More information about the debian-live-changes
mailing list