[SCM] Debian Live manual branch, master, updated. 0ad728f00ea683889d3463aa71fbcda3fa2bce00
Chris Lamb
chris at chris-lamb.co.uk
Sun May 11 21:52:18 UTC 2008
The following commit has been merged in the master branch:
commit 0ad728f00ea683889d3463aa71fbcda3fa2bce00
Author: Chris Lamb <chris at chris-lamb.co.uk>
Date: Sun May 11 22:52:14 2008 +0100
Add &live-helper; and &live-initramfs; HTML entities to save typing
Signed-off-by: Chris Lamb <chris at chris-lamb.co.uk>
diff --git a/chapters/basics.xml b/chapters/basics.xml
index b0f68e8..fac775c 100644
--- a/chapters/basics.xml
+++ b/chapters/basics.xml
@@ -19,7 +19,7 @@
$ lh_config
</screen>
-<para>Passing no parameters indicated that we wish to use the default binary image type. You will see that <filename>live-helper</filename> created a <filename>"config/"</filename> hierarchy in your current directory - this is used by the rest of <filename>live-helper</filename> 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>
@@ -61,7 +61,7 @@ $ wodim binary.iso
$ lh_clean --binary
</screen>
-<para>First, we must configure <filename>live-helper</filename> 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
diff --git a/chapters/customisation-packages.xml b/chapters/customisation-packages.xml
index c6864a0..dc217b7 100644
--- a/chapters/customisation-packages.xml
+++ b/chapters/customisation-packages.xml
@@ -44,7 +44,7 @@
<section>
<title>Installing additional packages</title>
-<para><filename>live-helper</filename> 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>
@@ -67,14 +67,14 @@ LH_PACKAGES="package1 package2 package3 ... "
% lh_config --packages "package1 package2 package3"
</screen>
-<para>The behaviour of <filename>live-helper</filename> 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>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>
</sect1>
<sect1 id="package-lists">
<title>Package lists</title>
-<para>Package lists are a powerful way of expressing which packages should be installed. <filename>live-helper</filename> 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>
@@ -82,12 +82,12 @@ LH_PACKAGES="package1 package2 package3 ... "
LH_PACKAGES_LISTS="gnome"
</screen>
-<para>Packages lists that a distributed with <filename>live-helper</filename> reside in view in the <computeroutput>/usr/share/live-helper/lists</computeroutput> directory.</para>
+<para>Packages lists that a distributed with &live-helper; reside in view in the <computeroutput>/usr/share/live-helper/lists</computeroutput> directory.</para>
<sect2>
<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 <filename>live-helper</filename>. This can cause undesired effects when..</para>
+<para>Package lists that exist in this directory always override package lists distributed with &live-helper;. This can cause undesired effects when..</para>
</sect2>
@@ -100,7 +100,7 @@ LH_PACKAGES_LISTS="gnome"
iceweasel
</screen>
-<para>The package lists that are included with <filename>live-helper</filename> 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>
</sect2>
<sect2>
@@ -137,7 +137,7 @@ vrms
#endif
</screen>
-<para>Any <filename>live-helper</filename> configuration variable that begins with <computeroutput>LH_</computeroutput> can be tested in this way.</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>
</sect2>
@@ -189,7 +189,7 @@ vrms
<sect1 id="custom-packages-apt">
<title>Custom packages and APT</title>
-<para><filename>live-helper</filename> 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>
diff --git a/chapters/installation.xml b/chapters/installation.xml
index f4ef066..070ec80 100644
--- a/chapters/installation.xml
+++ b/chapters/installation.xml
@@ -11,7 +11,7 @@
<para>Building Debian Live images has very few system requirements:</para>
<orderedlist>
-<listitem><para>An up-to-date version of <filename>live-helper</filename></para></listitem>
+<listitem><para>An up-to-date version of &live-helper;</para></listitem>
<listitem><para>A POSIX-compliant shell, such as <computeroutput>bash</computeroutput> or <computeroutput>dash</computeroutput>.</para></listitem>
<listitem><para><computeroutput>debootstrap</computeroutput> or <computeroutput>cdebootstrap</computeroutput></para></listitem>
<listitem><para>Linux 2.6.x</para></listitem>
@@ -19,9 +19,9 @@
</section>
<section>
-<title>Installing <filename>live-helper</filename></title>
+<title>Installing &live-helper;</title>
-<para>You may install <filename>live-helper</filename> 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>
@@ -30,7 +30,7 @@
<listitem><para>From backports.org</para></listitem>
</orderedlist>
-<para>If you are using <emphasis>lenny</emphasis> or <emphasis>sid</emphasis> the recommended way is to install <filename>live-helper</filename> is via APT.</para>
+<para>If you are using <emphasis>lenny</emphasis> or <emphasis>sid</emphasis> the recommended way is to install &live-helper; is via APT.</para>
<sect1>
<title>From the Debian repository</title>
@@ -53,17 +53,17 @@
<sect1>
<title>From 'snapshots'</title>
-<para>If you do not wish to build or install <filename>live-helper</filename> from source, you can use snapshots. These are built automatically from the latest version in Git.</para>
+<para>If you do not wish to build or install &live-helper; from source, you can use snapshots. These are built automatically from the latest version in Git.</para>
</sect1>
<sect1>
<title>From Backports.org</title>
-<para>Whilst <filename>live-helper</filename> and friends are currently not a part of Debian stable relase, they will work on <emphasis>etch</emphasis> as well. You will need the following programs:</para>
+<para>Whilst &live-helper; and friends are currently not a part of Debian stable relase, they will work on <emphasis>etch</emphasis> as well. You will need the following programs:</para>
<orderedlist>
<listitem><para>An <emphasis>etch</emphasis> backport of <computeroutput>cdebootstrap</computeroutput> from backports.org</para></listitem>
-<listitem><para>The <emphasis>lenny</emphasis> or <emphasis>sid</emphasis> version of <filename>live-helper</filename></para></listitem>
+<listitem><para>The <emphasis>lenny</emphasis> or <emphasis>sid</emphasis> version of &live-helper;</para></listitem>
</orderedlist>
<sect2>
@@ -92,9 +92,9 @@ apt-get install -t etch-backports cdebootstrap
</sect2>
<sect2>
-<title>Installing <filename>live-helper</filename> on etch</title>
+<title>Installing &live-helper; on etch</title>
-<para>It is not recommended that you use <filename>live-helper</filename> from backports.org as it is likely to be out of date.
+<para>It is not recommended that you use &live-helper; from backports.org as it is likely to be out of date.
The live-helper package from Lenny or Sid can be installed on Etch (without upgrading other packages, such as libc6; it's just shell scripts).
@@ -113,17 +113,17 @@ Of course you need the testing or unstable sources in /etc/apt/sources.list for
</section>
<section>
-<title><filename>live-initramfs</filename></title>
+<title>&live-initramfs;</title>
<para><emphasis>N.B. You do not need to install on your host system to create customised Debian Live systems. However, doing so will do no harm.</emphasis></para>
<sect1>
-<title>Using a customised <filename>live-initramfs</filename></title>
+<title>Using a customised &live-initramfs;</title>
<para>To modify the code you can follow the process below. Please ensure you are familiar with the terms mentioned in <xref linkend="terms"/>.</para>
<orderedlist>
-<listitem><para>Checkout the <filename>live-initramfs</filename> source</para>
+<listitem><para>Checkout the &live-initramfs; source</para>
<screen>
$ git clone git://git.debian.org/git/users/daniel/live-initramfs.git
@@ -133,7 +133,7 @@ $ git clone git://git.debian.org/git/users/daniel/live-initramfs.git
<listitem><para>Make changes to your local copy</para></listitem>
<listitem>
-<para>Build a <filename>live-initramfs</filename> <computeroutput>.deb</computeroutput></para>
+<para>Build a &live-initramfs; <computeroutput>.deb</computeroutput></para>
<para>You must build either on your target distribution or in a chroot containing your target platform: this means if your target is lenny then you should build against lenny. You can use a personal builder such <computeroutput>pbuilder</computeroutput> to automate building packages in chroot. To build directly on the target platform, use <computeroutput>debuild</computeroutput> (provided by the <computeroutput>devscripts</computeroutput> package):</para>
<screen>
@@ -143,9 +143,9 @@ $ debuild -us -uc -b
</listitem>
<listitem>
-<para>Use the generated <filename>live-initramfs</filename> <computeroutput>.deb</computeroutput></para>
+<para>Use the generated &live-initramfs; <computeroutput>.deb</computeroutput></para>
-<para>As <filename>live-initramfs</filename> is installed by the build system, installing the package in the host system is not sufficient: you should treat the generated <computeroutput>.deb</computeroutput> like another custom package. Please see <xref linkend="custom-packages"/> for more information. You should pay particular attention to <xref linkend="custom-packages-apt"/>.</para>
+<para>As &live-initramfs; is installed by the build system, installing the package in the host system is not sufficient: you should treat the generated <computeroutput>.deb</computeroutput> like another custom package. Please see <xref linkend="custom-packages"/> for more information. You should pay particular attention to <xref linkend="custom-packages-apt"/>.</para>
</listitem>
</orderedlist>
diff --git a/chapters/meta.xml b/chapters/meta.xml
index 93f3b6f..12d9cc2 100644
--- a/chapters/meta.xml
+++ b/chapters/meta.xml
@@ -20,7 +20,7 @@ The main goal of this manul is to serve as a single access point to all document
</varlistentry>
<varlistentry><term>Debian Live</term>
-<listitem><para>The Debian sub-project which maintains the <filename>live-helper</filename> and <filename>live-initramfs</filename> utilities.</para></listitem>
+<listitem><para>The Debian sub-project which maintains the &live-helper; and &live-initramfs; utilities.</para></listitem>
</varlistentry>
<varlistentry><term>Debian Live system</term>
@@ -31,16 +31,16 @@ The main goal of this manul is to serve as a single access point to all document
<listitem><para>The environment used to create the live system.</para></listitem>
</varlistentry>
-<varlistentry><term><filename>live-helper</filename></term>
+<varlistentry><term>&live-helper;</term>
<listitem><para>A collection of scripts used to build customised Debian Live systems.</para></listitem>
</varlistentry>
-<varlistentry><term><filename>live-initramfs</filename></term>
-<listitem><para>A collection of scripts used to boot live systems. <filename>live-initramfs</filename> is a fork of <filename>casper</filename> by Canonical, Ltd.</para></listitem>
+<varlistentry><term>&live-initramfs;</term>
+<listitem><para>A collection of scripts used to boot live systems. &live-initramfs; is a fork of <filename>casper</filename> by Canonical, Ltd.</para></listitem>
</varlistentry>
<varlistentry><term><filename>live-package</filename></term>
-<listitem><para>The former name of <filename>live-initramfs</filename>.</para></listitem>
+<listitem><para>The former name of &live-initramfs;.</para></listitem>
</varlistentry>
<varlistentry><term>Debian Installer / (d-i)</term>
diff --git a/chapters/overview.xml b/chapters/overview.xml
index 173f64e..132488d 100644
--- a/chapters/overview.xml
+++ b/chapters/overview.xml
@@ -9,8 +9,8 @@
<para>This chapter contains an overview of the two main tools used in building Debian Live systems.</para>
<section id="live-helper">
-<title><filename>live-helper</filename></title>
-<para><filename>live-helper</filename> is a collection of scripts that build Debian Live systems.</para>
+<title>&live-helper;</title>
+<para>&live-helper; is a collection of scripts that build Debian Live systems.</para>
<para>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.</para>
@@ -19,26 +19,26 @@
<orderedlist>
<listitem>
<para>The scripts have a central location for configuring their operation.</para>
-<para>In <computeroutput>debhelper</computeroutput>, this is the <filename class="directory">debian</filename> subdirectory of a package tree. For example, <computeroutput>dh_install</computeroutput> will look for file called <filename>debian/<packagename>.install</filename> to determine which files should exist in a particular binary package. In much the same way, <filename>live-helper</filename> stores its configuration entirely under a <filename class="directory">config/</filename> subdirectory.</para>
+<para>In <computeroutput>debhelper</computeroutput>, this is the <filename class="directory">debian</filename> subdirectory of a package tree. For example, <computeroutput>dh_install</computeroutput> will look for file called <filename>debian/<packagename>.install</filename> to determine which files should exist in a particular binary package. In much the same way, &live-helper; stores its configuration entirely under a <filename class="directory">config/</filename> subdirectory.</para>
</listitem>
<listitem><para>The scripts are indepodent - that is to say, it is always safe to run each command.</para></listitem>
</orderedlist>
-<para>Unlike <computeroutput>debhelper</computeroutput>, <filename>live-helper</filename> contains a tool to generate a skeleton configuration directory, <filename>lh_config</filename>. This could be considered to be similar to tools such as <computeroutput>dh-make</computeroutput>. For more information about <filename>lh_config</filename>, please see <xref linkend="lh_config"/>.</para>
+<para>Unlike <computeroutput>debhelper</computeroutput>, &live-helper; contains a tool to generate a skeleton configuration directory, <filename>lh_config</filename>. This could be considered to be similar to tools such as <computeroutput>dh-make</computeroutput>. For more information about <filename>lh_config</filename>, please see <xref linkend="lh_config"/>.</para>
-<para>Besides the common <filename>config/common</filename>, which is used by all <filename>live-helper</filename> commands, some additional files can be used to configure the behavior of specific helpers. These files are typically named <computeroutput>config/foo</computeroutput> or <computeroutput>config/stage</computeroutput> (where "stage", of course, is replaced with the name of the stage that they belong to, and "helper" with the name of the helper).</para>
+<para>Besides the common <filename>config/common</filename>, which is used by all &live-helper; commands, some additional files can be used to configure the behavior of specific helpers. These files are typically named <computeroutput>config/foo</computeroutput> or <computeroutput>config/stage</computeroutput> (where "stage", of course, is replaced with the name of the stage that they belong to, and "helper" with the name of the helper).</para>
-<para>For example, <computeroutput>lh_bootstrap_debootstrap</computeroutput> uses files named <filename>config/bootstrap</filename> and <filename>config/bootstrap_debootstrap</filename> to read the options it will use. Generally, these files contain variables with values assigned, one variable per line. Some programs in <filename>live-helper</filename> use pairs of values or slightly more complicated variable assignments.</para>
+<para>For example, <computeroutput>lh_bootstrap_debootstrap</computeroutput> uses files named <filename>config/bootstrap</filename> and <filename>config/bootstrap_debootstrap</filename> to read the options it will 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 assignments.</para>
-<para><filename>live-helper</filename> 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), <filename>live-helper</filename> will automatically set it to a default value.</para>
+<para>&live-helper; 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), &live-helper; will automatically set it to a default value.</para>
<para>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.</para>
<para>In some rare cases, you may want to have different versions of these files for different architectures or distributions. If files named <computeroutput>config/stage.arch</computeroutput> or <computeroutput>config/stage_helper.arch</computeroutput>, and <computeroutput>config/stage.dist</computeroutput> or <computeroutput>config/stage_helper.dist</computeroutput> exist (where "arch" is the same as the output of <computeroutput>dpkg --print-architecture</computeroutput> 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.</para>
-<para>Please see <xref linkend="installation"/> for information on how to install <filename>live-helper</filename>.
+<para>Please see <xref linkend="installation"/> for information on how to install &live-helper;.
<para>The remainder of this section discusses the three most important helpers:</para>
<variablelist>
@@ -58,7 +58,7 @@
<sect1 id="lh_config">
<title>The <filename>lh_config</filename> helper</title>
-<para>As discussed in <xref linkend="live-helper"/>, the scripts that make up <filename>live-helper</filename> source their configuration from a single directory named <computeroutput>config/</computeroutput>. As constructing this directory by hand would be time-consuming and error-prone, the <filename>lh_config</filename> helper can be used to create skeleton configuration folders.</para>
+<para>As discussed in <xref linkend="live-helper"/>, the scripts that make up &live-helper; source their configuration from a single directory named <computeroutput>config/</computeroutput>. As constructing this directory by hand would be time-consuming and error-prone, the <filename>lh_config</filename> helper can be used to create skeleton configuration folders.</para>
<para>Issuing <filename>lh_config</filename> without any arguments creates a <computeroutput>config</computeroutput> subdirectory which it populates with some default settings:</para>
<screen>
@@ -122,8 +122,8 @@ drwxr-xr-x 2 user group 4.1k 2008-05-09 21:37 templates
</section>
<section id="live-initramfs">
-<title>The <filename>live-initramfs</filename> package</title>
-<para><filename>live-initramfs</filename> is a collection of scripts.</para>
+<title>The &live-initramfs; package</title>
+<para>&live-initramfs; is a collection of scripts.</para>
<para>FIXME link to Kernel Handbook</para>
</section>
diff --git a/chapters/reporting-bugs.xml b/chapters/reporting-bugs.xml
index 10b6924..1c96809 100644
--- a/chapters/reporting-bugs.xml
+++ b/chapters/reporting-bugs.xml
@@ -13,12 +13,12 @@
<itemizedlist>
<listitem>
<para>
- Always try to reproduce the bug with the <emphasis>most recent version of <filename>live-helper</filename> and <filename>live-initramfs</filename></emphasis> before submitting a bug report.
+ Always try to reproduce the bug with the <emphasis>most recent version of &live-helper; and &live-initramfs;</emphasis> before submitting a bug report.
</para>
</listitem>
<listitem>
<para>
- Try to give <emphasis>as specific information as possible</emphasis> about the bug. This includes (at least) the version of <filename>live-helper</filename> and <filename>live-initramfs</filename> used and the distribution of the live system you are building.
+ Try to give <emphasis>as specific information as possible</emphasis> about the bug. This includes (at least) the version of &live-helper; and &live-initramfs; used and the distribution of the live system you are building.
</para>
</listitem>
</itemizedlist>
@@ -41,8 +41,8 @@ information:</para>
<itemizedlist>
<listitem><para>Architecture of the host system</para></listitem>
- <listitem><para>Version of <filename>live-helper</filename> on the host system</para></listitem>
- <listitem><para>Version of <filename>live-initramfs</filename> on the live system</para></listitem>
+ <listitem><para>Version of &live-helper; on the host system</para></listitem>
+ <listitem><para>Version of &live-initramfs; on the live system</para></listitem>
<listitem><para>Version of <filename>debootstrap</filename> and/or <filename>cdebootstrap</filename> on the host system</para></listitem>
<listitem><para>Architecture of the live system</para></listitem>
<listitem><para>Distribution of the live system</para></listitem>
@@ -68,7 +68,7 @@ encountered.</para>
<varlistentry><term>At build time whilst bootstrapping</term>
<listitem><para>
-<para><filename>live-helper</filename> first bootstraps a basic Debian system with <computeroutput>debootstrap</computeroutput> or <computeroutput>cdebootstrap</computeroutput>. Depending on the bootstrapping tool used and the Debian distribution it is bootstrapping, it may fail. If a bug appears here, check if the error is related to a specific Debian package (most likely), or if it is related to cdebootstrap itself.</para>
+<para>&live-helper; first bootstraps a basic Debian system with <computeroutput>debootstrap</computeroutput> or <computeroutput>cdebootstrap</computeroutput>. Depending on the bootstrapping tool used and the Debian distribution it is bootstrapping, it may fail. If a bug appears here, check if the error is related to a specific Debian package (most likely), or if it is related to cdebootstrap itself.</para>
<para>In both cases, this is not a bug in Debian Live, but rather in Debian itself which we can not fix this directly. Please report such a bug against <computeroutput>debootstrap</computeroutput>, <computeroutput>cdebootstrap</computeroutput> or the failing package.</para>
</para></listitem>
@@ -76,7 +76,7 @@ encountered.</para>
<varlistentry><term>At build time whilst installing packages</term>
-<listitem><para><filename>live-helper</filename> installs additional packages from the Debian archive and depending on the Debian distribution used and the daily archive state, it can fail. If a bug appears here, check if the error is also reproducible on a normal system.</para>
+<listitem><para>&live-helper; installs additional packages from the Debian archive and depending on the Debian distribution used and the daily archive state, it can fail. If a bug appears here, check if the error is also reproducible on a normal system.</para>
<para>If this is the case, this is not a bug in Debian Live, but rather in Debian - please report it against the failing package. Running <filename>debootstrap</filename> seperately from the Live system build or running <filename>lh_bootstrap</filename> with <computeroutput>--debug</computeroutput> will give you more information.</para>
diff --git a/ent/common.ent b/ent/common.ent
index 76ff659..d8dc264 100644
--- a/ent/common.ent
+++ b/ent/common.ent
@@ -1 +1,4 @@
<?xml version="1.0" encoding="iso-8859-1"?>
+
+<!ENTITY live-helper "<filename>live-helper</filename>">
+<!ENTITY live-initramfs "<filename>live-initramfs</filename>">
--
Debian Live manual
More information about the debian-live-changes
mailing list