[SCM] live-manual branch, master, updated. debian/20100301-1-16-ga6fffb3

Eric Dantan Rzewnicki eric at zhevny.com
Sat Apr 10 13:51:51 UTC 2010 

The following commit has been merged in the master branch:
commit 33cc6b28c38861a89432ee7c1aa080af1d0e1df9
Author: Eric Dantan Rzewnicki <eric at zhevny.com>
Date:   Sat Apr 10 08:41:43 2010 -0400

    Rewrapping and reformating xml for the Overview chapter.

diff --git a/xml/chapters/overview.xml b/xml/chapters/overview.xml
index cd07254..36f6eea 100644
--- a/xml/chapters/overview.xml
+++ b/xml/chapters/overview.xml
@@ -1,66 +1,180 @@
 <?xml version="1.0" encoding="utf-8"?>
+
 <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
-    "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
-  <!ENTITY % commondata SYSTEM "../entities/common.ent" > %commondata;
+	"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
+	<!ENTITY % commondata SYSTEM "../entities/common.ent" > %commondata;
 ]>
+
 <chapter id="overview">
 <title>Overview of tools</title>
 
-<para>This chapter contains an overview of the two main tools used in building Debian Live systems.</para>
+<para>
+	This chapter contains an overview of the two main tools used in
+	building Debian Live systems.
+</para>
 
 <section id="live-helper">
 <title>&live-helper;</title>
-<para>&live-helper; is a collection of scripts to build Debian Live systems. These scripts are also referred to as "helpers".</para>
 
-<para>The idea behind &live-helper; is to be a framework that uses a configuration directory to completely automate and customize all aspects of building a Live image.</para>
+<para>
+	&live-helper; is a collection of scripts to build Debian Live systems.
+	These scripts are also referred to as "helpers".
+</para>
 
-<para>Many concepts are similar with the <command>debhelper</command> Debian package tools written by Joey Hess:</para>
+<para>
+	The idea behind &live-helper; is to be a framework that uses a configuration
+	directory to completely automate and customize all aspects of building a Live
+	image.
+</para>
+
+<para>
+	Many concepts are similar with the <command>debhelper</command> Debian package
+	tools written by Joey Hess:
+</para>
 
 <orderedlist>
+
 <listitem>
-<para>The scripts have a central location for configuring their operation.</para>
-<para>In <command>debhelper</command>, this is the <filename class="directory">debian</filename> subdirectory of a package tree. For example, <command>dh_install</command> will look for file called <filename>debian/&lt;packagename&gt;.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>
+<para>
+	The scripts have a central location for configuring their operation.
+</para>
+
+<para>
+	In <command>debhelper</command>, this is the <filename
+	class="directory">debian</filename> subdirectory of a package tree. For
+	example, <command>dh_install</command> will look for file called
+	<filename>debian/&lt;packagename&gt;.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 independent - that is to say, it is always safe to run each command.</para></listitem>
+<listitem>
+<para>
+	The scripts are independent - that is to say, it is always safe to run
+	each command.
+</para>
+</listitem>
 
 </orderedlist>
 
-<para>Unlike <command>debhelper</command>, &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 <command>dh-make</command>. For more information about <filename>lh_config</filename>, please see <xref linkend="lh_config"/>.</para>
+<para>
+	Unlike <command>debhelper</command>, &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 <command>dh-make</command>. 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 &live-helper; helper commands, some additional files can be used to configure the behavior of specific helper commands. These files are typically named <command>config/foo</command> or <command>config/stage</command> (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; helper commands, some additional files can be used to configure
+	the behavior of specific helper commands. These files are typically named
+	<command>config/foo</command> or <command>config/stage</command> (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, the <command>lh_bootstrap_debootstrap</command> helper command 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>
+	For example, the <command>lh_bootstrap_debootstrap</command> helper command
+	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>&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>
+	&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>
+	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 <command>config/stage.arch</command> or <command>config/stage_helper.arch</command>, and <command>config/stage.dist</command> or <command>config/stage_helper.dist</command> exist (where "arch" is the same as the output of <command>dpkg --print-architecture</command> 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>
+	In some rare cases, you may want to have different versions of these files for
+	different architectures or distributions. If files named
+	<command>config/stage.arch</command> or
+	<command>config/stage_helper.arch</command>, and
+	<command>config/stage.dist</command> or
+	<command>config/stage_helper.dist</command> exist (where "arch" is the same as
+	the output of <command>dpkg --print-architecture</command> 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 &live-helper;.
+<para>
+	Please see <xref linkend="installation"/> for information on how to
+	install &live-helper;.
+</para>
+
+<para>
+	The remainder of this section discusses the three most important helpers:
+</para>
 
-<para>The remainder of this section discusses the three most important helpers:</para>
 <variablelist>
-<varlistentry><term><filename>lh_config</filename></term>
-<listitem><para>Responsible for initialising a Live system configuration directory. See <xref linkend="lh_config"/> for more information.</para></listitem>
+
+<varlistentry>
+<term><filename>lh_config</filename></term>
+
+<listitem>
+<para>
+	Responsible for initialising a Live system configuration directory. See <xref
+	linkend="lh_config"/> for more information.
+</para>
+</listitem>
 </varlistentry>
 
-<varlistentry><term><filename>lh_build</filename></term>
-<listitem><para>Responsible for starting a Live system build. See <xref linkend="lh_build"/> for more information.</para></listitem>
+<varlistentry>
+<term><filename>lh_build</filename></term>
+
+<listitem>
+<para>
+	Responsible for starting a Live system build. See <xref linkend="lh_build"/>
+	for more information.
+</para>
+</listitem>
 </varlistentry>
 
-<varlistentry><term><filename>lh_clean</filename></term>
-<listitem><para>Responsible for removing parts of a Live system build. <xref linkend="lh_clean"/> for more information.</para></listitem>
+<varlistentry>
+<term><filename>lh_clean</filename></term>
+
+<listitem>
+<para>
+	Responsible for removing parts of a Live system build. 
+	<xref linkend="lh_clean"/> for more information.
+</para>
+</listitem>
 </varlistentry>
 </variablelist>
-</para>
+
 
 <section id="lh-config">
 <title>The <filename>lh_config</filename> helper</title>
-<para>As discussed in <xref linkend="live-helper"/>, the scripts that make up &live-helper; source their configuration from a single directory named <command>config/</command>. 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 <command>config</command> subdirectory which it populates with some default settings:</para>
+<para>
+	As discussed in <xref linkend="live-helper"/>, the scripts that make up
+	&live-helper; source their configuration from a single directory named
+	<command>config/</command>. 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
+	<command>config</command> subdirectory which it populates with some default
+	settings:
+</para>
+
 <screen>
 $ lh_config
 $ ls -l
@@ -92,39 +206,68 @@ drwxr-xr-x 2 user group 4.1k 2008-05-09 21:37 includes
 drwxr-xr-x 2 user group 4.1k 2008-05-09 21:37 templates
 </screen>
 
-<para>Using <filename>lh_config</filename> 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.</para>
+<para>
+	Using <filename>lh_config</filename> 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.
+</para>
 
-<para>You can ask <filename>lh_config</filename> to generate <filename class="directory">config/</filename> 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:</para>
+<para>
+	You can ask <filename>lh_config</filename> to generate <filename
+	class="directory">config/</filename> 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:
+</para>
 
 <screen>
 $ lh_config -p gnome
 </screen>
 
-<para>will build a <filename class="directory">config/</filename> directory configured to include the '<command>gnome</command>' package list. It is possible to specify many options:</para>
+<para>
+	will build a <filename class="directory">config/</filename> directory
+	configured to include the '<command>gnome</command>' package list. It is
+	possible to specify many options:
+</para>
 
 <screen>
 $ lh_config --apt aptitude --binary-images net --hostname live-machine --username live-user ...
 </screen>
 
-<para>A full list of options is available FIXME. Most options have a parallel with an "<command>LH_</command>" prefixed variable.</para>
+<para>
+	A full list of options is available FIXME. Most options have a parallel with an
+	"<command>LH_</command>" prefixed variable.
+</para>
 
 </section>
 
 <section id="lh-build">
 <title>The <filename>lh_build</filename> helper</title>
-<para>FIXME</para>
+
+<para>
+	FIXME
+</para>
 </section>
 
 <section id="lh-clean">
 <title>The <filename>lh_clean</filename> helper</title>
-<para>It is the job of the <filename>lh_clean</filename> helper to remove various parts of a Live helper build.</para>
+
+<para>
+	It is the job of the <filename>lh_clean</filename> helper to remove various
+	parts of a Live helper build.
+</para>
 </section>
 </section>
 
 <section id="live-initramfs">
 <title>The &live-initramfs; package</title>
-<para>&live-initramfs; is a collection of scripts.</para>
-<para>FIXME link to Kernel Handbook</para>
+
+<para>
+	&live-initramfs; is a collection of scripts.
+</para>
+
+<para>
+	FIXME link to Kernel Handbook
+</para>
 </section>
 
 </chapter>

-- 
live-manual

More information about the debian-live-changes mailing list